Download README.md from vikba/fp2: direct link, hf CLI and curl.
- Browser
- Download file 13.2 kB
-
https://huggingface.co/spaces/vikba/fp2/resolve/main/README.md
- Command line
-
hf download hf://spaces/vikba/fp2/README.md
-
curl -L -o README.md https://huggingface.co/spaces/vikba/fp2/resolve/main/README.md
title: Fiberpose
emoji: π§΅
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.32.0
python_version: '3.12'
app_file: app.py
license: gpl-3.0
Fiberpose
Fiberpose is a research software package for segmentation and quantitative morphometry of fibrous microstructures. Instead of relying on threshold-based binarization, Fiberpose predicts a neural distance-transform field from microscopy images and uses it as a geometric representation for centerline extraction, instance segmentation, diameter measurement, orientation analysis, and pore statistics.
It is designed for fibrous materials where conventional thresholding becomes fragile: dense networks, weak contrast, uneven illumination, touching fibers, and overlapping structures.
Try it in the browser: Fiberpose on Hugging Face Spaces β no installation needed.
Status: research-preview software under active development. Validate outputs on your own data before using them for publication or production decisions.
Key features
- Neural distance-transform prediction from raw microscopy images.
- Fiber centerline extraction using ridge detection on the predicted distance-transform field.
- Instance segmentation of fiber fragments using marker-controlled watershed or radial expansion modes.
- Morphometric analysis of fiber diameter, orientation, orientation index, porosity, and pore-size distributions.
- Interactive desktop GUI for loading images, inspecting intermediate maps, adjusting parameters, visualizing overlays, and exporting results.
- Batch-oriented CLI for reproducible processing of folders and image stacks.
- Publication-oriented exports: distance-transform maps, labels, overlays, diameter/orientation overlays, measurement tables, summaries, and manifests.
Method overview
Fiberpose follows a simple geometric pipeline:
- A neural network predicts a continuous distance-transform field from the input image.
- Centerlines are extracted as ridges of this field.
- Fiber instances are separated using centerline markers and distance-transform geometry.
- Measurements are sampled along centerlines:
- local radius is one pixel plus the mean distance-transform value sampled one pixel away on each side,
- local orientation is estimated from the distance field gradients,
- pore sizes are estimated from the distance transform of the void space.
This makes the distance-transform field the central representation connecting neural inference, segmentation, and quantitative analysis.
Installation
Fiberpose requires Python 3.10 or newer. A fresh conda or virtual environment is recommended.
git clone https://github.com/vikba/Fiberpose.git
cd Fiberpose
conda create -n fiberpose python=3.11 -y
conda activate fiberpose
pip install -e ".[gui]"
This installs Fiberpose in editable mode: changes to the code in src/fiberpose/ take effect without reinstalling. Use pip install -e . (without [gui]) for the CLI and Python API only, without Qt dependencies.
GPU note
Fiberpose runtime inference uses ONNX Runtime. GPU acceleration is available only if your installed ONNX Runtime build exposes CUDAExecutionProvider. If CUDA is unavailable, Fiberpose automatically falls back to CPU execution.
GPU inference needs an NVIDIA GPU with CUDA on Linux or Windows; it is not available on macOS. After installing Fiberpose, replace the CPU build of ONNX Runtime with the GPU build (the two cannot be installed side by side):
pip uninstall -y onnxruntime
pip install onnxruntime-gpu
Running pip install -e . again reinstalls the CPU build, so repeat these two commands afterwards.
Pretrained model
The default model, R108_dt_fg.onnx, ships with the repository in checkpoints/, so a source checkout works offline. Fiberpose looks for models, by file name, in this order:
- the folder set in the
FIBERPOSE_MODELS_DIRenvironment variable; checkpoints/in the repository, when running from a source checkout;- the per-user cache (for example
~/Library/Caches/fiberpose/modelson macOS).
To use your own ONNX model, place it in one of these folders and select it in the GUI, or set model_path in the configuration to its file name or absolute path.
Running Fiberpose
The fiberpose command launches both GUI and CLI modes. python -m fiberpose is equivalent.
GUI mode
fiberpose
or explicitly:
fiberpose --gui
The GUI supports:
- single image, folder, and stack loading;
- raw image, distance-transform, gradient-magnitude, Laplacian, centerline, segmentation, overlay, pore, diameter, and orientation views;
- model selection and CPU/GPU toggle;
- scalebar calibration;
- DT profile plotting;
- batch processing;
- export of masks, overlays, and CSV tables.
CLI mode
Run segmentation on an image, folder, or stack:
fiberpose --cli --input /path/to/image_or_folder_or_stack
Run the full measurement pipeline:
fiberpose --cli --input /path/to/image_or_folder_or_stack --measurements
Write outputs to a selected directory:
fiberpose --cli --input /path/to/image_or_folder_or_stack --output /path/to/output
Use a custom config:
fiberpose --cli --input /path/to/image_or_folder_or_stack --config /path/to/config.json
Export only measurement CSV files:
fiberpose --cli --input /path/to/image_or_folder_or_stack --measurements --save-kind csv
CLI arguments
| Argument | Description |
|---|---|
--gui |
Force GUI mode. |
--cli |
Run command-line processing mode. |
--input <path> |
Input image, folder, or stack. Required in CLI mode. |
--config <path> |
Path to a JSON configuration file. Default: the user configuration file (see Configuration below). |
--output <dir> |
Output directory for exported files. |
--measurements |
Run full measurement pipeline. Without this flag, CLI runs segmentation-only. |
--invert |
Invert image intensities before inference. Useful when fibers are dark on a bright background. |
--save-kind results|csv |
Export full result artifacts or only CSV measurement tables. Default: results. |
--version |
Print the Fiberpose version and exit. |
CLI exit codes
| Code | Meaning |
|---|---|
0 |
Processing finished without failures. |
1 |
Processing finished, but one or more frames failed during processing or export. |
2 |
Invalid arguments, missing input/config/model, or startup/runtime error. |
Web interface
A hosted version runs at https://huggingface.co/spaces/vikba/fiberpose. To run it locally, from the repository folder:
pip install -e ".[web]"
fiberpose --web # http://localhost:7860
The same page runs in Docker (docker build -t fiberpose . && docker run -p 7860:7860 fiberpose)
and as a Hugging Face Gradio Space; .github/workflows/deploy.yml publishes both on a version tag.
Python API
import imageio.v3 as iio
import fiberpose
image = iio.imread("fibers.tif")
result = fiberpose.analyze(image, pixel_size=0.1, unit="um")
print(result.summary["diam_mean"], result.summary["orientation_index"])
result.labels # instance labels (0 = background)
result.distance_transform # predicted distance-transform field
result.diameters # per-sample diameters in `unit`
Pass a fiberpose.AppConfig as the second argument to change model or analysis parameters.
Supported inputs
Fiberpose can process common microscopy image formats, including:
.tif, .tiff, .png, .jpg, .jpeg, .bmp, .webp
Folders are processed as batches. Multi-page TIFF files and image stacks are treated as stack inputs.
Outputs
Depending on the selected export options, Fiberpose can save:
| Output | Description |
|---|---|
*_dt |
Predicted distance-transform map. |
*_labels |
Instance label visualization. |
*_overlay |
Segmentation overlay on the original image. |
*_diameters |
Diameter measurement overlay. |
*_orientations |
Orientation measurement overlay. |
*_outline |
Segmentation outline image. |
*_samples.csv |
Per-sample measurement table. |
*_summary.csv |
Batch-level summary table. |
manifest.json |
Export manifest with written files, skipped outputs, and errors. |
CSV exports include fiber diameter statistics, orientation metrics, porosity, and sample counts when the full measurement pipeline is enabled.
Configuration
Your settings are stored in a per-user configuration file, created from the bundled defaults on first run:
| OS | Location |
|---|---|
| macOS | ~/Library/Application Support/fiberpose/config.json |
| Linux | ~/.config/fiberpose/config.json |
| Windows | %LOCALAPPDATA%\fiberpose\config.json |
The GUI saves its settings there when it closes. Delete the file to restore the defaults.
The configuration controls model path, device preference, image scaling, ridge detection parameters, segmentation mode, centerline filtering, measurement spacing, and export options.
You can edit configuration values in the GUI through the configuration editor or pass a config file directly to the CLI:
fiberpose --cli --input /path/to/data --config /path/to/config.json
Project structure
Fiberpose/
βββ pyproject.toml # Package metadata, dependencies, `fiberpose` command
βββ README.md
βββ PIPELINE.md # Runtime pipeline details
βββ LICENSE
βββ app.py # Entry point of the Hugging Face Space
βββ requirements.txt # Dependencies of the Hugging Face Space
βββ Dockerfile # Web interface as a container
βββ checkpoints/ # Pretrained model (R108_dt_fg.onnx)
βββ docs/ # README images
βββ src/fiberpose/
βββ cli.py # GUI/CLI/web launcher (`fiberpose` command)
βββ api.py # Public Python API: analyze()
βββ models.py # Model lookup, download, and cache
βββ paths.py # Bundled resources and user config locations
βββ web/ # Gradio web interface (`fiberpose --web`)
βββ gui/ # PyQt desktop interface (`fiberpose --gui`)
βββ cli_runner.py # Batch CLI processing
βββ pipeline.py # Pipeline orchestration
βββ analysis.py # Stateless prediction, segmentation, and measurement functions
βββ render.py # Display/export images of a frame (overlays, views)
βββ raster.py # Vectorized disk rasterization helpers
βββ ridge_detector.py # Ridge/centerline detector
βββ ml.py # ONNX Runtime inference wrapper
βββ domain.py # Data models and configuration
βββ io_export.py # Export services
βββ utils.py # Numeric and image helper functions
βββ resources/
βββ config.json # Default configuration
βββ fiber_tool.ui # Qt GUI layout
βββ test.png # Example image
βββ example_*.png # More examples for the web interface
Troubleshooting
Model file not found
The default model is expected in checkpoints/ of the source checkout. If Fiberpose runs from elsewhere, copy R108_dt_fg.onnx into a folder and point FIBERPOSE_MODELS_DIR at it. For a custom model, check that model_path in your configuration is a file name in the models folder or an absolute path.
GPU is not used
Confirm that ONNX Runtime sees CUDA:
import onnxruntime as ort
print(ort.get_available_providers())
If CUDAExecutionProvider is missing, install the correct ONNX Runtime GPU package for your platform.
Segmentation is inverted or poor
Try the --invert CLI flag or the invert option in the GUI if your fibers are dark on a bright background.
Measurements are missing
Run the full analysis pipeline, not segmentation-only:
fiberpose --cli --input /path/to/data --measurements
Citation
If you use Fiberpose in scientific work, please cite the associated manuscript/preprint when available.
@software{fiberpose,
title = {Fiberpose: A deep learning framework for segmentation and quantitative analysis of fibrous structures},
author = {Balashov, Viktor},
year = {2026},
url = {https://github.com/vikba/Fiberpose}
}
License
Fiberpose is free software licensed under the GNU General Public License,
version 3 only (GPL-3.0-only). See LICENSE for details.
Disclaimer
Fiberpose is research software for microscopy image analysis. It is not a medical device and should not be used for clinical diagnosis or treatment decisions.
