Merge pull request #223 from siapy/fix

Author: janezlapajne

CONTRIBUTING.md

@@ -100,6 +100,10 @@ Most commands use PDM (Python package and dependency manager) internally, which
 
 ## Development
 
+### Quick design pattern guide
+
+For consistent code quality across the project, refer to [copilot-instructions](https://github.com/siapy/siapy-lib/blob/main/.github/copilot-instructions.md), which concisely describes key design patterns.
+
 ### Git
 
 _[Why use Git?](https://www.git-scm.com/about)_ Git enables creation of multiple versions of a code repository called branches, with the ability to track and undo changes in detail.
@@ -113,16 +117,14 @@ Contribute by following:
 - Commit your changes with a [properly-formatted Git commit message](https://chris.beams.io/posts/git-commit/).
 - Create a [pull request (PR)](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) to incorporate your changes into the upstream project you forked.
 
-### Project organization around git
-
-### Branch Structure
+### Branch structure
 
 | Branch    | Purpose                     | Protection Rules                |
 |-----------|-----------------------------|---------------------------------|
 | `main`    | Stable production code      | • Signed commits required<br>• No force pushing<br>• Status checks required<br>• Admin included |
 | `develop` | Integration branch          | • Signed commits required<br>• Force pushing allowed<br>• Admin included |
 
-### Workflow Rules
+### Workflow rules
 
 - The default branch is `main`
 - Feature branches must target `develop` for pull requests
@@ -149,7 +151,7 @@ _Type_ must be one of the following:
 - `build`: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm), hidden
 - `ci`: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs), hidden
 
-## GitHub Actions workflows
+## GitHub actions workflows
 
 [GitHub Actions](https://github.com/features/actions) is a continuous integration/continuous deployment (CI/CD) service that runs on GitHub repos. Actions are grouped into workflows and stored in _.github/workflows_.
 

docs/concepts/entities.md

@@ -1,8 +1,17 @@
 # Entities
 
+??? note "API Documentation"
+    `siapy.entities`
+
 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.
 
-## Design principles
+## Module architecture
+
+The relationships between components are shown in the following diagram:
+
+![Entities Schematics](images/entities_schematics.svg)
+
+### Design principles
 
 SiaPy's architecture follows several key design principles:
 
@@ -20,9 +29,23 @@ SiaPy's architecture follows several key design principles:
 - 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
 
-The class structure is depicted in the following diagram:
+### Visual representation of spectral entities
 
-![Entities Schematics](images/entities_schematics.svg)
+The components follow standard naming conventions for spectral image analysis. A `SpectralImage` represents a three-dimensional data cube (height × width × bands). Each pixel in this cube has spatial coordinates *(x, y)* and a corresponding spectral signal with values across all bands.
+
+A signature combines a pixel's spatial location with its spectral signal, creating a complete spatial-spectral data point. The `Signatures` class serves as a container for multiple such data points, enabling analysis across collections of pixels.
+
+Since spectral images often contain distinct objects with different spectral properties, `Shapes` (regions of connected pixels) allow for extraction and analysis of specific areas. The `SpectralImage` class therefore integrates all primitive structures: `Pixels` and `Signals` by definition, and `Shapes` when attached to the image.
+
+![Entities Relations](images/entities_relations.png)
+
+| Name                            | What it represents                                                                                                                                    | Shape / size                               |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| **`Spectral image`**             | A single hyperspectral or multispectral data cube.                                                                     | **`(H, W, B)`** → *height × width × bands* |
+| **`Spectral image set`**          | An ordered collection of `SpectralImage` objects. Think of it as a “dataset” with convenience methods that loop internally instead of in user code.   | *N* × `SpectralImage` for *N* spectral images |
+| **`Pixels`** | One Cartesian coordinate **`(x, y)`**.                                | **`(N, 2)`** for *N* pixels                |
+| **`Shapes`**                     | A geometric region of interest (e.g. rectangle, polygon, circle), serving as a *container of pixels*. | Vector geometry                            |
+| **`Signatures`**         | A collection of 1-D spectral signals **`(B,)`** tied to pixel values **`(x, y)`** or aggregated over a shape.                                                        |   **`(N, B + 2)`** → *N* signatures, each with *B* spectral bands plus **`(x, y)`** coordinates |
 
 ## Pixels
 
@@ -125,6 +148,19 @@ For specialized file formats or custom processing needs, you can extend the Imag
 --8<-- "docs/concepts/src/spectral_image_04.py"
 ```
 
+### Data conversion methods
+
+The example below demonstrates two key conversion methods of `SpectralImage` instance:
+
+1. `to_signatures()`: Extracts spectral data from specific pixel coordinates and returns a `Signatures` object that maintains the spatial-spectral relationship
+2. `to_subarray()`: Converts selected pixel data to a NumPy array for numerical processing or integration with other scientific libraries
+
+```python
+--8<-- "docs/concepts/src/spectral_image_05.py"
+```
+
+<!-- ### Manipulation of shapes -->
+
 ## Spectral Image Set
 
 ??? api "API Documentation"

docs/concepts/images/entities_relations.png

@@ -0,0 +1,70 @@
+<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36 Edg/135.0.0.0" version="26.2.14">
+  <diagram name="Page-1" id="KD9Rf0FGmBdKboop7PPn">
+    <mxGraphModel grid="0" page="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" pageScale="1" pageWidth="1200" pageHeight="1600" math="0" shadow="0" adaptiveColors="auto">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="Q9c8q2dsdVY6IwAu6Xcm-1" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#331A00;strokeWidth=0.5;" vertex="1" parent="1">
+          <mxGeometry x="227" y="272" width="785" height="414" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-1" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;Spectral Image Set&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=#B2C9AB;strokeColor=#788AA3;fontColor=#46495D;" vertex="1" parent="1">
+          <mxGeometry x="500" y="307" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-17" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;" edge="1" parent="1" source="2ScwjqWDhc_dIcK86GyV-2" target="2ScwjqWDhc_dIcK86GyV-1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-2" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;Spectral Image&amp;nbsp;&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=#B2C9AB;strokeColor=#788AA3;fontColor=#46495D;" vertex="1" parent="1">
+          <mxGeometry x="500" y="404" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-14" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="2ScwjqWDhc_dIcK86GyV-3" target="2ScwjqWDhc_dIcK86GyV-2">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-3" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;Shapes&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=#B2C9AB;strokeColor=#788AA3;fontColor=#46495D;" vertex="1" parent="1">
+          <mxGeometry x="654" y="404" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-12" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="2ScwjqWDhc_dIcK86GyV-4" target="2ScwjqWDhc_dIcK86GyV-6">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-4" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;Signals&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=#B2C9AB;strokeColor=#788AA3;fontColor=#46495D;" vertex="1" parent="1">
+          <mxGeometry x="500" y="597" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-13" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="2ScwjqWDhc_dIcK86GyV-5" target="2ScwjqWDhc_dIcK86GyV-6">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-5" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;Pixels&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=#B2C9AB;strokeColor=#788AA3;fontColor=#46495D;" vertex="1" parent="1">
+          <mxGeometry x="654" y="500" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-11" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="2ScwjqWDhc_dIcK86GyV-6" target="2ScwjqWDhc_dIcK86GyV-2">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-6" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;Signatures&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=#B2C9AB;strokeColor=#788AA3;fontColor=#46495D;" vertex="1" parent="1">
+          <mxGeometry x="500" y="500" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-15" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="2ScwjqWDhc_dIcK86GyV-8" target="2ScwjqWDhc_dIcK86GyV-3">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-8" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;Base Geometry&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=#B2C9AB;strokeColor=#788AA3;fontColor=#46495D;" vertex="1" parent="1">
+          <mxGeometry x="807" y="404" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-18" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="2ScwjqWDhc_dIcK86GyV-9" target="2ScwjqWDhc_dIcK86GyV-2">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="2ScwjqWDhc_dIcK86GyV-9" value="&lt;font style=&quot;font-size: 14px;&quot;&gt;Base Image&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;labelBackgroundColor=none;fillColor=#B2C9AB;strokeColor=#788AA3;fontColor=#46495D;" vertex="1" parent="1">
+          <mxGeometry x="347" y="404" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="ZhcXIKDLDVEHgMZw6Vce-7" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=diamond;endFill=1;" edge="1" parent="1" source="ZhcXIKDLDVEHgMZw6Vce-4" target="2ScwjqWDhc_dIcK86GyV-8">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="ZhcXIKDLDVEHgMZw6Vce-4" value="&lt;div style=&quot;text-align: center;&quot;&gt;&lt;br&gt;&lt;/div&gt;&lt;div style=&quot;text-align: center;&quot;&gt;&amp;nbsp; &amp;nbsp;Shapely library:&lt;/div&gt;&lt;div&gt;&lt;ul&gt;&lt;li&gt;&lt;span style=&quot;background-color: transparent; color: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));&quot;&gt;Points&lt;/span&gt;&lt;/li&gt;&lt;li&gt;&lt;span style=&quot;background-color: transparent; color: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));&quot;&gt;Lines&lt;/span&gt;&lt;/li&gt;&lt;li&gt;&lt;span style=&quot;background-color: transparent; color: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));&quot;&gt;Polygons&lt;/span&gt;&lt;/li&gt;&lt;li&gt;&lt;span style=&quot;background-color: transparent; color: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));&quot;&gt;...&lt;/span&gt;&lt;/li&gt;&lt;/ul&gt;&lt;/div&gt;" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;align=left;imageHeight=27;" vertex="1" parent="1">
+          <mxGeometry x="807" y="490" width="121" height="107" as="geometry" />
+        </mxCell>
+        <mxCell id="ZhcXIKDLDVEHgMZw6Vce-10" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;endArrow=diamond;endFill=1;" edge="1" parent="1" source="ZhcXIKDLDVEHgMZw6Vce-8" target="2ScwjqWDhc_dIcK86GyV-9">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="ZhcXIKDLDVEHgMZw6Vce-8" value="&lt;ul&gt;&lt;li&gt;Spectral library&lt;/li&gt;&lt;li&gt;Rasterio library&lt;/li&gt;&lt;li&gt;...&lt;/li&gt;&lt;/ul&gt;" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;align=left;imageHeight=27;" vertex="1" parent="1">
+          <mxGeometry x="314" y="490" width="153" height="70" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

docs/concepts/images/entities_relations.svg

@@ -1,4 +1,58 @@
-# Library Overview
+# Library overview
+
+## API design principles
+
+SiaPy follows consistent method naming conventions to make the API intuitive and predictable. Understanding these conventions helps you navigate the library more effectively and write code that aligns with the project's style.
+
+**Simple properties**: Noun form for direct attribute access
+
+- Examples: `image.geometric_shapes`, `pixels.df`
+- When to use: For quick, computationally inexpensive property access
+
+**Expensive computations**: Prefixed with `get_` for methods that require significant processing
+
+- Examples: `pixels.get_coordinate()`
+- When to use: When the operation involves complex calculations or data retrieval
+
+**Alternative constructors**: Prefixed with `from_` for methods that create objects from different data sources
+
+- Examples: `from_numpy()`, `from_dataframe()`, `from_shapefile()`
+- When to use: When creating an object from an existing data structure
+
+**Data converters**: Prefixed with `to_` for methods that transform data to another format
+
+- Examples: `to_numpy()`, `to_dataframe()`, `to_geojson()`
+- When to use: When exporting data to another representation
+
+**File operations**:
+
+Prefixed with `open_` for reading data from file
+
+- Examples: `open_envi()`, `open_shapefile()`, `open_csv()`
+
+Prefixed with `save_` for writing data to file
+
+- Examples: `save_to_csv()`, `save_to_geotiff()`, `save_as_json()`
+
+**Actions and processing**:
+
+Verbs for operations that modify data or perform calculations
+
+- Examples: `normalize()`, `calculate_ndvi()`, `extract_features()`
+
+Plural forms for batch operations on multiple items
+
+- Examples: `process_images()`, `extract_signatures()`, `calculate_indices()`
+
+**Boolean queries**: Prefixed with `is_`, `has_`, or `can_` for methods returning boolean values
+
+- Examples: `is_valid()`, `has_metadata()`, `can_transform()`
+- When to use: For methods that check conditions or properties
+
+**Factory methods**: Prefixed with `create_` for methods that generate new instances
+
+- Examples: `create_mask()`, `create_subset()`, `create_transformer()`
+- When to use: When creating new objects based on specific parameters
 
 ## Architecture
 

docs/concepts/images/entities_schematics.drawio

@@ -0,0 +1,26 @@
+import numpy as np
+from rich import print
+
+from siapy.entities import Pixels, SpectralImage
+
+# Create mock image
+rng = np.random.default_rng(seed=42)
+array = rng.random((100, 100, 10))  # height, width, bands
+image = SpectralImage.from_numpy(array)
+
+# Define pixels
+iterable = [(1, 2), (3, 4), (2, 4)]
+pixels = Pixels.from_iterable(iterable)
+
+# Get signatures
+signatures = image.to_signatures(pixels)
+print(f"Signatures:\n{signatures}")
+
+# Get numpy array
+subarray = image.to_subarray(pixels)
+print(f"Subarray:\n{subarray}")
+"""
+? Note:
+    The extracted block has shape (3, 3, 10): a 3 × 3 pixel window across 10 spectral bands.
+    Values are populated only at the requested pixel coordinates; all other elements are set to NaN.
+"""

docs/concepts/overview.md

@@ -147,6 +147,6 @@ keep-runtime-typing = true
 
 [tool.codespell]
 ignore-words-list = "janezlapajne"
-skip = 'dist/*, ./docs/images/*, htmlcov, LICENCE, *.lock, *.toml, CHANGELOG.md, *.cff'
+skip = 'dist/*, htmlcov, LICENCE, *.lock, *.toml, CHANGELOG.md, *.cff, *.svg'
 count = true
 check-hidden = false