Merge pull request #221 from siapy/fix

Author: janezlapajne

CONTRIBUTING.md

@@ -22,79 +22,113 @@ SiaPy's architecture follows several key design principles:
 
 The class structure is depicted in the following diagram:
 
-![Entities Schematics](images/entities_schematics.png)
+![Entities Schematics](images/entities_schematics.svg)
 
-## Spectral Image
+## Pixels
 
-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.
+??? api "API Documentation"
+    [`siapy.entities.Pixels`][siapy.entities.Pixels]<br>
 
-### Image Initialization Options
+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)
 
-#### 1. Load from ENVI format (using spectral python)
+```python
+--8<-- "docs/concepts/src/pixels_01.py"
+```
 
-This is commonly used for hyperspectral imagery from airborne or satellite sensors.
+## Signals
+
+??? api "API Documentation"
+    [`siapy.entities.signatures.Signals`][siapy.entities.signatures.Signals]<br>
+
+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.
 
 ```python
---8<-- "docs/concepts/src/spectral_image_01.py"
+--8<-- "docs/concepts/src/signals_01.py"
 ```
 
-#### 2. Load from GeoTIFF or other geospatial formats (using rasterio)
+However, direct initialization of `Signals` is typically not necessary in practice. When you create a `Signatures` instance, the underlying `Signals` object is automatically generated and managed for you. This section demonstrates the `Signals` class primarily to illustrate how the `Signatures` class (discussed next) is composed internally and to provide insight into the data structure that powers spectral analysis.
 
-Perfect for georeferenced data with spatial information.
+## Signatures
+
+??? api "API Documentation"
+    [`siapy.entities.Signatures`][siapy.entities.Signatures]<br>
+
+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.
+
+`Signatures` can be initialized in multiple ways. The explicit approach creates each component separately before combining them, providing clarity about the composition:
 
 ```python
---8<-- "docs/concepts/src/spectral_image_02.py"
+--8<-- "docs/concepts/src/signatures_01.py:long"
 ```
 
-#### 3. Create from numpy array
+For more concise code, you can initialize a `Signatures` object directly from coordinate and signal values:
 
-Useful for testing or when you already have image data in memory.
+```python
+--8<-- "docs/concepts/src/signatures_01.py:short"
+```
+
+Both approaches yield equivalent results when initialized with the same data. You can access and work with the data using various DataFrame operations and conversion methods:
 
 ```python
---8<-- "docs/concepts/src/spectral_image_03.py"
+--8<-- "docs/concepts/src/signatures_01.py:assert"
 ```
 
-#### 4. Create your own custom image class
+## Shape
 
-For specialized file formats or custom processing needs, you can extend the ImageBase class.
+??? api "API Documentation"
+    [`siapy.entities.Shape`][siapy.entities.Shape]<br>
+
+The `Shape` class represents geometric shapes that can be associated with images, such as points, lines, and polygons.
 
 ```python
---8<-- "docs/concepts/src/spectral_image_04.py"
+--8<-- "docs/concepts/src/shapes_01.py"
 ```
 
-## Pixels
+## Spectral Image
 
-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)
+??? api "API Documentation"
+    [`siapy.entities.SpectralImage`][siapy.entities.SpectralImage]<br>
+
+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.
+
+### Image Initialization Options
+
+#### 1. Load from ENVI format (using spectral python)
+
+This is commonly used for hyperspectral imagery from airborne or satellite sensors.
 
 ```python
---8<-- "docs/concepts/src/pixels_01.py"
+--8<-- "docs/concepts/src/spectral_image_01.py"
 ```
 
-## Signals
+#### 2. Load from GeoTIFF or other geospatial formats (using rasterio)
 
-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.
+Perfect for georeferenced data with spatial information.
 
 ```python
---8<-- "docs/concepts/src/signals_01.py"
+--8<-- "docs/concepts/src/spectral_image_02.py"
 ```
 
-## Signatures
+#### 3. Create from numpy array
 
