sdimg 0.2.0__tar.gz

sdimg-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kn
+
+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.

sdimg-0.2.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: sdimg
+Version: 0.2.0
+Summary: Small, function-based image and mask processing library built on numpy
+Author: kn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kn/sdimg
+Project-URL: Repository, https://github.com/kn/sdimg
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: opencv-python-headless
+Requires-Dist: concave-hull
+Dynamic: license-file
+
+# sdimg
+
+Small, function-based image and mask processing library built on `numpy.ndarray`.
+
+## Install
+
+```bash
+pip install sdimg
+```
+
+## Modules
+
+- `sdimg.image`: normalize, blur, denoise, sharpen, color helpers
+- `sdimg.mask`: binary mask cleanup, hull/edge/distance, bbox/ROI helpers
+- `sdimg.spatial`: resize, crop, rotate/flip, pad, split/merge patches
+- `sdimg.fusion`: `otsu_threshold` (OpenCV Otsu), `grabcut`
+
+## Core Contracts
+
+- Input arrays must be `numpy.ndarray`
+- Images: shape `(H, W)` or `(H, W, C)` with `C in 1..4`
+- Masks: shape `(H, W)`, binary values (`bool`, `{0,1}`, `{0,255}`)
+- Output images are `np.uint8`
+- Output masks are binary `np.uint8` in `{0, 1}`
+- BBox format: `(wmin, hmin, wmax, hmax)`
+- Empty-mask returns `None` for:
+  - `to_roi_box`
+  - `get_box_from_mask`
+  - `get_box_from_coords`
+  - `get_centroid`
+
+## Error Policy
+
+- `TypeError`: wrong input type (non-`numpy.ndarray`)
+- `ValueError`: invalid shape, invalid params, invalid mask values, invalid bbox
+- `RuntimeError`: wrapped lower-level failures (`cv2`, internal processing)
+
+## Internal Structure
+
+- `sdimg/_core/validate.py`: shared validators (`ensure_src`, `ensure_image`, `ensure_mask`, `ensure_bbox`)
+- `sdimg/_core/types.py`: shared type aliases
+- `sdimg/_core/errors.py`: shared error helpers
+
+## Quick Example
+
+```python
+import numpy as np
+from sdimg.image import hist_norm, gaussian_blur
+from sdimg.mask import morphology, to_roi_box
+from sdimg.fusion import grabcut
+
+image = np.random.randint(0, 256, (128, 128, 3), dtype=np.uint8)
+mask = np.zeros((128, 128), dtype=np.uint8)
+mask[32:96, 40:88] = 1
+
+image = hist_norm(image)
+image = gaussian_blur(image, (5, 5), 1.2)
+mask = morphology(mask, "open", (3, 3), 1)
+
+roi_box = to_roi_box(mask)
+if roi_box is not None:
+    refined = grabcut(image=image, roi=roi_box["roi"], box=roi_box["box"])
+```
+
+## Local Test
+
+```bash
+PYTHONPATH=. pytest -q
+```

sdimg-0.2.0/README.md

