Bone Surface Segmentation Provider for UniEM

This repository packages the publisher-provided UltraBones100k epoch_100.pth model as a mask-only provider for UniEM. It accepts one cropped uint8 BGR ultrasound frame and returns a same-size binary uint8 bone-surface mask. UniEM remains responsible for tracker pairing, calibration, 3D point projection, retention, rendering, and session logging.

Research software only. This model was trained on ex-vivo lower-limb data and has not been validated as a medical device or as the sole basis for a clinical decision.

Supported publisher model

The pinned checkpoint is:

UltraBones100k/AI_ultrasound_segmentation/models/
train_on_1_3_4_5_6_9_10_11_12_13_14/epoch_100.pth

It contains a full PyTorch segmentation_models_pytorch.FPN object with a ResNet-34 encoder, one grayscale input channel, and one output class. The publisher saved it with torch.save(model), so loading the original file uses Python pickle. Only use the checkpoint pinned by models/release-manifest.json and verified by SHA-256. Do not load an untrusted replacement.

Setup

Use the same Python 3.10 environment that runs UniEM. The UniEM 4080 environment already has a compatible PyTorch 2.4 runtime.

python -m pip install -r requirements.txt

Download and verify the publisher checkpoint:

.\scripts\download_model.ps1

If you downloaded epoch_100.pth manually, place it at models/epoch_100.pth and verify it without loading torch:

.\scripts\download_model.ps1 -VerifyOnly
# or
python scripts\verify_checkpoint.py

Expected asset identity:

size:   92782783 bytes
sha256: a0e82a14605e6100b344baf4841ef011680ceb2218ebe1f017f55b299027be12

Validate images

Run one image or every supported image in a directory:

python scripts\validate_images.py path\to\image.png
python scripts\validate_images.py path\to\images --output outputs\validation

The command writes source-size binary masks, green overlays, per-image timing, and report.json. Warmup occurs before timing the requested images.

The runtime reproduces the publisher preprocessing:

1. convert the source frame to grayscale;
2. resize to 256 x 256 with bilinear interpolation and antialiasing;
3. scale pixels to [0, 1];
4. normalize with mean 0.17475835978984833 and standard deviation 0.16475939750671387;
5. run the resident FPN and apply sigmoid plus a strict > 0.5 threshold;
6. restore the binary label map to the source size with nearest-neighbour interpolation.

Nearest-neighbour restoration intentionally differs from the publisher's visualization script, which uses OpenCV's default interpolation when writing a display PNG. A UniEM provider must return discrete label values, not interpolated grayscale values.

Evaluate UltraBones100k images

The evaluator understands the publisher dataset layout and defaults to the publisher's held-out specimens 2, 7, and 8:

python scripts\evaluate_dataset.py D:\data\UltraBones100k

For a small smoke evaluation:

python scripts\evaluate_dataset.py D:\data\UltraBones100k --specimens 2 --limit 100

It reads UltrasoundImages, visible-surface Labels, and space_factor from tracking.csv, then writes per-frame CSV and summary JSON containing Dice, precision, recall, average symmetric surface distance, and 95th-percentile surface distance. Distances are reported in millimetres when a valid space_factor is available and pixels otherwise.

Install for UniEM

UniEM discovers one manifest per immediate child of %LOCALAPPDATA%\UniEM\extensions. During development, create a directory junction so the checkout remains the source of truth:

$extensionRoot = Join-Path $env:LOCALAPPDATA "UniEM\extensions"
New-Item -ItemType Directory -Force -Path $extensionRoot | Out-Null
New-Item -ItemType Junction `
  -Path (Join-Path $extensionRoot "bone-surface-segmentation") `
  -Target (Get-Location)

Restart UniEM or press the reconstruction model refresh button, then select Bone Surface Segmentation (UltraBones100k).

This provider declares the open_surface_point_cloud reconstruction profile. Compatible UniEM hosts preserve the full binary mask for 2D display, then skeletonize every detected component and project the skeleton pixels into the tracked 3D point cloud. They do not use closed Delaunay meshing or report a bone volume. This follows the UltraBones100k reference point-cloud workflow while retaining UniEM's real-time pose pairing and bounded point retention.

Older UniEM hosts that do not recognize the profile fall back to their closed-region mesh path; do not interpret that output as a geometric bone surface. A final open-surface mesh remains a separate, offline refinement task.

Development checks

Fast tests do not import torch or load the real checkpoint:

python -m pip install -r requirements-ci.txt
python -m pytest
python -m ruff check .
python -m ruff format --check .

See docs/ARCHITECTURE.md, docs/MODEL_CARD.md, and docs/VALIDATION.md for the responsibility boundary, model provenance, and evaluation guidance.