Landmark Tools

Landmark reading, writing and comparison utilities. Landmarks are the independent check on a registration: transform a fixed-image landmark set with the recovered transform and measure the distance to the corresponding moving-image landmarks — the metric WorkflowFinetuneICONRegistration reports and the DIR-Lab benchmark is scored on.

Module Reference

Tools for reading and writing anatomical landmarks.

This module provides the LandmarkTools class with utilities for reading and writing point landmarks in 3D Slicer’s Markups JSON (.mrk.json) format and in a simple CSV format. Landmarks are kept in memory in LPS world coordinates (ITK’s native frame, matching the rest of the platform). RAS files are converted to LPS on read; outputs are always written in LPS.

class physiotwin4d.landmark_tools.LandmarkTools(log_level=20)[source]

Read and write anatomical landmarks in LPS world coordinates.

Landmarks are represented in memory as a dictionary keyed by label, with each value a three-tuple (x, y, z) of LPS millimeter coordinates:

{
    'apex': (x, y, z),
    'base': (x, y, z),
    ...
}

Positions are always in LPS. RAS input files are converted on read; outputs are always written in LPS.

Example

>>> tools = LandmarkTools()
>>> landmarks = tools.read_landmarks_3dslicer('points.mrk.json')
>>> tools.write_landmarks_csv(landmarks, 'points.csv')

__init__(log_level=20)[source]

Initialize the LandmarkTools class.

Parameters:: log_level (int | str) – Logging level (default: logging.INFO)

read_landmarks_3dslicer(path)[source]

Read landmarks from a 3D Slicer Markups JSON (.mrk.json) file.

Reads the first markup node from the file and returns its control points as a {label: (x, y, z)} dictionary. Other Slicer fields (id, description, orientation, …) are discarded.

Coordinates are returned in LPS. If the file declares RAS (or the legacy numeric codes '0' for LPS and '1' for RAS), each position is converted by negating its X and Y components.

Parameters:: path (str | Path) – Path to the .mrk.json file.
Return type:: dict[str, tuple[float, float, float]]
Returns:: Dict mapping landmark label to (x, y, z) tuple in LPS.
Raises:: ValueError – If the file contains no markups, declares an unrecognized coordinate system, or has a control point without a 3D position.

write_landmarks_3dslicer(landmarks, path)[source]

Write landmarks to a 3D Slicer Markups JSON file in LPS.

Wraps the landmarks in the Slicer Markups schema envelope and writes the result to disk. The output always declares coordinateSystem == 'LPS'; positions are written verbatim, so the caller must ensure they are already in LPS.

Parameters:

landmarks (dict[str, tuple[float, float, float]]) – Dict mapping label to (x, y, z) tuple, as returned by read_landmarks_3dslicer() or read_landmarks_csv().
path (str | Path) – Output .mrk.json path.

Return type:

None

read_landmarks_csv(path)[source]

Read landmarks from a CSV file with header Name,x,y,z (LPS).

Coordinates are assumed to be in LPS. The returned dictionary matches the in-memory format used by read_landmarks_3dslicer(), so the readers and writers are interchangeable.

Parameters:: path (str | Path) – Path to the CSV file. The first row must be the header Name,x,y,z (case-insensitive, surrounding whitespace tolerated); subsequent rows are label,x,y,z.
Return type:: dict[str, tuple[float, float, float]]
Returns:: Dict mapping landmark label to (x, y, z) tuple in LPS.
Raises:: ValueError – If the file is empty, has the wrong header, or contains a malformed row.

write_landmarks_csv(landmarks, path)[source]

Write landmarks to a CSV file with header Name,x,y,z (LPS).

Positions are written verbatim and assumed to be in LPS.