resenh 0.1.0__py3-none-any.whl

resenh/__init__.py

@@ -0,0 +1,14 @@
+"""resenh: robust low-light image restoration and enhancement.
+
+>>> import resenh
+>>> result = resenh.enhance("night.jpg")          # adaptive hybrid (classical + deep)
+>>> resenh.save_image(result.image, "night_enhanced.png")
+"""
+
+from resenh.io import ImageInputError, load_image, save_image
+from resenh.pipeline import MODES, EnhanceResult, enhance
+
+__version__ = "0.1.0"
+
+__all__ = ["enhance", "EnhanceResult", "MODES", "load_image", "save_image", "ImageInputError",
+           "__version__"]

resenh/analysis.py

@@ -0,0 +1,120 @@
+"""Image analyzer: measures the input and maps the measurements to enhancement parameters.
+
+This is what makes the pipeline adaptive (no fixed parameters): every classical stage and the
+controller read their settings from :class:`Params`, computed per image from :class:`Stats`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+import cv2
+import numpy as np
+
+LUMA = np.array([0.299, 0.587, 0.114], dtype=np.float32)
+
+
+def luma(img: np.ndarray) -> np.ndarray:
+    return img @ LUMA
+
+
+def noise_sigma(gray: np.ndarray) -> float:
+    """Immerkaer (1996) fast noise estimate on a [0,1] gray image (returns sigma in [0,1] units).
+
+    Uses the Laplacian-difference kernel, which cancels image structure up to 2nd order.
+    """
+    h, w = gray.shape
+    if h < 3 or w < 3:
+        return 0.0
+    k = np.array([[1, -2, 1], [-2, 4, -2], [1, -2, 1]], dtype=np.float32)
+    conv = cv2.filter2D(gray.astype(np.float32), -1, k, borderType=cv2.BORDER_REFLECT)
+    s = np.abs(conv[1:-1, 1:-1]).sum()
+    return float(s * np.sqrt(0.5 * np.pi) / (6.0 * (w - 2) * (h - 2)))
+
+
+@dataclass
+class Stats:
+    mean_luma: float          # global brightness
+    median_luma: float
+    dark_frac: float          # fraction of pixels with luma < 0.1
+    highlight_frac: float     # fraction of pixels with luma > 0.95 (lamps, signs)
+    noise_sigma: float        # Immerkaer estimate on the raw input
+    rel_noise: float          # noise relative to brightness (what gets amplified)
+    cast: tuple               # per-channel mean / gray mean (colour cast)
+    cast_strength: float      # max |channel ratio - 1|
+    nonuniformity: float      # std/mean of a heavily blurred luma map (uneven lighting)
+    width: int
+    height: int
+
+    def to_dict(self):
+        return asdict(self)
+
+
+@dataclass
+class Params:
+    is_low_light: bool
+    target_mean: float        # desired output mean luma
+    retinex_gamma: float      # illumination compression; smaller = stronger lift
+    gain_floor: float         # bounds max per-pixel gain (1 / floor)
+    clahe_clip: float
+    denoise_strength: float   # 0 = off, 1 = strong
+    wb_strength: float        # 0 = no white balance, 1 = full gray-world
+    highlight_protect: float  # 0..1 how strongly to keep bright regions
+    dl_weight_hint: float     # prior preference for the network output in the controller
+
+    def to_dict(self):
+        return asdict(self)
+
+
+def analyze(img: np.ndarray) -> Stats:
+    y = luma(img)
+    h, w = y.shape
+    small = cv2.resize(y, (max(8, w // 8), max(8, h // 8)), interpolation=cv2.INTER_AREA)
+    blur = cv2.GaussianBlur(small, (0, 0), sigmaX=max(2.0, min(small.shape) / 8))
+    means = img.reshape(-1, 3).mean(axis=0)
+    gray_mean = float(means.mean()) + 1e-6
+    cast = tuple(float(m / gray_mean) for m in means)
+    sigma = noise_sigma(y)
+    mean_l = float(y.mean())
+    return Stats(
+        mean_luma=mean_l,
+        median_luma=float(np.median(y)),
+        dark_frac=float((y < 0.1).mean()),
+        highlight_frac=float((y > 0.95).mean()),
+        noise_sigma=sigma,
+        rel_noise=float(sigma / max(mean_l, 1e-3)),
+        cast=cast,
+        cast_strength=float(max(abs(c - 1.0) for c in cast)),
+        nonuniformity=float(blur.std() / (blur.mean() + 1e-3)),
+        width=w,
+        height=h,
+    )
+
+
+def _lerp(a, b, t):
+    return a + (b - a) * float(np.clip(t, 0.0, 1.0))
+
+
+def choose_params(s: Stats) -> Params:
+    """Map measurements to parameters. Thresholds were set on LOL train/val, never on test."""
+    is_low = s.mean_luma < 0.35 or s.dark_frac > 0.5
+    darkness = np.clip((0.35 - s.mean_luma) / 0.33, 0.0, 1.0)  # 0 = normal, 1 = near black
+    gamma = _lerp(0.85, 0.45, darkness) if is_low else 0.95
+    gamma = min(0.95, gamma + 0.1 * np.clip(s.nonuniformity - 0.6, 0, 1))  # keep relief
+    denoise = np.clip((s.rel_noise - 0.02) / 0.10, 0.0, 1.0)
+    return Params(
+        is_low_light=bool(is_low),
+        target_mean=0.45 if is_low else max(s.mean_luma, 0.4),
+        retinex_gamma=float(gamma),
+        gain_floor=float(_lerp(0.08, 0.025, darkness)),
+        clahe_clip=float(_lerp(2.5, 1.5, denoise)),  # less local contrast when noisy
+        denoise_strength=float(denoise),
+        wb_strength=float(np.clip((s.cast_strength - 0.05) / 0.25, 0.0, 0.8)),
+        # the spatial mask in protect_highlights localises the effect, so even a tiny lamp
+        # gets full protection (networks trained on LOL hallucinate colour in clipped sources)
+        # strongest for small clipped sources (lamps, signs); large clipped areas (sky,
+        # windows) are left to the network. Thresholds checked on val_b.
+        highlight_protect=float(np.clip((0.08 - s.highlight_frac) / 0.05, 0.0, 1.0))
+        if s.highlight_frac > 1e-5 else 0.0,
+        dl_weight_hint=float(1.0 if is_low else 0.3),
+    )

resenh/app.py

@@ -0,0 +1,113 @@
+"""Gradio web app: upload a low-light photo, see the enhancement and every intermediate stage."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import numpy as np
+
+import resenh
+from resenh.metrics import edge_preservation, gain_matched, noise_ratio
+from resenh.viz import panels
+
+try:  # Hugging Face ZeroGPU: allocate a GPU only for the duration of a call
+    import spaces
+
+    _gpu = spaces.GPU(duration=20)
+except Exception:  # noqa: BLE001 - running locally / CPU / Docker
+    def _gpu(fn):
+        return fn
+
+MODE_MAP = {
+    "Hybrid (adaptive, recommended)": "hybrid",
+    "Deep learning only": "dl",
+    "Classical only": "classical",
+}
+
+EXAMPLES_DIR = Path(os.environ.get("RESENH_EXAMPLES",
+                                   Path(__file__).resolve().parents[2] / "app" / "examples"))
+
+
+@_gpu
+def _run(img, mode, tta):
+    return resenh.enhance(img, mode=mode, tta=tta,
+                          max_side=int(os.environ.get("RESENH_MAX_SIDE", 1280)))
+
+
+def process(img, mode_label, tta):
+    import gradio as gr  # noqa: PLC0415
+
+    if img is None:
+        raise gr.Error("Please upload an image first.")
+    try:
+        x = resenh.load_image(img)
+        res = _run(x, MODE_MAP[mode_label], bool(tta))
+    except resenh.ImageInputError as e:
+        raise gr.Error(str(e)) from e
+    out = res.image
+    ref = gain_matched(x, out)
+    s, p = res.stats, res.params
+    lines = [
+        f"### Result: `{res.mode}` mode" + (f" · model `{res.model}`" if res.model else ""),
+        f"**Time:** {res.timings['total']:.2f}s  ·  **Size:** {s.width}×{s.height}",
+        "",
+        "**Analyzer (input measurements → adaptive parameters)**",
+        f"- brightness {s.mean_luma:.3f}, dark pixels {s.dark_frac:.0%}, "
+        f"highlights {s.highlight_frac:.1%}",
+        f"- noise σ {s.noise_sigma:.4f} (relative {s.rel_noise:.3f}), "
+        f"colour cast {s.cast_strength:.2f}, uneven lighting {s.nonuniformity:.2f}",
+        f"- low-light: **{p.is_low_light}** → Retinex γ {p.retinex_gamma:.2f}, "
+        f"denoise {p.denoise_strength:.2f}, CLAHE clip {p.clahe_clip:.1f}, "
+        f"WB {p.wb_strength:.2f}, highlight protect {p.highlight_protect:.2f}",
+        "",
+        "**Output quality (no reference available)**",
+        f"- noise vs. brightened input: ×{noise_ratio(out, ref):.2f} (lower = cleaner)",
+        f"- edge preservation (EPI): {edge_preservation(out, ref):.3f} (1 = all structure kept)",
+    ]
+    if res.decision:
+        d = res.decision
+        lines += ["", "**Quality controller**",
+                  "- weights: " + ", ".join(f"{k} {v:.2f}" for k, v in d["weights"].items()),
+                  "- guard penalties: " + ", ".join(f"{k} {v:.2f}"
+                                                   for k, v in d["penalties"].items())]
+        lines += [f"- ⚠ {n}" for n in d["notes"]]
+    gallery = [((np.clip(im, 0, 1) * 255).astype(np.uint8), lab)
+               for im, lab in panels(res.intermediates, x, out)]
+    out_u8 = (np.clip(out, 0, 1) * 255 + 0.5).astype(np.uint8)
+    in_u8 = (np.clip(x, 0, 1) * 255 + 0.5).astype(np.uint8)
+    return (in_u8, out_u8), out_u8, gallery, "\n".join(lines)
+
+
+def build():
+    import gradio as gr  # noqa: PLC0415
+
+    examples = sorted(str(p) for p in EXAMPLES_DIR.glob("*")) if EXAMPLES_DIR.exists() else []
+    with gr.Blocks(title="resenh: low-light enhancement") as demo:
+        gr.Markdown(
+            "# resenh: robust low-light image enhancement\n"
+            "Adaptive hybrid of classical Retinex/CLAHE/edge-preserving denoising and a "
+            "fine-tuned Retinexformer, fused by a quality controller. "
+            "Upload a dark photo (JPEG/PNG)."
+        )
+        with gr.Row():
+            with gr.Column(scale=1):
+                inp = gr.Image(label="Low-light input", type="numpy", image_mode="RGB",
+                               sources=["upload", "clipboard", "webcam"])
+                mode = gr.Radio(list(MODE_MAP), value=list(MODE_MAP)[0], label="Method")
+                tta = gr.Checkbox(label="High quality (×8 self-ensemble, slower)", value=False)
+                btn = gr.Button("Enhance", variant="primary")
+                if examples:
+                    gr.Examples(examples, inputs=inp, label="Examples (unseen test images)")
+            with gr.Column(scale=2):
+                slider = gr.ImageSlider(label="Before / after", type="numpy")
+                out_img = gr.Image(label="Enhanced (download)", type="numpy", format="png")
+        report = gr.Markdown()
+        gallery = gr.Gallery(label="Intermediate stages", columns=4, height="auto")
+        btn.click(process, [inp, mode, tta], [slider, out_img, gallery, report],
+                  concurrency_limit=2)
+    return demo
+
+
+if __name__ == "__main__":
+    build().launch()