@@ -0,0 +1,69 @@
+# sdimg
+
+Small, function-based image and mask processing library built on `numpy.ndarray`.
+
+## Install
+
+```bash
+pip install sdimg
+```
+
+## Modules
+
+- `sdimg.image`: normalize, blur, denoise, sharpen, color helpers
+- `sdimg.mask`: binary mask cleanup, hull/edge/distance, bbox/ROI helpers
+- `sdimg.spatial`: resize, crop, rotate/flip, pad, split/merge patches
+- `sdimg.fusion`: `otsu_threshold` (OpenCV Otsu), `grabcut`
+
+## Core Contracts
+
+- Input arrays must be `numpy.ndarray`
+- Images: shape `(H, W)` or `(H, W, C)` with `C in 1..4`
+- Masks: shape `(H, W)`, binary values (`bool`, `{0,1}`, `{0,255}`)
+- Output images are `np.uint8`
+- Output masks are binary `np.uint8` in `{0, 1}`
+- BBox format: `(wmin, hmin, wmax, hmax)`
+- Empty-mask returns `None` for:
+  - `to_roi_box`
+  - `get_box_from_mask`
+  - `get_box_from_coords`
+  - `get_centroid`
+
+## Error Policy
+
+- `TypeError`: wrong input type (non-`numpy.ndarray`)
+- `ValueError`: invalid shape, invalid params, invalid mask values, invalid bbox
+- `RuntimeError`: wrapped lower-level failures (`cv2`, internal processing)
+
+## Internal Structure
+
+- `sdimg/_core/validate.py`: shared validators (`ensure_src`, `ensure_image`, `ensure_mask`, `ensure_bbox`)
+- `sdimg/_core/types.py`: shared type aliases
+- `sdimg/_core/errors.py`: shared error helpers
+
+## Quick Example
+
+```python
+import numpy as np
+from sdimg.image import hist_norm, gaussian_blur
+from sdimg.mask import morphology, to_roi_box
+from sdimg.fusion import grabcut
+
+image = np.random.randint(0, 256, (128, 128, 3), dtype=np.uint8)
+mask = np.zeros((128, 128), dtype=np.uint8)
+mask[32:96, 40:88] = 1
+
+image = hist_norm(image)
+image = gaussian_blur(image, (5, 5), 1.2)
+mask = morphology(mask, "open", (3, 3), 1)
+
+roi_box = to_roi_box(mask)
+if roi_box is not None:
+    refined = grabcut(image=image, roi=roi_box["roi"], box=roi_box["box"])
+```
+
+## Local Test
+
+```bash
+PYTHONPATH=. pytest -q
+```

sdimg-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sdimg"
+version = "0.2.0"
+description = "Small, function-based image and mask processing library built on numpy"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    { name = "kn" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+    "numpy",
+    "opencv-python-headless",
+    "concave-hull",
+]
+
+[project.urls]
+Homepage = "https://github.com/kn/sdimg"
+Repository = "https://github.com/kn/sdimg"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sdimg*"]
+
+[tool.pytest.ini_options]
+markers = []

sdimg-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sdimg-0.2.0/src/sdimg/_core/__init__.py

@@ -0,0 +1,9 @@
+from .errors import type_error, value_error
+from .types import BBox
+from .validate import (
+    ensure_bbox,
+    ensure_image,
+    ensure_mask,
+    ensure_ndarray,
+    ensure_src,
+)

sdimg-0.2.0/src/sdimg/_core/errors.py

@@ -0,0 +1,6 @@
+def type_error(name: str, expected: str) -> TypeError:
+    return TypeError(f"{name} must be {expected}.")
+
+
+def value_error(message: str) -> ValueError:
+    return ValueError(message)

sdimg-0.2.0/src/sdimg/_core/types.py

@@ -0,0 +1,3 @@
+from typing import TypeAlias
+
+BBox: TypeAlias = tuple[int, int, int, int]

sdimg-0.2.0/src/sdimg/_core/validate.py

@@ -0,0 +1,46 @@
+import numpy as np
+
+from .errors import type_error, value_error
+from .types import BBox
+
+
+def ensure_ndarray(value: object, name: str = "value") -> np.ndarray:
+    if not isinstance(value, np.ndarray):
+        raise type_error(name=name, expected="a numpy.ndarray")
+    return value
+
+
+def ensure_src(src: object, name: str = "src") -> np.ndarray:
+    arr = ensure_ndarray(src, name=name)
+    if arr.ndim not in {2, 3}:
+        raise value_error(f"{name} must have shape (H, W) or (H, W, C).")
+    return arr
+
+
+def ensure_image(image: object, name: str = "image") -> np.ndarray:
+    arr = ensure_src(image, name=name)
+    if arr.ndim == 2:
+        return arr
+    channels = arr.shape[2]
+    if channels not in {1, 2, 3, 4}:
+        raise value_error(f"{name} must have shape (H, W) or (H, W, C) with C in 1..4.")
+    return arr
+
+
+def ensure_mask(mask: object, name: str = "mask") -> np.ndarray:
+    arr = ensure_ndarray(mask, name=name)
+    if arr.ndim != 2:
+        raise value_error(f"{name} must have shape (H, W).")
+    return arr
+
+
+def ensure_bbox(
+    bbox: BBox,
+    shape: tuple[int, int],
+    name: str = "bbox",
+) -> BBox:
+    wmin, hmin, wmax, hmax = bbox
+    h, w = shape
+    if wmin < 0 or hmin < 0 or wmax > w or hmax > h or wmin >= wmax or hmin >= hmax:
+        raise value_error(f"{name} is out of bounds or invalid.")
+    return bbox

