You need to agree to share your contact information to access this model

This repository is publicly accessible, but you have to accept the conditions to access its files and content.

Hand X-ray Anatomical Measurement Engine v10.11

Research-only, fully offline PyTorch/MONAI inference for a single-hand PA/AP radiograph. The package exports:

whole-hand mask;
38 ordered endpoints for 5 metacarpals and 14 phalanges;
19 projected 2-D bone lengths;
optional millimetre estimates from trustworthy DICOM spacing;
within-hand ratios, confidence indicators and refusal reasons;
JSON, CSV, masks and overlays.

This is not a medical device, brachydactyly classifier, fracture diagnostic model or estimate of true 3-D anatomical length. It must not be used for clinical decisions without independent local validation and governance.

Distribution status

The current release directory is a publication candidate. Before making the weights public, the publisher must obtain and document permission to redistribute model derivatives of the Hand Skeleton/Digital Hand Atlas and RHPE resources. See LICENSE_MODEL.md. The uploader refuses to execute unless the publisher explicitly confirms this review.

Model components

File	Role
`keypoints_correct480_ensemble_v0.9.pt`	Initial 38-point axes
`axis_profile_consistency_transplanted_v5.4_candidate_v6.9.pt`	Selected 19-length engine
`axis_recenter_ram_mask_confidence_anchored_v10.11.json`	Length-preserving, confidence-anchored axis-recenter configuration
`ram_h1200_bone_patch_mask_seed20260744_v10.6.pt`	RAM local bone-mask model 1
`ram_h1200_bone_patch_mask_seed20260745_v10.6.pt`	RAM local bone-mask model 2
`hand_mask_rsna_manual_v0.1.pt`	Whole-hand mask
`quality_graz_part1_v0.1.pt`	Research refusal support

Every byte size and SHA-256 is recorded in checkpoints/model_manifest.json. The recenter configuration additionally verifies the exact length and RAM-mask checkpoints before inference.

For component details and collaborator retraining, see ARCHITECTURE.md and TRAINING.md.

Installation

Python 3.10 and PyTorch with a CUDA build compatible with the local NVIDIA driver are recommended. CPU inference is supported but slower.

hf auth login
git clone https://huggingface.co/yhlin/HXR_measurement
cd HXR_measurement

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e . --no-deps

For an existing CUDA/PyTorch environment, install the project without replacing PyTorch:

python -m pip install -e . --no-deps

Inference

Single DICOM:

hand_measure infer \
  --input /path/to/image.dcm \
  --output ./results \
  --model checkpoints/keypoints_correct480_ensemble_v0.9.pt \
  --length-model checkpoints/axis_profile_consistency_transplanted_v5.4_candidate_v6.9.pt \
  --axis-recenter-model checkpoints/axis_recenter_ram_mask_confidence_anchored_v10.11.json \
  --hand-mask-model checkpoints/hand_mask_rsna_manual_v0.1.pt \
  --quality-model checkpoints/quality_graz_part1_v0.1.pt \
  --save-masks --save-overlays --save-csv

PNG/JPEG without reliable metadata:

hand_measure infer \
  --input /path/to/png_or_folder \
  --output ./results \
  --model checkpoints/keypoints_correct480_ensemble_v0.9.pt \
  --length-model checkpoints/axis_profile_consistency_transplanted_v5.4_candidate_v6.9.pt \
  --axis-recenter-model checkpoints/axis_recenter_ram_mask_confidence_anchored_v10.11.json \
  --hand-mask-model checkpoints/hand_mask_rsna_manual_v0.1.pt \
  --quality-model checkpoints/quality_graz_part1_v0.1.pt \
  --laterality L --view PA \
  --save-masks --save-overlays --save-csv

Do not guess laterality or view. Split mixed non-DICOM folders by known laterality/view before inference.

The tool never uploads images. One unreadable input is logged and rejected without terminating the rest of the batch.

Output

results/
  masks/<image_id>.png
  overlays/<image_id>.png
  json/<image_id>.json
  measurements.csv
  rejected.csv
  error.log
  run_manifest.json

length_mm is populated only when valid PixelSpacing or ImagerPixelSpacing is present. Detector-plane spacing is explicitly marked.

The overlay contains the source radiograph, whole-hand mask when requested, yellow bone axes, blue proximal points and red distal points. Machine-readable measurements, ratios, confidence values, quality flags and recenter diagnostics are stored in per-image JSON and the batch measurements.csv.

Collaborator training

The repository includes an offline, leakage-safe site-training entry point:

python scripts/train.py template \
  --output ./site_data/annotations.csv

python scripts/train.py train \
  --annotations ./site_data/annotations.csv \
  --output ./site_training/run_001 \
  --architecture resnet18 \
  --device cuda:0 \
  --epochs 120 \
  --batch-size 16 \
  --model-version collaborator-site-v1

It audits native-pixel endpoint annotations, locks group-level splits and trains Engine-compatible 38-endpoint and 19-length checkpoints. It does not reproduce every research ensemble/local refiner and must not use the released hash-locked v10.11 recenter JSON with a newly trained length checkpoint. See TRAINING.md.

Measured public feasibility results

Hand Skeleton fixed test: 12 images / 228 bones, official 480 × 600 frame.

mean length absolute error: 1.31706 px;
median length absolute error: 1.02009 px;
mean relative length error: 1.8565%;
image-bootstrap 95% interval for mean MAE: 1.05596–1.61234 px.

The optional v10.11 RAM-mask recenter and confidence-anchored overlap correction:

endpoint MRE: 6.7083 → 1.9586 px;
axis-center MRE: 6.2959 → 1.3398 px;
digit-V endpoint MRE versus v10.10: 2.7196 → 1.9949 px;
12/12 images improved;
canonical length MAE remained 1.31706 px.

The confidence-anchored correction was developed after inspecting two fixed-test fifth-digit failures, so this is a known-case regression result rather than a new independent generalization estimate.

The test set is very small and has been observed during iterative research. These results are feasibility evidence, not a clinical or population-level performance guarantee. The mean length target of less than one pixel was not achieved.

Required validation before institutional use

patient-independent local data stratified by scanner, age, sex, side, view and pathology;
at least two qualified readers with repeated endpoint annotations and an adjudicated mask subset;
pixel/mm MAE, per-bone agreement, ICC and Bland–Altman analysis;
independent right-hand, DICOM spacing, rejection and confidence calibration;
prospective workflow and governance review.

See INFERENCE.md, docs/axis_recenter_v10.7.md, and docs/axis_overlap_fix_v10.10.md, and docs/digit5_refinement_v10.11.md.

Downloads last month: -; Downloads are not tracked for this model. How to track

yhlin
/

HXR_measurement