Merge pull request #218 from siapy/fix

Author: janezlapajne

README.md

@@ -75,7 +75,7 @@ imageset = SpectralImageSet.spy_open(
 print(imageset)
 ```
 
-For an overview of the key concepts and functionalities of the SiaPy library, please refer to the [documentation](https://siapy.github.io/siapy-lib/examples/introduction/). Additionally, explore the use cases that demonstrate the library's capabilities [here](https://siapy.github.io/siapy-lib/examples/use_cases/).
+For an overview of the key concepts and functionalities of the SiaPy library, please refer to the [documentation](https://siapy.github.io/siapy-lib/latest/concepts/overview/). Additionally, explore the use cases that demonstrate the library's capabilities [here](https://siapy.github.io/siapy-lib/latest/examples/case_study/).
 
 ## 🔍 Contribution guidelines
 
@@ -89,7 +89,7 @@ Contributing to SiaPy isn’t limited to coding. You can also:
 
 Not sure where to start or how your skills might fit in? Don’t hesitate to reach out! You can contact us via email, or connect with us directly on GitHub by opening a new issue or commenting on an existing one.
 
-If you’re new to open-source contributions, check out our [guide](https://siapy.github.io/siapy-lib/contributing/) for helpful tips on getting started.
+If you’re new to open-source contributions, check out our [guide](https://siapy.github.io/siapy-lib/latest/contributing/) for helpful tips on getting started.
 
 ## 🕐 Issues and new features
 
@@ -101,4 +101,4 @@ Have a question? First, ensure that the setup process was completed successfully
 
 ## 🤝 License
 
-This project is licensed under the MIT License. See [LICENSE](https://siapy.github.io/siapy-lib/license/) for more details.
+This project is licensed under the MIT License. See [LICENSE](https://siapy.github.io/siapy-lib/latest/permit/) for more details.

docs/api/entities/shapes/geometric_shapes.md

@@ -0,0 +1 @@
+::: siapy.entities.shapes.geometric_shapes

docs/concepts/entities.md

@@ -1,257 +1,103 @@
 # Entities
 
-Entities form the core data structures in SiaPy that represent fundamental elements of spectral image processing. They provide consistent interfaces for working with various kinds of spectral data and spatial information.
+Entities serve as the foundational data structures in SiaPy, representing key elements of spectral image analysis and processing workflows. They implement consistent, strongly-typed interfaces that allow seamless interaction between spectral data, spatial coordinates, and geometric information.
 
-## Overview
+## Design principles
 
-The SiaPy Entities module defines a set of interconnected classes that represent the foundational building blocks for spectral image analysis:
+SiaPy's architecture follows several key design principles:
 
-- **SpectralImage**: A generic container for different types of hyperspectral/multispectral images
-- **SpectralImageSet**: A collection of spectral images
-- **Pixels**: Spatial coordinates within an image
-- **Signatures**: Spectral signals associated with specific pixel locations
-- **Shape**: Geometric shapes associated with image locations (points, lines, polygons)
+**Specialized yet compatible**: Each entity is optimized for its specific role while maintaining compatibility with the broader SiaPy ecosystem
 
-These entity classes are designed to work together, forming a cohesive system for analyzing spectral imagery.
+**Independence**: Most entities can function independently (with the exception of abstract base classes)
 
-## SpectralImage
+**Composition over inheritance**:
 
-A `SpectralImage` is the primary container for spectral image data. It's a generic class that can wrap different image backends:
+- The composition is preferred, so that one class can leverage another by injecting it into its architecture
+- Inheritance is primarily used to implement common interfaces through base classes
 
-```python
-from siapy.entities import SpectralImage
-
-# Load from ENVI format
-image = SpectralImage.spy_open(
-    header_path="path/to/header.hdr",
-    image_path="path/to/image.img"
-)
+**Extensibility**:
 
-# Load from GeoTIFF or other raster formats
-image = SpectralImage.rasterio_open(filepath="path/to/image.tif")
+- The `SpectralImage` class supports multiple data sources through *spectral* or *rasterio* libraries, however, custom data loading can be implemented by creating your own driver
+- Basic geometric shapes (e.g. points, lines, polygons) are implemented using the *shapely* library, which could also be extended through base abstraction
 
-# Create from NumPy array
-import numpy as np
-array = np.zeros((100, 100, 10))  # height, width, bands
-image = SpectralImage.from_numpy(array)
-```
+The class structure is depicted in the following diagram:
 
-### Key Properties
+![Entities Schematics](images/entities_schematics.png)
 
-- **shape**: Dimensions as (height, width, bands)
-- **width**, **height**: Image dimensions
-- **bands**: Number of spectral bands
-- **wavelengths**: List of wavelength values for each band
-- **default_bands**: Default bands for RGB visualization
-- **metadata**: Dictionary of metadata from the image file
-- **filepath**: Path to the source file
-- **camera_id**: Camera identifier (if available)
-- **geometric_shapes**: Associated geometric shapes collection
+## Spectral Image
 
-### Key Methods
+A `SpectralImage` is the primary container for spectral image data. It's a generic class that can wrap different image backends, allowing you to work with various file formats through a unified interface.
 
-- **to_numpy()**: Convert to NumPy array
-- **to_display()**: Convert to PIL Image for visualization
-- **to_xarray()**: Convert to xarray.DataArray
-- **to_signatures()**: Extract signatures at specified pixels
-- **to_subarray()**: Extract a subarray for a region of interest
-- **average_intensity()**: Calculate mean intensity across specified axes
+### Image Initialization Options
 
-## Pixels
+#### 1. Load from ENVI format (using spectral python)
 
-The `Pixels` class represents spatial coordinates within an image, typically stored as x,y pairs.
+This is commonly used for hyperspectral imagery from airborne or satellite sensors.
 
 ```python
-from siapy.entities import Pixels
-
-# Create from list of coordinates
-pixels = Pixels.from_iterable([(10, 20), (30, 40), (50, 60)])
-
-# Load from parquet file
-pixels = Pixels.load_from_parquet("pixels.parquet")
+--8<-- "docs/concepts/src/spectral_image_01.py"
 ```
 
-### Key Properties
-
-- **df**: Underlying pandas DataFrame with x,y coordinates
-- **coords**: Coordinate system definition
+#### 2. Load from GeoTIFF or other geospatial formats (using rasterio)
 
-### Key Methods
-
-- **x()**, **y()**: Access x and y coordinates as pandas Series
-- **to_numpy()**: Convert to NumPy array
-- **to_list()**: Convert to list of coordinates
-- **as_type()**: Convert coordinates to a specific data type
-- **get_coordinate()**: Get a specific coordinate pair
-- **df_homogenious()**: Get homogeneous coordinates (x,y,1)
-
-## Signatures
-
-The `Signatures` class combines `Pixels` with their corresponding spectral signals.
+Perfect for georeferenced data with spatial information.
 
 ```python
-from siapy.entities import Signatures, Pixels, Signals
-
-# Create from pixels and signals
-pixels = Pixels.from_iterable([(10, 20), (30, 40)])
-signals_df = pd.DataFrame([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]])  # 2 pixels, 3 bands
-signals = Signals(signals_df)
-signatures = Signatures(pixels, signals)
-
-# Extract signatures from an image at specific pixels
-pixels = Pixels.from_iterable([(10, 20), (30, 40)])
-signatures = spectral_image.to_signatures(pixels)
+--8<-- "docs/concepts/src/spectral_image_02.py"
 ```
 
-### Key Properties
+#### 3. Create from numpy array
 
-- **pixels**: The `Pixels` object with coordinate information
-- **signals**: The `Signals` object with spectral values
-
-### Key Methods
-
-- **to_dataframe()**: Convert to a pandas DataFrame
-- **to_dataframe_multiindex()**: Convert to a DataFrame with MultiIndex columns
-- **to_numpy()**: Convert to tuple of NumPy arrays (pixels, signals)
-- **to_dict()**: Convert to dictionary representation
-- **reset_index()**: Reset DataFrame indices
-- **copy()**: Create a deep copy
-
-## Signals
-
-The `Signals` class represents spectral values associated with pixels.
+Useful for testing or when you already have image data in memory.
 
 ```python