resenh/classical/__init__.py

@@ -0,0 +1,55 @@
+"""Classical low-light enhancement branch (adaptive, parameters come from the analyzer)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from resenh.analysis import Params, analyze, choose_params
+from resenh.classical.clahe import clahe_luma
+from resenh.classical.color import gray_world, match_exposure, protect_highlights
+from resenh.classical.denoise import denoise, denoise_measured
+from resenh.classical.illumination import estimate_illumination, reflectance, retinex_enhance
+
+__all__ = ["enhance_classical"]
+
+
+def enhance_classical(img: np.ndarray, params: Params | None = None,
+                      denoise_method: str = "guided",
+                      disable: frozenset[str] = frozenset()) -> tuple[np.ndarray, dict]:
+    """Run the classical branch. Returns (output, intermediates).
+
+    Stage order: denoise (before any gain, so noise is not amplified) -> illumination
+    estimation -> Retinex/LIME lift -> CLAHE on luma -> gray-world WB -> exposure match ->
+    highlight protection. ``disable`` names stages to skip (for ablation): any of
+    {"denoise", "retinex", "clahe", "wb", "exposure", "highlights"}.
+    """
+    if params is None:
+        params = choose_params(analyze(img))
+    inter: dict[str, np.ndarray] = {}
+    x = img
+    if "denoise" not in disable:
+        x = denoise(x, params.denoise_strength, denoise_method)
+    inter["denoised"] = x
+    illum = estimate_illumination(x)
+    inter["illumination"] = illum
+    inter["reflectance"] = reflectance(x, illum)
+    if "retinex" not in disable:
+        x, applied = retinex_enhance(x, illum, gamma=params.retinex_gamma,
+                                     floor=params.gain_floor)
+        inter["retinex"] = x
+        inter["gain_map"] = np.clip(1.0 / applied / 25.0, 0, 1)
+        if "denoise" not in disable:
+            # residual noise is amplified by the gain: re-estimate it and filter adaptively
+            x = denoise_measured(x)
+            inter["post_denoised"] = x
+    if "clahe" not in disable:
+        c = clahe_luma(x, params.clahe_clip)
+        x = (0.5 * x + 0.5 * c).astype(np.float32)  # half-strength: CLAHE alone over-sharpens noise
+        inter["clahe"] = c
+    if "wb" not in disable:
+        x = gray_world(x, params.wb_strength)
+    if "exposure" not in disable:
+        x = match_exposure(x, params.target_mean)
+    if "highlights" not in disable:
+        x = protect_highlights(x, img, params.highlight_protect)
+    return np.clip(x, 0.0, 1.0).astype(np.float32), inter

resenh/classical/clahe.py

@@ -0,0 +1,15 @@
+"""Contrast-limited adaptive histogram equalisation on the luma channel only (keeps hue)."""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+
+def clahe_luma(img: np.ndarray, clip_limit: float = 2.0, tiles: int = 8) -> np.ndarray:
+    """Apply CLAHE to the L channel of Lab; ``img`` is RGB float in [0, 1]."""
+    u8 = (np.clip(img, 0, 1) * 255.0 + 0.5).astype(np.uint8)
+    lab = cv2.cvtColor(u8, cv2.COLOR_RGB2LAB)
+    clahe = cv2.createCLAHE(clipLimit=float(clip_limit), tileGridSize=(tiles, tiles))
+    lab[..., 0] = clahe.apply(lab[..., 0])
+    return cv2.cvtColor(lab, cv2.COLOR_LAB2RGB).astype(np.float32) / 255.0

resenh/classical/color.py

@@ -0,0 +1,48 @@
+"""Colour and tone stages: gray-world white balance, exposure normalisation, highlight protection."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from resenh.analysis import luma
+
+
+def gray_world(img: np.ndarray, strength: float = 1.0) -> np.ndarray:
+    """Partial gray-world white balance (``strength`` 0 = off, 1 = full)."""
+    if strength <= 0:
+        return img
+    means = img.reshape(-1, 3).mean(axis=0) + 1e-6
+    gains = means.mean() / means
+    gains = 1.0 + strength * (gains - 1.0)
+    return np.clip(img * gains, 0.0, 1.0).astype(np.float32)
+
+
+def match_exposure(img: np.ndarray, target_mean: float, max_gain: float = 4.0) -> np.ndarray:
+    """Scale so mean luma approaches ``target_mean`` with a soft shoulder (no hard clipping)."""
+    m = float(luma(img).mean())
+    if m <= 1e-4:
+        return img
+    g = float(np.clip(target_mean / m, 1.0 / max_gain, max_gain))
+    x = img * g
+    # filmic shoulder above 0.8 to avoid blown highlights
+    knee = 0.8
+    over = x > knee
+    x = np.where(over, knee + (1 - knee) * np.tanh((x - knee) / (1 - knee)), x)
+    return np.clip(x, 0.0, 1.0).astype(np.float32)
+
+
+def protect_highlights(enhanced: np.ndarray, original: np.ndarray,
+                       strength: float) -> np.ndarray:
+    """Blend back the original where it was already bright (lamps, signs), to stop blow-out."""
+    if strength <= 0:
+        return enhanced
+    import cv2  # noqa: PLC0415
+
+    y = luma(original)
+    # soft mask of already-bright sources, dilated so halos/colour fringes around them are
+    # also restored (networks trained on LOL hallucinate colour in saturated lamps)
+    m = np.clip((y - 0.88) / 0.1, 0.0, 1.0).astype(np.float32)  # only (near-)clipped sources
+    k = max(3, int(round(min(y.shape) / 100)) | 1)
+    m = cv2.GaussianBlur(cv2.dilate(m, np.ones((k, k), np.uint8)), (0, 0), k / 2)
+    w = np.clip(m, 0, 1)[..., None] * strength
+    return (enhanced * (1 - w) + original * w).astype(np.float32)

