zsplit 1.0.0__py3-none-any.whl

zsplit/__init__.py

@@ -0,0 +1,25 @@
+"""
+zsplit — Z-Split Normalization (Zero-Preserving Split Normalization)
+=====================================================================
+
+A normalization technique for bipolar spectral indices where zero
+carries physical meaning as a class boundary.
+
+    >>> import numpy as np
+    >>> from zsplit import normalize
+    >>> arr = np.array([-0.0004, -0.0002, 0.0, 0.0001, 0.00015])
+    >>> normalize(arr)
+    array([-1.  , -0.5 ,  0.  ,  0.667,  1.  ])
+
+Author : Abdulrhman Almoadi (KACST)
+DOI    : https://doi.org/10.5194/egusphere-2026-672
+"""
+
+from .core import normalize, normalize_raster
+
+__version__ = "1.0.0"
+__author__  = "Abdulrhman Almoadi"
+__email__   = "aalmoadi@kacst.edu.sa"
+__doi__     = "https://doi.org/10.5194/egusphere-2026-672"
+
+__all__ = ["normalize", "normalize_raster"]

zsplit/core.py

@@ -0,0 +1,118 @@
+"""
+Z-Split Normalization (Zero-Preserving Split Normalization)
+===========================================================
+
+A normalization technique for bipolar indices where zero carries
+physical meaning as a class boundary (e.g., water vs. non-water).
+
+Author : Abdulrhman Almoadi
+Affil. : King Abdulaziz City for Science and Technology (KACST)
+DOI    : https://doi.org/10.5194/egusphere-2026-672
+"""
+
+import numpy as np
+
+
+def normalize(array, nodata=None):
+    """
+    Apply Z-Split (Zero-Preserving Split Normalization) to a NumPy array.
+
+    Positive values are normalized to [0, 1] by dividing by max(positive values).
+    Negative values are normalized to [-1, 0] by dividing by abs(min(negative values)).
+    Zero values remain exactly zero.
+
+    Parameters
+    ----------
+    array : array-like
+        Input array (1D, 2D, or nD). Typically a spectral index raster.
+    nodata : float or None
+        NoData value to exclude. These pixels are returned as NaN.
+
+    Returns
+    -------
+    result : np.ndarray
+        Normalized array in range [-1, 1] with zero strictly preserved.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from zsplit import normalize
+    >>> arr = np.array([-0.0004, -0.0002, 0.0, 0.0001, 0.00015])
+    >>> normalize(arr)
+    array([-1.  , -0.5 ,  0.  ,  0.667,  1.  ])
+    """
+    arr = np.asarray(array, dtype=np.float64).copy()
+
+    if nodata is not None:
+        arr[arr == nodata] = np.nan
+
+    result = np.zeros_like(arr)
+
+    # Positive half: normalize to [0, 1]
+    pos_mask = arr > 0
+    if pos_mask.any():
+        max_pos = np.nanmax(arr[pos_mask])
+        if max_pos != 0:
+            result[pos_mask] = arr[pos_mask] / max_pos
+
+    # Negative half: normalize to [-1, 0]
+    neg_mask = arr < 0
+    if neg_mask.any():
+        min_neg = np.nanmin(arr[neg_mask])
+        if min_neg != 0:
+            result[neg_mask] = arr[neg_mask] / abs(min_neg)
+
+    # Restore NaN
+    result[np.isnan(arr)] = np.nan
+
+    return result
+
+
+def normalize_raster(input_path, output_path, nodata=None):
+    """
+    Apply Z-Split normalization to a GeoTIFF raster file.
+
+    Requires rasterio. Reads the raster, applies normalize(),
+    and saves the result as a new GeoTIFF.
+
+    Parameters
+    ----------
+    input_path : str
+        Path to input raster (e.g., raw ENDWI .tif).
+    output_path : str
+        Path where normalized raster will be saved.
+    nodata : float or None
+        NoData value. If None, reads from raster metadata.
+
+    Returns
+    -------
+    output_path : str
+        Path to the saved output raster.
+
+    Examples
+    --------
+    >>> from zsplit import normalize_raster
+    >>> normalize_raster('ENDWI_raw.tif', 'ENDWI_zsplit.tif')
+    """
+    try:
+        import rasterio
+    except ImportError:
+        raise ImportError(
+            "rasterio is required for normalize_raster(). "
+            "Install it with: pip install rasterio"
+        )
+
+    with rasterio.open(input_path) as src:
+        raw = src.read(1).astype(np.float64)
+        profile = src.profile
+        if nodata is None:
+            nodata = src.nodata
+
+    result = normalize(raw, nodata=nodata)
+
+    profile.update(dtype=rasterio.float32, nodata=float('nan'))
+
+    with rasterio.open(output_path, 'w', **profile) as dst:
+        dst.write(result.astype(np.float32), 1)
+
+    return output_path