-from siapy.entities.signatures import Signals
-
-# Create from DataFrame
-signals_df = pd.DataFrame([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]])  # 2 pixels, 3 bands
-signals = Signals(signals_df)
-
-# Create from iterable
-signals = Signals.from_iterable([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]])
+--8<-- "docs/concepts/src/spectral_image_03.py"
 ```
 
-### Key Properties
-
-- **df**: Underlying pandas DataFrame with spectral values
-
-### Key Methods
+#### 4. Create your own custom image class
 
-- **to_numpy()**: Convert to NumPy array
-- **average_signal()**: Calculate mean signal across specified axis
-- **save_to_parquet()**: Save to parquet file
-
-## Shape
-
-The `Shape` class represents geometric shapes that can be associated with images, such as points, lines, and polygons.
+For specialized file formats or custom processing needs, you can extend the ImageBase class.
 
 ```python
-from siapy.entities import Shape
-from siapy.entities import Pixels
+--8<-- "docs/concepts/src/spectral_image_04.py"
+```
 
-# Create a point
-point = Shape.from_point(10, 20)
+## Pixels
 
-# Create a polygon from pixels
-pixels = Pixels.from_iterable([(0, 0), (10, 0), (10, 10), (0, 10)])
-polygon = Shape.from_polygon(pixels)
+The `Pixels` class represents spatial coordinates within spectral image, providing a container for *(x, y)* coordinate pairs. It uses pandas DataFrame internally for storage, enabling high-performance operations. The class provides multiple initialization methods and conversion functions to work with different data representations (i.e. DataFrames, list, arrays)
 
-# Load from shapefile
-shape = Shape.open_shapefile("path/to/shapefile.shp")
+```python
+--8<-- "docs/concepts/src/pixels_01.py"
 ```
 
-### Shape Types
+## Signals
 
-- **Point**: Single coordinate point (x,y)
-- **LineString**: Series of connected points forming a line
-- **Polygon**: Closed shape with interior area
-- **MultiPoint**: Collection of independent points
-- **MultiLineString**: Collection of independent lines
-- **MultiPolygon**: Collection of independent polygons
+The `Signals` class stores spectral data for each pixel in a pandas DataFrame, allowing you to use any column names you choose (e.g. "band_1", "nir", "red_edge"). You can initialize it from a DataFrame, lists, dicts or NumPy arrays.
 
-### Key Properties
+```python
+--8<-- "docs/concepts/src/signals_01.py"
+```
 
-- **geometry**: The underlying shapely geometry
-- **label**: Optional label for the shape
-- **shape_type**: Type of geometry (point, line, polygon, etc.)
-- **bounds**: Bounding box of the shape
-- **centroid**: Centroid point of the shape
+## Signatures
 
-### Key Methods
+The `Signatures` class represents spectral data collections by combining spatial coordinates (`Pixels`) with their corresponding spectral values (`Signals`). It provides a unified container that maintains the spatial-spectral relationship, allowing for analysis of spectral information at specific image locations. Internally, the data is stored as pandas DataFrames for efficient operations and indexing.
 
-- **buffer()**: Create a buffered version of the shape
-- **intersection()**: Find intersection with another shape
-- **union()**: Combine with another shape
-- **to_file()**: Save to a shapefile
+```python
+--8<-- "docs/concepts/src/signatures_01.py"
+```
 
-## GeometricShapes
+## Shape
 
-The `GeometricShapes` class manages a collection of shapes associated with a spectral image.
+The `Shape` class represents geometric shapes that can be associated with images, such as points, lines, and polygons.
 
 ```python
