The first open-source Python package for fully automated CT pelvimetry and body composition analysis.
ctpelvimetry transforms the manual, time-consuming process of measuring pelvic dimensions and body composition into a rapid, fully automated pipeline. Built for surgical data science and preoperative risk assessment, it integrates seamlessly with pre-trained deep learning models (e.g., TotalSegmentator) to extract crucial anatomical metrics directly from raw CT scans—eliminating inter-observer variability entirely.
Get up and running in seconds.
# Basic install (if you already have segmentations)
pip install ctpelvimetry
# Full install (includes TotalSegmentator for end-to-end automation)
pip install "ctpelvimetry[seg]"Because the full end-to-end pipeline relies on deep learning models (TotalSegmentator) for 3D image segmentation, a dedicated GPU is strongly recommended.
- Recommended Setup (for
ctpelvimetry[seg]):- GPU: NVIDIA GPU with at least 8GB VRAM (16GB+ recommended for high-resolution CTs, e.g., NVIDIA T4, RTX 3060/4090, or A100).
- RAM: 16GB+ System RAM.
- Time: With a dedicated GPU, a single patient scan takes < 2 minutes.
- Without a GPU (CPU-only):
- The pipeline will still run, but segmentation may take 10 to 30+ minutes per scan, and you risk running out of memory (OOM) on large DICOM series.
- Pro Tip for Clinical Researchers: If you don't have a local GPU workstation, you can easily run the full pipeline in a cloud environment like Google Colab (using a free T4 GPU).
(Note: If you are only running the basic ctpelvimetry on pre-existing segmentations, a standard CPU is perfectly fine.)
Go from raw DICOM to structured measurements in one command:
ctpelvimetry pelv --dicom_dir /path/to/patient_scan --output_root ./output --qcThat's it. The pipeline will handle DICOM-to-NIfTI conversion, segmentation, landmark detection, metric calculation, and QC figure generation automatically.
Manual measurement of the mid-pelvic workspace and body composition is tedious and highly subjective.
- Clinical Problem: Measuring Inter-Spinous Distance (ISD) or Visceral Adipose Tissue (VAT) manually takes ~15 minutes per scan and suffers from significant inter-observer variability.
- The
ctpelvimetrySolution: Fully automated measurement in < 2 minutes, providing standardized, reproducible data suitable for large-scale surgical data science and machine learning applications.
- ⚡ Fully Automated: From raw DICOM to structured CSVs without a single manual click.
- 📊 High-Throughput Batching: Process hundreds of scans sequentially with built-in failure handling and progress tracking.
- 🛡️ Robust Quality Control: Automatic detection of pelvic rotation/tilt, and generation of multi-planar QC visualisations for immediate verification.
- 🧩 Modular Design: Use it as a CLI tool for batch processing or import it as a Python API for custom research pipelines.
ctpelvimetry extracts two major categories of surgical metrics:
| Metric | Description |
|---|---|
| ISD (mm) | Inter-Spinous Distance (Crucial for deep pelvic surgery) |
| Inlet AP (mm) | Promontory → Upper Symphysis |
| Outlet AP (mm) | Coccygeal Apex → Lower Symphysis |
| Outlet Transverse (mm) | Intertuberous diameter |
| Sacral Depth & Length (mm) | Pelvic concavity quantification |
| Metric | Description |
|---|---|
| VAT / SAT (cm²) | Visceral / Subcutaneous Adipose Tissue area |
| V/S Ratio | VAT / SAT ratio (Indicator of visceral obesity) |
| SMA (cm²) | Skeletal Muscle Area (Measured at L3 and mid-pelvis levels) |
Trust, but verify. ctpelvimetry automatically generates detailed QC panels for every scan to ensure landmark accuracy.
Sagittal QC showing automated landmark detection: sacral length (magenta), inlet AP (green), outlet AP (orange), and sacral depth (cyan).
Extended QC panel: (a) outlet transverse diameter, (b) interspinous distance (ISD), and (c) tabular measurement summary.
For data scientists building custom pipelines, ctpelvimetry provides a clean Python API:
from ctpelvimetry import run_combined_pelvimetry, process_single_patient
# 1. Run Pelvimetry analysis
pelv_results = run_combined_pelvimetry(
patient_id="Patient_001",
seg_path="/path/to/segmentation_masks",
nifti_path="/path/to/ct.nii.gz"
)
print(f"Automated ISD: {pelv_results['isd_mm']} mm")
# 2. Run Body Composition analysis
body_comp_results = process_single_patient(
patient_id="Patient_001",
seg_root="/path/to/seg_root",
nifti_path="/path/to/ct.nii.gz",
pelvimetry_csv="/path/to/report.csv"
)(See the batch.py module for large-scale dataset orchestration.)
ctpelvimetry/
├── cli.py # Unified CLI entry point
├── pipeline.py # Core orchestration (DICOM → Metrics)
├── segmentation.py # TotalSegmentator integration wrapper
├── landmarks.py # 3D geometric landmark detection
├── metrics.py # Pelvimetric calculations (ISD, etc.)
├── body_composition.py # Fat/Muscle area quantification
├── qc.py # Visual reporting generation
└── batch.py # High-throughput batch processing
We welcome contributions from both the surgical and data science communities!
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m "Add amazing feature") - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
If you use ctpelvimetry to facilitate your research, please consider citing our work:
@software{huang2025ctpelvimetry,
author = {Huang, Shih-Feng},
title = {ctpelvimetry: Automated CT Pelvimetry and Body Composition Analysis},
year = {2025},
url = {[https://github.com/odafeng/ctpelvimetry](https://github.com/odafeng/ctpelvimetry)},
version = {1.1.0}
}A peer-reviewed manuscript detailing the clinical validation of this pipeline is currently in preparation.
License: Apache License 2.0 | Author: Shih-Feng Huang, MD