Surface To Volume Registration
===============================

Aligns external surface-scan point clouds to a **volume-derived body surface** from a CT or MR scan. The Suite workflow is built around **automatic skin extraction**; it is not a general “register scans to any volume label” tool.

Input
-----

* **Volume** — one CT or MR ``SharedImageSet``.
* **Surface scans** — one or more point clouds, assigned in the controller (see below).
* **Volume weight map** (optional) — label map aligned with the volume. Used together with **Volume weights** to weight regions on the **volume-side surface points** during ICP (for example emphasize the torso). It does **not** replace skin extraction or select a different anatomy as the registration target.

Output
------

Aligned surface point clouds (green in the display). Optionally the extracted volume-side surface points (cyan) when **Export skin points** is enabled. Transformation history is stored on each aligned scan when **Align volume to surface** is disabled.

Description
-----------

Typical use case: register handheld or structured-light **surface scans** of a patient to the **skin surface** implied by a CT or MR volume (for example before or during image-guided therapy).

The workflow:

1. Select the volume and open the algorithm.
2. Select surface-scan point clouds in the annotation view and click **Set Surface Points** in the controller (order defines scan index for ground-truth matrices).
3. Configure sensor orientation relative to the patient, then run.

On each run the algorithm reorients the volume for surface extraction, builds a point cloud (and optionally a mesh) of the **outer skin** using the built-in skin-segmentation step unless a volume-side point cloud was already supplied programmatically (see **Volume-side target surface** below), optionally downsamples each input scan, computes a centroid-based initial alignment, and refines with point-to-plane ICP against that volume-side surface. Use **Reset** in the controller to restore original volume and scan poses.

Volume-side target surface
--------------------------

In the **Suite UI**, the registration target on the volume is always the **skin surface**:

* By default, skin is extracted automatically from the CT/MR volume (see **Automatic skin extraction** below).
* The optional **Volume weight map** only assigns per-point weights on those skin points during ICP — it cannot point the algorithm at an arbitrary organ or label volume instead of skin.

Programmatic integrations can inject a precomputed volume-side point cloud before ``compute()`` (for example skin from another tool, or any surface already sampled as points). That path is not available from the algorithm controller. Passing a label map alone is not supported; an arbitrary segmentation would need to be converted to a point cloud first.

Sensor setup
------------

**Surface right orientation** — patient-centric orientation of the volume's local axes relative to the 3D sensor (*Feet*, *Head*, *Patient Left*, *Patient Right*).

**Surface viewing angle** — tilt in degrees from a top-down view (for example ``90`` when the sensor views the patient from the side).

Registration options
--------------------

**Align volume to surface** — when enabled with a single surface scan, moves the volume to match the scan instead of moving scans to the volume. Not supported for multiple scans.

**Downsample surface** — subsample each input scan before registration (faster, coarser).

**ICP overlap ratio** — overlap fraction passed to the internal ICP alignment.

**Volume weights** — per-label weights indexed by label value in the weight map; applied to **skin surface points** during ICP, not to pick a different structure.

**GT registration (surface to volume)** — optional ground-truth transforms per scan for evaluation logging.

Automatic skin extraction
-------------------------

When no volume-side point cloud is supplied via the API, skin is extracted from the volume automatically:

**Skin segmentation threshold** — optional override of the default skin threshold.

**Skin segmentation padding** / **Skin segmentation padding size** / **Skin segmentation padding mode** — morphological padding on the segmentation mask.

**Skin segmentation subvoxel refinement** — use subvoxel skin extraction instead of mesh-based extraction.

**Export skin points** — add the extracted skin point cloud to the algorithm output.