cl-convert Converter API

Converter API

class cl_convert.model.Converter

Utility to aid in conversion of Cell Locator files.

“Specialized” – a dict representation of a version-specific JSON. That representation may only work in one version of Cell Locator.

“Normalized” – a dataclass representation common to all versions of cell locator. An intermediate representation during the conversion process.

For example, the flow to update a file to a different version would be:

>>> doc = old_converter.normalize(data)
>>> new_data = new_converter.specialize(doc)

It is also easier to perform manipulations on a Document. For example:

>>> doc = converter.normalize(data)
>>> for annotation in doc.annotations:
...     annotation.name = annotation.name.lower()
>>> data = converter.specialize(data)

abstract classmethod normalize(data: dict): Convert a specialized dict to a normalized Document

abstract classmethod specialize(doc: Document): Convert a normalized Document to a specialized dict; specific to this version.

@cl_convert.model.versioned

Automatically infer version string from calling filename.

When the caller’s filename is formatted 'v{version}.py', extract {version} from that filename and set the "version" key in the result.

For example, in the file v1.0.0.py:

@versioned
def specialize():
    return {}

data = specialize()
assert data['version'] == '1.0.0'

Version Registration

cl_convert.converters.find_latest(target: str = '') → Tuple[str, Converter]

Find the most-recent matching version and converter.

Parameters:: target – The target version string. See match() for details on matching logic.
Returns:: The inferred version and the corresponding converter.

cl_convert.converters.infer_normalize(data: dict) → Tuple[str, Document]

Find the most-recent converter that can normalize the document.

Returns:: (version, document) — The inferred version and the normalized document.

cl_convert.converters.match(target: str = '') → Generator[str, None, None]

Find the most-recent versions matching the target.

Prefix with d to interpret as a date. Prefix with v, or no prefix, to interpret as a literal version.

Example Versions	`v1.1`	`v1.1.`	`d2020.`
`1.1.0+2019.02.01`	yes	yes	no
`1.1.1+2020.02.07`	yes	yes	yes
`1.2.0+2020.05.01`	no	no	yes
`1.10.1+2021.03.01`	yes	no	no

Parameters:: target – String describing target versions.
Returns:: Matching versions, in order of precedence (most-recent first)

Document Model

class cl_convert.model.Document(annotations: ~typing.List[~cl_convert.model.Annotation] = <factory>, current_id: int = 0, reference_view: str = 'Coronal', ontology: str = 'Structure', stepSize: float = 0.5, camera_position: ~typing.Tuple[float, float, float] = (51.6226, -631.3969, -605.9925), camera_view_up: ~typing.Tuple[float, float, float] = (-0.5686, -0.6042, 0.5582))

Store minimal information about an annotation.json document.

camera_position: Tuple[float, float, float] = (51.6226, -631.3969, -605.9925): Initial camera position.

camera_view_up: Tuple[float, float, float] = (-0.5686, -0.6042, 0.5582): Initial camera ‘up’ vector.

current_id: int = 0: Index of the currently-selected annotation.

ontology: str = 'Structure': Initial atlas ontology. Ex. ‘Structure’, ‘Layer’, or ‘None’

reference_view: str = 'Coronal': Initial reference view. Ex. ‘Coronal’, ‘Axial’, or ‘Sagittal’.

stepSize: float = 0.5: Distance in Annotation.coordinate_units to move slice plane in Explore mode.

class cl_convert.model.Annotation(name: str = '', markup_type: str = 'ClosedCurve', representation_type: str = 'spline', thickness: float = 50, coordinate_system: str = 'LPS', coordinate_units: str = 'um', orientation: ~typing.Tuple[float, float, float, float, float, float, float, float, float, float, float, float, float, float, float, float] = (1.0, 0.0, 0.0, 0.25, 0.0, 0.0, 1.0, -17.5, 0.0, 1.0, 0.0, 22.25, 0.0, 0.0, 0.0, 1.0), points: ~typing.List[~cl_convert.model.Point] = <factory>)

Store minimal information about a single annotation

coordinate_system: str = 'LPS': Should always be LPS here; older versions of Slicer use RAS.

coordinate_units: str = 'um': Should be um for CCF atlas, mm for MNI atlas.

orientation: Tuple[float, float, float, float, float, float, float, float, float, float, float, float, float, float, float, float] = (1.0, 0.0, 0.0, 0.25, 0.0, 0.0, 1.0, -17.5, 0.0, 1.0, 0.0, 22.25, 0.0, 0.0, 0.0, 1.0): A transformation matrix storing the orientation of the slicing plane.

points: List[Point]: Control point positions for the annotation markup.

representation_type: str = 'spline': Type for a closed curve annotation; ex ‘spline’ or ‘polyline’.

thickness: float = 50: Thickness of the annotation model