sdimg-0.2.0/src/sdimg/fusion/__init__.py

@@ -0,0 +1,2 @@
+from .grabcut import grabcut
+from .otsu import otsu_threshold

sdimg-0.2.0/src/sdimg/fusion/grabcut.py

@@ -0,0 +1,158 @@
+import cv2
+import numpy as np
+
+from .._core.validate import ensure_image
+from ..image.helper import to_gray
+from ..spatial.crop import crop
+from ..mask.helper import get_roi_size, to_mask
+
+
+def _get_k(shape: tuple[int, int]) -> int:
+    h, w = shape
+    k = int(round(min(h, w) / 5.0))
+    k = max(3, k)
+    return k if k % 2 == 1 else k + 1
+
+
+def _blur_mask(mask: np.ndarray) -> np.ndarray:
+    k = _get_k(shape=mask.shape[:2])
+    blur = cv2.GaussianBlur(
+        src=mask.astype(np.float32),
+        ksize=(k, k),
+        sigmaX=0.0,
+        sigmaY=0.0,
+    )
+    return np.rint(np.clip(blur * 255.0, 0.0, 255.0)).astype(np.uint8)
+
+
+def _edge(gray: np.ndarray) -> np.ndarray:
+    median = cv2.medianBlur(src=gray, ksize=3)
+    grad = cv2.morphologyEx(
+        src=median,
+        op=cv2.MORPH_GRADIENT,
+        kernel=np.ones((3, 3), dtype=np.uint8),
+    )
+    return cv2.normalize(
+        src=grad,
+        dst=None,
+        alpha=0,
+        beta=255,
+        norm_type=cv2.NORM_MINMAX,
+        dtype=cv2.CV_8U,
+    )
+
+
+def _build_img(image: np.ndarray, roi: np.ndarray) -> np.ndarray:
+    gray = to_gray(image)
+    edge_map = _edge(gray=gray)
+    blur = _blur_mask(mask=roi)
+    return np.stack([gray, edge_map, blur], axis=2)
+
+
+def _build_mask(roi: np.ndarray) -> np.ndarray:
+    din = cv2.distanceTransform(roi, cv2.DIST_L2, 3, dstType=cv2.CV_32F)
+    dout = cv2.distanceTransform(1 - roi, cv2.DIST_L2, 3, dstType=cv2.CV_32F)
+
+    max_in = float(din.max())
+    max_out = float(dout.max())
+
+    th = min(max_in, max_out) / 5.0
+
+    if th <= 0:
+        mask = np.full(roi.shape, cv2.GC_PR_BGD, dtype=np.uint8)
+        mask[roi == 1] = cv2.GC_PR_FGD
+        return mask
+
+    mask = np.full(roi.shape, cv2.GC_BGD, dtype=np.uint8)
+    mask[(roi == 0) & (dout < th)] = cv2.GC_PR_BGD
+    mask[(roi == 1) & (din < th)] = cv2.GC_PR_FGD
+    mask[din >= th] = cv2.GC_FGD
+
+    return mask
+
+
+def grabcut(
+    image: np.ndarray,
+    roi: np.ndarray,
+    box: tuple[int, int, int, int],
+    iter_count: int = 5,
+    margin: int = 20,
+    tol: float = 0.5,
+) -> np.ndarray:
+    """Refine a binary ROI mask using GrabCut.
+
+    Args:
+        image: Source image (H, W, C).
+        roi: Binary mask cropped to the bounding box region.
+        box: Bounding box as (wmin, hmin, wmax, hmax).
+        iter_count: Number of GrabCut iterations.
+        margin: Pixel margin added around the ROI for context.
+        tol: Maximum allowed relative change in mask area.
+            If abs(new - old) / old > tol, the original roi is returned.
+    """
+    if iter_count <= 0:
+        raise ValueError("iter_count must be greater than 0.")
+    if margin <= 0:
+        raise ValueError("margin must be greater than 0.")
+    if tol < 0:
+        raise ValueError("tol must be greater than or equal to 0.")
+
+    image = ensure_image(image, name="image")
+    roi = to_mask(roi)
+
+    orig_area = float(get_roi_size(roi))
+    if orig_area == 0:
+        return roi
+
+    image = crop(src=image, bbox=box)
+
+    if image.shape[:2] != roi.shape[:2]:
+        raise ValueError(
+            f"Cropped image shape {image.shape[:2]} does not match "
+            f"roi shape {roi.shape[:2]}."
+        )
+
+    try:
+        image = cv2.copyMakeBorder(
+            src=image,
+            top=margin,
+            bottom=margin,
+            left=margin,
+            right=margin,
+            borderType=cv2.BORDER_REFLECT,
+        )
+        roi = cv2.copyMakeBorder(
+            src=roi,
+            top=margin,
+            bottom=margin,
+            left=margin,
+            right=margin,
+            borderType=cv2.BORDER_CONSTANT,
+            value=0,
+        )
+
+        feat = _build_img(image=image, roi=roi)
+        gc_mask = _build_mask(roi=roi)
+
+        bgd = np.zeros((1, 65), dtype=np.float64)
+        fgd = np.zeros((1, 65), dtype=np.float64)
+        cv2.grabCut(
+            img=feat,
+            mask=gc_mask,
+            rect=None,
+            bgdModel=bgd,
+            fgdModel=fgd,
+            iterCount=iter_count,
+            mode=cv2.GC_INIT_WITH_MASK,
+        )
+    except Exception as exc:
+        raise RuntimeError(f"grabcut failed: {exc}") from exc
+
+    out = np.isin(gc_mask, (cv2.GC_FGD, cv2.GC_PR_FGD)).astype(np.uint8)
+    out_final = out[margin:-margin, margin:-margin]
+
+    new_area = float(get_roi_size(out_final))
+    if abs(new_area - orig_area) / orig_area > tol:
+        return roi[margin:-margin, margin:-margin]
+
+    return out_final

