shapeworks::ImageRegistration

Module: Image Classes

More...

#include <ImageRegistration.h>

Public Types

	Name
enum class	TransformType { Rigid, Affine, SyN} Which stages to run. Each mode includes the stages before it.
using itk::CompositeTransform< double, 3 >	CompositeTransformType

Public Functions

	Name
	ImageRegistration()
	~ImageRegistration()
void	set_transform_type(TransformType type) set which registration stages to run (default SyN)
void	set_gradient_step(double step) set the SyN gradient step size (default 0.25, ANTs grad_step)
void	set_update_field_variance(double variance) set the variance for gaussian smoothing of the SyN update field (default 3.0, ANTs flow_sigma)
void	set_total_field_variance(double variance) set the variance for gaussian smoothing of the SyN total field (default 0.0, ANTs total_sigma)
void	set_iterations(const std::vector< unsigned int > & iterations) set the deformable stage's per-level iteration counts, coarsest level first (default {40, 20, 0})
void	set_shrink_factors(const std::vector< unsigned int > & shrink_factors)
void	set_smoothing_sigmas(const std::vector< double > & sigmas)
void	set_linear_iterations(const std::vector< unsigned int > & iterations) Set the schedule used by the rigid and affine stages.
void	set_linear_shrink_factors(const std::vector< unsigned int > & shrink_factors)
void	set_linear_smoothing_sigmas(const std::vector< double > & sigmas)
void	set_correlation_radius(unsigned int radius) set the radius of the neighborhood correlation metric window used by the SyN stage (default 4)
void	run(const Image & fixed, const Image & moving) run the registration. Throws std::runtime_error if any stage fails.
std::vector< Point3 >	transform_points(const std::vector< Point3 > & points) const map points from fixed image space into moving image space. run() must have been called.
Image	warped_moving() const the moving image resampled onto the fixed image grid. Useful for inspecting registration quality.
CompositeTransformType::Pointer	get_transform() const the composed transform from all stages, mapping fixed space to moving space
void	save_transform(const std::string & filename) const Write the transform computed by run() so that it can be reused.
bool	load_transform(const std::string & filename) Read a transform written by save_transform(), in place of running the registration.
Image	make_registration_image(const Image & dt, double band =5.0) Prepare a distance transform for registration by clamping and rescaling it.

Detailed Description

class shapeworks::ImageRegistration;

Intensity based registration of one image to another, following the same recipe as the ANTs SyNRA pipeline: a multi-resolution rigid stage, then affine, then symmetric normalization (SyN) with a neighborhood cross correlation metric.

The resulting transform maps points from the fixed image space into the moving image space. This is the ITK convention: resampling walks the fixed (output) grid and pulls samples from the moving image. So to carry a point set from image A onto image B, register with A as the fixed image and B as the moving image, then call transform_points().

Distance transforms rather than binary images are the expected input. Use make_registration_image() to clamp a distance transform to a band around the surface; unbounded far-field values otherwise dominate the metric.

Public Types Documentation

enum TransformType

Enumerator	Value	Description
Rigid		rigid only
Affine		rigid, then affine
SyN		rigid, then affine, then symmetric normalization

Which stages to run. Each mode includes the stages before it.

using CompositeTransformType

using shapeworks::ImageRegistration::CompositeTransformType =  itk::CompositeTransform<double, 3>;

Public Functions Documentation

function ImageRegistration

ImageRegistration()

function ~ImageRegistration

~ImageRegistration()

function set_transform_type

void set_transform_type(
    TransformType type
)

set which registration stages to run (default SyN)

function set_gradient_step

void set_gradient_step(
    double step
)

set the SyN gradient step size (default 0.25, ANTs grad_step)

function set_update_field_variance

void set_update_field_variance(
    double variance
)

set the variance for gaussian smoothing of the SyN update field (default 3.0, ANTs flow_sigma)

function set_total_field_variance

void set_total_field_variance(
    double variance
)

set the variance for gaussian smoothing of the SyN total field (default 0.0, ANTs total_sigma)

function set_iterations

void set_iterations(
    const std::vector< unsigned int > & iterations
)

set the deformable stage's per-level iteration counts, coarsest level first (default {40, 20, 0})

function set_shrink_factors

void set_shrink_factors(
    const std::vector< unsigned int > & shrink_factors
)

set the deformable shrink factors per level, coarsest first (default {4, 2, 1}); must match set_iterations() size

function set_smoothing_sigmas

void set_smoothing_sigmas(
    const std::vector< double > & sigmas
)

set the deformable gaussian smoothing sigmas (in physical units) per level, coarsest first (default {2, 1, 0})

function set_linear_iterations

void set_linear_iterations(
    const std::vector< unsigned int > & iterations
)

Set the schedule used by the rigid and affine stages.

These stages need a coarser and much longer schedule than the deformable one. Their coarse levels are cheap, and an unconverged linear stage leaves the deformable stage with a starting point it cannot recover from. Defaults follow ANTs: iterations {2100, 1200, 1200, 10}, shrink factors {6, 4, 2, 1}, sigmas {3, 2, 1, 0}.

function set_linear_shrink_factors

void set_linear_shrink_factors(
    const std::vector< unsigned int > & shrink_factors
)

function set_linear_smoothing_sigmas

void set_linear_smoothing_sigmas(
    const std::vector< double > & sigmas
)

function set_correlation_radius

void set_correlation_radius(
    unsigned int radius
)

set the radius of the neighborhood correlation metric window used by the SyN stage (default 4)

function run

void run(
    const Image & fixed,
    const Image & moving
)

run the registration. Throws std::runtime_error if any stage fails.

function transform_points

std::vector< Point3 > transform_points(
    const std::vector< Point3 > & points
) const

map points from fixed image space into moving image space. run() must have been called.

function warped_moving

Image warped_moving() const

the moving image resampled onto the fixed image grid. Useful for inspecting registration quality.

function get_transform

CompositeTransformType::Pointer get_transform() const

the composed transform from all stages, mapping fixed space to moving space

function save_transform

void save_transform(
    const std::string & filename
) const

Write the transform computed by run() so that it can be reused.

The transform depends only on the two images and the registration settings, so a saved one can stand in for re-running the registration whenever those are unchanged.

function load_transform

bool load_transform(
    const std::string & filename
)

Read a transform written by save_transform(), in place of running the registration.

Return: whether the transform was read

transform_points() and get_transform() work afterwards exactly as they would have after run(). warped_moving() does not, since no images were supplied.

function make_registration_image

static Image make_registration_image(
    const Image & dt,
    double band =5.0
)

Prepare a distance transform for registration by clamping and rescaling it.

Parameters:

• dt a distance transform
• band the half-width of the retained band, in physical units

Return: the clamped and rescaled image

Values are clamped to +/- band and then mapped to [0,1]. This keeps the metric focused on the region near the surface, where the distance transform is informative, instead of on the unbounded values far away from it.

---

Updated on 2026-08-09 at 22:28:04 +0000