Metadata-Version: 2.1
Name: fabrictensor
Version: 1.0.1
Summary: Stereological estimation of second- and fourth-order fabric tensors from micro-CT images
Author-email: Salvatore Sessa <salvatore.sessa2@unina.it>
License: MIT
Project-URL: Homepage, https://github.com/salsessa/fabrictensor
Project-URL: Repository, https://github.com/salsessa/fabrictensor
Project-URL: Bug Tracker, https://github.com/salsessa/fabrictensor/issues
Keywords: fabric tensor,mean intercept length,micro-CT,stereology,bone microstructure,anisotropy,fourth-order tensor
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-image>=0.20
Requires-Dist: Pillow>=9.0
Requires-Dist: matplotlib>=3.6
Provides-Extra: dev
Requires-Dist: pydicom>=2.3; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: dicom
Requires-Dist: pydicom>=2.3; extra == "dicom"

# 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

```bash
pip install fabrictensor
```

Or from source:

```bash
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

```python
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](https://creativecommons.org/licenses/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](NOTICE) and [data/palanca/README.md](data/palanca/README.md)
for full attribution details.

## License

**fabrictensor** is released under the [MIT License](LICENSE).

## Contact

Salvatore Sessa  
Università degli Studi di Napoli Federico II  
salvatore.sessa2@unina.it  
https://github.com/salsessa/fabrictensor