sdimg-0.2.0/src/sdimg/fusion/otsu.py

@@ -0,0 +1,34 @@
+import cv2
+import numpy as np
+
+from .._core.validate import ensure_image
+from ..image.helper import to_gray
+
+
+def otsu_threshold(
+    image: np.ndarray,
+    scale: float = 1.0,
+) -> np.ndarray:
+    """Binarize an image using Otsu's threshold.
+
+    Args:
+        scale: Multiplier for the computed threshold. scale=0 makes all
+            nonzero pixels foreground; scale=1 uses the raw Otsu threshold.
+    """
+    if scale < 0:
+        raise ValueError("scale must be greater than or equal to 0.")
+
+    image = ensure_image(image, name="image")
+    gray = to_gray(image)
+    try:
+        threshold, _ = cv2.threshold(
+            gray,
+            0,
+            255,
+            cv2.THRESH_BINARY + cv2.THRESH_OTSU,
+        )
+    except Exception as exc:
+        raise RuntimeError(f"otsu_threshold failed: {exc}") from exc
+
+    adjusted_threshold = float(threshold) * scale
+    return (gray > adjusted_threshold).astype(np.uint8)

sdimg-0.2.0/src/sdimg/image/__init__.py

@@ -0,0 +1,6 @@
+from .bc import adjust_brightness_contrast
+from .blur import gaussian_blur, median_blur
+from .denoise import denoise
+from .helper import is_image, to_gray, to_rgb, to_uint8
+from .norm import clahe_norm, hist_norm, minmax_norm, zscore_norm
+from .sharpen import sharpen

sdimg-0.2.0/src/sdimg/image/bc.py

