Skip to main content


DOI Stable Version Python Versions Downloads tests codecov Documentation Ruff License

Quick use · Documentation · Contributing

The Torso Processing ToolBox (TPTBox) is a multi-functional package to handle any sort of bids-conform dataset (CT, MRI, ...)

Publication

This is the official repository of "TPTBox: Extensive torso processing toolbox for simple and automatic analysis of CT and MR imaging"

If you use this toolbox, please cite our publication: https://doi.org/10.1016/j.softx.2026.103055

@article{MollerGraf2026TPTBox,
  title = {TPTBox: Extensive torso processing toolbox for simple and automatic analysis of CT and MR imaging},
  journal = {SoftwareX},
  pages = {103055},
  year = {2026},
  issn = {2352-7110},
  doi = {https://doi.org/10.1016/j.softx.2026.103055},
  url = {https://www.sciencedirect.com/science/article/pii/S2352711026005467},
  author = {Hendrik Möller and Robert Graf and Tanja Lerchl and Daniel Rueckert and Jan S. Kirschke},
}

Features

  • Dataset Handling: Loop over datasets, search query, and find images and their corresponding derivatives

  • I/O Handling: Read and Write nifti files and point coordinate files as JSONs

  • Image Processing: Reorient, Resample, Shift Niftys, Centroids, labels, compute connected components, and so much more

  • Visualization: Modular 2D snapshot generation (different views, maximum intensity projections, depth-color map)

  • 3D Mesh generation: Use 3D segmentations to create 3D meshes and then take snapshots for visualization

  • Registration: Register two images to each other, using available data (image, segmentation, points)

  • Stitching: You have multiple MRI of the same person, split into different regions? Use our stitching algorithm to create one unified view.

  • Logger: Log every function in a file automatically, color important messages in the terminal for easy recognition.

Install the package

conda create -n 3.10 python=3.10
conda activate 3.10
pip install TPTBox
# Optional dependency Registration (deepali backend)
pip install "TPTBox[reg]"

Install via github:

(you should be in the project folder)

pip install poetry
poetry install

or: Develop mode is really, really nice:

pip install poetry
poetry install --with dev

Quick Use:

from TPTBox import NII

nii = NII.load("...path/xyz.nii.gz", seg=True)
# R right, L left
# S superior/up, I inferior/down
# A anterior/front, P posterior/back
img_rot = nii.reorient(axcodes_to=("P", "I", "R"))
img_scale = nii.rescale((1.5, 5, 1))  # in mm as currently rotated
# resample to an other image
img_resampled_to_other = nii.resample_from_to(img_scale)

nii.get_array()  # get numpy array
nii.affine  # Affine matrix
nii.header  # NIFTY header
nii.orientation  # Orientation in 3-Letters
nii.zoom  # Scale of the three image axis
nii.shape  # shape

Documentation

Full API reference and usage guides are available at https://tptbox.readthedocs.io.

The docs cover all sub-packages — NII, POI, BIDS_FILE, NumPy utilities, vertebra constants, spine analysis, registration, segmentation, mesh3D, stitching, and the logger — with hyperlinks back to the GitHub source.

The three pillars

NII: nii_wrapper.py -- NIfTI image wrapper

This is the core of image handling, this takes care of loading images and segmentations, and any data processing

POI: poi.py -- Points of Interests

This is the core of handling 2D/3D coordinates in any defined space. Center of mass locations can be computed in this format, and other landmarks. Similar to Niftis, this contains an affine matrix so it is aware of its global space relation, voxel spacing, ...

BIDS: bids_files.py -- Dataset Handling

This is the core of handling datasets that are BIDS-compliant. Easily search through your datasets and find all images following your constraints, such as every CT that also has a specific segmentation available.

Modules

Each sub-package has its own README with API tables and examples. Click on the name to get the corresponding README with quick examples and more explanations.

Module Description
core NII (NIfTI I/O and transforms), POI (anatomical landmarks), BIDS dataset navigation, NumPy utilities, vertebra constants
core/poi_fun Internal POI computation strategies (surface points, corpus centers, disc points)
spine Spine-specific tools: 2D snapshot generation and statistical measurements
spine/snapshot2D Modular 2D image generation — axial/sagittal/coronal slices, MIPs, segmentation overlays
spine/spinestats Clinical spine measurements: distances, angles, disc heights, IVD landmarks
registration Rigid and deformable image registration via ANTs and DeepALI
segmentation Integration with SPINEPS, VibeSeg/TotalVibeSeg, and nnU-Net pipelines
mesh3D 3D surface mesh generation and rendering from segmentation volumes
stitching Multi-station NIfTI stitching for whole-body or long-spine acquisitions
logger Structured, consistent logging for medical image processing pipelines

Metadata

Release files for TPTBox 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for TPTBox 1.1.0
File Interpreter ABI Platform Actions
tptbox-1.1.0-py3-none-any.whl Python 3 none any Details for tptbox-1.1.0-py3-none-any.whl

Release files / tptbox-1.1.0-py3-none-any.whl

Download URL tptbox-1.1.0-py3-none-any.whl
Size 8.8 MB
Tags Python 3
SHA-256 checksum
How to use checksums
975a68f4117ab81fcc2d819d6127f301b1cc50210e08e73df1b9a818ee3be984
BLAKE2b-256 checksum
How to use checksums
c031c8d3be1a2753742c04a7e8dc8e252c008e394e620429be949032712fee2a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Security for TPTBox 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page