Upload 6 files

README.md

@@ -1,13 +1,76 @@
 ---
-title: Iman
-emoji: 🌍
-colorFrom: yellow
+title: Cochlear Neurofilament Tracer
+emoji: 🧠
+colorFrom: indigo
 colorTo: purple
 sdk: gradio
-sdk_version: 6.19.0
-python_version: '3.13'
+sdk_version: 5.49.1
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🧠 Cochlear Neurofilament Tracer
+
+A HuggingFace app that traces auditory-nerve fibers in confocal z-stacks of the
+organ of Corti and quantifies them **per frequency region**, separating
+**IHC-innervating** from **OHC-innervating** fibers.
+
+It is an alternative to IMARIS filament tracing that keeps each neuron as a
+**single continuous traced element** instead of splitting it into many
+threshold-dependent segments.
+
+## Input
+
+- **File type:** Zeiss `.czi` 3D z-stacks. Generic `.tif/.tiff` stacks are also
+  accepted for flexibility.
+- **Channels:**
+  - *Neurofilament* — traces the neuron.
+  - *Myo7a* — marks hair cells; used as a reference to separate IHC- vs
+    OHC-innervating fibers. IHCs form a single row and OHCs form three adjacent
+    rows, so the Myo7a band is used to place the IHC/OHC boundary.
+- **Frequency region:** selectable (8/16/22/32/64 kHz), auto-detected from the
+  file name when possible.
+- Channels are auto-detected from CZI metadata (Alexa-555 → Neurofilament,
+  Alexa-405 → Myo7a) but can be reassigned in the UI.
+
+## What it does
+
+1. Segments and **skeletonises the Neurofilament network in 3D** using physical
+   voxel spacing (from CZI metadata, or entered for TIFF).
+2. Uses the **Myo7a channel** to place an IHC/OHC boundary. This can be set
+   manually (ROI 1 vs ROI 2) by moving the boundary slider while viewing the
+   Myo7a preview, choosing the split axis, and choosing which side is IHC.
+3. Computes, per region (Whole field / IHC / OHC):
+   - **Number of fibers** (continuous skeleton components above a minimum length)
+   - **Thickness / diameter** (from the 3D distance transform)
+   - **Length** (µm, spacing-aware)
+   - **Branching** (number of branch points)
+   - **Area covered** within the field of view (µm² and % of FOV)
+
+## Output
+
+- A **black-background image** of the traced neurons in **white** (skeletonised
+  trace), plus a colour-coded IHC/OHC overlay.
+- An **Excel workbook** with all quantification, organized by frequency region,
+  with IHC and OHC fibers reported separately (tidy "Per region" sheet plus
+  per-metric frequency × region summary sheets).
+
+The **Batch** tab processes several stacks at once (e.g. all frequency regions
+of one cochlea) and compiles one Excel workbook plus a ZIP of skeleton images.
+
+## Notes on method
+
+Confocal images of the organ of Corti are dense, so fully separating every
+individual axon is inherently ambiguous. This tool traces the network
+continuously and reports metrics **per region surrounding the IHCs / OHCs**,
+with a human-in-the-loop boundary for reliable IHC vs OHC assignment. The
+`sensitivity` control scales the segmentation threshold to capture more or fewer
+thin fibers.
+
+## Local run
+
+```bash
+pip install -r requirements.txt
+python app.py
+```

app.py

