Skip to main content

mspdetect

Automatic detection of the mid-sagittal plane (MSP) in head and neck planning CTs, and metrics of structures relative to it (left/right volumes, laterality and distance of the tumour to the midline).

The plane is found by maximising the left-right symmetry of the bone: bone voxels are mirrored across a candidate plane and compared with the CT intensity at the mirrored position.

Research software. mspdetect is not a medical device and must not be used for clinical decisions. Always check results visually (see Visualization).

Installation

Requires Python ≥ 3.10.

pip install "mspdetect[viz]"

[viz] adds plotting (matplotlib, ipywidgets) and can be omitted.

Usage

Python

import mspdetect as msp

case = msp.load_case(
    "data/patient01",
    image="CT",
    structures={"GTVp": "ROI__[GTVp]", "Body": "ROI__[EXTERNAL]", "Parotid_L": "ROI__[Parotid_L]"},
)
result = msp.detect_msp(case)                     # default settings, see DetectionConfig
print(result.plane)                               # normal and offset in world coordinates

metrics = msp.compute_metrics(case, result.plane, structures=["Parotid_L"], target="GTVp")
msp.save_result(result, "results/patient01")      # msp.json + details.npz

Settings are passed as a DetectionConfig, e.g. msp.DetectionConfig(crop={"reference": None}) to use the whole scan.

Command line

mspdetect check-config config.yaml   # validate and print all settings (incl. defaults)
mspdetect run config.yaml            # detect the plane of all patients
mspdetect metrics config.yaml        # compute metrics from the detected planes

See the command line documentation for the behaviour of the commands and all configuration options.

Inputs and outputs

Input are NIfTI files containing the CT in Hounsfield units and, optionally, binary structure masks of the Body, GTVp, or other structures. All volumes are reoriented to RAS+ on loading.

The outputs contain the detected plane, objective values along other information such as the package version, settings, etc. Planes are stored in world coordinates.

When calculating metrics on the detected planes, for each specified structure (metrics.structures) a handful of information related to the detected MSP will be determined, e.g. the side, the distance to the MSP, lateral extent, etc.

See the documentation for further details.

Method

  1. Crop a slab of slices around the reference structure (fixed margins or a fixed-size window), optionally extended to the mandible and cropped laterally to exclude the shoulders.
  2. Bone: voxels inside Body with HU in hu_range (default 300–2800).
  3. Grid search over the normal's azimuth and polar angle, for planes through the bone's centre of mass, scored with the sum of squared differences between each bone voxel and the (cubic-interpolated) CT at its mirror position. A robust Huber threshold δ is estimated from the residuals (1.345 · 1.4826 · MAD).
  4. Optimisation of the Huber loss with BFGS, starting from the best grid plane and using the δ of that plane. With n_starts > 1, further starts from the next-best grid planes are run, each with the δ of its own grid plane. Since these starts minimise different Huber losses, the plane with the lowest final quadratic loss (independent of δ) is returned as the best, and first_start_agrees reports whether the first start reached the same plane (within 0.5° and 0.5 mm).

Citation

If you use mspdetect, please cite the article in CITATION.cff.

Metadata

Release files for mspdetect 0.2.0

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

Source distribution (sdist)

Source distribution for mspdetect 0.2.0
File Size Uploaded Provenance Actions
mspdetect-0.2.0.tar.gz 194.0 kB With provenance Details for mspdetect-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 230.6 kB

Release files / mspdetect-0.2.0.tar.gz

Download URL mspdetect-0.2.0.tar.gz
Size 194.0 kB
Tags Source
SHA-256 checksum
How to use checksums
2ee820ec7f530ce8177e799af7435d3699c9864ff1a37c515aeda209ab2c80ba
BLAKE2b-256 checksum
How to use checksums
2f85714ba489b578a67a396f2346b3c5a789c9f9e4fa7f6c35d1c711c1a7c415
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / mspdetect-0.2.0-py3-none-any.whl

Download URL mspdetect-0.2.0-py3-none-any.whl
Size 36.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d2edabda1606ba89eab2bb4560c63008372cf2425bea1fd07d0910ea8ac07f9e
BLAKE2b-256 checksum
How to use checksums
7ec0b118ea77df43818532b422e819cc67d84f284f97368fdf3b97af39e25ac5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for mspdetect 0.2.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mspdetect-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

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.

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