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] @ git+https://github.com/lycosystem/mspdetect"
[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
- 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.
- Bone: voxels inside
Bodywith HU inhu_range(default 300–2800). - 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).
- 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, andfirst_start_agreesreports 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.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mspdetect-0.1.0.tar.gz | 194.0 kB | With provenance | Details for mspdetect-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mspdetect-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for mspdetect-0.1.0-py3-none-any.whl |
Total release size: 230.7 kB
Release files / mspdetect-0.1.0.tar.gz
| Download URL | mspdetect-0.1.0.tar.gz |
|---|---|
| Size | 194.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
559937b520704d2bbde6935955c66106d0478b7336ea43afd597dae5db152821
|
|
BLAKE2b-256 checksum How to use checksums |
89823e83dbcf762ac1944916ecc335e42be6d60d3f1340b3098a3e4586c084c8
|
| 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 26, 2026.
Transparency logRelease files / mspdetect-0.1.0-py3-none-any.whl
| Download URL | mspdetect-0.1.0-py3-none-any.whl |
|---|---|
| Size | 36.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
105a55040d054e2462466f8d2a007eadeaa186d9d630f1b77e33a7c366651350
|
|
BLAKE2b-256 checksum How to use checksums |
e14c3fb784b95718195a14b6d2f47b701388bb8a24fecf29425f6ed56b539803
|
| 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 26, 2026.
Transparency logSecurity for mspdetect 0.1.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.
Attestation for mspdetect-0.1.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 26, 2026.
Transparency logA 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.