-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.
+Useful for testing or when you already have image data in memory.
 
 ```python
---8<-- "docs/concepts/src/signatures_01.py"
+--8<-- "docs/concepts/src/spectral_image_03.py"
 ```
 
-## Shape
+#### 4. Create your own custom image class
 
-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
---8<-- "docs/concepts/src/shapes_01.py"
+--8<-- "docs/concepts/src/spectral_image_04.py"
 ```
 
-## SpectralImageSet
+## Spectral Image Set
+
+??? api "API Documentation"
+    [`siapy.entities.SpectralImageSet`][siapy.entities.SpectralImageSet]<br>
 
 The `SpectralImageSet` class manages a collection of spectral images.
 

docs/concepts/entities.md

@@ -4,7 +4,10 @@
 
 SiaPy follows a modular architecture organized around key components that work together to provide a comprehensive toolkit for spectral image analysis.
 
-### Core (`siapy.core`)
+### Core
+
+??? note "API Documentation"
+    `siapy.core`
 
 The foundation of the library providing essential functionality:
 
@@ -13,7 +16,10 @@ The foundation of the library providing essential functionality:
 - **Type definitions**: Common types used throughout the library
 - **Configuration**: System paths and global configuration settings
 
-### Entities (`siapy.entities`)
+### Entities
+
+??? note "API Documentation"
+    `siapy.entities`
 
 Fundamental data structures that represent spectral imaging data:
 
@@ -23,34 +29,49 @@ Fundamental data structures that represent spectral imaging data:
 - **Shapes**: Geometric shapes for images' regions selection and masking
 - **Signatures**: Spectral signatures extracted from images
 
-### Datasets (`siapy.datasets`)
+### Datasets
+
+??? note "API Documentation"
+    `siapy.datasets`
 
 Tools for managing and working with datasets:
 
 - **Tabular datasets**: Handling tabular data with spectral information
 
-### Features (`siapy.features`)
+### Features
+
+??? note "API Documentation"
+    `siapy.features`
 
 Functionality for working with spectral features:
 
 - **Features**: Abstractions for feature extraction and selection
 - **Spectral indices**: Calculation of various spectral indices
 
-### Transformations (`siapy.transformations`)
+### Transformations
+
+??? note "API Documentation"
+    `siapy.transformations`
 
 Transformation capabilities:
 
 - **Co-registration**: Aligning images from different sources
 - **Image processing**: Functions for image manipulation
 
-### Optimizers (`siapy.optimizers`)
+### Optimizers
+
+??? note "API Documentation"
+    `siapy.optimizers`
 
 Optimization, hyperparameter tuning and evaluation:
 
 - **Optimization**: Machine learning training and optimization of hyperparameters
 - **Evaluation metrics and scoring mechanisms**: Tools for assessing model performance
 
-### Utils (`siapy.utils`)
+### Utils
+
+??? note "API Documentation"
+    `siapy.utils`
 
 Utility and plotting functions:
 

docs/concepts/images/entities_schematics.png

@@ -1,3 +1,4 @@
 from siapy.entities.signatures import Signals
 
+# Create from iterable (e.g. list, array)
 signals = Signals.from_iterable([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]])

docs/concepts/images/entities_schematics.svg

@@ -1,11 +1,39 @@
-from siapy.entities import Signatures
+# --8<-- [start:long]
+import pandas as pd
+from rich import print
 
-signatures = Signatures.from_signals_and_pixels(
+from siapy.entities import Pixels, Signatures
+from siapy.entities.signatures import Signals
+
+# Option 1: Step-by-step initialization
+# Initialize Pixels object from a DataFrame
+pixels_df = pd.DataFrame({"x": [10, 30], "y": [20, 40]})
+pixels = Pixels(pixels_df)
+
+# Initialize Signals object from a DataFrame
+signals_df = pd.DataFrame([[1, 2, 3], [4, 5, 6]])
+signals = Signals(signals_df)
+
+# Create Signatures object from Pixels and Signals objects
+signatures1 = Signatures(pixels, signals)
+# --8<-- [end:long]
+
+# --8<-- [start:short]
+# Option 2: Direct initialization with raw data
+# Initialize Signatures directly from raw signals and coordinates data
+signatures2 = Signatures.from_signals_and_pixels(
     signals=[[1, 2, 3], [4, 5, 6]],
     pixels=[[10, 20], [30, 40]],
 )
+# --8<-- [end:short]
+
+# --8<-- [start:assert]
+# Verify that both approaches produce equivalent results
+assert signatures1 == signatures2
 
-df_multi = signatures.to_dataframe_multiindex()
+# Print the DataFrame representation of Pixels and Signals
+df_multi = signatures2.to_dataframe_multiindex()
 print(f"MultiIndex DataFrame:\n{df_multi}")
-print(f"Signals DataFrame:\n{signatures.signals.df}")
-print(f"Pixels DataFrame:\n{signatures.pixels.df}")
+print(f"Signals DataFrame:\n{signatures2.signals.df}")
+print(f"Pixels DataFrame:\n{signatures2.pixels.df}")
+# --8<-- [end:assert]

docs/concepts/overview.md

@@ -1,6 +1,8 @@
 This section offers an overview of a case study based on real-world data.
 
+/// Note
 > 💡 **All code snippets** used in this case study are available in the [GitHub repository](https://github.com/siapy/siapy-lib/tree/main/docs/examples/src).
+///
 
 To follow along:
 
@@ -16,7 +18,9 @@ The hyperspectral dataset used in this case study was acquired using Hyspex push
 | VNIR-1600  | Visible to near-infrared (400–988 nm) | 160   | 3.6 nm     |
 | SWIR-384   | Short-wave infrared (950–2500 nm)    | 288   | 5.4 nm     |
 
-> **Note**: All hyperspectral data is provided as calibrated reflectance values, ensuring accuracy and reliability for your analysis.
+/// Note
+All hyperspectral data is provided as calibrated reflectance values, ensuring accuracy and reliability for your analysis.
+///
 
 ### 📁 File Naming Convention
 
@@ -47,12 +51,12 @@ Before diving into the examples, verify that your SiaPy installation and data ar
 ```
 
 /// Warning
