|
Download PIPELINE.md from vikba/fiberpose: direct link, hf CLI and curl.
- Browser
- Download file 6.94 kB
-
https://huggingface.co/spaces/vikba/fiberpose/resolve/main/PIPELINE.md
- Command line
-
hf download hf://spaces/vikba/fiberpose/PIPELINE.md
-
curl -L -o PIPELINE.md https://huggingface.co/spaces/vikba/fiberpose/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, andsrc/fiberpose/analysis.py. - Covers GUI and CLI startup, segmentation, measurement, and batch execution/export.
Runtime Modes and Flags
segmentation_mode=watershedmakesanalysis.segment(...)run a gradient-masked watershed (watershed_grad_threshold).segmentation_mode=radial_expansionmakesanalysis.segment(...)rasterize the expanded ridge fragments.merge_expansion_factorcontrols overlap-based ridge-fragment merging (default0.7).segmentation_expansion_factorcontrols radial label expansion (default1.0).strict_centerlinesaffects the measurement-centerline filtering stage.keep_segments_without_measurement_centerlineskeeps 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 viewchanges 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;analysisfunctions are stateless andPipelineControllerkeeps only the loaded model.BatchResult:frame_results: list[Frame].dt: model output distance transform (float32).foreground_prob: optional foreground probability (float32) fromnout == 2checkpoints.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:uint16segmentation labels.samples_table,thickness_units,angles_samples_deg,porosity,pores,pore_diams_units: measurement outputs.
Entry Flow
fiberpose.cli.main()(thefiberposecommand) dispatches mode:
- GUI default (
fiberposeorfiberpose --gui) - CLI (
fiberpose --cli --input <path> ...)
- GUI path:
MainWindow.open_source(...)loads input intoImageBatch.- User action calls
segment()oranalyze_fibers(). - If
_image_batchexists and not already in callbacks, GUI routes through_run_batch_analysis(...).
- CLI path:
CliRunnerloads config and source viaImageBatch.from_source(...).- It instantiates
PipelineController(model_path, device), processes each frame, buildsBatchResult, and exports.
Batch Execution Flow
_run_batch_analysis(...)configuresBatchCallbacksand callsBatchService.run_batch(...).BatchService.run_batch(...)loops frames and invokes the provided per-frame callback.- Per-frame callback in
_run_batch_analysis(...):
- create or hydrate
current_framewithFrame.empty(...)or asnapshot()of the cached frame result - run
_run_current_frame_pipeline(...), which callsensure_segmentationorensure_measurements(_is_batch_processing=Truekeepssegment()/analyze_fibers()from re-dispatching a batch) - capture result with
current_frame.snapshot(frame_id=..., z_index=...)
- Collected outputs become
BatchResult(frame_results=[...]). - GUI stores
_batch_resultand rehydrates selected slice with_apply_frame_result(...). - CLI uses the same controller stages (
ensure_segmentation/ensure_measurements) and writes exports viaBatchResult.save_all(...).
Per-Frame Segmentation Flow
ensure_prediction: if the frame has no prediction for the current signature, resolve the scaled processing image and runanalysis.predict(model, image):
- pads to the model stride, runs
OnnxFiberposeModel.predict(...)->(dt, foreground_prob);nout != 2uses the last channel as DT and has no foreground - smooths DT, computes gradients/laplacian; stored via
Frame.set_prediction_outputs(...)
- If the frame's segmentation signature (prediction signature +
segmentation_params(config)) matches, stop. - Otherwise
clear_segmentation()and runanalysis.segment(dt, dt_u8, gx, gy, foreground_prob, **segmentation_params):
RidgeDetector.detect_ridges(...)(raw ridge lines)_group_detected_polylines_into_segmentation_fragments(...)merges ridges whosemerge_expansion_factor * DTdisks 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
- Store the labels and fragments via
set_segmentation_outputs(...). The pipeline draws no images.
Per-Frame Measurement Flow
- GUI
analyze_fibers()or CLI measurement mode ensures prediction + segmentation are ready. - Calls
analysis.sample_centerlines(dt, gx, gy, frame.fragments, spacing_px, frame.scale_factor)returning measurement and drawing samples. - Builds thickness arrays/sample table and orientation stats in
PipelineController. - Computes porosity and pore sampling:
analysis.void_mask_and_pore_dt(dt_u8, thr_u8)analysis.sample_inscribed_circles(...)
- Stores outputs in
Frameviaset_measurement_outputs(...). - 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 frameHxWxC-> single frameZxHxW-> grayscale stackZxHxWxC-> color stack
Class Roles
cli.py: top-level GUI/CLI dispatch and argument parsing (fiberposecommand).analyze()(api.py): public single-image entry point wrappingPipelineController.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 onFrameby 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 inFrame.viewsuntil a stage is recomputed.ImageBatch/Frame/BatchResult(domain.py): runtime data transport/state.RidgeDetector: ridge/junction extraction backend.