|
Download PIPELINE.md from vikba/fp2: direct link, hf CLI and curl.
- Browser
- Download file 6.94 kB
-
https://huggingface.co/spaces/vikba/fp2/resolve/main/PIPELINE.md
- Command line
-
hf download hf://spaces/vikba/fp2/PIPELINE.md
-
curl -L -o PIPELINE.md https://huggingface.co/spaces/vikba/fp2/resolve/main/PIPELINE.md
6.94 kB
| # Fiberpose Pipeline | |
| ## Scope | |
| - Documents runtime behavior in `src/fiberpose/cli.py`, `src/fiberpose/gui/main_window.py`, `src/fiberpose/pipeline.py`, and `src/fiberpose/analysis.py`. | |
| - Covers GUI and CLI startup, segmentation, measurement, and batch execution/export. | |
| ## Runtime Modes and Flags | |
| - `segmentation_mode=watershed` makes `analysis.segment(...)` run a gradient-masked watershed (`watershed_grad_threshold`). | |
| - `segmentation_mode=radial_expansion` makes `analysis.segment(...)` rasterize the expanded ridge fragments. | |
| - `merge_expansion_factor` controls overlap-based ridge-fragment merging (default `0.7`). | |
| - `segmentation_expansion_factor` controls radial label expansion (default `1.0`). | |
| - `strict_centerlines` affects the measurement-centerline filtering stage. | |
| - `keep_segments_without_measurement_centerlines` keeps segmentation fragments even when no measurement centerline survives filtering. | |
| - `scale factor` (`cb_scale`) rescales input for prediction/segmentation and rescales thresholds/measurements back to original units. | |
| - `pores view` changes overlay/histogram to pore circles and pore diameter distribution. | |
| ## Core Runtime Data | |
| - `ImageBatch`: ordered list of frames plus metadata (`filenames`, `z_indices`, `source_type`). | |
| - `Frame`: per-slice state container (`orig_img`, prediction outputs, segmentation outputs, measurement outputs). It is the only owner of per-image state; `analysis` functions are stateless and `PipelineController` keeps only the loaded model. | |
| - `BatchResult`: `frame_results: list[Frame]`. | |
| - `dt`: model output distance transform (`float32`). | |
| - `foreground_prob`: optional foreground probability (`float32`) from `nout == 2` checkpoints. | |
| - `dt_u8`, `dt_normalized`, `gx`, `gy`, `laplacian`: cached prediction products. | |
| - `fragments`: `list[FiberFragment]` that own a label; each carries its segmentation and measurement centerlines. | |
| - `labels_2d`: `uint16` segmentation labels. | |
| - `samples_table`, `thickness_units`, `angles_samples_deg`, `porosity`, `pores`, `pore_diams_units`: measurement outputs. | |
| ## Entry Flow | |
| 1. `fiberpose.cli.main()` (the `fiberpose` command) dispatches mode: | |
| - GUI default (`fiberpose` or `fiberpose --gui`) | |
| - CLI (`fiberpose --cli --input <path> ...`) | |
| 2. GUI path: | |
| - `MainWindow.open_source(...)` loads input into `ImageBatch`. | |
| - User action calls `segment()` or `analyze_fibers()`. | |
| - If `_image_batch` exists and not already in callbacks, GUI routes through `_run_batch_analysis(...)`. | |
| 3. CLI path: | |
| - `CliRunner` loads config and source via `ImageBatch.from_source(...)`. | |
| - It instantiates `PipelineController(model_path, device)`, processes each frame, builds `BatchResult`, and exports. | |
| ## Batch Execution Flow | |
| 1. `_run_batch_analysis(...)` configures `BatchCallbacks` and calls `BatchService.run_batch(...)`. | |
| 2. `BatchService.run_batch(...)` loops frames and invokes the provided per-frame callback. | |
| 3. Per-frame callback in `_run_batch_analysis(...)`: | |
| - create or hydrate `current_frame` with `Frame.empty(...)` or a `snapshot()` of the cached frame result | |
| - run `_run_current_frame_pipeline(...)`, which calls `ensure_segmentation` or `ensure_measurements` (`_is_batch_processing=True` keeps `segment()` / `analyze_fibers()` from re-dispatching a batch) | |
| - capture result with `current_frame.snapshot(frame_id=..., z_index=...)` | |
| 4. Collected outputs become `BatchResult(frame_results=[...])`. | |
| 5. GUI stores `_batch_result` and rehydrates selected slice with `_apply_frame_result(...)`. | |
| 6. CLI uses the same controller stages (`ensure_segmentation` / `ensure_measurements`) and writes exports via `BatchResult.save_all(...)`. | |
| ## Per-Frame Segmentation Flow | |
| 1. `ensure_prediction`: if the frame has no prediction for the current signature, resolve the scaled processing image and run `analysis.predict(model, image)`: | |
| - pads to the model stride, runs `OnnxFiberposeModel.predict(...)` -> `(dt, foreground_prob)`; `nout != 2` uses the last channel as DT and has no foreground | |
| - smooths DT, computes gradients/laplacian; stored via `Frame.set_prediction_outputs(...)` | |
| 2. If the frame's segmentation signature (prediction signature + `segmentation_params(config)`) matches, stop. | |
| 3. Otherwise `clear_segmentation()` and run `analysis.segment(dt, dt_u8, gx, gy, foreground_prob, **segmentation_params)`: | |
| - `RidgeDetector.detect_ridges(...)` (raw ridge lines) | |
| - `_group_detected_polylines_into_segmentation_fragments(...)` merges ridges whose `merge_expansion_factor * DT` disks overlap | |
| - `_filter_measurement_centerlines(...)` derives measurement centerlines; the shortest fraction is dropped | |
| - `_filter_fragments_by_grad_quality(...)` drops fragments with unreliable DT gradients | |
| - watershed thresholds the DT gradient magnitude, unions two 3x3 dilations of the centerline markers, then applies erode -> dilate; radial_expansion rasterizes the expanded fragments | |
| - foreground, when available, prunes labels; only fragments that keep a label are returned | |
| 4. Store the labels and fragments via `set_segmentation_outputs(...)`. The pipeline draws no images. | |
| ## Per-Frame Measurement Flow | |
| 1. GUI `analyze_fibers()` or CLI measurement mode ensures prediction + segmentation are ready. | |
| 2. Calls `analysis.sample_centerlines(dt, gx, gy, frame.fragments, spacing_px, frame.scale_factor)` returning measurement and drawing samples. | |
| 3. Builds thickness arrays/sample table and orientation stats in `PipelineController`. | |
| 4. Computes porosity and pore sampling: | |
| - `analysis.void_mask_and_pore_dt(dt_u8, thr_u8)` | |
| - `analysis.sample_inscribed_circles(...)` | |
| 5. Stores outputs in `Frame` via `set_measurement_outputs(...)`. | |
| 6. GUI shows the selected view and histograms: | |
| - thickness histogram always | |
| - angles histogram or pore size histogram depending on pores view | |
| ## Stack Input | |
| Stack input normalization in `ImageBatch._normalize_stack(...)`: | |
| - `HxW` -> single frame | |
| - `HxWxC` -> single frame | |
| - `ZxHxW` -> grayscale stack | |
| - `ZxHxWxC` -> color stack | |
| ## Class Roles | |
| - `cli.py`: top-level GUI/CLI dispatch and argument parsing (`fiberpose` command). | |
| - `analyze()` (`api.py`): public single-image entry point wrapping `PipelineController`. | |
| - `MainWindow` (`gui/main_window.py`): GUI orchestration, UI state, view updates, and user-triggered batch runs. | |
| - `CliRunner` (`cli_runner.py`): CLI orchestration for batch processing/export. | |
| - `PipelineController` (`pipeline.py`): shared processing engine; owns the lazily loaded model and caches each stage on `Frame` by signature. | |
| - `BatchService` (`pipeline.py`): frame iteration orchestration using callbacks. | |
| - `analysis.py`: stateless prediction, centerline extraction, segmentation, pore and measurement functions. | |
| - `render(frame, view)` (`render.py`): builds every displayed or exported image from frame data on demand and caches it in `Frame.views` until a stage is recomputed. | |
| - `ImageBatch` / `Frame` / `BatchResult` (`domain.py`): runtime data transport/state. | |
| - `RidgeDetector`: ridge/junction extraction backend. | |