resenh/classical/denoise.py

@@ -0,0 +1,48 @@
+"""Edge-preserving denoising: guided filter (self-guided, per channel) or bilateral."""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+from resenh.classical.filters import guided_filter
+
+
+def denoise(img: np.ndarray, strength: float, method: str = "guided") -> np.ndarray:
+    """Denoise an RGB float image. ``strength`` in [0, 1] (0 returns the input unchanged).
+
+    Guided filtering uses the luma as guide, so colour noise is smoothed along luma edges
+    (edges preserved); bilateral is offered for comparison/ablation.
+    """
+    if strength <= 1e-3:
+        return img
+    if method == "bilateral":
+        sigma_c = 0.02 + 0.10 * strength
+        d = 5 if strength < 0.5 else 9
+        return cv2.bilateralFilter(img.astype(np.float32), d, sigma_c, d).clip(0, 1)
+    guide = img @ np.array([0.299, 0.587, 0.114], dtype=np.float32)
+    r = 2 if strength < 0.5 else 3
+    eps = (0.01 + 0.04 * strength) ** 2
+    out = guided_filter(guide, img, r, eps)
+    return np.clip(out, 0.0, 1.0).astype(np.float32)
+
+
+def denoise_measured(img: np.ndarray, k: float = 2.5) -> np.ndarray:
+    """Noise-adaptive guided filtering: eps tied to the *measured* noise variance.
+
+    Regions whose local variance is well above (k*sigma)^2 are edges and are kept; flatter
+    regions are averaged. Chroma gets a stronger pass than luma (colour noise is the most
+    visible artefact after brightening dark images).
+    """
+    from resenh.analysis import noise_sigma  # noqa: PLC0415
+
+    y = img @ np.array([0.299, 0.587, 0.114], dtype=np.float32)
+    sigma = noise_sigma(y)
+    if sigma < 0.004:
+        return img
+    eps = (k * sigma) ** 2
+    r = 2 if sigma < 0.03 else 3
+    y_d = guided_filter(y, y, r, eps)
+    chroma = img - y[..., None]
+    chroma_d = guided_filter(y_d, chroma, r + 2, eps)
+    return np.clip(y_d[..., None] + chroma_d, 0.0, 1.0).astype(np.float32)