+If you encounter issues:
 
-    If you encounter issues:
-    - Check that SiaPy is properly installed and your environment is activated
-    - Verify that you've downloaded the example data
-    - Ensure the `data_dir` variable points to the correct location of your dataset
-    - Make sure both `.img` and `.hdr` files are present in your data directory
+- Check that SiaPy is properly installed and your environment is activated
+- Verify that you've downloaded the example data
+- Ensure the `data_dir` variable points to the correct location of your dataset
+- Make sure both `.img` and `.hdr` files are present in your data directory
 ///
 
 ## 🧪 Source Code Examples
@@ -78,7 +82,8 @@ Before diving into the examples, verify that your SiaPy installation and data ar
   - File metadata and path information
   - Camera identification and associated geometric data
 
-> 💡 **Implementation Note**: This script uses SiaPy's property decorators for read-only access to image attributes, following the library's design pattern for consistent data access.
+??? note "Implementation Details"
+    This script uses decorators for read-only access to image attributes, following the library's design pattern for consistent data access.
 
 **Example:**
 
@@ -96,7 +101,8 @@ Before diving into the examples, verify that your SiaPy installation and data ar
 - **Data Extraction**: Methods for extracting spectral signatures and subarrays from specific image regions
 - **Visualization**: Converting hyperspectral data to displayable RGB images with optional histogram equalization
 
-> 💡 **Implementation Note**: Notice how methods follow SiaPy's naming convention: converters use `to_` prefix (e.g., `to_numpy()`, `to_signatures()`, `to_display()`), while calculation methods use descriptive verbs.
+??? note "Implementation Details"
+    Notice how methods follow SiaPy's naming convention: converters use `to_` prefix (e.g., `to_numpy()`, `to_signatures()`, `to_display()`), while calculation methods use descriptive verbs.
 
 ### Managing Image Collections
 