zsplit-1.0.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: zsplit
+Version: 1.0.0
+Summary: Z-Split Normalization: Zero-Preserving Split Normalization for bipolar spectral indices
+Author-email: Abdulrhman Almoadi <aalmoadi@kacst.edu.sa>
+License: MIT License
+        
+        Copyright (c) 2026 Abdulrhman Almoadi
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/aalmoadi/endwi
+Project-URL: Repository, https://github.com/aalmoadi/endwi
+Project-URL: Documentation, https://github.com/aalmoadi/endwi/tree/main/Z-Split_Normalization
+Project-URL: Bug Tracker, https://github.com/aalmoadi/endwi/issues
+Project-URL: DOI, https://doi.org/10.5281/zenodo.20602710
+Project-URL: Paper, https://doi.org/10.5194/egusphere-2026-672
+Keywords: normalization,remote-sensing,flood-detection,spectral-index,ENDWI,NDWI,bipolar,zero-preserving,Otsu,GIS,GeoAI,machine-learning,deep-learning,SAR,Sentinel-2
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: raster
+Requires-Dist: rasterio>=1.2; extra == "raster"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: rasterio>=1.2; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Dynamic: license-file
+
+# zsplit — Zero-Preserving Split Normalization
+
+[![PyPI version](https://badge.fury.io/py/zsplit.svg)](https://pypi.org/project/zsplit/)
+[![DOI](https://zenodo.org/badge/1037018439.svg)](https://doi.org/10.5281/zenodo.20602709)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A normalization technique for **bipolar spectral indices** where **zero carries physical meaning as a class boundary** (e.g., water vs. non-water in flood detection).
+
+## Installation
+
+```bash
+pip install zsplit
+```
+
+With raster support:
+
+```bash
+pip install zsplit[raster]
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from zsplit import normalize
+
+# Simulated raw ENDWI values (DN scale — extremely narrow range)
+arr = np.array([-0.00041, -0.00020, 0.0, 0.00008, 0.00015])
+
+result = normalize(arr)
+print(result)
+# [-1.     -0.488   0.      0.533   1.   ]
+```
+
+## Raster Support
+
+```python
+from zsplit import normalize_raster
+
+normalize_raster('ENDWI_raw.tif', 'ENDWI_zsplit.tif')
+```
+
+## Formula
+
+```
+         ⎧  x / max(X⁺)    if x > 0   →  [0,  1]
+Z(x)  =  ⎨  0               if x = 0   →  0 (preserved)
+         ⎩  x / |min(X⁻)|  if x < 0   →  [-1, 0]
+```
+
+## Why Z-Split?
+
+| Property | Min-Max | Z-Score | **Z-Split** |
+|---|---|---|---|
+| Preserves zero as class boundary | ❌ | ❌ | ✅ |
+| Stable on narrow near-zero ranges | ❌ | ⚠️ | ✅ |
+| Suitable for Otsu thresholding | ❌ | ⚠️ | ✅ |
+| Handles skewed distributions | ❌ | ⚠️ | ✅ |
+| Multi-temporal direction preserved | ❌ | ❌ | ✅ |
+| Output range | [0, 1] | Unbounded | **[−1, 1]** |
+
+## Citation
+
+```bibtex
+@article{almoadi2026endwi,
+  author  = {Almoadi, Abdulrhman},
+  title   = {Reducing False Alarms in Urban Flood Detection: An Enhanced NDWI (ENDWI)
+             with Hybrid Max Fusion on Sentinel-2 Data},
+  journal = {EGUsphere [preprint]},
+  year    = {2026},
+  doi     = {10.5194/egusphere-2026-672}
+}
+```
+
+## License
+
+MIT License

zsplit-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+zsplit/__init__.py,sha256=xFTDpE6xhEBPBlBkU4r9hKhynbgDynBaZtw77Txr5Wk,799
+zsplit/core.py,sha256=48Sz6taLAlYE73H4URBJdOXb2LxKahQPR93cmmtdkH8,3333
+zsplit-1.0.0.dist-info/licenses/LICENSE,sha256=_8N29XRi8p8QyvL5JPM0QN1Ctx_7NZvaFLfNlPdfY6M,1075
+zsplit-1.0.0.dist-info/METADATA,sha256=ZwU6XdIn3K9gkHatRoHPkCazVAv5Taw41iZjde_30nw,5148
+zsplit-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+zsplit-1.0.0.dist-info/top_level.txt,sha256=BWiFE55QJQvX2OttKLw8bwoE563ydr-BVu5KM8vPs04,7
+zsplit-1.0.0.dist-info/RECORD,,

zsplit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zsplit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdulrhman Almoadi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zsplit-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zsplit