fiberpose / PIPELINE.md
vikba's picture
Upload folder using huggingface_hub
b21f8dc verified
|
Raw History Blame Contribute Delete
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> ...)
  1. 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(...).
  1. 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=...)
  1. Collected outputs become BatchResult(frame_results=[...]).
  2. GUI stores _batch_result and rehydrates selected slice with _apply_frame_result(...).
  3. 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(...)
  1. If the frame's segmentation signature (prediction signature + segmentation_params(config)) matches, stop.
  2. 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
  1. 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(...)
  1. Stores outputs in Frame via set_measurement_outputs(...).
  2. 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.