README.md

---
title: Cochlear Neurofilament Tracer
emoji: 🧠
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
---

# 🧠 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.
   Optionally, **Detect hair cells** runs **Cellpose** (or a classical
   watershed fallback) on the Myo7a channel to mark hair cells, count them per
   region, and *propose* a boundary + side with a confidence score. On dense
   fields this detection is often incomplete, so it is a **visual assist**: the
   quantified numbers come from the deterministic pipeline and the boundary
   stays under your control. Detection is much better on a GPU Space.
3. Computes, per region (Whole field / IHC / OHC):
   - **Number of fibers** (continuous skeleton components above a minimum length)
   - **Hair cells (Myo7a)** counted in the region (when detection is run)
   - **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
```