SpineData
=========

Overview
--------
``SpineData`` is the main data type used by the Spine plugin. It collects a set of anatomical structures (vertebrae) and may include a ``Sacrum`` and an ``Ilium``. Each vertebra is represented as an ``OrientedVertebra`` with per-structure geometry and annotations.

.. note::
   ``SpineData`` is a specialized form of an Anatomy ``AnatomicalStructureCollection`` (ASC). Where relevant, generic ASC tools (e.g., ASC Registration, Projection) also apply to ``SpineData``.

Contents
--------
- Vertebrae: collection of ``OrientedVertebra`` instances.
- Optional: one ``Sacrum`` and one ``Ilium``.
- Optional: intervertebral discs if the workflow includes the disc segmentation.
- ``Properties`` container for general metadata associated with the ``SpineData``.

``SpineData`` (and each ``OrientedVertebra``) exposes standard data containers which can be accessed via their keys in the ``AnatomicalStructure`` interface. Typically they include:

- Images (volumetric images, e.g., segmentation predictions or cropped regions)
- Meshes (vertebral surfaces)
- Keypoints (e.g., vertebral body and pedicle coordinates)
- Planes (e.g., end plates)
- Point clouds (e.g., extracted landmarks)
- Splines (e.g., centerline/association splines)

.. note::
    - Actual keys present depend on your workflow and models.
    - At the vertebra level, these containers hold per-vertebra data; at the spine level, containers can hold global artifacts (e.g., context predictions).
    - Vertebrae can be sorted in multiple ways; workflows may choose a strategy based on data properties.

.. _spinedata-save-load:

Save and load
-------------
- Standalone: save/load as `.imf` using standard file I/O.
- Algorithm state: the Spine Base Algorithm can save/load its state (including the current ``SpineData`` and derived artifacts). Loading a state created from different input data may be rejected; loading without a current image is supported when the state encapsulates the data.

Template usage
--------------
- A ready-to-use template ``SpineData`` is provided by the plugin resources.
- Use "Load Spine Template" to insert the template, then select subject and template ``SpineData`` as needed for registration or label transfer.