FEZtool-team · aradfarahani · Aug 21, 2026 · Aug 20, 2026
diff --git a/README.md b/README.md
@@ -1,112 +1,121 @@
-# **FEZrs**     
-
-[![DOI](https://zenodo.org/badge/710286874.svg)](https://doi.org/10.5281/zenodo.14938038) [![Tests](https://github.com/FEZtool-team/FEZrs/actions/workflows/FEZrs_Tests.yml/badge.svg?branch=main)](https://github.com/FEZtool-team/FEZrs/actions/workflows/FEZrs_Tests.yml) [![Documentation](https://img.shields.io/website?url=https%3A%2F%2Ffeztool-team.github.io%2FFEZdocs%2Flibraries%2Ffezrs%2F&label=docs)](https://feztool-team.github.io/FEZdocs/libraries/fezrs/) [![Downloads/month](https://static.pepy.tech/badge/fezrs/month)](https://pepy.tech/project/fezrs) [![PyPI version](https://img.shields.io/pypi/v/fezrs.svg)](https://pypi.org/project/fezrs/)
-[![Conda Version](https://img.shields.io/conda/vn/FEZtool/fezrs?label=Anaconda&color=orange&logo=anaconda)](https://anaconda.org/FEZtool/fezrs) ![License](https://img.shields.io/pypi/l/FEZrs) [![PyPI Downloads](https://static.pepy.tech/badge/fezrs)](https://pepy.tech/projects/fezrs) ![GitHub last commit](https://img.shields.io/github/last-commit/FEZtool-team/fezrs) [![Platform](https://img.shields.io/conda/pn/feztool/fezrs?color=blue&label=Platform&style=flat)](https://anaconda.org/feztool/fezrs) ![GitHub stars](https://img.shields.io/github/stars/FEZtool-team/FEZrs?style=social)
-
-**FEZrs** is an advanced Python library developed by [**FEZtool**](https://feztool.com/) for Remote Sensing applications. It provides a set of powerful tools for image processing, feature extraction, and analysis of geospatial data.
-
-## **Features**
-
-✅ Apply various image filtering techniques (Gaussian, Laplacian, Sobel, Median, Mean)  
-✅ Contrast enhancement and edge detection  
-✅ Support for geospatial raster data (TIFF)  
-✅ Designed for remote sensing and satellite imagery analysis  
-✅ Easy integration with FastAPI for web-based processing
-
-## Documentation
-
-Full documentation, API references, tutorials, and examples are available here:
-https://feztool-team.github.io/FEZdocs/libraries/fezrs/
-
-## **📦 Installation**
-
-You can install **FEZrs** using your preferred Python package manager:
-
-### Using `pip` (PyPI)
-
-```bash
-pip install fezrs
-```
-
-### Using `conda` (Anaconda)
-
-```bash
-conda install -c FEZtool fezrs
-```
-
-### Using `mamba` (optional, faster conda alternative)
-
-```bash
-mamba install FEZtool::fezrs
-```
-
-> **Note:** The `mamba` command requires [Mamba](https://github.com/mamba-org/mamba) to be installed. If it's not installed, use the `conda` command instead.
-
-## **Usage**
-
-Example of applying a Gaussian filter to an image:
-
-```python
-from fezrs import EqualizeRGBCalculator
-
-equalize = EqualizeRGBCalculator(
-    blue_path="path/to/your/image_band.tif",
-    green_path="path/to/your/image_band.tif",
-    red_path="path/to/your/image_band.tif",
-)
-
-equalize.chart_export(output_path="./your/export/path")
-equalize.execute(output_path="./your/export/path")
-```
-
-## **Modules**
-
-- `KMeansCalculator`
-- `GaussianCalculator`
-- `LaplacianCalculator`
-- `MeanCalculator`
-- `MedianCalculator`
-- `SobelCalculator`
-- `GLCMCalculator`
-- `HSVCalculator`
-- `IRHSVCalculator`
-- `AdaptiveCalculator`
-- `AdaptiveRGBCalculator`
-- `EqualizeCalculator`
-- `EqualizeRGBCalculator`
-- `FloatCalculator`
-- `GammaCalculator`
-- `GammaRGBCalculator`
-- `LogAdjustCalculator`
-- `OriginalCalculator`
-- `OriginalRGBCalculator`
-- `SigmoidAdjustCalculator`
-- `PCACalculator`
-- `AFRICalculator`
-- `BICalculator`
-- `NDVICalculator`
-- `NDWICalculator`
-- `SAVICalculator`
-- `UICalculator`
-- `SpectralProfileCalculator`
-
-## **Contributing**
-
-We welcome contributions! To contribute:
-
-1. Fork the repository
-2. Create a new branch (`git checkout -b feature-name`)
-3. Commit your changes (`git commit -m "Add new feature"`)
-4. Push to your branch (`git push origin feature-name`)
-5. Open a Pull Request
-
-## **Acknowledgment**
-
-Special thanks to [**Chakad Cafe**](https://www.chakadcoffee.com/) for the coffee that kept us fueled during development! ☕
-
-## **License**
-
-This project is licensed under the [**Apache-2.0 license**.](https://github.com/FEZtool-team/FEZrs/edit/main/LICENSE)
-
-
-
+# **FEZrs**     
+
+[![DOI](https://zenodo.org/badge/710286874.svg)](https://doi.org/10.5281/zenodo.14938038) [![Tests](https://github.com/FEZtool-team/FEZrs/actions/workflows/FEZrs_Tests.yml/badge.svg?branch=main)](https://github.com/FEZtool-team/FEZrs/actions/workflows/FEZrs_Tests.yml) [![Documentation](https://img.shields.io/website?url=https%3A%2F%2Ffeztool-team.github.io%2FFEZdocs%2Flibraries%2Ffezrs%2F&label=docs)](https://feztool-team.github.io/FEZdocs/libraries/fezrs/) [![Downloads/month](https://static.pepy.tech/badge/fezrs/month)](https://pepy.tech/project/fezrs) [![PyPI version](https://img.shields.io/pypi/v/fezrs.svg)](https://pypi.org/project/fezrs/)
+[![Conda Version](https://img.shields.io/conda/vn/FEZtool/fezrs?label=Anaconda&color=orange&logo=anaconda)](https://anaconda.org/FEZtool/fezrs) ![License](https://img.shields.io/pypi/l/FEZrs) [![PyPI Downloads](https://static.pepy.tech/badge/fezrs)](https://pepy.tech/projects/fezrs) ![GitHub last commit](https://img.shields.io/github/last-commit/FEZtool-team/fezrs) [![Platform](https://img.shields.io/conda/pn/feztool/fezrs?color=blue&label=Platform&style=flat)](https://anaconda.org/feztool/fezrs) ![GitHub stars](https://img.shields.io/github/stars/FEZtool-team/FEZrs?style=social)
+
+**FEZrs** is an advanced Python library developed by [**FEZtool**](https://github.com/FEZtool-team) for Remote Sensing applications. It provides a set of powerful tools for image processing, feature extraction, and analysis of geospatial data.
+
+## **Features**
+
+✅ Apply various image filtering techniques (Gaussian, Laplacian, Sobel, Median, Mean)  
+✅ Contrast enhancement and edge detection  
+✅ Support for geospatial raster data (TIFF)  
+✅ Designed for remote sensing and satellite imagery analysis  
+✅ Easy integration with FastAPI for web-based processing
+
+## Documentation
+
+Full documentation, API references, tutorials, and examples are available here:
+https://feztool-team.github.io/FEZdocs/libraries/fezrs/
+
+## **📦 Installation**
+
+You can install **FEZrs** using your preferred Python package manager:
+
+### Using `pip` (PyPI)
+
+```bash
+pip install fezrs
+```
+
+### Using `conda` (Anaconda)
+
+```bash
+conda install -c FEZtool fezrs
+```
+
+### Using `mamba` (optional, faster conda alternative)
+
+```bash
+mamba install FEZtool::fezrs
+```
+
+> **Note:** The `mamba` command requires [Mamba](https://github.com/mamba-org/mamba) to be installed. If it's not installed, use the `conda` command instead.
+
+## **Usage**
+
+Example of applying a Gaussian filter to an image:
+
+```python
+from fezrs import EqualizeRGBCalculator
+
+equalize = EqualizeRGBCalculator(
+    blue_path="path/to/your/image_band.tif",
+    green_path="path/to/your/image_band.tif",
+    red_path="path/to/your/image_band.tif",
+)
+
+equalize.execute(output_path="./your/export/path")
+equalize.histogram_export(output_path="./your/export/path")
+```
+
+## **Modules**
+
+- `KMeansCalculator`
+- `GaussianCalculator`
+- `LaplacianCalculator`
+- `MeanCalculator`
+- `MedianCalculator`
+- `SobelCalculator`
+- `GLCMCalculator`
+- `HSVCalculator`
+- `IRHSVCalculator`
+- `AdaptiveCalculator`
+- `AdaptiveRGBCalculator`
+- `EqualizeCalculator`
+- `EqualizeRGBCalculator`
+- `FloatCalculator`
+- `GammaCalculator`
+- `GammaRGBCalculator`
+- `LogAdjustCalculator`
+- `OriginalCalculator`
+- `OriginalRGBCalculator`
+- `SigmoidAdjustCalculator`
+- `PCACalculator`
+- `AFRICalculator`
+- `BICalculator`
+- `NDVICalculator`
+- `NDWICalculator`
+- `SAVICalculator`
+- `UICalculator`
+- `SpectralProfileCalculator`
+- `MosaicCalculator`
+- `SVMCalculator`
+- `Landsat8Calculator`
+- `GeoeyeCalculator`
+- `BurnCalculator`
+- `IndicesCalculator`
+- `MagDirCalculator`
+- `SubDivCalculator`
+- `TimeCalculator`
+
+## **Contributing**
+
+We welcome contributions! To contribute:
+
+1. Fork the repository
+2. Create a new branch (`git checkout -b feature-name`)
+3. Commit your changes (`git commit -m "Add new feature"`)
+4. Push to your branch (`git push origin feature-name`)
+5. Open a Pull Request
+
+## **Acknowledgment**
+
+Special thanks to [**Chakad Cafe**](https://www.chakadcoffee.com/) for the coffee that kept us fueled during development! ☕
+
+## **License**
+
+This project is licensed under the [**Apache-2.0 license**.](https://github.com/FEZtool-team/FEZrs/edit/main/LICENSE)
+
+
+
diff --git a/docs/filters.md b/docs/filters.md
@@ -15,7 +15,7 @@ The `filters` module provides a comprehensive suite of digital image processing
             ▼                                   ▼
 [Linear Shift-Invariant Filters]     [Non-Linear Statistical Filters]
 ├─ MeanCalculator                    └─ MedianCalculator
-├─ GuassianCalculator
+├─ GaussianCalculator
 ├─ SobelCalculator
 └─ LaplacianCalculator
 ```
@@ -54,11 +54,11 @@ This approach minimizes edge artifacts and prevents artificial gradient boundari
 
 ## Comprehensive Class Specifications
 
-### GuassianCalculator` — Isotropic Low-Pass Smoothing
+### GaussianCalculator` — Isotropic Low-Pass Smoothing
 
 #### Scientific & Physical Objective
 
-The algorithmic goal of `GuassianCalculator` is to apply an isotropic low-pass filter to remove continuous high-frequency background noise (such as thermal electronic sensor noise or atmospheric scattering). This smoothing step helps maintain structural boundaries and edge locations more effectively than a standard unweighted box-average filter.
+The algorithmic goal of `GaussianCalculator` is to apply an isotropic low-pass filter to remove continuous high-frequency background noise (such as thermal electronic sensor noise or atmospheric scattering). This smoothing step helps maintain structural boundaries and edge locations more effectively than a standard unweighted box-average filter.
 
 #### Theoretical Foundation & Mathematical Formulations
 
@@ -102,10 +102,10 @@ In the frequency domain, the Fourier transform of a Gaussian kernel is itself a
 
 ```Python
 from pathlib import Path
-from fezrs.tools.filters import GuassianCalculator
+from fezrs.tools.filters import GaussianCalculator
 
 # Initialize low-pass isotropic Gaussian engine
-gaussian_blur = GuassianCalculator(
+gaussian_blur = GaussianCalculator(
     tif_path=Path("./data/Landsat8_Band5.tif")
 )
 

diff --git a/docs/image-enhancement.md b/docs/image-enhancement.md
@@ -10,7 +10,7 @@ The `enhancement` module delivers a comprehensive suite of linear and non-linear
                                           │
                                           ▼
                       ┌───────────────────────────────────────┐
-                      │    fezrs.tools.enhancement Module     │
+                      │    fezrs.tools.image_enhancement Module     │
                       └───────────────────┬───────────────────┘
                                           │
          ┌────────────────────────────────┴────────────────────────────────┐
@@ -96,7 +96,7 @@ $$I_{\text{eq}}(x, y) = \frac{1}{N} \sum_{j=1}^{\text{rank}(I(x, y))} \text{coun
 
 ```Python
 from pathlib import Path
-from fezrs.tools.enhancement import EqualizeCalculator
+from fezrs.tools.image_enhancement import EqualizeCalculator
 
 # Initialize global histogram equalization pipeline
 equalizer = EqualizeCalculator(nir_path=Path("./data/Hazy_NIR.tif"))
@@ -145,7 +145,7 @@ $$I_{\text{CLAHE}}(x, y) = \text{BilinearInterpolate}\left(T_{t_1}, T_{t_2}, T_{
 
 ```Python
 from pathlib import Path
-from fezrs.tools.enhancement import AdaptiveCalculator
+from fezrs.tools.image_enhancement import AdaptiveCalculator
 
 # Execute local adaptive contrast optimization via CLAHE
 clahe_engine = AdaptiveCalculator(
@@ -195,7 +195,7 @@ Where:
 
 ```Python
 from pathlib import Path
-from fezrs.tools.enhancement import GammaCalculator
+from fezrs.tools.image_enhancement import GammaCalculator
 
 # Initialize power-law gamma transformation engine
 gamma_corrector = GammaCalculator(

diff --git a/docs/pca.md b/docs/pca.md
@@ -127,7 +127,25 @@ These higher-order components capture progressively smaller variations in the da
 
     - `swir2_path` (`str` | `Path`): File path to the Short-Wave Infrared 2 band raster layer.
 
-    - `selectBand` (`Literal["red","green","blue","nir","swir1","swir2", None]`): Optional parameter. Selects a specific input band to map against the component outputs during specialized diagnostic profiling.
+    - `component` (`int | None`): Principal component to inspect, numbered $1 \dots 6$ in order of decreasing explained variance. Required by `histogram_export()`.
+
+    - `standardize` (`bool`, default `False`): Decompose the **correlation** matrix instead of the covariance matrix, by scaling each band to unit variance first. `sklearn` decomposes the covariance matrix, which lets whichever band carries the widest digital-number range dominate the leading components regardless of how much information it holds. Standardized PCA is the usual choice for multispectral work where band ranges differ substantially.
+
+    - `selectBand` (`Literal["red","green","blue","nir","swir1","swir2", None]`): **Deprecated.** A band name that resolves to a fixed component index, emitting a `DeprecationWarning` naming the component it maps to.
+
+    > **Why `selectBand` was replaced.** A principal component is a linear combination of *all six* input bands, weighted by the corresponding eigenvector, so **no component corresponds to an input band**. The parameter indexed into a fixed name-to-index map, meaning `selectBand="red"` plotted the **first principal component** and titled the figure "Histogram of PCA Band Red" — attributing the output to a band that did not produce it. A user selecting `"swir2"` to inspect the SWIR2 response was shown the fifth component. The mapping order was also arbitrary: it followed the insertion order of the band dictionary in `FileHandler.__init__`, which is why it read `red, nir, blue, swir1, swir2, green` rather than any order a user would expect.
+
+#### Eigen-structure Accessors
+
+Both raise `RuntimeError` before `process()` has run.
+
+- `explained_variance_ratio_` (`np.ndarray`, shape `(6,)`): Share of total variance per component, ordered decreasing. On the bundled Landsat subset PC1 carries 90.6%, PC2 7.3% and PC3 1.8% — the strong concentration typical of multispectral imagery, where PC1 largely captures scene brightness.
+
+- `components_` (`np.ndarray`, shape `(6, 6)` as `(component, band)`): Eigenvector loadings, with band order given by `band_order`.
+
+    **Loadings, not variance share, are what identify a useful component.** A target is isolated by the component in which the diagnostic bands carry high loadings of *opposing* sign, and that component is frequently not the one with the most variance — PC1 usually just encodes albedo.
+
+> **Component signs are fixed.** Eigenvector signs are mathematically arbitrary, so without a convention the same scene can yield an inverted component image between runs, or between a scene and a crop of it. FEZrs forces the largest-magnitude loading of each component positive, making repeated runs directly comparable.
 
 #### Processing Pipeline Lifecycle (`process()`)
 

diff --git a/docs/spectral-indices.md b/docs/spectral-indices.md
@@ -232,7 +232,7 @@ The following matrix cross-references the required sensor channels, target range
 
 ```Python
 from pathlib import Path
-from fezrs.tools.indices import NDVICalculator
+from fezrs.tools.spectral_indices import NDVICalculator
 
 # Instantiate the NDVI processing engine using Landsat 8 paths
 ndvi_engine = NDVICalculator(
@@ -253,7 +253,7 @@ ndvi_engine.execute(
 
 ```Python
 from pathlib import Path
-from fezrs.tools.indices import NDWICalculator
+from fezrs.tools.spectral_indices import NDWICalculator
 
 # Instantiate McFeeters NDWI calculator using Sentinel-2 paths
 ndwi_engine = NDWICalculator(

diff --git a/example/clustering.py b/example/clustering.py
@@ -1,5 +1,18 @@
+"""
+K-means clustering example.
+
+Paths resolve relative to this file, so the script runs from any directory.
+"""
+
+from pathlib import Path
+
 from fezrs import KMeansCalculator
 
-KMeansCalculator(nir_path="./data/nir.tif", n_clusters=4, random_state=0).execute(
-    output_path="./outputs/clustering",
+DATA = Path(__file__).parent / "data"
+OUTPUTS = Path(__file__).parent / "outputs"
+
+KMeansCalculator(
+    nir_path=DATA / "nir.tif", n_clusters=4, random_state=0
+).execute(
+    output_path=OUTPUTS / "clustering",
 )