Merge pull request #225 from siapy/fix

Author: janezlapajne

docs/concepts/datasets.md

@@ -0,0 +1,10 @@
+# Datasets
+
+??? note "API Documentation"
+    `siapy.datasets`
+
+The `datasets` module provides structured containers and utilities for transforming spectral image data into formats optimized for analysis and machine learning. It bridges the gap between raw spectral data and analytical workflows.
+
+```python
+--8<-- "docs/concepts/src/datasets_01.py"
+```

docs/concepts/entities.md

@@ -159,7 +159,21 @@ The example below demonstrates two key conversion methods of `SpectralImage` ins
 --8<-- "docs/concepts/src/spectral_image_05.py"
 ```
 
-<!-- ### Manipulation of shapes -->
+### Manipulation of Shapes
+
+Each `SpectralImage` instance automatically initializes a `GeometricShapes` object as a property called `geometric_shapes`. This property provides a container for managing shape objects associated with the image. It lets you work with image regions while maintaining the connection between spatial geometries and their spectral data. This is particularly useful for region-based analysis, masking, and feature extraction from specific areas of interest.
+
+The `GeometricShapes` class provides a list-like interface that wraps a standard Python list, enhancing it with specialized functionality for manipulating geometric shapes while preserving standard list behavior. The list of shapes can be accessed via the `image.geometric_shapes.shapes` property.
+
+```python
+--8<-- "docs/concepts/src/spectral_image_shapes_01.py:init"
+```
+
+As a result, shapes can be added to the spectral image using standard list operations. The example below demonstrates how this can be done:
+
+```python
+--8<-- "docs/concepts/src/spectral_image_shapes_01.py:operations"
+```
 
 ## Spectral Image Set
 

docs/concepts/src/datasets_01.py

@@ -0,0 +1,39 @@
+import numpy as np
+from rich import print
+
+from siapy.datasets.tabular import TabularDataset
+from siapy.entities import Shape, SpectralImage, SpectralImageSet
+
+# Create two mock spectral images with dimensions 100x100 pixels and 10 bands
+rng = np.random.default_rng(seed=42)
+image1 = SpectralImage.from_numpy(rng.random((100, 100, 10)))
+image2 = SpectralImage.from_numpy(rng.random((100, 100, 10)))
+
+# Define a region of interest as a rectangular shape (coordinates in pixel space)
+# This will select pixels from position (50,50) to (80,80) in both images
+rectangle = Shape.from_rectangle(x_min=50, y_min=50, x_max=80, y_max=80)
+image1.geometric_shapes.append(rectangle)
+image2.geometric_shapes.append(rectangle)
+
+# Combine the images into a SpectralImageSet for batch processing
+image_set = SpectralImageSet([image1, image2])
+
+# Initialize the TabularDataset with our image set and process the data
+# This extracts pixel data from the regions defined by our shapes
+dataset = TabularDataset(image_set)
+dataset.process_image_data()
+
+# The dataset is now iterable - we can access each entity (processed region)
+for entity in dataset:
+    print(f"Processing entity: {entity}")
+
+# Generate tabular data from our processed dataset
+# Setting mean_signatures=False preserves individual pixel values instead of averaging them
+dataset_data = dataset.generate_dataset_data(mean_signatures=False)
+
+# Convert the tabular data to a pandas DataFrame with multi-level indexing
+# This makes it easy to analyze and manipulate the data
+df = dataset_data.to_dataframe_multiindex()
+
+print(f"dataset_data: \n{dataset_data}")
+print(f"df: \n{df}")

docs/concepts/src/spectral_image_shapes_01.py

@@ -0,0 +1,37 @@
+# --8<-- [start:init]
+import numpy as np
+from rich import print
+
+from siapy.entities import Shape, SpectralImage
+from siapy.entities.shapes import GeometricShapes
+
+# Create a mock spectral image
+rng = np.random.default_rng(seed=42)
+array = rng.random((100, 100, 10))  # height, width, bands
+image = SpectralImage.from_numpy(array)
+
+# SpectralImage automatically initializes GeometricShapes
+assert isinstance(image.geometric_shapes, GeometricShapes)
+# You can access the underlying list via the shapes property
+assert isinstance(image.geometric_shapes.shapes, list)
+
+# GeometricShapes implements common list operations directly, i.e. number of shapes:
+length_via_geometric_shapes = len(image.geometric_shapes)
+length_via_raw_list = len(image.geometric_shapes.shapes)
+# --8<-- [end:init]
+
+# --8<-- [start:operations]
+# Create two Shape objects with distinct spatial coordinates and semantic labels
+coords1 = [(1, 2), (3, 4), (2, 4)]
+shape1 = Shape.from_multipoint(coords1, label="coords1")
+coords2 = [(19, 20), (21, 22), (20, 22)]
+shape2 = Shape.from_multipoint(coords2, label="coords2")
+
+# Add multiple shapes to the SpectralImage's geometric_shapes container at once
+image.geometric_shapes.extend([shape1, shape2])
+
+# Display the current collection of shapes stored in the image
+# Each shape will be shown with its type and label
+print(f"Shapes in GeometricShapes: {image.geometric_shapes}")
+
+# --8<-- [end:operations]

mkdocs.yml

@@ -67,7 +67,7 @@ nav:
   - Concepts:
       - Overview: concepts/overview.md
       - Entities: concepts/entities.md
-      # - Datasets: concepts/datasets.md
+      - Datasets: concepts/datasets.md
       # - Features: concepts/features.md
       # - Optimizers: concepts/optimizers.md
       # - Transformations: concepts/transformations.md

siapy/entities/shapes/geometric_shapes.py

@@ -26,6 +26,9 @@ def __init__(
         self._geometric_shapes = geometric_shapes if geometric_shapes is not None else []
         _check_shape_type(self._geometric_shapes, is_list=True)
 
+    def __repr__(self) -> str:
+        return f"GeometricShapes(\n{self._geometric_shapes}\n)"
+
     def __iter__(self) -> Iterator["Shape"]:
         return iter(self.shapes)