processinator 0.1.0__tar.gz

processinator-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.3
+Name: processinator
+Version: 0.1.0
+Summary: Astronomy image processing library
+Author: Steven
+Author-email: Steven <erewhon@flatland.org>
+Requires-Dist: astropy>=7.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=11.0
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.9 ; extra == 'dev'
+Requires-Python: >=3.12
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# processinator
+
+Much photo. So process. Wow!
+
+This is mostly a library for processing astrophotographs automatically. It has some of its own algorithms, but it will also leverage other tools, including Siril and Seti Astro Pro.

processinator-0.1.0/README.md

@@ -0,0 +1,5 @@
+# processinator
+
+Much photo. So process. Wow!
+
+This is mostly a library for processing astrophotographs automatically. It has some of its own algorithms, but it will also leverage other tools, including Siril and Seti Astro Pro.

processinator-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "processinator"
+version = "0.1.0"
+description = "Astronomy image processing library"
+readme = "README.md"
+authors = [
+    { name = "Steven", email = "erewhon@flatland.org" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "astropy>=7.0",
+    "numpy>=1.26",
+    "pillow>=11.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

processinator-0.1.0/src/processinator/__init__.py

@@ -0,0 +1,10 @@
+"""Processinator - astronomy image processing library."""
+
+from processinator.stretching import StretchAlgorithm, fits_to_image, read_fits, stretch
+
+__all__ = [
+    "StretchAlgorithm",
+    "fits_to_image",
+    "read_fits",
+    "stretch",
+]

processinator-0.1.0/src/processinator/stretching/__init__.py

@@ -0,0 +1,9 @@
+from processinator.stretching.algorithms import StretchAlgorithm, stretch
+from processinator.stretching.fits_io import fits_to_image, read_fits
+
+__all__ = [
+    "StretchAlgorithm",
+    "stretch",
+    "read_fits",
+    "fits_to_image",
+]

processinator-0.1.0/src/processinator/stretching/algorithms.py

@@ -0,0 +1,252 @@
+"""Image stretching algorithms for astronomy images.
+
+Converts linear FITS data (where most detail is in low pixel values) into
+visually useful images by applying nonlinear transfer functions.
+"""
+
+from enum import Enum
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class StretchAlgorithm(Enum):
+    """Available stretch algorithms."""
+
+    MTF = "mtf"
+    """Midtones Transfer Function (GraXpert-style). Default. Good all-around choice."""
+
+    ARCSINH = "arcsinh"
+    """Inverse hyperbolic sine. Preserves color ratios well."""
+
+    LOG = "log"
+    """Logarithmic stretch. Good for high dynamic range images."""
+
+    LINEAR = "linear"
+    """Simple percentile-based linear stretch."""
+
+    STATISTICAL = "statistical"
+    """Gamma correction targeting a specific median brightness."""
+
+
+def stretch(
+    data: NDArray[np.floating],
+    algorithm: StretchAlgorithm = StretchAlgorithm.MTF,
+    **kwargs: float,
+) -> NDArray[np.floating]:
+    """Stretch image data from linear to nonlinear for display.
+
+    Args:
+        data: Image array, shape (H, W) or (H, W, 3). Values should be in
+            their original FITS range (not pre-normalized).
+        algorithm: Which stretch algorithm to use.
+        **kwargs: Algorithm-specific parameters (see individual functions).
+
+    Returns:
+        Stretched image normalized to [0.0, 1.0], same shape as input.
+    """
+    normalized = _normalize_to_01(data)
+
+    match algorithm:
+        case StretchAlgorithm.MTF:
+            return _stretch_mtf(normalized, **kwargs)
+        case StretchAlgorithm.ARCSINH:
+            return _stretch_arcsinh(normalized, **kwargs)
+        case StretchAlgorithm.LOG:
+            return _stretch_log(normalized, **kwargs)
+        case StretchAlgorithm.LINEAR:
+            return _stretch_linear(normalized, **kwargs)
+        case StretchAlgorithm.STATISTICAL:
+            return _stretch_statistical(normalized, **kwargs)
+
+
+def _normalize_to_01(data: NDArray[np.floating]) -> NDArray[np.floating]:
+    """Normalize raw FITS data to [0, 1] range."""
+    result = data.astype(np.float64)
+    vmin = np.nanmin(result)
+    vmax = np.nanmax(result)
+    if vmax - vmin == 0:
+        return np.zeros_like(result)
+    return (result - vmin) / (vmax - vmin)
+
+
+# ---------------------------------------------------------------------------
+# MTF (Midtones Transfer Function) - adapted from pyscopinator/GraXpert
+# ---------------------------------------------------------------------------
+
+
+def _mtf(m: float, x: NDArray[np.floating]) -> NDArray[np.floating]:
+    """Apply Midtones Transfer Function.
+
+    MTF(m, x) = (m - 1) * x / ((2m - 1) * x - m)
+    """
+    numerator = (m - 1.0) * x
+    denominator = (2.0 * m - 1.0) * x - m
+    # Avoid division by zero
+    safe = np.where(np.abs(denominator) < 1e-10, x, numerator / denominator)
+    return np.clip(safe, 0.0, 1.0)
+
+
+def _stretch_mtf(
+    data: NDArray[np.floating],
+    bg_percent: float = 0.15,
+    sigma: float = 3.0,
+) -> NDArray[np.floating]:
+    """MTF stretch using background/sigma clipping.
+
+    Args:
+        data: Normalized [0, 1] image data.
+        bg_percent: Target background level (0-1). Default 0.15.
+        sigma: Number of sigma above background for shadow clipping. Default 3.0.
+    """
+    result = data.copy()
+
+    # Process each channel (or the single channel for grayscale)
+    if result.ndim == 2:
+        channels = [result]
+    else:
+        channels = [result[:, :, i] for i in range(result.shape[2])]
+
+    processed = []
+    for channel in channels:
+        flat = channel.ravel()
+        valid = flat[(flat > 0.0) & (flat < 1.0)]
+
+        if len(valid) == 0:
+            processed.append(channel)
+            continue
+
+        median = np.median(valid)
+        mad = np.median(np.abs(valid - median))
+
+        shadow_clip = max(0.0, median - sigma * mad * 1.4826)
+        highlight_clip = 1.0
+
+        # Normalize between clipping points
+        stretched = np.clip(channel, shadow_clip, highlight_clip)
+        if highlight_clip - shadow_clip > 0:
+            stretched = (stretched - shadow_clip) / (highlight_clip - shadow_clip)
+
+        # Calculate midtone balance for target background
+        median_norm = (median - shadow_clip) / (highlight_clip - shadow_clip)
+        if 0 < median_norm < 1 and bg_percent > 0:
+            midtone = (
+                median_norm
+                * (bg_percent - 1.0)
+                / (2.0 * bg_percent * median_norm - bg_percent - median_norm)
+            )
+            midtone = np.clip(midtone, 0.01, 0.99)
+        else:
+            midtone = 0.5
+
+        stretched = _mtf(midtone, stretched)
+        processed.append(stretched)
+
+    if result.ndim == 2:
+        return processed[0]
+    for i, ch in enumerate(processed):
+        result[:, :, i] = ch
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Arcsinh stretch - adapted from astra
+# ---------------------------------------------------------------------------
+
+
+def _stretch_arcsinh(
+    data: NDArray[np.floating],
+    factor: float = 0.15,
+) -> NDArray[np.floating]:
+    """Inverse hyperbolic sine stretch. Preserves color ratios.
+
+    Args:
+        data: Normalized [0, 1] image data.
+        factor: Controls stretch aggressiveness. Smaller = more aggressive. Default 0.15.
+    """
+    scale = 1.0 / factor
+    result = np.arcsinh(data * scale) / np.arcsinh(scale)
+    return np.clip(result, 0.0, 1.0)
+
+
+# ---------------------------------------------------------------------------
+# Log stretch - adapted from astra/pyscopinator
+# ---------------------------------------------------------------------------
+
+
+def _stretch_log(
+    data: NDArray[np.floating],
+    factor: float = 0.15,
+) -> NDArray[np.floating]:
+    """Logarithmic stretch. Good for high dynamic range.
+
+    Args:
+        data: Normalized [0, 1] image data.
+        factor: Controls stretch aggressiveness. Smaller = more aggressive. Default 0.15.
+    """
+    offset = factor * 0.01
+    result = np.log1p(data / offset) / np.log1p(1.0 / offset)
+    return np.clip(result, 0.0, 1.0)
+
+
+# ---------------------------------------------------------------------------
+# Linear stretch
+# ---------------------------------------------------------------------------
+
+
+def _stretch_linear(
+    data: NDArray[np.floating],
+    low_percentile: float = 1.0,
+    high_percentile: float = 99.0,
+) -> NDArray[np.floating]:
+    """Simple percentile-based linear stretch.
+
+    Args:
+        data: Normalized [0, 1] image data.
+        low_percentile: Lower clipping percentile. Default 1.0.
+        high_percentile: Upper clipping percentile. Default 99.0.
+    """
+    vmin = np.percentile(data, low_percentile)
+    vmax = np.percentile(data, high_percentile)
+    if vmax - vmin == 0:
+        return data
+    result = (data - vmin) / (vmax - vmin)
+    return np.clip(result, 0.0, 1.0)
+
+
+# ---------------------------------------------------------------------------
+# Statistical stretch (gamma correction) - adapted from astra
+# ---------------------------------------------------------------------------
+
+
+def _stretch_statistical(
+    data: NDArray[np.floating],
+    target_median: float = 0.15,
+    low_percentile: float = 0.5,
+    high_percentile: float = 99.9,
+) -> NDArray[np.floating]:
+    """Stretch using percentile clipping then gamma correction.
+
+    Clips to percentile range, then applies gamma correction to achieve
+    a target median brightness.
+
+    Args:
+        data: Normalized [0, 1] image data.
+        target_median: Desired median value after stretch. Default 0.15.
+        low_percentile: Black point percentile. Default 0.5.
+        high_percentile: White point percentile. Default 99.9.
+    """
+    vmin = np.percentile(data, low_percentile)
+    vmax = np.percentile(data, high_percentile)
+    if vmax - vmin == 0:
+        return data
+
+    result = np.clip((data - vmin) / (vmax - vmin), 0.0, 1.0)
+
+    current_median = np.median(result[result > 0])
+    if current_median > 0 and current_median != target_median:
+        gamma = np.log(target_median) / np.log(current_median)
+        gamma = np.clip(gamma, 0.2, 5.0)
+        result = np.power(result, gamma)
+
+    return np.clip(result, 0.0, 1.0)

processinator-0.1.0/src/processinator/stretching/fits_io.py

@@ -0,0 +1,105 @@
+"""FITS file reading and image output."""
+
+from pathlib import Path
+
+import numpy as np
+from astropy.io import fits
+from numpy.typing import NDArray
+from PIL import Image
+
+from processinator.stretching.algorithms import StretchAlgorithm, stretch
+
+
+def read_fits(file_path: str | Path) -> tuple[NDArray[np.floating], dict]:
+    """Read a FITS file and return image data and header metadata.
+
+    Handles common FITS layouts:
+    - (H, W) grayscale
+    - (3, H, W) RGB channels-first
+    - (H, W, 3) RGB channels-last
+
+    Args:
+        file_path: Path to the FITS file.
+
+    Returns:
+        Tuple of (image_data as float64, header as dict).
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the FITS file contains no image data.
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"FITS file not found: {path}")
+
+    with fits.open(path) as hdul:
+        # Find the first HDU with image data
+        image_data = None
+        header = {}
+
+        for hdu in hdul:
+            if hdu.data is not None and hdu.data.ndim >= 2:
+                image_data = hdu.data.astype(np.float64)
+                header = dict(hdu.header)
+                break
+
+        if image_data is None:
+            raise ValueError(f"No image data found in FITS file: {path}")
+
+    # Normalize array layout to (H, W) or (H, W, 3)
+    if image_data.ndim == 3:
+        if image_data.shape[0] == 3:
+            # (3, H, W) -> (H, W, 3)
+            image_data = np.transpose(image_data, (1, 2, 0))
+        elif image_data.shape[2] != 3:
+            raise ValueError(
+                f"Unexpected FITS shape: {image_data.shape}. "
+                "Expected (H, W), (3, H, W), or (H, W, 3)."
+            )
+    elif image_data.ndim != 2:
+        raise ValueError(f"Unexpected FITS dimensions: {image_data.ndim}. Expected 2 or 3.")
+
+    return image_data, header
+
+
+def fits_to_image(
+    fits_path: str | Path,
+    output_path: str | Path | None = None,
+    algorithm: StretchAlgorithm = StretchAlgorithm.MTF,
+    output_format: str = "PNG",
+    **stretch_kwargs: float,
+) -> Image.Image:
+    """Read a FITS file, apply stretching, and produce a displayable image.
+
+    Args:
+        fits_path: Path to the input FITS file.
+        output_path: If provided, save the image to this path.
+        algorithm: Stretch algorithm to use.
+        output_format: Image format for saving ("PNG" or "JPEG").
+        **stretch_kwargs: Passed through to the stretch algorithm.
+
+    Returns:
+        PIL Image object.
+    """
+    data, _header = read_fits(fits_path)
+    stretched = stretch(data, algorithm=algorithm, **stretch_kwargs)
+
+    # Convert to 8-bit
+    img_8bit = (stretched * 255.0).clip(0, 255).astype(np.uint8)
+
+    if img_8bit.ndim == 2:
+        pil_image = Image.fromarray(img_8bit, mode="L")
+    else:
+        pil_image = Image.fromarray(img_8bit, mode="RGB")
+
+    if output_path is not None:
+        output_path = Path(output_path)
+        save_kwargs = {}
+        if output_format.upper() == "JPEG":
+            save_kwargs["quality"] = 95
+            # JPEG doesn't support 'L' with alpha or palette issues, convert if needed
+            if pil_image.mode == "L":
+                pil_image = pil_image.convert("RGB")
+        pil_image.save(output_path, format=output_format, **save_kwargs)
+
+    return pil_image