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:
... =
>>> 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.


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

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.


target – The target version string. See match() for details on matching logic.


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.


(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





















target – String describing target versions.


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