resenh/classical/filters.py

@@ -0,0 +1,57 @@
+"""Edge-preserving filters implemented with OpenCV box filters (no contrib dependency)."""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+
+def box(x: np.ndarray, r: int) -> np.ndarray:
+    return cv2.boxFilter(x, -1, (2 * r + 1, 2 * r + 1), borderType=cv2.BORDER_REFLECT)
+
+
+def guided_filter(guide: np.ndarray, src: np.ndarray, r: int, eps: float) -> np.ndarray:
+    """Gray-guide guided filter (He et al., TPAMI 2013).
+
+    ``guide`` is HxW float32; ``src`` is HxW or HxWxC float32. Works per channel of ``src``.
+    """
+    guide = guide.astype(np.float32)
+    src = src.astype(np.float32)
+    mean_i = box(guide, r)
+    var_i = box(guide * guide, r) - mean_i * mean_i
+    if src.ndim == 3:
+        mean_i3, var_i3, guide3 = mean_i[..., None], var_i[..., None], guide[..., None]
+    else:
+        mean_i3, var_i3, guide3 = mean_i, var_i, guide
+    mean_p = box(src, r)
+    cov_ip = box(guide3 * src if src.ndim == 3 else guide * src, r) - mean_i3 * mean_p
+    a = cov_ip / (var_i3 + eps)
+    b = mean_p - a * mean_i3
+    return box(a, r) * guide3 + box(b, r)
+
+
+def fast_guided_filter(guide: np.ndarray, src: np.ndarray, r: int, eps: float,
+                       scale: int = 4) -> np.ndarray:
+    """Subsampled guided filter (He & Sun 2015): same result shape, ~scale^2 faster."""
+    if scale <= 1 or min(guide.shape[:2]) < 8 * scale:
+        return guided_filter(guide, src, r, eps)
+    h, w = guide.shape[:2]
+    small = (max(1, w // scale), max(1, h // scale))
+    g_s = cv2.resize(guide, small, interpolation=cv2.INTER_AREA)
+    p_s = cv2.resize(src, small, interpolation=cv2.INTER_AREA)
+    rs = max(1, r // scale)
+    mean_i = box(g_s, rs)
+    var_i = box(g_s * g_s, rs) - mean_i * mean_i
+    if p_s.ndim == 3:
+        mean_i, var_i, g3 = mean_i[..., None], var_i[..., None], g_s[..., None]
+    else:
+        g3 = g_s
+    mean_p = box(p_s, rs)
+    a = (box(g3 * p_s, rs) - mean_i * mean_p) / (var_i + eps)
+    b = mean_p - a * mean_i
+    a_up = cv2.resize(box(a, rs), (w, h), interpolation=cv2.INTER_LINEAR)
+    b_up = cv2.resize(box(b, rs), (w, h), interpolation=cv2.INTER_LINEAR)
+    if src.ndim == 3 and a_up.ndim == 2:
+        a_up, b_up = a_up[..., None], b_up[..., None]
+    g = guide[..., None] if src.ndim == 3 else guide
+    return a_up * g + b_up

resenh/classical/illumination.py

@@ -0,0 +1,43 @@
+"""Illumination estimation and Retinex-style decomposition.
+
+``estimate_illumination`` follows LIME (Guo et al., TIP 2017): the initial map is the per-pixel
+max over RGB, refined with a structure-aware smoother (here a guided filter, which keeps strong
+edges and flattens texture). ``retinex_enhance`` divides the image by the gamma-adjusted
+illumination, so dark regions are lifted more than bright ones (non-uniform lighting handled
+per pixel).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from resenh.classical.filters import fast_guided_filter
+
+
+def estimate_illumination(img: np.ndarray, radius: int | None = None,
+                          eps: float = 1e-3) -> np.ndarray:
+    """Return a smooth HxW illumination map in (0, 1] for an RGB float image in [0, 1]."""
+    t0 = img.max(axis=2)
+    h, w = t0.shape
+    r = radius or max(4, int(round(min(h, w) / 40)))
+    t = fast_guided_filter(t0, t0, r, eps)
+    return np.clip(t, 1e-3, 1.0).astype(np.float32)
+
+
+def retinex_enhance(img: np.ndarray, illum: np.ndarray | None = None, gamma: float = 0.6,
+                    floor: float = 0.04) -> tuple[np.ndarray, np.ndarray]:
+    """LIME-style enhancement. Returns (enhanced RGB, illumination actually applied).
+
+    ``gamma`` < 1 compresses the illumination map before division: smaller gamma = stronger
+    lift. ``floor`` bounds the gain at 1/floor to stop noise blow-up in near-black regions.
+    """
+    if illum is None:
+        illum = estimate_illumination(img)
+    t = np.maximum(illum, floor) ** gamma
+    out = img / t[..., None]
+    return np.clip(out, 0.0, 1.0).astype(np.float32), t.astype(np.float32)
+
+
+def reflectance(img: np.ndarray, illum: np.ndarray, floor: float = 0.04) -> np.ndarray:
+    """Retinex reflectance R = I / L (clipped), for visualisation and priors."""
+    return np.clip(img / np.maximum(illum, floor)[..., None], 0.0, 1.0).astype(np.float32)

resenh/classical/priors.py

@@ -0,0 +1,18 @@
+"""Classical priors fed to the hybrid network (fixed, non-adaptive so train == test)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from resenh.classical.clahe import clahe_luma
+from resenh.classical.illumination import estimate_illumination, retinex_enhance
+
+PRIOR_CHANNELS = 7  # illumination (1) + Retinex/LIME output (3) + CLAHE output (3)
+
+
+def compute_priors(img: np.ndarray) -> np.ndarray:
+    """Return an HxWx7 float32 stack of classical priors for an RGB float image in [0, 1]."""
+    illum = estimate_illumination(img)
+    lime, _ = retinex_enhance(img, illum, gamma=0.6)
+    clahe = clahe_luma(lime, clip_limit=2.0)
+    return np.concatenate([illum[..., None], lime, clahe], axis=2).astype(np.float32)

resenh/cli.py

@@ -0,0 +1,132 @@
+"""resenh command-line interface.
+
+    resenh enhance night.jpg -o out.png [--mode hybrid] [--save-intermediates DIR]
+    resenh bench [--device cpu] [--size 1024]
+    resenh app [--port 7860]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+from resenh import __version__
+
+
+def _cmd_enhance(a) -> int:
+    import resenh  # noqa: PLC0415
+    from resenh.viz import panels  # noqa: PLC0415
+
+    srcs = [Path(s) for s in a.inputs]
+    for src in srcs:
+        try:
+            res = resenh.enhance(src, mode=a.mode, model=a.model, device=a.device,
+                                 max_side=a.max_side, tta=a.tta)
+        except resenh.ImageInputError as e:
+            print(f"error: {src}: {e}", file=sys.stderr)
+            return 2
+        dst = Path(a.output) if (a.output and len(srcs) == 1) else (
+            Path(a.output or ".") / f"{src.stem}_resenh.png")
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        resenh.save_image(res.image, dst)
+        print(f"{src} -> {dst}  mode={res.mode} model={res.model} "
+              f"time={res.timings['total']:.2f}s")
+        if a.save_intermediates:
+            d = Path(a.save_intermediates) / src.stem
+            d.mkdir(parents=True, exist_ok=True)
+            for i, (img, label) in enumerate(panels(res.intermediates, resenh.load_image(src),
+                                                    res.image)):
+                resenh.save_image(img, d / f"{i:02d}_{label.split(' ', 1)[-1][:40]}.png"
+                                  .replace("/", "-").replace(" ", "_"))
+            (d / "report.json").write_text(json.dumps({
+                "stats": res.stats.to_dict(), "params": res.params.to_dict(),
+                "decision": res.decision, "timings": res.timings}, indent=1, default=float))
+    return 0
+
+
+def _cmd_bench(a) -> int:
+    import numpy as np  # noqa: PLC0415
+
+    import resenh  # noqa: PLC0415
+
+    rng = np.random.default_rng(0)
+    h = a.size * 3 // 4
+    img = (rng.random((h, a.size, 3)) * 0.15).astype(np.float32)
+    rows = []
+    for mode in a.modes:
+        resenh.enhance(img, mode=mode, device=a.device, max_side=a.max_side)  # warm-up
+        ts = []
+        for _ in range(a.repeat):
+            t = time.perf_counter()
+            resenh.enhance(img, mode=mode, device=a.device, max_side=a.max_side)
+            ts.append(time.perf_counter() - t)
+        mp = img.shape[0] * img.shape[1] / 1e6
+        print(f"{mode:10s} {a.size}x{h} ({mp:.2f} MP) device={a.device}: "
+              f"{np.median(ts):.3f}s median, {np.median(ts) / mp * 1000:.0f} ms/MP")
+        from resenh.models.runner import pick_device  # noqa: PLC0415
+
+        rows.append({"mode": mode, "device": pick_device(a.device) if mode != "classical" else "cpu",
+                     "size": f"{a.size}x{h}", "mean_s": float(np.median(ts)),
+                     "ms_per_mp": float(np.median(ts) / mp * 1000)})
+    if a.json:
+        import json  # noqa: PLC0415
+        from pathlib import Path  # noqa: PLC0415
+
+        f = Path(a.json)
+        old = json.loads(f.read_text()) if f.exists() else []
+        keep = {(r["mode"], r["device"], r["size"]) for r in rows}
+        old = [r for r in old if (r["mode"], r["device"], r["size"]) not in keep]
+        f.write_text(json.dumps(old + rows, indent=1))
+    return 0
+
+
+def _cmd_app(a) -> int:
+    from resenh.app import build  # noqa: PLC0415
+
+    build().launch(server_name=a.host, server_port=a.port, share=a.share)
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="resenh", description="Robust low-light image enhancement")
+    ap.add_argument("--version", action="version", version=f"resenh {__version__}")
+    sub = ap.add_subparsers(dest="cmd")
+
+    e = sub.add_parser("enhance", help="enhance one or more images")
+    e.add_argument("inputs", nargs="+")
+    e.add_argument("-o", "--output", help="output file (single input) or directory")
+    e.add_argument("--mode", default="auto", choices=["auto", "classical", "dl", "hybrid"])
+    e.add_argument("--model", default=None)
+    e.add_argument("--device", default="auto")
+    e.add_argument("--max-side", type=int, default=1280)
+    e.add_argument("--tta", action="store_true")
+    e.add_argument("--save-intermediates", metavar="DIR")
+    e.set_defaults(func=_cmd_enhance)
+
+    b = sub.add_parser("bench", help="measure latency")
+    b.add_argument("--modes", nargs="+", default=["classical", "dl", "hybrid"])
+    b.add_argument("--device", default="auto")
+    b.add_argument("--size", type=int, default=1155, help="width; height = 3/4 (default ~1 MP)")
+    b.add_argument("--max-side", type=int, default=1280)
+    b.add_argument("--repeat", type=int, default=3)
+    b.add_argument("--json", metavar="FILE", help="append results to a JSON file")
+    b.set_defaults(func=_cmd_bench)
+
+    p = sub.add_parser("app", help="launch the Gradio web app")
+    p.add_argument("--host", default="0.0.0.0")
+    p.add_argument("--port", type=int, default=7860)
+    p.add_argument("--share", action="store_true")
+    p.set_defaults(func=_cmd_app)
+
+    a = ap.parse_args(argv)
+    if not getattr(a, "func", None):
+        ap.print_help()
+        return 0
+    return a.func(a)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())