@@ -116,7 +122,8 @@ Before diving into the examples, verify that your SiaPy installation and data ar
 - **Iteration Patterns**: Iterating through the image collection with standard Python iteration
 - **Filtering and Selection**: Selecting images by specific criteria (e.g., camera ID)
 
-> 💡 **Implementation Note**: SpectralImageSet implements standard Python container interfaces, making it behave like a familiar collection type with additional hyperspectral-specific functionality.
+??? note "Implementation Details"
+    `SpectralImageSet` implements standard Python container interfaces, making it behave like a familiar collection type with additional hyperspectral-specific functionality.
 
 ### Interactive Pixel and Area Selection
 
@@ -139,7 +146,8 @@ The selected pixels are highlighted in the image below.
 - **User Interaction**: Simple keyboard-based interaction model (press Enter to finish selection)
 - **Results Access**: Accessing the resulting Pixels object and its DataFrame representation
 
-> 💡 **Implementation Note**: The `pixels_select_click` function handles the display, interaction, and collection of pixel coordinates in a single operation, simplifying user interaction code.
+??? note "Implementation Details"
+    The `pixels_select_click` function handles the display, interaction, and collection of pixel coordinates in a single operation, simplifying user interaction code.
 
 **Example:**
 
@@ -160,7 +168,8 @@ The selected areas are highlighted in the image below.
 - **Polygon-Based Selection**: Defining complex shapes for region-based analysis
 - **Selection Management**: Organized representation of selected areas for further processing
 
-> 💡 **Implementation Note**: Selected areas are returned as a list of Pixels objects, each representing a distinct region that can be separately analyzed or processed.
+??? note "Implementation Details"
+    Selected areas are returned as a list of `Pixels` objects, each representing a distinct region that can be separately analyzed or processed.
 
 ### Image Transformation and Processing
 
@@ -179,7 +188,8 @@ The selected areas are highlighted in the image below.
 - **Transformation Calculation**: Computing the mathematical transformation between coordinate systems
 - **Spatial Alignment**: Creating a foundation for aligning multi-sensor hyperspectral data
 
-> 💡 **Implementation Note**: The `corregistrator.align()` function computes a transformation matrix that can transform coordinates from one image space to another, essential for multi-sensor data fusion.
+??? note "Implementation Details"
+    The `corregistrator.align()` function computes a transformation matrix that can transform coordinates from one image space to another, essential for multi-sensor data fusion.
 
 **Example:**
 
@@ -196,7 +206,8 @@ The selected areas are highlighted in the image below.
 - **Cross-Spectral Analysis**: Enabling analysis of the same physical regions across different spectral data
 - **Visual Verification**: Displaying both images with highlighted areas to verify correct transformation
 
-> 💡 **Implementation Note**: The transformation is applied to the Pixels objects directly, allowing selected regions to be mapped between different spectral ranges while preserving their shape relationships.
+??? note "Implementation Details"
+    The transformation is applied to the `Pixels` objects directly, allowing selected regions to be mapped between different spectral ranges while preserving their shape relationships.
 
 **Example:**
 
@@ -213,7 +224,8 @@ The selected areas are highlighted in the image below.
 - **Normalization**: Area-based normalization for standardizing image intensity distributions
 - **Data Augmentation**: Creating modified versions of images for machine learning training
 
-> 💡 **Implementation Note**: All transformation functions follow a consistent input/output pattern, taking NumPy arrays as input and returning the transformed arrays, making them easily composable for complex processing pipelines.
+??? note "Implementation Details"
+    All transformation functions follow a consistent input/output pattern, taking NumPy arrays as input and returning the transformed arrays, making them easily composable for complex processing pipelines.
 
 ---
 

docs/concepts/src/signals_01.py

@@ -187,6 +187,7 @@ plugins:
   - exclude:
       glob:
         - __pycache__/*
+        - data/*
   - mkdocstrings:
       handlers:
         python: