Merge pull request #214 from siapy/fix

Author: janezlapajne

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.4
+    rev: v0.11.6
     hooks:
       - id: ruff
         args:
@@ -23,7 +23,7 @@ repos:
         files: ^(siapy|tests)/
       - id: ruff-format
   - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.24.2
+    rev: v8.24.3
     hooks:
       - id: gitleaks
   - repo: https://github.com/codespell-project/codespell

docs/api/entities/helpers.md

@@ -0,0 +1 @@
+::: siapy.utils.image_validators

docs/api/utils/image_validators.md

@@ -0,0 +1 @@
+::: siapy.utils.signatures

docs/api/utils/signatures.md

@@ -23,7 +23,7 @@
 print("Image shape:", image_np.shape)
 
 # Calculate mean
-mean_val = image.mean(axis=(0, 1))
+mean_val = image.average_intensity(axis=(0, 1))
 print("Mean value per band:", mean_val)
 
 # Create a Pixels object from an iterable with pixels coordinates

docs/examples/src/spectral_image_02.py

@@ -93,7 +93,6 @@ nav:
           - Image Sets: api/entities/imagesets.md
           - Pixels: api/entities/pixels.md
           - Signatures: api/entities/signatures.md
-          - Helpers: api/entities/helpers.md
       - Features:
           - Features: api/features/features.md
           - Helpers: api/features/helpers.md
@@ -110,7 +109,9 @@ nav:
           - Image: api/transformations/image.md
       - Utils:
           - Images: api/utils/images.md
+          - Images Validators: api/utils/image_validators.md
           - Plots: api/utils/plots.md
+          - Signatures: api/utils/signatures.md
   - Release Notes: changelog.md
   - License: permit.md
 

mkdocs.yml

@@ -9,7 +9,7 @@
 from siapy.core.types import ImageContainerType
 from siapy.datasets.schemas import TabularDatasetData
 from siapy.entities import Signatures, SpectralImage, SpectralImageSet
-from siapy.entities.helpers import get_signatures_within_convex_hull
+from siapy.utils.signatures import get_signatures_within_convex_hull
 
 __all__ = [
     "TabularDataset",

siapy/datasets/tabular.py

@@ -1,11 +1,13 @@
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Generic, Sequence, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, Iterable, Sequence, TypeVar
 
 import numpy as np
+import pandas as pd
 from numpy.typing import NDArray
 from PIL import Image
 
+from ..pixels import CoordinateInput, Pixels, validate_pixel_input
 from ..shapes import GeometricShapes, Shape
 from ..signatures import Signatures
 from .interfaces import ImageBase
@@ -16,8 +18,6 @@
 if TYPE_CHECKING:
     from siapy.core.types import XarrayType
 
-    from ..pixels import Pixels
-
 
 __all__ = [
     "SpectralImage",
@@ -47,6 +47,13 @@ def __eq__(self, other: Any) -> bool:
             return NotImplemented
         return self.filepath.name == other.filepath.name and self._image == other._image
 
+    def __array__(self, dtype: np.dtype | None = None) -> NDArray[np.floating[Any]]:
+        """Convert this spectral image to a numpy array when requested by NumPy."""
+        array = self.to_numpy()
+        if dtype is not None:
+            return array.astype(dtype)
+        return array
+
     @classmethod
     def spy_open(
         cls, *, header_path: str | Path, image_path: str | Path | None = None
@@ -117,26 +124,30 @@ def to_numpy(self, nan_value: float | None = None) -> NDArray[np.floating[Any]]:
     def to_xarray(self) -> "XarrayType":
         return self.image.to_xarray()
 
-    def to_signatures(self, pixels: "Pixels") -> Signatures:
+    def to_signatures(self, pixels: Pixels | pd.DataFrame | Iterable[CoordinateInput]) -> Signatures:
+        pixels = validate_pixel_input(pixels)
         image_arr = self.to_numpy()
         signatures = Signatures.from_array_and_pixels(image_arr, pixels)
         return signatures
 
-    def to_subarray(self, pixels: "Pixels") -> NDArray[np.floating[Any]]:
+    def to_subarray(self, pixels: Pixels | pd.DataFrame | Iterable[CoordinateInput]) -> NDArray[np.floating[Any]]:
+        pixels = validate_pixel_input(pixels)
         image_arr = self.to_numpy()
-        u_max = pixels.x().max()
-        u_min = pixels.x().min()
-        v_max = pixels.y().max()
-        v_min = pixels.y().min()
+        x_max = pixels.x().max()
+        x_min = pixels.x().min()
+        y_max = pixels.y().max()
+        y_min = pixels.y().min()
         # create new image
-        image_arr_area = np.nan * np.ones((int(v_max - v_min + 1), int(u_max - u_min + 1), self.bands))
+        image_arr_area = np.nan * np.ones((int(y_max - y_min + 1), int(x_max - x_min + 1), self.bands))
         # convert original coordinates to coordinates for new image
-        v_norm = pixels.y() - v_min
-        u_norm = pixels.x() - u_min
+        y_norm = pixels.y() - y_min
+        x_norm = pixels.x() - x_min
         # write values from original image to new image
-        image_arr_area[v_norm, u_norm, :] = image_arr[pixels.y(), pixels.x(), :]
+        image_arr_area[y_norm, x_norm, :] = image_arr[pixels.y(), pixels.x(), :]
         return image_arr_area
 
-    def mean(self, axis: int | tuple[int, ...] | Sequence[int] | None = None) -> float | NDArray[np.floating[Any]]:
+    def average_intensity(
+        self, axis: int | tuple[int, ...] | Sequence[int] | None = None
+    ) -> float | NDArray[np.floating[Any]]:
         image_arr = self.to_numpy()
         return np.nanmean(image_arr, axis=axis)

siapy/entities/images/spimage.py

@@ -13,6 +13,9 @@
 __all__ = [
     "Pixels",
     "PixelCoordinate",
+    "CoordinateInput",
+    "HomogeneousCoordinate",
+    "validate_pixel_input",
 ]
 
 
@@ -53,6 +56,13 @@ def __eq__(self, other: Any) -> bool:
             return False
         return self.df.equals(other.df)
 
+    def __array__(self, dtype: np.dtype | None = None) -> NDArray[np.floating[Any]]:
+        """Convert this pixels object to a numpy array when requested by NumPy."""
+        array = self.to_numpy()
+        if dtype is not None:
+            return array.astype(dtype)
+        return array
+
     def __post_init__(self) -> None:
         validate_pixel_input_dimensions(self._data)
 
@@ -128,3 +138,42 @@ def validate_pixel_input_dimensions(df: pd.DataFrame | pd.Series) -> None:
             message=f"Invalid column names: expected ['{HomogeneousCoordinate.X}', '{HomogeneousCoordinate.Y}'], got",
             input_value=sorted(df.columns),
         )
+
+
+def validate_pixel_input(input_data: Pixels | pd.DataFrame | Iterable[CoordinateInput]) -> Pixels:
+    """Validates and converts various input types to Pixels object."""
+    try:
+        if isinstance(input_data, Pixels):
+            return input_data
+
+        if isinstance(input_data, pd.DataFrame):
+            validate_pixel_input_dimensions(input_data)
+            return Pixels(input_data)
+
+        if isinstance(input_data, np.ndarray):
+            if input_data.ndim != 2 or input_data.shape[1] != 2:
+                raise InvalidInputError(
+                    input_value=input_data.shape,
+                    message=f"NumPy array must be 2D with shape (n, 2), got shape {input_data.shape}",
+                )
+            return Pixels(pd.DataFrame(input_data, columns=[HomogeneousCoordinate.X, HomogeneousCoordinate.Y]))
+
+        if isinstance(input_data, Iterable):
+            return Pixels.from_iterable(input_data)  # type: ignore
+
+        raise InvalidTypeError(
+            input_value=input_data,
+            allowed_types=(Pixels, pd.DataFrame, np.ndarray, Iterable),
+            message=f"Unsupported input type: {type(input_data).__name__}",
+        )
+
+    except Exception as e:
+        if isinstance(e, (InvalidTypeError, InvalidInputError)):
+            raise
+
+        raise InvalidInputError(
+            input_value=input_data,
+            message=f"Failed to convert input to Pixels: {str(e)}"
+            f"\nExpected a Pixels instance or an iterable (e.g. list, np.array, tuple, pd.DataFrame)."
+            f"\nThe input must contain 2D coordinates with x and y values.",
+        )

siapy/entities/pixels.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Iterable, Optional
 
 import geopandas as gpd
 import numpy as np
@@ -11,7 +11,7 @@
 from shapely.geometry.base import BaseGeometry
 
 from siapy.core.exceptions import ConfigurationError, InvalidFilepathError, InvalidInputError, InvalidTypeError
-from siapy.entities.pixels import PixelCoordinate, Pixels
+from siapy.entities.pixels import CoordinateInput, PixelCoordinate, Pixels, validate_pixel_input
 
 __all__ = [
     "Shape",
@@ -72,6 +72,13 @@ def __repr__(self) -> str:
     def __len__(self) -> int:
         return len(self.df)
 
+    def __array__(self, dtype: np.dtype | None = None) -> NDArray[np.floating[Any]]:
+        """Convert this shape object to a numpy array when requested by NumPy."""
+        array = self.to_numpy()
+        if dtype is not None:
+            return array.astype(dtype)
+        return array
+
     @classmethod
     def open_shapefile(cls, filepath: str | Path, label: str = "") -> "Shape":
         filepath = Path(filepath)
@@ -108,30 +115,44 @@ def from_point(cls, x: float, y: float, label: str = "") -> "Shape":
         return cls(geometry=Point(x, y), label=label)
 
     @classmethod
-    def from_multipoint(cls, points: "Pixels", label: str = "") -> "Shape":
+    def from_multipoint(cls, points: Pixels | pd.DataFrame | Iterable[CoordinateInput], label: str = "") -> "Shape":
+        points = validate_pixel_input(points)
         if len(points) < 1:
             raise ConfigurationError("At least one point is required")
         coords = points.to_list()
         return cls(geometry=MultiPoint(coords), label=label)
 
     @classmethod
-    def from_line(cls, pixels: Pixels, label: str = "") -> "Shape":
+    def from_line(cls, pixels: Pixels | pd.DataFrame | Iterable[CoordinateInput], label: str = "") -> "Shape":
+        pixels = validate_pixel_input(pixels)
         if len(pixels) < 2:
             raise ConfigurationError("At least two points are required for a line")
 
         return cls(geometry=LineString(pixels.to_list()), label=label)
 
     @classmethod
-    def from_multiline(cls, line_segments: list[Pixels], label: str = "") -> "Shape":
+    def from_multiline(
+        cls, line_segments: list[Pixels | pd.DataFrame | Iterable[CoordinateInput]], label: str = ""
+    ) -> "Shape":
         if not line_segments:
             raise ConfigurationError("At least one line segment is required")
 
-        lines = [LineString(segment.to_list()) for segment in line_segments]
+        lines = []
+        for segment in line_segments:
+            validated_segment = validate_pixel_input(segment)
+            lines.append(LineString(validated_segment.to_list()))
+
         multi_line = MultiLineString(lines)
         return cls(geometry=multi_line, label=label)
 
     @classmethod
-    def from_polygon(cls, exterior: Pixels, holes: Optional[list[Pixels]] = None, label: str = "") -> "Shape":
+    def from_polygon(
+        cls,
+        exterior: Pixels | pd.DataFrame | Iterable[CoordinateInput],
+        holes: Optional[list[Pixels | pd.DataFrame | Iterable[CoordinateInput]]] = None,
+        label: str = "",
+    ) -> "Shape":
+        exterior = validate_pixel_input(exterior)
         if len(exterior) < 3:
             raise ConfigurationError("At least three points are required for a polygon")
 
@@ -144,7 +165,8 @@ def from_polygon(cls, exterior: Pixels, holes: Optional[list[Pixels]] = None, la
             # Close each hole if not already closed
             closed_holes = []
             for hole in holes:
-                hole_coords = hole.to_list()
+                validated_hole = validate_pixel_input(hole)
+                hole_coords = validated_hole.to_list()
                 if hole_coords[0] != hole_coords[-1]:
                     hole_coords.append(hole_coords[0])
                 closed_holes.append(hole_coords)
@@ -155,13 +177,16 @@ def from_polygon(cls, exterior: Pixels, holes: Optional[list[Pixels]] = None, la
         return cls(geometry=geometry, label=label)
 
     @classmethod
-    def from_multipolygon(cls, polygons: list[Pixels], label: str = "") -> "Shape":
+    def from_multipolygon(
+        cls, polygons: list[Pixels | pd.DataFrame | Iterable[CoordinateInput]], label: str = ""
+    ) -> "Shape":
         if not polygons:
             raise ConfigurationError("At least one polygon is required")
 
         polygon_objects = []
         for pixels in polygons:
-            coords = pixels.to_list()
+            validated_pixels = validate_pixel_input(pixels)
+            coords = validated_pixels.to_list()
             # Close the polygon if not already closed
             if coords[0] != coords[-1]:
                 coords.append(coords[0])