pelvitect 0.1.0

Pediatric hip geometry engine for developmental dysplasia of the hip (DDH) analysis from pelvic X-rays

Pelvitect

Pediatric Hip Geometry Engine for Developmental Dysplasia of the Hip (DDH)

[]

Pelvitect is an open-source Python library that measures and classifies developmental dysplasia of the hip (DDH) from anteroposterior pelvic radiographs. Given anatomical landmarks — provided manually or predicted by bundled SegFormer-B3 and ViTPose-Plus-Base models — it deterministically computes:

Output	Description
Acetabular index (AI)	Hilgenreiner line ∠ acetabular roof
Center-edge angle (CE)	Perkins line ∠ ASM → FHC
Tönnis grade (I–IV)	FHC quadrant position
IHDI grade (I–IV)	MOFM position relative to H, P, D-lines
Hilgenreiner / Yamamuro / Smith distances	Displacement metrics
Shenton line continuity	Arc gap in pixels
Image quality control	MTDDH symmetry standard (ORI, OAR, IRI, IAR)

Pelvitect is the geometry engine behind PelviSet — a unified dataset of 14,622 pediatric pelvic radiographs.

---

Installation

pip install pelvitect

Python ≥ 3.9 required.

---

Quick start

Full auto-inference from an image URL

import numpy as np, requests
from PIL import Image
from io import BytesIO
from pelvitect import Pelvitect

url = "https://prod-images-static.radiopaedia.org/images/155111/24d626dbf763635f29e9f4efeacbb1_big_gallery.jpg"
img = np.array(Image.open(BytesIO(requests.get(url).content)).convert("RGB"))

# Downloads both models on first call (~380 MB total)
result = Pelvitect(image=img).analyze()
print(result.summary())

---

Input modes

Constructor call	What runs
Pelvitect(landmarks=lm)	Pure geometry — no models
Pelvitect(mask=mask)	Mask-derived landmarks + Shenton + QC
Pelvitect(mask=mask, landmarks=lm)	Combined — KPs take priority over mask, mask adds Shenton + QC
Pelvitect(image=img)	Full auto: SegFormer-B3 → ViTPose → geometry

---

Output schema

result.to_dict() / result.to_json() return a structured dict:

{
  "landmarks": {
    "tcc_r": {"x": 200.0, "y": 300.0, "source": "provided"},
    ...
  },
  "metrics": {
    "ai_l":     {"value": 28.4, "status": "computed", "unit": "°"},
    "h_dist_l": {"value": 45.0, "status": "computed", "unit": "px"},
    ...
  },
  "classifications": {
    "tonnis_l": {"grade": "I",  "status": "computed", "note": ""},
    "ihdi_l":   {"grade": "II", "status": "computed", "note": "MOFM below H-line …"},
    ...
  },
  "quality_control": {
    "status": "pass",
    "caution_msg": "",
    "criteria": [
      {"name": "ORI", "value": 1.02, "range": [0.78, 1.42], "status": "pass"},
      ...
    ]
  }
}

---

Models

Model	Architecture	Input	HuggingFace
pelvitect-seg	SegFormer-B3	512×512 RGB	amirmmahdavikia/pelvitect-seg
pelvitect-kp	ViTPose-Plus-Base (4-ch)	256×192 ROI crop	amirmmahdavikia/pelvitect-kp

Both models are trained on PelviSet and download automatically from HuggingFace Hub on first use. Model weights are cached at ~/.cache/huggingface/hub/.

---

Coordinate conventions

• Origin: top-left of image; y increases downward (standard image convention).
• Patient right hip = image left (smaller x).
• Landmark keys: {name}_{side} where l = patient left, r = patient right.
• Default coordinate space: pixel. Pass coord_space="normalized" for [0, 1] inputs with image_size=(w, h).

---

Image quality control

Pelvitect automatically assesses radiograph quality when a segmentation mask is available, using the MTDDH symmetry standard (Qi et al., Scientific Data 2025):

Metric	Definition	Accepted range
ORI	Obturator rotation index	[0.78, 1.42]
OAR	Obturator area ratio	[0.77, 1.46]
IRI	Ilium rotation index	[0.71, 1.22]
IAR	Iliac area ratio	[0.71, 1.22]

A violation produces a WARNING status and caution_msg:

"Image quality criterion failed (ORI). Measurements should be interpreted with caution."

The QC result is a non-blocking warning — all geometry measurements are still returned.

---

Dataset

PelviSet is available at Zenodo and HuggingFace:

• Zenodo: 10.5281/zenodo.20615290
• HuggingFace: amirmmahdavikia/pelviset

14,622 cases · 4 sources · 3 institutions · 2 countries · 12-class segmentation · 8-point keypoints · geometry-derived clinical labels

---

Citation

If you use Pelvitect in research, please cite:

@software{mahdavikia2026pelvitect,
  author    = {Mahdavikia, Amir M.},
  title     = {Pelvitect: Pediatric Hip Geometry Engine},
  year      = {2026},
  version = {0.1.0},
  doi     = {10.xxxx/zenodo.xxxxxxx},
  url     = {https://doi.org/10.xxxx/zenodo.xxxxxxx}
}

---

License

MIT — see LICENSE.