fabrictensor 1.0.0

Stereological estimation of second- and fourth-order fabric tensors from micro-CT images

fabrictensor

fabrictensor is a Python library for estimating second- and fourth-order fabric tensors from three-dimensional binary micro-CT image stacks. Five independent stereological methods are implemented, each probing a distinct positive orientation measure on the unit sphere S².

Methods

Key	Method	M2	M4 PSD
MIL	Mean Intercept Length (Harrigan & Mann 1984)	approx.	projected
SVD	Star Volume Distribution	approx.	exact
SKELETON	Trabecular skeletonization	exact	exact
INTERCEPTS	Second moment of intercept length distribution	approx.	exact
S2	Two-point correlation function via FFT	approx.	projected

Installation

pip install fabrictensor

Or from source:

git clone https://github.com/salsessa/fabrictensor.git
cd fabrictensor
pip install -e .

Dependencies

numpy
scipy
scikit-image
Pillow
matplotlib
pydicom      # only for DICOM input

Quick start

from fabrictensor import (
    load_stack, threshold_stack,
    centered_sphere_mask, icosahedral_directions, add_random_spin,
    compute_intercept_moments_all,
    fit_fabric_tensor, fit_fabric_tensor_M4_intercepts,
    fabric_eigendecomposition, fabric_indices,
)

# Load a folder of TIFF slices
vol, _ = load_stack("path/to/rve/")
binary, thr, bvtv = threshold_stack(vol, method="otsu")

# Direction grid
mask = centered_sphere_mask(binary.shape)
dirs = add_random_spin(icosahedral_directions(subdivisions=3), seed=42)

# Compute M2 and M4 (INTERCEPTS method)
mil_vals, mil2_vals = compute_intercept_moments_all(
    binary, mask, dirs, n_rays=5000, seed=42)

M2 = fit_fabric_tensor(dirs, mil_vals, method="MIL-H")
M4 = fit_fabric_tensor_M4_intercepts(dirs, mil2_vals)

ev, _ = fabric_eigendecomposition(M2)
print("M2 eigenvalues:", ev)
print("DA =", fabric_indices(ev)["DA"])

See the examples/ folder for complete annotated scripts, including DICOM input (single multi-frame file and folder of single-frame slices) and TIFF stacks (grayscale and binary).

Repository structure

fabrictensor/
├── fabrictensor.py          # library (all public functions)
├── pyproject.toml
├── LICENSE
├── README.md
├── examples/
│   ├── template_fabrictensor.py          # general-purpose template
│   ├── run_DCM_Palanca_et_al.py          # multi-frame DICOM example
│   └── run_StereomTest.py                # TIFF stack example
├── tests/
│   └── test_fabrictensor.py             # 80-test suite (no external data)
└── data/
    └── palanca/                          # sample micro-CT data
        └── ...                           # CC BY 4.0  Palanca et al. (2025)

Citation

If you use fabrictensor in your research, please cite:

Sessa, S. (in preparation). fabrictensor: a Python library for second- and fourth-order fabric tensor estimation from micro-CT images. SoftwareX. (manuscript submitted)

The theoretical framework implemented in this library is described in:

Sessa, S. (2026). Symmetry classes of linear elasticity induced by fabric tensors. (manuscript in press)

These entries will be updated with full bibliographic details (volume, pages, DOI) upon publication.

Sample data

The data/palanca/ folder contains a subset of the micro-CT dataset published by Palanca et al. (2016) on figshare, distributed under CC BY 4.0.

Palanca, M., Tozzi, G., Cristofolini, L., Dall'Ara, E. (2016). microCT scans of bone and cement-bone microstructures. figshare. Dataset. https://doi.org/10.6084/m9.figshare.4308926

The MIT License of fabrictensor does not apply to those files. See NOTICE and data/palanca/README.md for full attribution details.

License

fabrictensor is released under the MIT License.

Contact

Salvatore Sessa
Università degli Studi di Napoli Federico II
[e-mail]
https://github.com/salsessa/fabrictensor