@@ -0,0 +1,373 @@
+"""
+Cochlear Neurofilament Tracer — HuggingFace Gradio app
+======================================================
+
+Traces auditory-nerve fibers (Neurofilament channel) in confocal z-stacks of
+the organ of Corti, uses the Myo7a hair-cell channel to separate
+IHC-innervating from OHC-innervating fibers, and reports per-region
+quantification (number of fibers, diameter, length, branch points, area
+covered) plus a black-background skeleton image and an Excel workbook.
+
+Accepts Zeiss **CZI** z-stacks and generic **TIFF** stacks.
+"""
+
+import os
+import tempfile
+import zipfile
+import traceback
+
+import numpy as np
+import pandas as pd
+import gradio as gr
+from skimage.io import imsave
+from scipy import ndimage as ndi
+
+import processing as P
+
+OUT_DIR = tempfile.mkdtemp(prefix="neuron_tracer_")
+
+METRIC_COLS = [
+    "File", "Frequency region", "Region", "Number of fibers",
+    "Total length (um)", "Mean diameter (um)", "Median diameter (um)",
+    "Branch points", "Area covered (um^2)", "FOV area (um^2)",
+    "Area covered (% of FOV)",
+]
+
+
+# --------------------------------------------------------------------------- #
+#  Small helpers
+# --------------------------------------------------------------------------- #
+
+def _channel_choices(img: P.LoadedImage):
+    choices = []
+    for i, ch in enumerate(img.channels):
+        dye = ch.get("dye") or "no dye / transmitted"
+        choices.append((f"Ch {i} — {ch.get('name','?')} ({dye})", i))
+    return choices
+
+
+def _draw_boundary_on(gray_u8, boundary_frac, axis="Y"):
+    """Return an RGB copy of a grayscale MIP with a yellow boundary line."""
+    rgb = np.stack([gray_u8] * 3, axis=-1)
+    ny, nx = gray_u8.shape
+    if axis.upper() == "Y":
+        b = min(max(int(round(boundary_frac * ny)), 0), ny - 1)
+        rgb[b, :] = (255, 255, 0)
+    else:
+        b = min(max(int(round(boundary_frac * nx)), 0), nx - 1)
+        rgb[:, b] = (255, 255, 0)
+    return rgb
+
+
+def _save_png(arr, name):
+    path = os.path.join(OUT_DIR, name)
+    imsave(path, arr)
+    return path
+
+
+def _build_excel(rows, path):
+    """Write a tidy per-region sheet plus a frequency×region summary sheet."""
+    df = pd.DataFrame(rows, columns=METRIC_COLS)
+    with pd.ExcelWriter(path, engine="openpyxl") as xl:
+        df.to_excel(xl, sheet_name="Per region", index=False)
+        # Summary: only IHC / OHC rows, pivoted by frequency region.
+        sub = df[df["Region"].isin(["IHC region", "OHC region"])]
+        if not sub.empty:
+            for metric in ["Number of fibers", "Total length (um)",
+                           "Mean diameter (um)", "Branch points",
+                           "Area covered (um^2)"]:
+                piv = sub.pivot_table(index="Frequency region",
+                                      columns="Region", values=metric,
+                                      aggfunc="mean")
+                sheet = metric.split(" (")[0][:28]
+                piv.to_excel(xl, sheet_name=f"{sheet}")
+    return df
+
+
+# --------------------------------------------------------------------------- #
+#  Single-image interactive flow
+# --------------------------------------------------------------------------- #
+
+def load_and_preview(file_obj, dz, dy, dx):
+    if file_obj is None:
+        return (None, gr.update(), gr.update(), gr.update(),
+                gr.update(), None, None, "Please upload a CZI or TIFF file.")
+    try:
+        img = P.load_image(file_obj, dz=float(dz), dy=float(dy), dx=float(dx))
+    except Exception as e:
+        return (None, gr.update(), gr.update(), gr.update(),
+                gr.update(), None, None,
+                f"❌ Failed to load file:\n{e}\n{traceback.format_exc()}")
+
+    nf, myo = P.guess_channels(img)
+    choices = _channel_choices(img)
+    freq = P.detect_frequency(img.source_name)
+    bfrac = P.suggest_boundary(img.data[myo])
+
+    nf_prev = P.channel_preview(img.data[nf])
+    myo_prev = _draw_boundary_on(P.channel_preview(img.data[myo]), bfrac, "Y")
+
+    dz_, dy_, dx_ = img.voxel
+    status = (f"✅ Loaded **{img.source_name}** — shape "
+              f"{img.data.shape} (C,Z,Y,X)\n\n"
+              f"Voxel size: dz={dz_:.3f}, dy={dy_:.4f}, dx={dx_:.4f} µm.  "
+              f"Detected frequency region: **{freq}**.\n\n"
+              f"Auto-picked Neurofilament = Ch {nf}, Myo7a = Ch {myo}. "
+              f"Adjust below if needed, then press **Run analysis**.")
+    return (img,
+            gr.update(choices=choices, value=nf),
+            gr.update(choices=choices, value=myo),
+            gr.update(value=freq),
+            gr.update(value=round(bfrac, 3)),
+            nf_prev, myo_prev, status)
+
+
+def refresh_boundary_preview(img, myo_idx, boundary, axis):
+    if img is None or myo_idx is None:
+        return None
+    myo_prev = P.channel_preview(img.data[int(myo_idx)])
+    return _draw_boundary_on(myo_prev, float(boundary), axis)
+
+
+def run_single(img, nf_idx, myo_idx, freq, axis, ihc_side, boundary,
+               sensitivity, min_fiber):
+    if img is None:
+        return None, None, None, None, None, "Please load an image first."
+    if nf_idx is None:
+        return None, None, None, None, None, "Please select the Neurofilament channel."
+    try:
+        nf_idx, myo_idx = int(nf_idx), int(myo_idx)
+        trace = P.trace_neurites(img.data[nf_idx], img.voxel,
+                                 sensitivity=float(sensitivity))
+        shape_yx = img.data[nf_idx].shape[1:]
+        side = "low" if ihc_side.startswith("Low") else "high"
+        ihc_roi, ohc_roi = P.make_region_masks(shape_yx, float(boundary),
+                                               ihc_side=side, axis=axis)
+
+        whole = P.compute_metrics(trace, "Whole field",
+                                  min_fiber_um=float(min_fiber))
+        m_ihc = P.compute_metrics(trace, "IHC region", ihc_roi,
+                                  min_fiber_um=float(min_fiber))
+        m_ohc = P.compute_metrics(trace, "OHC region", ohc_roi,
+                                  min_fiber_um=float(min_fiber))
+
+        skel_img = P.skeleton_image(trace.skeleton)
+        region_img = P.region_overlay(trace.skeleton, ihc_roi, ohc_roi,
+                                      float(boundary), axis)
+        myo_img = _draw_boundary_on(P.channel_preview(img.data[myo_idx]),
+                                    float(boundary), axis)
+
+        stem = os.path.splitext(img.source_name)[0]
+        skel_path = _save_png(skel_img, f"{stem}_skeleton.png")
+
+        rows = []
+        for m in (whole, m_ihc, m_ohc):
+            r = m.as_row()
+            r = {"File": img.source_name, "Frequency region": freq, **r}
+            rows.append(r)
+        df = pd.DataFrame(rows, columns=METRIC_COLS)
+        xl_path = os.path.join(OUT_DIR, f"{stem}_quantification.xlsx")
+        _build_excel(rows, xl_path)
+
+        status = (f"✅ Done. Traced {int(trace.skeleton.sum())} skeleton voxels. "
+                  f"IHC={m_ihc.n_fibers} fibers / {m_ihc.total_length_um:.0f} µm, "
+                  f"OHC={m_ohc.n_fibers} fibers / {m_ohc.total_length_um:.0f} µm.")
+        # Return skeleton path also as downloadable file
+        return (skel_img, region_img, myo_img, df,
+                [skel_path, xl_path], status)
+    except Exception as e:
+        return (None, None, None, None, None,
+                f"❌ Error:\n{e}\n{traceback.format_exc()}")
+
+
+# --------------------------------------------------------------------------- #
+#  Batch flow
+# --------------------------------------------------------------------------- #
+
+def run_batch(files, axis, ihc_side, sensitivity, min_fiber, dz, dy, dx,
+              progress=gr.Progress()):
+    if not files:
+        return None, None, None, "Please upload one or more files."
+    side = "low" if ihc_side.startswith("Low") else "high"
+    all_rows, gallery, skel_paths = [], [], []
+    log = []
+    for f in progress.tqdm(files, desc="Processing"):
+        path = f if isinstance(f, str) else f.name
+        name = os.path.basename(path)
+        try:
+            img = P.load_image(path, dz=float(dz), dy=float(dy), dx=float(dx))
+            nf, myo = P.guess_channels(img)
+            freq = P.detect_frequency(name)
+            trace = P.trace_neurites(img.data[nf], img.voxel,
+                                     sensitivity=float(sensitivity))
+            bfrac = P.suggest_boundary(img.data[myo])
+            shape_yx = img.data[nf].shape[1:]
+            ihc_roi, ohc_roi = P.make_region_masks(shape_yx, bfrac,
+                                                   ihc_side=side, axis=axis)
+            for m in (P.compute_metrics(trace, "Whole field",
+                                        min_fiber_um=float(min_fiber)),
+                      P.compute_metrics(trace, "IHC region", ihc_roi,
+                                        min_fiber_um=float(min_fiber)),
+                      P.compute_metrics(trace, "OHC region", ohc_roi,
+                                        min_fiber_um=float(min_fiber))):
+                all_rows.append({"File": name, "Frequency region": freq,
+                                 **m.as_row()})
+            skel_img = P.skeleton_image(trace.skeleton)
+            stem = os.path.splitext(name)[0]
+            sp = _save_png(skel_img, f"{stem}_skeleton.png")
+            skel_paths.append(sp)
+            gallery.append((skel_img, f"{name} ({freq})"))
+            log.append(f"✅ {name}: {freq}")
+        except Exception as e:
+            log.append(f"❌ {name}: {e}")
+
+    if not all_rows:
+        return None, None, gallery, "No files processed.\n" + "\n".join(log)
+
+    xl_path = os.path.join(OUT_DIR, "batch_quantification.xlsx")
+    df = _build_excel(all_rows, xl_path)
+
+    zip_path = os.path.join(OUT_DIR, "batch_skeletons.zip")
+    with zipfile.ZipFile(zip_path, "w") as z:
+        for sp in skel_paths:
+            z.write(sp, os.path.basename(sp))
+        z.write(xl_path, os.path.basename(xl_path))
+
+    return df, [xl_path, zip_path], gallery, "\n".join(log)
+
+
+# --------------------------------------------------------------------------- #
+#  UI
+# --------------------------------------------------------------------------- #
+
+INTRO = """
+# 🧠 Cochlear Neurofilament Tracer
+
+Trace auditory-nerve fibers in confocal z-stacks and quantify them **per
+frequency region**, separating **IHC-innervating** from **OHC-innervating**
+fibers using the Myo7a hair-cell channel.
+
+**Channels expected:** *Neurofilament* (traces the neuron) and *Myo7a* (hair
+cells — reference to split IHC vs OHC). IHCs form a single row, OHCs form three
+rows, so the Myo7a band is used to place the IHC/OHC boundary — which you can
+fine-tune by hand.
+
+**Input:** Zeiss `.czi` z-stacks or generic `.tif/.tiff` stacks.
+"""
+
+with gr.Blocks(title="Cochlear Neurofilament Tracer", theme=gr.themes.Soft()) as demo:
+    gr.Markdown(INTRO)
+
+    with gr.Tab("Single image (interactive)"):
+        img_state = gr.State()
+        with gr.Row():
+            with gr.Column(scale=1):
+                file_in = gr.File(label="Upload CZI or TIFF",
+                                  file_types=[".czi", ".tif", ".tiff"],
+                                  type="filepath")
+                with gr.Accordion("Voxel size (µm) — used for TIFF; CZI reads "
+                                  "its own", open=False):
+                    dz_in = gr.Number(0.35, label="dz (µm/plane)")
+                    dy_in = gr.Number(0.0895, label="dy (µm/px)")
+                    dx_in = gr.Number(0.0895, label="dx (µm/px)")
+                load_btn = gr.Button("① Load & preview", variant="secondary")
+
+                nf_dd = gr.Dropdown(label="Neurofilament channel", choices=[])
+                myo_dd = gr.Dropdown(label="Myo7a channel", choices=[])
+                freq_dd = gr.Dropdown(label="Frequency region",
+                                      choices=P.FREQ_CHOICES,
+                                      value="Other / unknown")
+
+                gr.Markdown("**IHC / OHC region split** (Myo7a-guided)")
+                axis_dd = gr.Radio(["Y", "X"], value="Y",
+                                   label="Split axis (Y = radial, usual)")
+                side_dd = gr.Radio(["Low side = IHC", "High side = IHC"],
+                                   value="Low side = IHC",
+                                   label="Which side is IHC?")
+                boundary_sl = gr.Slider(0.0, 1.0, value=0.5, step=0.005,
+                                        label="Boundary position (fraction "
+                                              "along split axis)")
+
+                gr.Markdown("**Tracing**")
+                sens_sl = gr.Slider(0.5, 1.5, value=1.0, step=0.05,
+                                    label="Sensitivity (↑ = capture more/thinner "
+                                          "fibers)")
+                minfib_sl = gr.Slider(0.0, 20.0, value=5.0, step=0.5,
+                                      label="Min fiber length to count (µm)")
+                run_btn = gr.Button("② Run analysis", variant="primary")
+
+            with gr.Column(scale=2):
+                status = gr.Markdown()
+                with gr.Row():
+                    nf_prev = gr.Image(label="Neurofilament (MIP)",
+                                       height=220)
+                    myo_prev = gr.Image(label="Myo7a (MIP) + boundary",
+                                        height=220)
+                skel_out = gr.Image(label="Traced neurons — white on black",
+                                    height=300)
+                region_out = gr.Image(label="Region overlay (cyan = IHC, "
+                                            "magenta = OHC)", height=300)
+                table = gr.Dataframe(label="Quantification", wrap=True)
+                files_out = gr.Files(label="Downloads (skeleton PNG + Excel)")
+
+        load_btn.click(load_and_preview,
+                       [file_in, dz_in, dy_in, dx_in],
+                       [img_state, nf_dd, myo_dd, freq_dd, boundary_sl,
+                        nf_prev, myo_prev, status])
+        # Live boundary preview
+        for comp in (boundary_sl, myo_dd, axis_dd):
+            comp.change(refresh_boundary_preview,
+                        [img_state, myo_dd, boundary_sl, axis_dd], myo_prev)
+        run_btn.click(run_single,
+                      [img_state, nf_dd, myo_dd, freq_dd, axis_dd, side_dd,
+                       boundary_sl, sens_sl, minfib_sl],
+                      [skel_out, region_out, myo_prev, table, files_out, status])
+
+    with gr.Tab("Batch (multiple images)"):
+        gr.Markdown(
+            "Upload several z-stacks (e.g. all frequency regions of one "
+            "cochlea). Each is auto-traced with an auto-placed IHC/OHC "
+            "boundary, and results are combined into one Excel workbook "
+            "organized by frequency region.")
+        with gr.Row():
+            with gr.Column(scale=1):
+                batch_files = gr.File(label="Upload CZI/TIFF files",
+                                      file_count="multiple",
+                                      file_types=[".czi", ".tif", ".tiff"],
+                                      type="filepath")
+                b_axis = gr.Radio(["Y", "X"], value="Y", label="Split axis")
+                b_side = gr.Radio(["Low side = IHC", "High side = IHC"],
+                                  value="Low side = IHC",
+                                  label="Which side is IHC?")
+                b_sens = gr.Slider(0.5, 1.5, value=1.0, step=0.05,
+                                   label="Sensitivity")
+                b_minfib = gr.Slider(0.0, 20.0, value=5.0, step=0.5,
+                                     label="Min fiber length (µm)")
+                with gr.Accordion("Voxel size (µm) for TIFF", open=False):
+                    b_dz = gr.Number(0.35, label="dz")
+                    b_dy = gr.Number(0.0895, label="dy")
+                    b_dx = gr.Number(0.0895, label="dx")
+                batch_btn = gr.Button("Run batch", variant="primary")
+            with gr.Column(scale=2):
+                batch_log = gr.Textbox(label="Log", lines=6)
+                batch_table = gr.Dataframe(label="Combined quantification",
+                                           wrap=True)
+                batch_files_out = gr.Files(label="Downloads (Excel + ZIP)")
+                batch_gallery = gr.Gallery(label="Skeleton traces",
+                                           columns=3, height=400)
+        batch_btn.click(run_batch,
+                        [batch_files, b_axis, b_side, b_sens, b_minfib,
+                         b_dz, b_dy, b_dx],
+                        [batch_table, batch_files_out, batch_gallery, batch_log])
+
+    gr.Markdown(
+        "---\n*Method:* the Neurofilament channel is smoothed, thresholded "
+        "(Otsu, scaled by the sensitivity control) and skeletonised in 3D; "
+        "length, diameter (from the 3D distance transform), branch points and "
+        "footprint area are measured with physical voxel spacing. Each fiber is "
+        "a connected skeleton component ≥ the minimum length. The Myo7a band "
+        "defines the IHC/OHC boundary, and metrics are reported for each "
+        "region.")
+
+if __name__ == "__main__":
+    demo.launch()