@@ -0,0 +1,28 @@
+import numpy as np
+
+from .._core.validate import ensure_image
+from .helper import to_uint8
+
+
+def adjust_brightness_contrast(
+    image: np.ndarray,
+    brightness: float = 0.0,
+    contrast: float = 0.0,
+) -> np.ndarray:
+    image = ensure_image(image, name="image")
+
+    brightness_val = np.clip(brightness, -1.0, 1.0)
+    contrast_val = np.clip(contrast, -1.0, 1.0)
+
+    adjusted = image.astype(np.float32)
+
+    if brightness_val != 0.0:
+        adjusted += brightness_val * 255.0
+
+    factor = 1.0 + contrast_val
+    if factor != 1.0:
+        adjusted -= 128.0
+        adjusted *= factor
+        adjusted += 128.0
+
+    return to_uint8(adjusted)

sdimg-0.2.0/src/sdimg/image/blur.py

@@ -0,0 +1,31 @@
+import cv2
+import numpy as np
+
+from .._core.validate import ensure_image
+
+
+def gaussian_blur(
+    image: np.ndarray,
+    ksize: tuple[int, int],
+    sigmaX: float,
+    sigmaY: float = 0.0,
+    borderType: int = cv2.BORDER_DEFAULT,
+) -> np.ndarray:
+    image = ensure_image(image, name="image")
+
+    return cv2.GaussianBlur(
+        image,
+        ksize,
+        sigmaX,
+        sigmaY=sigmaY,
+        borderType=borderType,
+    )
+
+
+def median_blur(
+    image: np.ndarray,
+    ksize: int,
+) -> np.ndarray:
+    image = ensure_image(image, name="image")
+
+    return cv2.medianBlur(image, ksize)

sdimg-0.2.0/src/sdimg/image/denoise.py

@@ -0,0 +1,34 @@
+import cv2
+import numpy as np
+
+from .._core.validate import ensure_image
+from .helper import to_gray
+
+
+def denoise(
+    image: np.ndarray,
+    h: float = 3.0,
+    hColor: float = 3.0,
+    templateWindowSize: int = 7,
+    searchWindowSize: int = 21,
+) -> np.ndarray:
+    image = ensure_image(image, name="image")
+
+    if image.ndim == 3 and image.shape[2] == 3:
+        return cv2.fastNlMeansDenoisingColored(
+            image,
+            h=h,
+            hColor=hColor,
+            templateWindowSize=templateWindowSize,
+            searchWindowSize=searchWindowSize,
+        )
+
+    if image.ndim == 3:
+        image = to_gray(image)
+
+    return cv2.fastNlMeansDenoising(
+        image,
+        h=h,
+        templateWindowSize=templateWindowSize,
+        searchWindowSize=searchWindowSize,
+    )

sdimg-0.2.0/src/sdimg/image/helper.py

@@ -0,0 +1,58 @@
+import numpy as np
+
+from .._core.validate import ensure_image, ensure_ndarray
+
+
+def is_image(image: object) -> bool:
+    try:
+        ensure_image(image, name="image")
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def to_rgb(image: np.ndarray) -> np.ndarray:
+    image = ensure_image(image, name="image")
+
+    if image.ndim == 2:
+        rgb = np.repeat(image[..., None], 3, axis=2)
+        return to_uint8(rgb)
+
+    channels = image.shape[2]
+    if channels <= 2:
+        rgb = np.repeat(image[..., 0:1], 3, axis=2)
+    elif channels == 3:
+        rgb = image
+    else:
+        rgb = image[..., :3]
+    return to_uint8(rgb)
+
+
+def to_gray(image: np.ndarray) -> np.ndarray:
+    image = ensure_image(image, name="image")
+
+    if image.ndim == 2:
+        return to_uint8(image)
+
+    channels = image.shape[2]
+    if channels <= 2:
+        gray = image[..., 0]
+    else:
+        gray = image[..., 0] * np.float32(0.299)
+        gray += image[..., 1] * np.float32(0.587)
+        gray += image[..., 2] * np.float32(0.114)
+
+    return to_uint8(gray)
+
+
+def to_uint8(image: np.ndarray) -> np.ndarray:
+    image = ensure_ndarray(image, name="image")
+
+    if image.dtype == np.uint8:
+        return image
+
+    if np.issubdtype(image.dtype, np.floating):
+        clipped = np.clip(image, 0.0, 255.0)
+        return np.rint(clipped).astype(np.uint8)
+
+    return np.clip(image, 0, 255).astype(np.uint8)