Hugging face demo v1

LICENSE

@@ -0,0 +1,12 @@
+Copyright © 2026 scub.ai. All rights reserved.
+
+UWColorKit, the ScubAI name, the underwater color-recovery method (patent-pending),
+and the contents of this repository are proprietary.
+
+This Space is published for live demonstration and evaluation only. No license or
+right is granted to use, copy, modify, distribute, publish, sublicense,
+reverse-engineer, or create derivative works from this code, the engine, the API,
+or the brand — in whole or in part — without prior written permission. Using the
+hosted demo grants no rights to the underlying technology.
+
+Contact: info@scub.ai

README.md

@@ -10,6 +10,23 @@ app_file: app.py
 pinned: false
 license: other
 short_description: Zero-shot underwater white balance
+license_name: "Proprietary — all rights reserved"
+license_link: LICENSE
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🤿 UWColorKit — zero-shot underwater white balance
+
+The color engine inside **[ScubAI](https://apps.apple.com/us/app/scubai/id6741768984)** — it
+brings back the reds and oranges the water strips away, from GPS + depth alone.
+
+🐠 Shooting underwater on an iPhone? ScubAI does this automatically, every dive → **[Get it on iOS](https://apps.apple.com/us/app/scubai/id6741768984)**
+
+- **Zero-shot** — no per-image tuning, no presets, no reference chart.
+- **On-device, offline-capable.**
+- **Patent-pending.**
+
+---
+
+© scub.ai — UWColorKit is proprietary and **patent-pending**. Published for live demonstration
+only; **not licensed** for reuse, redistribution, or reverse-engineering. See [`LICENSE`](LICENSE) ·
+[scub.ai](https://scub.ai)

app.py

@@ -0,0 +1,230 @@
+"""UWColorKit demo: zero-shot underwater color recovery from location + depth."""
+
+import json
+import os
+
+import gradio as gr
+
+import client
+import color
+import exif_gps
+
+DEFAULT_LAT, DEFAULT_LNG, DEFAULT_DEPTH = 20.21, -87.43, 12
+
+RAW_EXTENSIONS = [
+    ".dng", ".cr2", ".cr3", ".arw", ".arq", ".nef", ".nrw", ".raf", ".rw2",
+    ".orf", ".pef", ".srw", ".sr2", ".raw", ".rwl", ".dcr", ".kdc", ".3fr",
+    ".mef", ".mos", ".iiq", ".erf", ".x3f",
+]
+
+MAP_HTML = (
+    '<div id="scubai-map" style="height:360px;border-radius:8px;'
+    'overflow:hidden;margin:6px 0;border:1px solid #ddd;"></div>'
+)
+
+LEAFLET_JS = """
+() => {
+  const CSS = "https://unpkg.com/leaflet@1.9.4/dist/leaflet.css";
+  const JS  = "https://unpkg.com/leaflet@1.9.4/dist/leaflet.js";
+  function setNumber(id, v) {
+    const el = document.getElementById(id);
+    const inp = el ? el.querySelector("input") : null;
+    if (!inp) return;
+    const set = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value").set;
+    set.call(inp, v);
+    inp.dispatchEvent(new Event("input", { bubbles: true }));
+  }
+  function readNumber(id, fb) {
+    const el = document.getElementById(id);
+    const inp = el ? el.querySelector("input") : null;
+    const v = inp ? parseFloat(inp.value) : NaN;
+    return isNaN(v) ? fb : v;
+  }
+  function initMap() {
+    const el = document.getElementById("scubai-map");
+    if (!el || !window.L) { setTimeout(initMap, 200); return; }
+    if (el.dataset.ready === "1") return;
+    el.dataset.ready = "1";
+    const map = L.map(el).setView([readNumber("scubai_lat", 20.21), readNumber("scubai_lng", -87.43)], 5);
+    L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
+                { maxZoom: 19, attribution: "© OpenStreetMap" }).addTo(map);
+    const marker = L.marker(map.getCenter(), { draggable: true }).addTo(map);
+    function publish(ll) {
+      setNumber("scubai_lat", Math.round(ll.lat * 1e6) / 1e6);
+      setNumber("scubai_lng", Math.round(ll.lng * 1e6) / 1e6);
+    }
+    map.on("click", (e) => { marker.setLatLng(e.latlng); publish(e.latlng); });
+    marker.on("dragend", () => publish(marker.getLatLng()));
+    window.scubaiSetPin = (la, ln) => {
+      la = parseFloat(la); ln = parseFloat(ln);
+      if (!isNaN(la) && !isNaN(ln)) { marker.setLatLng([la, ln]); map.panTo([la, ln]); }
+    };
+    setTimeout(() => map.invalidateSize(), 300);
+  }
+  function ensure() {
+    if (!document.querySelector('link[data-scubai]')) {
+      const l = document.createElement("link");
+      l.rel = "stylesheet"; l.href = CSS; l.setAttribute("data-scubai", "1");
+      document.head.appendChild(l);
+    }
+    if (window.L) return initMap();
+    let s = document.querySelector('script[data-scubai]');
+    if (!s) {
+      s = document.createElement("script");
+      s.src = JS; s.async = true; s.setAttribute("data-scubai", "1");
+      s.onload = initMap; document.head.appendChild(s);
+    } else { s.addEventListener("load", initMap); }
+  }
+  ensure();
+}
+"""
+
+MOVE_PIN_JS = "(la, ln) => { if (window.scubaiSetPin) window.scubaiSetPin(la, ln); }"
+
+APP_STORE_URL = "https://apps.apple.com/us/app/scubai/id6741768984"
+SITE_URL = "https://scub.ai"
+
+HEADER_MD = """
+# 🤿 UWColorKit — zero-shot underwater white balance
+The color engine inside **ScubAI** — it brings back the reds and oranges the water strips away.
+"""
+
+APP_CTA_MD = (
+    f"🐠 Shooting underwater on an iPhone? **[ScubAI]({APP_STORE_URL})** "
+    "does this automatically, every dive."
+)
+
+FOOTER_MD = (
+    "*Your RAW is decoded for this preview and discarded right after.*\n\n"
+    f"*UWColorKit · patent-pending underwater color engine · [scub.ai]({SITE_URL})*"
+)
+
+EXAMPLES_DIR = os.path.join(os.path.dirname(__file__), "examples")
+
+
+def load_examples():
+    """Read examples/examples.json -> [[file, lat, lng, depth], ...]; skip missing files."""
+    manifest = os.path.join(EXAMPLES_DIR, "examples.json")
+    if not os.path.exists(manifest):
+        return []
+    try:
+        with open(manifest) as fh:
+            entries = json.load(fh)
+    except (OSError, ValueError):
+        return []
+    rows, missing = [], 0
+    for e in entries:
+        path = os.path.join(EXAMPLES_DIR, e.get("file", ""))
+        if os.path.exists(path):
+            rows.append([path, e["lat"], e["lng"], e["depth"]])
+        else:
+            missing += 1
+    if missing:
+        print(f"[uwcolorkit] {missing} example(s) listed in examples.json have no file yet")
+    return rows
+
+
+def _discard(path):
+    try:
+        if path and os.path.exists(path):
+            os.remove(path)
+    except OSError:
+        pass
+
+
+# Decoded image (+ month) per upload, RAM only. Lets the user re-run with a
+# different depth without re-reading the file (which we discard after decoding).
+_DECODE_CACHE = {}
+_DECODE_CACHE_MAX = 6
+
+
+def _cache_put(path, value):
+    _DECODE_CACHE[path] = value
+    while len(_DECODE_CACHE) > _DECODE_CACHE_MAX:
+        _DECODE_CACHE.pop(next(iter(_DECODE_CACHE)))
+
+
+def on_upload(path):
+    gps = exif_gps.extract_gps(path) if path else None
+    if gps:
+        return gr.update(value=round(gps[0], 6)), gr.update(value=round(gps[1], 6))
+    return gr.update(), gr.update()
+
+
+def correct(path, lat, lng, depth):
+    if not path:
+        raise gr.Error("Upload a RAW file first.")
+    if lat is None or lng is None:
+        raise gr.Error("Set a location on the map.")
+
+    # Decode once per upload, cache it, then discard the file. Re-runs (e.g. a
+    # new depth) reuse the cached image — no second read of a deleted file.
+    cached = _DECODE_CACHE.get(path)
+    if cached is None:
+        if not os.path.exists(path):
+            raise gr.Error("Please re-upload the RAW — the previous file was cleared.")
+        month = exif_gps.extract_month(path)  # read metadata before discarding
+        try:
+            linear = color.decode_raw(path)
+        except Exception as exc:
+            raise gr.Error(f"Could not decode RAW ({type(exc).__name__}): {exc}")
+        finally:
+            _discard(path)
+        cached = (linear, month)
+        _cache_put(path, cached)
+    linear, month = cached  # month is None when no EXIF date -> engine uses yearly data
+
+    try:
+        illum = client.fetch_illuminant(lat, lng, depth, month)
+    except Exception as exc:
+        raise gr.Error(f"Parameter API error: {exc}")
+
+    print(f"[uwcolorkit] month={month} illuminant={illum.as_tuple()} stub={client.using_stub()}")
+    matrix = color.correction_matrix(illum.as_tuple())
+    before = color.encode_display(linear)
+    after = color.encode_display(color.apply_correction(linear, matrix))
+    return (before, after)
+
+
+def build():
+    with gr.Blocks(title="UWColorKit — underwater color engine", theme=gr.themes.Soft()) as demo:
+        gr.Markdown(HEADER_MD)
+        with gr.Row():
+            with gr.Column():
+                raw_file = gr.File(
+                    label="RAW photo",
+                    file_count="single",
+                    type="filepath",
+                    file_types=RAW_EXTENSIONS,
+                )
+                gr.HTML(MAP_HTML)
+                with gr.Row():
+                    lat = gr.Number(label="Latitude", value=DEFAULT_LAT, elem_id="scubai_lat", precision=6)
+                    lng = gr.Number(label="Longitude", value=DEFAULT_LNG, elem_id="scubai_lng", precision=6)
+                depth = gr.Slider(0, 40, value=DEFAULT_DEPTH, step=1, label="Depth (m)")
+                correct_btn = gr.Button("Correct colour", variant="primary")
+                examples = load_examples()
+                if examples:
+                    gr.Examples(
+                        examples=examples,
+                        inputs=[raw_file, lat, lng, depth],
+                        label="Or try a sample dive",
+                    )
+            with gr.Column():
+                slider = gr.ImageSlider(label="RAW → Corrected", type="numpy", slider_position=50)
+
+        gr.Markdown(APP_CTA_MD)
+        gr.Markdown(FOOTER_MD)
+
+        raw_file.upload(on_upload, inputs=raw_file, outputs=[lat, lng])
+        correct_btn.click(correct, inputs=[raw_file, lat, lng, depth], outputs=slider)
+        lat.change(None, [lat, lng], None, js=MOVE_PIN_JS)
+        lng.change(None, [lat, lng], None, js=MOVE_PIN_JS)
+        demo.load(None, None, None, js=LEAFLET_JS)
+    return demo
+
+
+demo = build()
+
+if __name__ == "__main__":
+    demo.queue().launch()

client.py

@@ -0,0 +1,60 @@
+"""Parameter API client: sends only {lat, lng, depth_m}, returns illuminant (x, y)."""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+ALLOWED_REQUEST_KEYS = frozenset({"lat", "lng", "depth_m", "month"})
+STUB_ILLUMINANT_XY = (0.25, 0.30)  # TODO(owner): replace with the live solver
+ENV_API_URL = "SCUBAI_PARAM_API_URL"
+ENV_API_TOKEN = "SCUBAI_PARAM_API_TOKEN"
+
+
+@dataclass(frozen=True)
+class Illuminant:
+    x: float
+    y: float
+
+    def as_tuple(self):
+        return (self.x, self.y)
+
+
+def using_stub():
+    return not os.environ.get(ENV_API_URL)
+
+
+def _validate(x, y):
+    x, y = float(x), float(y)
+    if not (0.0 < x < 0.8 and 0.0 < y < 0.9 and (x + y) < 1.0):
+        raise ValueError(f"illuminant out of range: x={x}, y={y}")
+    return Illuminant(x, y)
+
+
+def fetch_illuminant(lat, lng, depth_m, month=None, *, timeout=10.0):
+    payload = {"lat": float(lat), "lng": float(lng), "depth_m": float(depth_m)}
+    if month is not None:
+        payload["month"] = int(month)  # omitted when EXIF has no date -> engine uses yearly data
+    assert set(payload).issubset(ALLOWED_REQUEST_KEYS)  # only location/depth/date — never pixels
+
+    url = os.environ.get(ENV_API_URL)
+    if not url:
+        return _validate(*STUB_ILLUMINANT_XY)
+
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data, method="POST", headers={"Content-Type": "application/json"}
+    )
+    token = os.environ.get(ENV_API_TOKEN)
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            body = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"parameter API request failed: {exc}") from exc
+    try:
+        return _validate(body["x"], body["y"])
+    except (KeyError, TypeError) as exc:
+        raise RuntimeError(f"parameter API response missing x/y: {body!r}") from exc

color.py

@@ -0,0 +1,79 @@
+"""RAW decode and Bradford chromatic adaptation."""
+
+import numpy as np
+
+D65_XY = (0.3127, 0.3290)
+
+M_RGB2XYZ = np.array([
+    [0.4124564, 0.3575761, 0.1804375],
+    [0.2126729, 0.7151522, 0.0721750],
+    [0.0193339, 0.1191920, 0.9503041],
+])
+M_XYZ2RGB = np.linalg.inv(M_RGB2XYZ)
+
+M_BRADFORD = np.array([
+    [0.8951000, 0.2664000, -0.1614000],
+    [-0.7502000, 1.7135000, 0.0367000],
+    [0.0389000, -0.0685000, 1.0296000],
+])
+M_BRADFORD_INV = np.linalg.inv(M_BRADFORD)
+
+HALF_SIZE = True
+MAX_LONG_EDGE = 2000
+
+
+def xy_to_XYZ(x, y, Y=1.0):
+    return np.array([Y * x / y, Y, Y * (1.0 - x - y) / y])
+
+
+def bradford_cat(src_white_XYZ, dst_white_XYZ):
+    src = M_BRADFORD @ src_white_XYZ
+    dst = M_BRADFORD @ dst_white_XYZ
+    return M_BRADFORD_INV @ np.diag(dst / src) @ M_BRADFORD
+
+
+def correction_matrix(illuminant_xy, target_xy=D65_XY):
+    cat = bradford_cat(xy_to_XYZ(*illuminant_xy), xy_to_XYZ(*target_xy))
+    return M_XYZ2RGB @ cat @ M_RGB2XYZ
+
+
+def apply_correction(linear_rgb, matrix):
+    return linear_rgb @ matrix.T
+
+
+def encode_display(linear_rgb):
+    lin = np.clip(linear_rgb, 0.0, 1.0)
+    srgb = np.where(lin <= 0.0031308, lin * 12.92, 1.055 * np.power(lin, 1 / 2.4) - 0.055)
+    return (np.clip(srgb, 0.0, 1.0) * 255.0 + 0.5).astype(np.uint8)
+
+
+def _resize_max(img, max_long_edge):
+    from PIL import Image
+
+    h, w = img.shape[:2]
+    if max(h, w) <= max_long_edge:
+        return img
+    scale = max_long_edge / max(h, w)
+    new_w, new_h = max(1, round(w * scale)), max(1, round(h * scale))
+    chans = [
+        np.asarray(Image.fromarray(img[..., c], mode="F").resize((new_w, new_h), Image.BILINEAR))
+        for c in range(img.shape[2])
+    ]
+    return np.stack(chans, axis=-1)
+
+
+def decode_raw(path, half_size=HALF_SIZE, max_long_edge=MAX_LONG_EDGE):
+    import rawpy
+
+    # rawpy.imread (Cython) needs an exact str; Gradio passes a NamedString.
+    with rawpy.imread(str(path)) as raw:
+        rgb16 = raw.postprocess(
+            no_auto_bright=True,
+            output_bps=16,
+            use_camera_wb=False,
+            use_auto_wb=False,
+            gamma=(1, 1),
+            output_color=rawpy.ColorSpace.sRGB,
+            half_size=half_size,
+        )
+    return _resize_max(rgb16.astype(np.float32) / 65535.0, max_long_edge)

examples/examples.json

@@ -0,0 +1,5 @@
+[
+  { "file": "cozumel-reef-12m.dng",   "label": "Cozumel reef",   "lat": 20.21,  "lng": -87.43, "depth": 12 },
+  { "file": "red-sea-wall-18m.dng",   "label": "Red Sea wall",   "lat": 27.85,  "lng": 34.31,  "depth": 18 },
+  { "file": "mediterranean-6m.dng",   "label": "Mediterranean",  "lat": 41.53,  "lng": 2.45,   "depth": 6 }
+]

exif_gps.py

@@ -0,0 +1,63 @@
+"""Local EXIF GPS extraction to prefill the map pin (no pixels touched)."""
+
+from typing import Optional, Tuple
+
+
+def _to_degrees(tag):
+    try:
+        d, m, s = (float(p.num) / float(p.den) for p in tag.values)
+        return d + m / 60.0 + s / 3600.0
+    except (AttributeError, TypeError, ValueError, ZeroDivisionError):
+        return None
+
+
+def extract_gps(path) -> Optional[Tuple[float, float]]:
+    try:
+        import exifread
+    except ImportError:
+        return None
+    try:
+        with open(path, "rb") as fh:
+            tags = exifread.process_file(fh, details=False)
+    except Exception:
+        return None
+
+    lat = _to_degrees(tags.get("GPS GPSLatitude"))
+    lng = _to_degrees(tags.get("GPS GPSLongitude"))
+    if lat is None or lng is None:
+        return None
+    if str(tags.get("GPS GPSLatitudeRef", "N")).strip().upper().startswith("S"):
+        lat = -lat
+    if str(tags.get("GPS GPSLongitudeRef", "E")).strip().upper().startswith("W"):
+        lng = -lng
+    if not (-90 <= lat <= 90 and -180 <= lng <= 180):
+        return None
+    return (lat, lng)
+
+
+def extract_month(path) -> Optional[int]:
+    """Calendar month (1-12) from the EXIF capture date, or None."""
+    try:
+        import exifread
+    except ImportError:
+        return None
+    try:
+        with open(path, "rb") as fh:
+            tags = exifread.process_file(fh, details=False)
+    except Exception:
+        return None
+
+    for key in ("EXIF DateTimeOriginal", "EXIF DateTimeDigitized", "Image DateTime"):
+        raw = str(tags.get(key, "")).strip()
+        if not raw:
+            continue
+        date_part = raw.split()[0]  # "YYYY:MM:DD" or "YYYY-MM-DD"
+        bits = date_part.replace("-", ":").split(":")
+        if len(bits) >= 2:
+            try:
+                month = int(bits[1])
+            except ValueError:
+                continue
+            if 1 <= month <= 12:
+                return month
+    return None

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=6.0        # modern UI; needs Python >= 3.10. gr.ImageSlider is built in.
+rawpy>=0.19.0      # libraw RAW decode (manylinux wheels bundle libraw)
+numpy>=1.24
+Pillow>=9.0        # linear-light downsample for the preview
+exifread>=3.0.0    # local EXIF GPS read (no pixels touched)