openfcd 0.0.1__tar.gz

openfcd-0.0.1/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# macOS
+.DS_Store
+._*
+
+# Editor
+.idea/
+.vscode/
+*.swp
+*~
+
+# OpenFCD runtime / local state
+*.ofcd/autosave/
+*.ofcd/runs/
+reference_built.npy
+
+# Claude Code / OMC local orchestration
+.omc/
+.claude/
+.omx/
+.sisyphus/
+.code-review-graph/
+
+# Local scratch
+test_crash*.py
+progress.txt
+scratch/
+tmp/
+tests/scratch/
+.gitnexus
+*.bak
+~$*
+
+# Internal dev / reference material — not for distribution or remote
+design/
+docs/
+AGENTS.md
+CLAUDE.md
+*.pptx

openfcd-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenFCD contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openfcd-0.0.1/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: openfcd
+Version: 0.0.1
+Summary: Fast Checkerboard Demodulation desktop app for free-surface reconstruction
+License: MIT License
+        
+        Copyright (c) 2026 OpenFCD contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: h5py>=3.10
+Requires-Dist: loky>=3.4
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.6
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: scikit-image>=0.22
+Requires-Dist: scipy>=1.12
+Requires-Dist: threadpoolctl>=3.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: gui
+Requires-Dist: pyqt6>=6.6; extra == 'gui'
+Requires-Dist: pyqtgraph>=0.13; extra == 'gui'
+Description-Content-Type: text/markdown
+
+# OpenFCD
+
+**Fast Checkerboard Demodulation for free-surface reconstruction — desktop app + CLI.**
+
+Reconstructs the free-surface height field η(x, y, t) from high-speed video of
+a checkerboard pattern viewed through water, using the Wildeman / Moisy
+*synthetic schlieren* FCD algorithm. Designed for thin-film wave studies,
+sloshing experiments, mm-scale swimming-robot wakes, and any free-surface
+experiment that films a patterned backdrop through a transparent fluid.
+
+## Status
+
+**v0.0.1** — early release. Core pipeline and GUI are functional; expect
+rough edges. Contributions welcome.
+
+## Features
+
+- **End-to-end desktop GUI** (PyQt6) with a STAR-CCM+-style 3-pane layout:
+  simulation tree · scene tabs · properties.
+- **First-class CLI** (`openfcd run path.ofcd`) — GUI and CLI share the same
+  pipeline, producing byte-identical `results.h5`.
+- **Per-frame debug mode** — compute a single frame, tune parameters live with
+  a slider, re-compute without re-running the whole sequence.
+- **Robust to imperfect reference frames**:
+  - Automatic carrier-period *scale normalization* when the reference was
+    captured at a slightly different zoom
+  - Optional spatial high-pass to remove non-physical low-frequency drift from
+    cross-session ref/def pairs
+- **Project files on disk** — `*.ofcd/` directories contain a git-friendly
+  `project.yaml`, snapshot runs under `runs/{id}/`, and annotations under
+  `annotations/default.json`.
+- **HDF5 results** with SWMR so scripts can tail the output while a run is in
+  progress.
+- **Session resume on re-open** — re-opening a previously-computed `.ofcd`
+  lands directly on the last saved state: frames are filtered, reference is
+  set, the most recent run's η overlay is restored, and the annotation
+  ROI/mask is populated. Stale `last_run_id` self-heals when the result
+  file is missing. Use *File → Re-import Frames…* to re-run the import flow
+  (blocked while a run is active).
+- **Window/splitter geometry persisted** across sessions via `QSettings`.
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+# Clone and install in development mode with GUI
+git clone https://github.com/xunhe730/OpenFCD.git
+cd OpenFCD
+pip install -e '.[gui,dev]'
+```
+
+For CLI-only usage (no PyQt6 dependency):
+
+```bash
+pip install -e '.[dev]'
+```
+
+## Quick start
+
+### GUI
+
+```bash
+python -m openfcd.gui
+# or
+python -m openfcd
+```
+
+Workflow:
+
+1. **File → New Project** → point at a folder of image frames, set the
+   checker cell side length (mm), window thickness, fluid depth.
+2. Click a frame in the tree → **Set as Reference** (pick a flat-water frame
+   captured in the same session).
+3. Draw an ROI + optional occlusion polygon on the preview.
+4. Click **Compute This Frame** to preview one frame.
+5. Tune the **Highpass σ** slider if the result shows large-scale drift.
+6. Click **Run All Frames** when satisfied.
+
+### CLI
+
+```bash
+# Create a new project
+openfcd new myproject --image-folder /path/to/frames --pattern 'Img*.jpg'
+
+# Edit myproject.ofcd/project.yaml for geometry & process parameters,
+# then run
+openfcd run myproject.ofcd
+
+# Results land under myproject.ofcd/runs/{timestamp}/results.h5
+
+# Render QC panels for a frame or for all frames in a run
+openfcd qc-summary myproject.ofcd --run run-YYYYMMDD-HHMMSS --frame 0 -o qc.png
+openfcd qc-summary myproject.ofcd --run run-YYYYMMDD-HHMMSS --all --output-dir qc/
+
+# Estimate flat-water noise floor and calibration sensitivity
+openfcd noise-floor myproject.ofcd --from-run run-YYYYMMDD-HHMMSS -o noise_floor.json
+openfcd sensitivity myproject.ofcd --run run-YYYYMMDD-HHMMSS --frame 0 -o sensitivity.json
+```
+
+## Algorithm notes
+
+FCD measures η by comparing the apparent displacement of a checkerboard
+pattern seen through the water surface. The algorithm steps:
+
+1. **Flatfield** (`openfcd.core.flatfield`) — divide out smooth illumination
+   variation using a Gaussian background.
+2. **Carrier detection** (`openfcd.core.fcd.calculate_carriers`) — find the
+   two dominant spatial-frequency peaks of the checkerboard in k-space.
+3. **Scale normalization** (`openfcd.core.registration`) — if the reference
+   and deformed frames were shot at slightly different zooms, rescale the
+   reference to match the deformed frame's carrier period. Triggers at 0.5 %
+   mismatch.
+4. **Occlusion inpaint** — mask the robot/object and replace with a
+   synthesized carrier field so the FCD demodulation sees continuous texture.
+5. **Cosine taper** — soften image boundaries to suppress FFT edge artifacts.
+6. **Demodulation + phase unwrap** (`openfcd.core.fcd.fcd`) — extract the
+   pixel-displacement field (u, v) at each carrier.
+7. **Poisson integration** (`fftinvgrad`) — integrate (u, v) to get the
+   apparent depth, then calibrate to mm using the optical stack geometry.
+8. **Post-processing** — plane detrend, filament suppression, optional
+   high-pass filter, edge NaN margin.
+
+`geometry.pattern_period_mm` is the legacy project-file key, but its physical
+meaning is `checker_cell_mm`: the side length of one single checkerboard cell,
+not the full black-white cycle. The carrier calibration assumes
+`|k_phys| = π√2 / checker_cell_mm`.
+
+Each computed frame stores a QC verdict (`PASS`, `WARN`, or `FAIL`) plus the
+stats and QC maps used to reach it. The default warning/fail thresholds are
+kept under `project.qc`: saturated ratio 0.001, invalid ratio 0.20,
+carrier amplitude median minimum 1e-6, normalized Poisson/curl residual
+warning 0.10 and fail 0.20, and phase warning at 0.7π / fail at 0.9π. These
+are conservative starting points and should be calibrated against flat-water
+data for each optical setup.
+
+Physical correctness depends on the reference frame. Best results come from
+a flat-water reference captured in the same acquisition session as the
+deformed frames. For cross-session references the high-pass filter (slider
+in the GUI, `process.highpass_sigma_px` in project.yaml) removes
+low-frequency drift.
+
+## Project structure
+
+```
+openfcd/
+├── core/          # FCD algorithm (fcd, flatfield, inpaint, mask, …)
+├── geometry/      # Optical-stack calibration
+├── io/            # project.yaml schema, HDF5 results, annotations
+├── pipeline/      # Stage protocol + orchestration
+├── cli/           # Typer CLI (new / run / replay / project)
+└── gui/           # PyQt6 GUI (main window, panels, scenes, renderers)
+```
+
+## Development
+
+```bash
+# Run tests
+pytest
+
+# Lint
+ruff check openfcd tests
+```
+
+Golden-comparison tests (`tests/golden/`) require a local BOS reference
+dataset. Set `OPENFCD_BOS_ROOT` to the dataset root to enable them; otherwise
+they are skipped.
+
+## License
+
+[MIT](LICENSE) — see `LICENSE` for full text.
+
+## Acknowledgements
+
+The FCD method is due to Moisy, Rabaud & Salsac (2009), "A synthetic
+Schlieren method for the measurement of the topography of a liquid
+interface", and Wildeman (2018), "Real-time quantitative Schlieren imaging
+by fast Fourier demodulation of a checkered backdrop". This project's
+reference implementation follows Wildeman's **pyfcd** approach, extended
+with a PyQt6 GUI, CLI, and engineering polish for experimental use.

openfcd-0.0.1/README.md

@@ -0,0 +1,180 @@
+# OpenFCD
+
+**Fast Checkerboard Demodulation for free-surface reconstruction — desktop app + CLI.**
+
+Reconstructs the free-surface height field η(x, y, t) from high-speed video of
+a checkerboard pattern viewed through water, using the Wildeman / Moisy
+*synthetic schlieren* FCD algorithm. Designed for thin-film wave studies,
+sloshing experiments, mm-scale swimming-robot wakes, and any free-surface
+experiment that films a patterned backdrop through a transparent fluid.
+
+## Status
+
+**v0.0.1** — early release. Core pipeline and GUI are functional; expect
+rough edges. Contributions welcome.
+
+## Features
+
+- **End-to-end desktop GUI** (PyQt6) with a STAR-CCM+-style 3-pane layout:
+  simulation tree · scene tabs · properties.
+- **First-class CLI** (`openfcd run path.ofcd`) — GUI and CLI share the same
+  pipeline, producing byte-identical `results.h5`.
+- **Per-frame debug mode** — compute a single frame, tune parameters live with
+  a slider, re-compute without re-running the whole sequence.
+- **Robust to imperfect reference frames**:
+  - Automatic carrier-period *scale normalization* when the reference was
+    captured at a slightly different zoom
+  - Optional spatial high-pass to remove non-physical low-frequency drift from
+    cross-session ref/def pairs
+- **Project files on disk** — `*.ofcd/` directories contain a git-friendly
+  `project.yaml`, snapshot runs under `runs/{id}/`, and annotations under
+  `annotations/default.json`.
+- **HDF5 results** with SWMR so scripts can tail the output while a run is in
+  progress.
+- **Session resume on re-open** — re-opening a previously-computed `.ofcd`
+  lands directly on the last saved state: frames are filtered, reference is
+  set, the most recent run's η overlay is restored, and the annotation
+  ROI/mask is populated. Stale `last_run_id` self-heals when the result
+  file is missing. Use *File → Re-import Frames…* to re-run the import flow
+  (blocked while a run is active).
+- **Window/splitter geometry persisted** across sessions via `QSettings`.
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+# Clone and install in development mode with GUI
+git clone https://github.com/xunhe730/OpenFCD.git
+cd OpenFCD
+pip install -e '.[gui,dev]'
+```
+
+For CLI-only usage (no PyQt6 dependency):
+
+```bash
+pip install -e '.[dev]'
+```
+
+## Quick start
+
+### GUI
+
+```bash
+python -m openfcd.gui
+# or
+python -m openfcd
+```
+
+Workflow:
+
+1. **File → New Project** → point at a folder of image frames, set the
+   checker cell side length (mm), window thickness, fluid depth.
+2. Click a frame in the tree → **Set as Reference** (pick a flat-water frame
+   captured in the same session).
+3. Draw an ROI + optional occlusion polygon on the preview.
+4. Click **Compute This Frame** to preview one frame.
+5. Tune the **Highpass σ** slider if the result shows large-scale drift.
+6. Click **Run All Frames** when satisfied.
+
+### CLI
+
+```bash
+# Create a new project
+openfcd new myproject --image-folder /path/to/frames --pattern 'Img*.jpg'
+
+# Edit myproject.ofcd/project.yaml for geometry & process parameters,
+# then run
+openfcd run myproject.ofcd
+
+# Results land under myproject.ofcd/runs/{timestamp}/results.h5
+
+# Render QC panels for a frame or for all frames in a run
+openfcd qc-summary myproject.ofcd --run run-YYYYMMDD-HHMMSS --frame 0 -o qc.png
+openfcd qc-summary myproject.ofcd --run run-YYYYMMDD-HHMMSS --all --output-dir qc/
+
+# Estimate flat-water noise floor and calibration sensitivity
+openfcd noise-floor myproject.ofcd --from-run run-YYYYMMDD-HHMMSS -o noise_floor.json
+openfcd sensitivity myproject.ofcd --run run-YYYYMMDD-HHMMSS --frame 0 -o sensitivity.json
+```
+
+## Algorithm notes
+
+FCD measures η by comparing the apparent displacement of a checkerboard
+pattern seen through the water surface. The algorithm steps:
+
+1. **Flatfield** (`openfcd.core.flatfield`) — divide out smooth illumination
+   variation using a Gaussian background.
+2. **Carrier detection** (`openfcd.core.fcd.calculate_carriers`) — find the
+   two dominant spatial-frequency peaks of the checkerboard in k-space.
+3. **Scale normalization** (`openfcd.core.registration`) — if the reference
+   and deformed frames were shot at slightly different zooms, rescale the
+   reference to match the deformed frame's carrier period. Triggers at 0.5 %
+   mismatch.
+4. **Occlusion inpaint** — mask the robot/object and replace with a
+   synthesized carrier field so the FCD demodulation sees continuous texture.
+5. **Cosine taper** — soften image boundaries to suppress FFT edge artifacts.
+6. **Demodulation + phase unwrap** (`openfcd.core.fcd.fcd`) — extract the
+   pixel-displacement field (u, v) at each carrier.
+7. **Poisson integration** (`fftinvgrad`) — integrate (u, v) to get the
+   apparent depth, then calibrate to mm using the optical stack geometry.
+8. **Post-processing** — plane detrend, filament suppression, optional
+   high-pass filter, edge NaN margin.
+
+`geometry.pattern_period_mm` is the legacy project-file key, but its physical
+meaning is `checker_cell_mm`: the side length of one single checkerboard cell,
+not the full black-white cycle. The carrier calibration assumes
+`|k_phys| = π√2 / checker_cell_mm`.
+
+Each computed frame stores a QC verdict (`PASS`, `WARN`, or `FAIL`) plus the
+stats and QC maps used to reach it. The default warning/fail thresholds are
+kept under `project.qc`: saturated ratio 0.001, invalid ratio 0.20,
+carrier amplitude median minimum 1e-6, normalized Poisson/curl residual
+warning 0.10 and fail 0.20, and phase warning at 0.7π / fail at 0.9π. These
+are conservative starting points and should be calibrated against flat-water
+data for each optical setup.
+
+Physical correctness depends on the reference frame. Best results come from
+a flat-water reference captured in the same acquisition session as the
+deformed frames. For cross-session references the high-pass filter (slider
+in the GUI, `process.highpass_sigma_px` in project.yaml) removes
+low-frequency drift.
+
+## Project structure
+
+```
+openfcd/
+├── core/          # FCD algorithm (fcd, flatfield, inpaint, mask, …)
+├── geometry/      # Optical-stack calibration
+├── io/            # project.yaml schema, HDF5 results, annotations
+├── pipeline/      # Stage protocol + orchestration
+├── cli/           # Typer CLI (new / run / replay / project)
+└── gui/           # PyQt6 GUI (main window, panels, scenes, renderers)
+```
+
+## Development
+
+```bash
+# Run tests
+pytest
+
+# Lint
+ruff check openfcd tests
+```
+
+Golden-comparison tests (`tests/golden/`) require a local BOS reference
+dataset. Set `OPENFCD_BOS_ROOT` to the dataset root to enable them; otherwise
+they are skipped.
+
+## License
+
+[MIT](LICENSE) — see `LICENSE` for full text.
+
+## Acknowledgements
+
+The FCD method is due to Moisy, Rabaud & Salsac (2009), "A synthetic
+Schlieren method for the measurement of the topography of a liquid
+interface", and Wildeman (2018), "Real-time quantitative Schlieren imaging
+by fast Fourier demodulation of a checkered backdrop". This project's
+reference implementation follows Wildeman's **pyfcd** approach, extended
+with a PyQt6 GUI, CLI, and engineering polish for experimental use.

openfcd-0.0.1/openfcd/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

openfcd-0.0.1/openfcd/__main__.py

@@ -0,0 +1,4 @@
+from openfcd.cli import app
+
+if __name__ == "__main__":
+    app()