processing.py

@@ -0,0 +1,434 @@
+"""
+Core image-processing pipeline for cochlear neurofilament tracing.
+
+Handles:
+  * Loading Zeiss CZI z-stacks and generic TIFF stacks (with voxel sizes).
+  * Channel identification (Neurofilament vs Myo7a).
+  * 3D tracing of the neurofilament network into a single continuous skeleton.
+  * Myo7a-guided splitting of the field into an IHC region and an OHC region.
+  * Per-region quantification: number of fibers, diameter, length,
+    branch points and area covered within the field of view.
+
+The module has no Gradio dependency so it can be unit-tested on its own.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+from scipy import ndimage as ndi
+from skimage.filters import gaussian, threshold_otsu
+from skimage.morphology import remove_small_objects, skeletonize
+from skan import Skeleton, summarize
+
+# --------------------------------------------------------------------------- #
+#  Data containers
+# --------------------------------------------------------------------------- #
+
+FREQ_CHOICES = ["8kHz", "16kHz", "22kHz", "32kHz", "64kHz", "Other / unknown"]
+
+
+@dataclass
+class LoadedImage:
+    """A loaded multi-channel z-stack."""
+
+    data: np.ndarray               # (C, Z, Y, X) float32
+    channels: list                 # list of dicts: {name, dye, color}
+    voxel: tuple                   # (dz, dy, dx) in microns
+    source_name: str = ""
+
+    @property
+    def n_channels(self) -> int:
+        return self.data.shape[0]
+
+
+@dataclass
+class RegionMetrics:
+    """Quantification for one region (whole field, IHC region or OHC region)."""
+
+    region: str = ""
+    n_fibers: int = 0
+    total_length_um: float = 0.0
+    mean_diameter_um: float = 0.0
+    median_diameter_um: float = 0.0
+    n_branch_points: int = 0
+    area_covered_um2: float = 0.0
+    fov_area_um2: float = 0.0
+    pct_area_covered: float = 0.0
+
+    def as_row(self) -> dict:
+        return {
+            "Region": self.region,
+            "Number of fibers": self.n_fibers,
+            "Total length (um)": round(self.total_length_um, 2),
+            "Mean diameter (um)": round(self.mean_diameter_um, 3),
+            "Median diameter (um)": round(self.median_diameter_um, 3),
+            "Branch points": self.n_branch_points,
+            "Area covered (um^2)": round(self.area_covered_um2, 2),
+            "FOV area (um^2)": round(self.fov_area_um2, 2),
+            "Area covered (% of FOV)": round(self.pct_area_covered, 2),
+        }
+
+
+@dataclass
+class TraceResult:
+    """Everything produced by tracing one image."""
+
+    mask: np.ndarray               # 3D bool
+    skeleton: np.ndarray           # 3D bool
+    distance_um: np.ndarray        # 3D float, EDT in microns
+    voxel: tuple
+    metrics: dict = field(default_factory=dict)   # region name -> RegionMetrics
+
+
+# --------------------------------------------------------------------------- #
+#  Loading
+# --------------------------------------------------------------------------- #
+
+def detect_frequency(filename: str) -> str:
+    """Guess the frequency-region label from a filename (e.g. '16kHz')."""
+    m = re.search(r"(\d+)\s*k\s*hz", filename, re.IGNORECASE)
+    if m:
+        label = f"{int(m.group(1))}kHz"
+        if label in FREQ_CHOICES:
+            return label
+    return "Other / unknown"
+
+
+def _czi_channel_meta(czi) -> list:
+    """Extract per-channel name/dye/color from CZI metadata (best effort)."""
+    meta = czi.meta
+    seen = {}
+    order = []
+    for ch in meta.iter("Channel"):
+        name = ch.get("Name")
+        if not name:
+            continue
+        dye = ch.findtext("DyeName") or ch.findtext("Fluor")
+        color = ch.findtext("Color")
+        ex = ch.findtext("ExcitationWavelength")
+        if name not in seen:
+            seen[name] = {"name": name, "dye": None, "color": None, "ex": None}
+            order.append(name)
+        rec = seen[name]
+        rec["dye"] = rec["dye"] or dye
+        rec["color"] = rec["color"] or color
+        rec["ex"] = rec["ex"] or ex
+    return [seen[n] for n in order]
+
+
+def _czi_voxel(czi) -> tuple:
+    """Return (dz, dy, dx) in microns from CZI scaling metadata."""
+    scale = {}
+    for d in czi.meta.iter("Distance"):
+        idv = d.get("Id")
+        val = d.findtext("Value")
+        if idv in ("X", "Y", "Z") and val:
+            scale[idv] = float(val) * 1e6  # metres -> microns
+    dx = scale.get("X", 0.0895)
+    dy = scale.get("Y", dx)
+    dz = scale.get("Z", 0.35)
+    return (dz, dy, dx)
+
+
+def load_czi(path: str) -> LoadedImage:
+    from aicspylibczi import CziFile
+
+    czi = CziFile(path)
+    img, shp = czi.read_image()
+    dims = [d for d, _ in shp]
+    arr = np.asarray(img)
+    # collapse everything except C, Z, Y, X
+    # find axis indices
+    idx = {d: i for i, d in enumerate(dims)}
+    # move to C,Z,Y,X ordering, squeezing singletons (B,V,T,...)
+    keep = ["C", "Z", "Y", "X"]
+    order = [idx[k] for k in keep if k in idx]
+    other = [i for i in range(arr.ndim) if i not in order]
+    arr = np.transpose(arr, other + order)
+    arr = arr.reshape((-1,) + arr.shape[len(other):]) if other else arr
+    # after reshape leading axis is product of others -> take first
+    if other:
+        arr = arr[0]
+    # arr now (C,Z,Y,X) or missing Z
+    if "Z" not in idx:
+        arr = arr[:, None]
+    arr = arr.astype(np.float32)
+    channels = _czi_channel_meta(czi)
+    if len(channels) != arr.shape[0]:
+        channels = [{"name": f"Channel {i}", "dye": None, "color": None}
+                    for i in range(arr.shape[0])]
+    return LoadedImage(arr, channels, _czi_voxel(czi), os.path.basename(path))
+
+
+def load_tiff(path: str, dz=0.35, dy=0.0895, dx=0.0895) -> LoadedImage:
+    import tifffile
+
+    arr = tifffile.imread(path)
+    arr = np.squeeze(arr)
+    # Heuristic to reach (C, Z, Y, X). The two largest axes are Y, X.
+    if arr.ndim == 2:                       # (Y, X) single channel, single plane
+        arr = arr[None, None]
+    elif arr.ndim == 3:
+        # Could be (Z,Y,X) single channel or (C,Y,X). Assume small first axis = C
+        if arr.shape[0] <= 5:
+            arr = arr[:, None]              # (C, 1, Y, X)
+        else:
+            arr = arr[None]                 # (1, Z, Y, X)
+    elif arr.ndim == 4:
+        # find the two largest axes -> Y, X; of the remaining two the smaller = C
+        yx = sorted(range(4), key=lambda a: arr.shape[a])[-2:]
+        rest = [a for a in range(4) if a not in yx]
+        c_axis = min(rest, key=lambda a: arr.shape[a])
+        z_axis = [a for a in rest if a != c_axis][0]
+        arr = np.transpose(arr, (c_axis, z_axis, *sorted(yx)))
+    else:
+        raise ValueError(f"Unsupported TIFF with {arr.ndim} dimensions")
+    arr = arr.astype(np.float32)
+    channels = [{"name": f"Channel {i}", "dye": None, "color": None}
+                for i in range(arr.shape[0])]
+    return LoadedImage(arr, channels, (dz, dy, dx), os.path.basename(path))
+
+
+def load_image(path: str, dz=0.35, dy=0.0895, dx=0.0895) -> LoadedImage:
+    ext = os.path.splitext(path)[1].lower()
+    if ext == ".czi":
+        return load_czi(path)
+    if ext in (".tif", ".tiff"):
+        return load_tiff(path, dz, dy, dx)
+    raise ValueError(f"Unsupported file type: {ext}")
+
+
+# --------------------------------------------------------------------------- #
+#  Channel identification
+# --------------------------------------------------------------------------- #
+
+# Wavelength-based hints: neurofilament here is Alexa-555 (red/green range),
+# Myo7a is Alexa-405 (blue). Transmitted-light PMT channels have no dye.
+def guess_channels(img: LoadedImage) -> tuple:
+    """Best-effort (neurofilament_index, myo7a_index) from metadata + content."""
+    nf_idx, myo_idx = None, None
+    blue_like, red_like, plain = [], [], []
+    for i, ch in enumerate(img.channels):
+        dye = (ch.get("dye") or "").lower()
+        color = (ch.get("color") or "").upper()
+        ex = ch.get("ex")
+        ex = float(ex) if ex else None
+        if "405" in dye or (ex and ex < 430) or color == "#0000FF":
+            blue_like.append(i)
+        elif dye and dye not in ("", "none"):
+            red_like.append(i)
+        else:
+            plain.append(i)     # e.g. transmitted-light PMT
+    if blue_like:
+        myo_idx = blue_like[0]
+    if red_like:
+        nf_idx = red_like[0]
+
+    # Fall back to image content when metadata is missing (e.g. plain TIFF).
+    # Fluorescence channels have a mostly-dark background; transmitted-light
+    # (brightfield) channels fill the frame, so we skip those.  We cannot
+    # reliably tell fibers from blobs automatically, so we default NF to the
+    # first fluorescent channel and Myo7a to the last — the user confirms
+    # via the channel previews in the UI.
+    if nf_idx is None or myo_idx is None:
+        fluo = [i for i in range(img.n_channels)
+                if _dark_fraction(img.data[i]) >= 0.2]
+        if not fluo:
+            fluo = list(range(img.n_channels))
+        if nf_idx is None:
+            nf_idx = fluo[0]
+        if myo_idx is None or myo_idx == nf_idx:
+            myo_idx = fluo[-1] if fluo[-1] != nf_idx else fluo[0]
+    return nf_idx, myo_idx
+
+
+def _dark_fraction(vol: np.ndarray) -> float:
+    """Fraction of the (normalised) MIP that is near-black background."""
+    mip = vol.max(0).astype(np.float32)
+    mip = (mip - mip.min()) / (np.ptp(mip) + 1e-6)
+    return float((mip < 0.15).mean())
+
+
+# --------------------------------------------------------------------------- #
+#  Neurofilament tracing
+# --------------------------------------------------------------------------- #
+
+def _threshold_volume(vol: np.ndarray, sensitivity: float) -> np.ndarray:
+    """Smooth + Otsu threshold. `sensitivity` (0.5-1.5) scales the threshold;
+    higher sensitivity -> lower threshold -> more fibers captured."""
+    lo, hi = np.percentile(vol, 1), np.percentile(vol, 99.8)
+    norm = np.clip((vol - lo) / (hi - lo + 1e-6), 0, 1)
+    sm = gaussian(norm, sigma=(0.6, 1.0, 1.0), preserve_range=True)
+    fg = sm[sm > sm.mean() * 0.3]
+    base = threshold_otsu(fg) if fg.size else sm.mean()
+    thr = base * (2.0 - sensitivity)        # sensitivity 1.0 -> base
+    return sm > thr
+
+
+def trace_neurites(nf_vol: np.ndarray, voxel: tuple,
+                   sensitivity: float = 1.0,
+                   min_object_vox: int = 64) -> TraceResult:
+    """Segment and skeletonise the neurofilament network in 3D."""
+    dz, dy, dx = voxel
+    mask = _threshold_volume(nf_vol, sensitivity)
+    mask = remove_small_objects(mask, min_object_vox)
+    mask = ndi.binary_closing(mask, iterations=1)
+    if mask.sum() == 0:
+        z = np.zeros_like(mask)
+        return TraceResult(mask, z, np.zeros(mask.shape, np.float32), voxel)
+    skel = skeletonize(mask)
+    dist = ndi.distance_transform_edt(mask, sampling=(dz, dy, dx)).astype(np.float32)
+    return TraceResult(mask, skel, dist, voxel)
+
+
+# --------------------------------------------------------------------------- #
+#  Region definition (IHC vs OHC) from Myo7a
+# --------------------------------------------------------------------------- #
+
+def myo_band_profile(myo_vol: np.ndarray) -> np.ndarray:
+    """Row-wise (Y) intensity profile of the Myo7a hair-cell band."""
+    mip = myo_vol.max(0).astype(np.float32)
+    sm = gaussian(mip, 3, preserve_range=True)
+    return sm.sum(1)
+
+
+def suggest_boundary(myo_vol: np.ndarray) -> float:
+    """Suggest an IHC/OHC boundary as a fraction (0-1) along the Y axis.
+
+    Places the boundary at the centre of the Myo7a hair-cell band, which sits
+    between the (single) IHC row and the (three) OHC rows in a well-oriented
+    organ-of-Corti image.  Users can refine this manually.
+    """
+    prof = myo_band_profile(myo_vol)
+    if prof.sum() == 0:
+        return 0.5
+    ys = np.arange(prof.size)
+    centroid = float((ys * prof).sum() / prof.sum())
+    return centroid / prof.size
+
+
+def make_region_masks(shape_yx: tuple, boundary_frac: float,
+                      ihc_side: str = "low", axis: str = "Y") -> tuple:
+    """Return (ihc_roi, ohc_roi) boolean 2D masks split by a straight line.
+
+    axis="Y" splits along rows (radial axis, the usual case); axis="X" splits
+    along columns.  ihc_side selects which side of the boundary is IHC.
+    """
+    ny, nx = shape_yx
+    low = np.zeros((ny, nx), bool)
+    if axis.upper() == "Y":
+        b = int(round(np.clip(boundary_frac, 0, 1) * ny))
+        low[:b] = True
+    else:
+        b = int(round(np.clip(boundary_frac, 0, 1) * nx))
+        low[:, :b] = True
+    ihc = low if ihc_side == "low" else ~low
+    return ihc, ~ihc
+
+
+# --------------------------------------------------------------------------- #
+#  Quantification
+# --------------------------------------------------------------------------- #
+
+def _branch_point_count(skel: np.ndarray) -> int:
+    if skel.sum() == 0:
+        return 0
+    k = np.ones((3, 3, 3), int) if skel.ndim == 3 else np.ones((3, 3), int)
+    nb = ndi.convolve(skel.astype(np.uint8), k, mode="constant") - skel
+    return int((skel & (nb > 2)).sum())
+
+
+def compute_metrics(trace: TraceResult, region_name: str,
+                    roi_yx: Optional[np.ndarray] = None,
+                    min_fiber_um: float = 5.0) -> RegionMetrics:
+    """Quantify the skeleton, optionally restricted to a 2D ROI (broadcast in Z)."""
+    dz, dy, dx = trace.voxel
+    skel = trace.skeleton
+    mask = trace.mask
+    if roi_yx is not None:
+        roi3d = np.broadcast_to(roi_yx, skel.shape)
+        skel = skel & roi3d
+        mask = mask & roi3d
+
+    m = RegionMetrics(region=region_name)
+    m.fov_area_um2 = float(roi_yx.sum() if roi_yx is not None
+                           else mask.shape[1] * mask.shape[2]) * dx * dy
+
+    foot = mask.max(0)
+    m.area_covered_um2 = float(foot.sum()) * dx * dy
+    m.pct_area_covered = (100.0 * m.area_covered_um2 / m.fov_area_um2
+                          if m.fov_area_um2 else 0.0)
+
+    if skel.sum() < 2:
+        return m
+
+    m.n_branch_points = _branch_point_count(skel)
+
+    diam = 2.0 * trace.distance_um[skel]
+    if diam.size:
+        m.mean_diameter_um = float(diam.mean())
+        m.median_diameter_um = float(np.median(diam))
+
+    # Length and fiber count via skan (per connected skeleton component).
+    try:
+        S = Skeleton(skel, spacing=(dz, dy, dx))
+        df = summarize(S, separator="_")
+        comp_len = df.groupby("skeleton_id")["branch_distance"].sum()
+        kept = comp_len[comp_len >= min_fiber_um]
+        m.n_fibers = int(kept.size)
+        m.total_length_um = float(kept.sum())
+    except Exception:
+        # Fallback: label components, approximate length by voxel count.
+        lbl, n = ndi.label(skel, structure=np.ones((3, 3, 3)))
+        m.n_fibers = int(n)
+        m.total_length_um = float(skel.sum()) * np.mean([dz, dy, dx])
+    return m
+
+
+# --------------------------------------------------------------------------- #
+#  Rendering
+# --------------------------------------------------------------------------- #
+
+def skeleton_image(skel: np.ndarray, dilate: int = 1) -> np.ndarray:
+    """White skeleton on black background (2D uint8), as a MIP over Z."""
+    flat = skel.max(0) if skel.ndim == 3 else skel
+    if dilate:
+        flat = ndi.binary_dilation(flat, iterations=dilate)
+    return (flat * 255).astype(np.uint8)
+
+
+def region_overlay(skel: np.ndarray, ihc_roi: np.ndarray, ohc_roi: np.ndarray,
+                   boundary_frac: float, axis: str = "Y",
+                   dilate: int = 1) -> np.ndarray:
+    """Colour-coded RGB preview: IHC fibers cyan, OHC fibers magenta,
+    with the boundary line drawn in yellow."""
+    flat = skel.max(0) if skel.ndim == 3 else skel
+    if dilate:
+        flat = ndi.binary_dilation(flat, iterations=dilate)
+    ny, nx = flat.shape
+    rgb = np.zeros((ny, nx, 3), np.uint8)
+    ihc_pix = flat & ihc_roi
+    ohc_pix = flat & ohc_roi
+    rgb[ihc_pix] = (0, 220, 255)      # cyan  = IHC
+    rgb[ohc_pix] = (255, 60, 200)     # magenta = OHC
+    if axis.upper() == "Y":
+        b = int(round(np.clip(boundary_frac, 0, 1) * ny))
+        b = min(max(b, 0), ny - 1)
+        rgb[b, :] = (255, 255, 0)
+    else:
+        b = int(round(np.clip(boundary_frac, 0, 1) * nx))
+        b = min(max(b, 0), nx - 1)
+        rgb[:, b] = (255, 255, 0)
+    return rgb
+
+
+def channel_preview(vol: np.ndarray) -> np.ndarray:
+    """Contrast-stretched MIP of a channel for display (uint8)."""
+    mip = vol.max(0).astype(np.float32)
+    lo, hi = np.percentile(mip, 1), np.percentile(mip, 99.5)
+    return (np.clip((mip - lo) / (hi - lo + 1e-6), 0, 1) * 255).astype(np.uint8)

requirements.txt

@@ -0,0 +1,10 @@
+gradio>=5.0
+numpy>=1.26
+scipy>=1.11
+scikit-image>=0.22
+skan>=0.12
+pandas>=2.0
+openpyxl>=3.1
+tifffile>=2024.1.1
+aicspylibczi>=3.1.1
+imagecodecs>=2024.1.1