File size: 6,940 Bytes
beb4f15
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
# 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.