Cardiotensor

A Python package to quantify and visualize 3D cardiomyocyte orientation in heart imaging datasets

Introduction

Cardiotensor is a user-friendly and memory-efficient toolkit designed for analyzing the orientation of cardiomyocyte fibers in large heart imaging datasets. It uses advanced image processing techniques to help researchers to accurately quantify 3D cardiomyocyte orientations with high efficiency.

Installation

cardiotensor is published as a Python package and can be installed with pip, ideally by using a virtual environment. Open up a terminal and install cardiotensor with:

pip install cardiotensor

⚠️ Require python 3.10 or newer

Documentation

cardiotensor's documentation is available at josephbrunet.fr/cardiotensor/

Getting Started

Have a look at our simple example that runs you through all the commands of the package

Overview of the cardiotensor pipeline for 3D cardiac orientation analysis and tractography. (a) Input data consist of a whole‑ or partial‑heart volume and, optionally, a binary mask to restrict analysis to myocardial tissue. (b) Local cardiomyocyte orientation is derived by 3D structure tensor computation and eigenvector decomposition. The third eigenvector (smallest eigenvalue) is visualized as arrows, color‑coded by helix angle (HA); inset shows a zoom of the ventricular septum highlighting transmural fiber rotation. (c) After transforming to a cylindrical coordinate system aligned with the left ventricle, voxel‑wise HA, transverse angle (TA), and fractional anisotropy (FA) maps are computed for quantitative analysis. (d) Streamline tractography generated from the eigenvector field reveals continuous cardiomyocyte bundles throughout the heart, color‑coded by HA.

More Information

This package uses the structure-tensor package to calculate the structure tensor, extending its capabilities for cardiac imaging.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! If you encounter a bug or have suggestions for new features:

• Report an Issue: Open an issue in the repository.
• Submit a Pull Request: Fork the repository, make changes, and submit a pull request.

For major changes, please discuss them in an issue first.

Contact

For questions, feedback, or support, please contact the maintainers at [j.brunet@ucl.ac.uk].

Reference

Brunet, J., Cook, A. C., Walsh, C. L., Cranley, J., Tafforeau, P., Engel, K., Arthurs, O., Berruyer, C., Burke O’Leary, E., Bellier, A., et al. (2024). Multidimensional analysis of the adult human heart in health and disease using hierarchical phase-contrast tomography. Radiology, 312(1), e232731. https://doi.org/10.1148/radiol.232731. [PDF]

@article{brunet2024multidimensional,
  title={Multidimensional analysis of the adult human heart in health and disease using hierarchical phase-contrast tomography},
  author={Brunet, Joseph and Cook, Andrew C and Walsh, Claire L and Cranley, James and Tafforeau, Paul and Engel, Klaus and Arthurs, Owen and Berruyer, Camille and Burke O’Leary, Emer and Bellier, Alexandre and others},
  journal={Radiology},
  volume={312},
  number={1},
  pages={e232731},
  year={2024},
  publisher={Radiological Society of North America}
}