-# Access shapes associated with an image
-image = SpectralImage.spy_open(header_path="...", image_path="...")
-shapes = image.geometric_shapes
-
-# Add a shape
-polygon = Shape.from_rectangle(10, 20, 30, 40)
-shapes.append(polygon)
-
-# Find a shape by name
-shape = shapes.get_by_name("vegetation")
+--8<-- "docs/concepts/src/shapes_01.py"
 ```
 
-### Key Methods
-
-- **append()**, **extend()**: Add shapes to the collection
-- **remove()**, **pop()**, **clear()**: Remove shapes
-- **index()**, **count()**: Find and count shapes
-- **get_by_name()**: Find a shape by its label
-
 ## SpectralImageSet
 
 The `SpectralImageSet` class manages a collection of spectral images.
 
 ```python
-from siapy.entities import SpectralImageSet
-from pathlib import Path
-
-# Load multiple images
-header_paths = list(Path("data_dir").glob("*.hdr"))
-image_paths = list(Path("data_dir").glob("*.img"))
-image_set = SpectralImageSet.spy_open(
-    header_paths=header_paths,
-    image_paths=image_paths
-)
-
-# Access images
-first_image = image_set[0]
-
-# Sort images
-image_set.sort()
+--8<-- "docs/concepts/src/spectral_image_set_01.py"
 ```
-
-### Key Properties
-
-- **images**: List of SpectralImage objects
-- **cameras_id**: List of unique camera IDs
-
-### Key Methods
-
-- **images_by_camera_id()**: Get images from a specific camera
-- **sort()**: Sort the images
-
-## Relationship Between Entities
-
-The entities in SiaPy form a cohesive system:
-
-1. A `SpectralImage` contains pixel data across multiple spectral bands
-2. `Pixels` represent spatial coordinates within that image
-3. `Signals` contain spectral values at those coordinates
-4. `Signatures` combine pixels and signals to represent spectral signatures at specific locations
-5. `Shape` objects define geometric regions in the image
-6. `GeometricShapes` organize multiple shapes associated with an image
-7. `SpectralImageSet` manages multiple related spectral images
-
-This modular design allows for flexible workflows in spectral image analysis - from loading image data, to selecting regions of interest, to extracting and analyzing spectral signatures.

docs/concepts/images/entities_schematics.png

@@ -2,20 +2,7 @@
 
 ## Architecture
 
-SiaPy follows a modular architecture organized around key components that work together to provide a comprehensive toolkit for spectral image analysis:
-
-``` sh
-siapy/
-├── core/            # Core functionality
-├── datasets/        # Dataset handling and management
-├── entities/        # Key data structures and representations
-├── features/        # Feature extraction and analysis
-├── optimizers/      # Optimization algorithms and machine learning
-├── transformations/ # Transformation operations
-└── utils/           # Utility functions and helpers
-```
-
-## Core Components
+SiaPy follows a modular architecture organized around key components that work together to provide a comprehensive toolkit for spectral image analysis.
 
 ### Core (`siapy.core`)
 
@@ -30,8 +17,8 @@ The foundation of the library providing essential functionality:
 
 Fundamental data structures that represent spectral imaging data:
 
-- **SpectralImage**: An abstraction for various image formats
-- **SpectralImageSet**: Collection of spectral images with batch operations
+- **Spectral image**: An abstraction for various image formats
+- **Spectral image set**: Collection of spectral images with batch operations
 - **Pixels**: Representation of pixel coordinates and groups
 - **Shapes**: Geometric shapes for images' regions selection and masking
 - **Signatures**: Spectral signatures extracted from images

docs/concepts/overview.md

@@ -0,0 +1,16 @@
+import numpy as np
+import pandas as pd
+
+from siapy.entities import Pixels
+
+# Create from pandas DataFrame
+pixels1 = Pixels(pd.DataFrame({"x": [10, 20, 30], "y": [40, 50, 60]}))
+
+# Create from numpy array
+pixels2 = Pixels.from_iterable(np.array([[10, 40], [20, 50], [30, 60]]))
+
+# Create from list of coordinates
+pixels3 = Pixels.from_iterable([(10, 40), (20, 50), (30, 60)])
+
+# Should be the same
+assert pixels1 == pixels2 == pixels3

docs/concepts/src/pixels_01.py

@@ -0,0 +1,11 @@
+from siapy.entities import Pixels, Shape
+
+# Create a point
+point = Shape.from_point(10, 20)
+
+# Create a polygon from pixels
+pixels = Pixels.from_iterable([(0, 0), (10, 0), (10, 10), (0, 10)])
+polygon = Shape.from_polygon(pixels)
+
+# Load from shapefile
+shape = Shape.open_shapefile("path/to/shapefile.shp")

docs/concepts/src/shapes_01.py

@@ -0,0 +1,3 @@
+from siapy.entities.signatures import Signals
+
+signals = Signals.from_iterable([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]])