CV Zebrafish

Desktop toolkit for validating DeepLabCut zebrafish CSVs, generating JSON configs, running kinematic calculations, and rendering Plotly graphs through a PyQt UI.

A smaller web app runs the same zebrafish analysis in the browser, with nothing to install: oss-slu.github.io/cv_zebrafish (details in web_prototype/README.md).

Quickstart

Prereqs

• Python 3.10+
• Git
• System packages for Qt (Windows: included with PyQt5 wheels; macOS/Linux may need Qt libraries)

Setup

Conda (recommended)

conda env create -f environment.yml
conda activate cv-zebrafish
pip install -e .

environment.yml declares Python 3.10 and all app/test dependencies; prefer this over ad-hoc pip installs.

### Plotly/Kaleido image export

The application uses Plotly and Kaleido to export graphs as PNG images. Kaleido may require Google Chrome or Chromium to be installed for image export.

If PNG export reports that Chrome is missing, install Google Chrome or Chromium and restart the application.

### Run the UI
```bash
python app.py

This opens the main window and starts the step-by-step workflow. The progress indicator shows which scene you're in: the flow walks through CSV/JSON selection, validation, config generation calculations, and graph viewing.

Run tests

pytest

User Workflow

The app follows a 6-step linear workflow guided by a progress bar at the top of the window (green = completed, blue = current, gray = upcoming) | 1 | Verify Input | Upload CSV file(s) or a folder + a JSON config; validation runs automatically and results appear in the console below | | 2 | Generate Config | Set body points, video scale, and graph options across tabs, then save to include the new JSON in the current session | | 3 | Select Config | In the session file tree, pick a CSV and a config JSON, then click Run Calculation; right-click rows for extra options | | 4 | Run Calculation | Kinematic metrics computed in a background thread; a progress bar shows status; click Stop to cancel mid-run | | 5 | View Graphs | Browse Plotly graphs by name; use the Compare tab for side-by-side views; use Cross-Correlation for lag analysis | | 6 | Export | PNG figures and enriched CSVs are saved to the configured output directory for reports |

Project Layout (current)

app.py                         # PyQt entry point (adds src/ to sys.path)
assets/
├── images/                    # UI icons / art
└── sample_data/               # Example configs/CSVs (paired with data/samples)
data/
└── samples/
   ├── csv/                   # DLC CSV fixtures used by UI/tests
   └── jsons/                 # BaseConfig + generated config examples
docs/
├── architecture/              # Calculation/graph design notes
├── howtos/                    # UI + validation how-tos
└── product/                   # Product summary, presentations, meeting minutes
legacy/                        # Original pipeline for regression comparisons
src/
├── app_platform/paths.py      # Writable paths/utilities
├── core/
│   ├── calculations/          # Metrics, driver, enriched exports
│   ├── comparison/            # Dataset comparison engine
│   ├── config/configSetup.py  # Config discovery/merging
│   ├── graphs/                # Loader, runner, Plotly plotters (fin/tail, spines)
│   ├── parsing/Parser.py      # DLC CSV parser + body part detection
│   └── validation/            # CSV/JSON validators + config generator
├── data/                      # DB ingestion helpers
├── session/                   # Session persistence for the UI
└── ui/
    ├── components/            # Shared widgets: sliders, checkboxes, ProgressIndicator, etc.
    ├── main_panels/           # Main workflow panels
    ├── popup_panels/          # Dialogs and popup panels
    ├── main_window_shell.py   # Main window shell
    └── workers/               # Background calculation workers
tests/
└── unit/                      # Core + UI unit tests (pytest)

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