fp2 / README.md
vikba's picture
Upload folder using huggingface_hub
c0ce05e verified
|
Raw History Blame Contribute Delete
13.2 kB
---
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.
![Fiberpose desktop GUI: instance segmentation with diameter measurements, diameter and orientation histograms](docs/gui.png)
**Try it in the browser:** [Fiberpose on Hugging Face Spaces](https://huggingface.co/spaces/vikba/fiberpose) β€” 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:
1. A neural network predicts a continuous distance-transform field from the input image.
2. Centerlines are extracted as ridges of this field.
3. Fiber instances are separated using centerline markers and distance-transform geometry.
4. 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.
```bash
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):
```bash
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:
1. the folder set in the `FIBERPOSE_MODELS_DIR` environment variable;
2. `checkpoints/` in the repository, when running from a source checkout;
3. the per-user cache (for example `~/Library/Caches/fiberpose/models` on 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
```bash
fiberpose
```
or explicitly:
```bash
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:
```bash
fiberpose --cli --input /path/to/image_or_folder_or_stack
```
Run the full measurement pipeline:
```bash
fiberpose --cli --input /path/to/image_or_folder_or_stack --measurements
```
Write outputs to a selected directory:
```bash
fiberpose --cli --input /path/to/image_or_folder_or_stack --output /path/to/output
```
Use a custom config:
```bash
fiberpose --cli --input /path/to/image_or_folder_or_stack --config /path/to/config.json
```
Export only measurement CSV files:
```bash
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:
```bash
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
```python
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:
```text
.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:
```bash
fiberpose --cli --input /path/to/data --config /path/to/config.json
```
---
## Project structure
```text
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:
```python
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:
```bash
fiberpose --cli --input /path/to/data --measurements
```
---
## Citation
If you use Fiberpose in scientific work, please cite the associated manuscript/preprint when available.
```bibtex
@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.