ImageDev

CudaTemplateMatching3d

Computes a similarity score for each voxel of a three-dimensional image for localizing a searched structure.

Access to parameter description

This command is experimental, his signature may be modified between now and his final version.

 For an introduction: section Image Correlation.

This algorithm aims to detect a known structure, defined in a template image, within a three-dimensional image.

The template can be optionally transformed to be compared at different orientations and scales at each position of the input image. These transformations are provided in a data frame where each row represents a transformation to test, and each column, a component of the rotation and scale factor to apply.
For each transformation of the template, a cross-correlation is performed with the input image and the highest correlation score is retained for each voxel.

Two output images are provided by the algorithm: Two types of masks can be managed by the algorithm: The main steps of a pattern detection by template matching are: Reference:
A.M. Roseman. "Particle finding in electron micrographs using a fast local correlation algorithm", Ultramicroscopy, 94(3-4), pp. 225-236, 2003.

See also

Function Syntax

This function returns a CudaTemplateMatching3dOutput structure containing outputImage and outputTransformIndexImage. 
// Output structure of the cudaTemplateMatching3d function.
struct CudaTemplateMatching3dOutput
{
    /// The correlation scores image. Its dimensions are forced to the same values as the input. Its data type is forced to floating point.
    std::shared_ptr< iolink::ImageView > outputImage;
    /// The index image for transform. Its dimensions are forced to the same values as the input. Its data type is forced to unsigned integer.
    std::shared_ptr< iolink::ImageView > outputTransformIndexImage;
    /// The data frame indicating the rotations and scales to apply.
    std::shared_ptr< const iolink::DataFrameView > transformTable;
};

// Function prototype
CudaTemplateMatching3dOutput
cudaTemplateMatching3d( std::shared_ptr< iolink::ImageView > inputImage,
                        std::shared_ptr< iolink::ImageView > inputTemplate,
                        std::shared_ptr< iolink::ImageView > inputMask,
                        std::shared_ptr< iolink::ImageView > inputFilter,
                        bool rotateMask,
                        std::shared_ptr< const iolink::DataFrameView > transformTable,
                        CudaTemplateMatching3d::TilingMode tilingMode,
                        const iolink::Vector3u32& tileSize,
                        CudaContext::Ptr cudaContext,
                        std::shared_ptr< iolink::ImageView > outputImage = nullptr,
                        std::shared_ptr< iolink::ImageView > outputTransformIndexImage = nullptr );
This function returns a tuple containing output_image and output_transform_index_image. 
// Function prototype.
cuda_template_matching_3d(input_image: idt.ImageType,
                          input_template: idt.ImageType,
                          input_mask: idt.ImageType,
                          input_filter: idt.ImageType,
                          rotate_mask: bool = False,
                          transform_table: Union[iolink.DataFrameView, None] = None,
                          tiling_mode: CudaTemplateMatching3d.TilingMode = CudaTemplateMatching3d.TilingMode.NONE,
                          tile_size: Iterable[int] = [128, 128, 128],
                          cuda_context: Union[CudaContext, None] = None,
                          output_image: idt.ImageType = None,
                          output_transform_index_image: idt.ImageType = None) -> Tuple[idt.ImageType, idt.ImageType]
This function returns a CudaTemplateMatching3dOutput structure containing outputImage and outputTransformIndexImage. 
/// Output structure of the CudaTemplateMatching3d function.
public struct CudaTemplateMatching3dOutput
{
    /// 
    /// The correlation scores image. Its dimensions are forced to the same values as the input. Its data type is forced to floating point.
    /// 
    public IOLink.ImageView outputImage;
    /// 
    /// The index image for transform. Its dimensions are forced to the same values as the input. Its data type is forced to unsigned integer.
    /// 
    public IOLink.ImageView outputTransformIndexImage;
    /// The data frame indicating the rotations and scales to apply.
    public IOLink.DataFrameView transformTable;
};

// Function prototype.
public static CudaTemplateMatching3dOutput
CudaTemplateMatching3d( IOLink.ImageView inputImage,
                        IOLink.ImageView inputTemplate,
                        IOLink.ImageView inputMask,
                        IOLink.ImageView inputFilter,
                        bool rotateMask = false,
                        IOLink.DataFrameView transformTable = null,
                        CudaTemplateMatching3d.TilingMode tilingMode = ImageDev.CudaTemplateMatching3d.TilingMode.NONE,
                        uint[] tileSize = null,
                        Data.CudaContext cudaContext = null,
                        IOLink.ImageView outputImage = null,
                        IOLink.ImageView outputTransformIndexImage = null );

Class Syntax

Parameters

Parameter Name Description Type Supported Values Default Value
input
inputImage
The input image where the template is searched. Image Grayscale nullptr
input
inputTemplate
The template image. Its shape must be contained in the input image. Image Grayscale nullptr
input
inputMask
The input mask. Its shape must be the same as the template image. This parameter is optional. Image Binary nullptr
input
inputFilter
The input filter image used to correct the input template in the Fourier domain. Its spacing must be the same as the input image. This parameter is optional.
The image should correspond to a centered representation of a Fourier transform, the zero frequency (DC component) must be positioned at the center of the image. This ensures that the symmetry and frequency components are correctly interpreted. Furthermore, the dimensions of the image should be odd to allow for a true center pixel, which facilitates the proper alignment of the frequency components around this central point.
Since the correction process will be applied to the transformed templates, determining the minimum image size is complex and not straightforward. To simplify, we advise supplying an image with dimensions that are at least twice the size of the template's largest dimension. 		Image Binary or Grayscale nullptr
input
rotateMask
The flag that indicates if the mask has to be rotated with the template.
It increases significantly the computation time but has to be set to True if the mask is not rotation invariant (not a sphere). This option can be used when only some rotations are applied. When some scale factors are provided in the transform table, it is recommended to set it to True. 		Bool false
input
transformTable
The data frame indicating the rotations and scales to apply.
The columns are (RZ1, RX2, RZ3, SX, SY, SZ), where (RZ1, RX2, RZ3) represents the rotation components with the proper Euler angles ZXZ convention, and (SX, SY, SZ), the scale factor for each axis.
Their default values are respectively (0, 0, 0, 1, 1, 1). If some columns are omitted, their default values are considered. If this parameter is omitted no transform is applied (default values). The output of RotationGenerator3d can be directly set for this parameter. 		DataFrameViewConst nullptr
input
tilingMode
The way to manage the GPU memory. If the input image is already on GPU, this parameter is ignored.
NONE The entire input image is transferred to the GPU memory. If the total input, intermediate and output data size exceed the GPU memory, the computation will fail.
USER_DEFINED The input image is processed by tiles of a predefined size.
Enumeration NONE
input
tileSize
The tile width and height in voxels. They must be greater than or equal to the correlation kernel width and height. This parameter is used only in USER_DEFINED tiling mode. Vector3u32 Any value {128, 128, 128}
input
cudaContext
The CUDA context information.
For more information: CudaContext 		CudaContext nullptr
output
outputImage
The correlation scores image. Its dimensions are forced to the same values as the input. Its data type is forced to floating point. Image nullptr
output
outputTransformIndexImage
The index image for transform. Its dimensions are forced to the same values as the input. Its data type is forced to unsigned integer. Image nullptr
Parameter Name Description Type Supported Values Default Value
input
input_image
The input image where the template is searched. image Grayscale None
input
input_template
The template image. Its shape must be contained in the input image. image Grayscale None
input
input_mask
The input mask. Its shape must be the same as the template image. This parameter is optional. image Binary None
input
input_filter
The input filter image used to correct the input template in the Fourier domain. Its spacing must be the same as the input image. This parameter is optional.
The image should correspond to a centered representation of a Fourier transform, the zero frequency (DC component) must be positioned at the center of the image. This ensures that the symmetry and frequency components are correctly interpreted. Furthermore, the dimensions of the image should be odd to allow for a true center pixel, which facilitates the proper alignment of the frequency components around this central point.
Since the correction process will be applied to the transformed templates, determining the minimum image size is complex and not straightforward. To simplify, we advise supplying an image with dimensions that are at least twice the size of the template's largest dimension. 		image Binary or Grayscale None
input
rotate_mask
The flag that indicates if the mask has to be rotated with the template.
It increases significantly the computation time but has to be set to True if the mask is not rotation invariant (not a sphere). This option can be used when only some rotations are applied. When some scale factors are provided in the transform table, it is recommended to set it to True. 		bool False
input
transform_table
The data frame indicating the rotations and scales to apply.
The columns are (RZ1, RX2, RZ3, SX, SY, SZ), where (RZ1, RX2, RZ3) represents the rotation components with the proper Euler angles ZXZ convention, and (SX, SY, SZ), the scale factor for each axis.
Their default values are respectively (0, 0, 0, 1, 1, 1). If some columns are omitted, their default values are considered. If this parameter is omitted no transform is applied (default values). The output of RotationGenerator3d can be directly set for this parameter. 		data_frame_view_const None
input
tiling_mode
The way to manage the GPU memory. If the input image is already on GPU, this parameter is ignored.
NONE The entire input image is transferred to the GPU memory. If the total input, intermediate and output data size exceed the GPU memory, the computation will fail.
USER_DEFINED The input image is processed by tiles of a predefined size.
enumeration NONE
input
tile_size
The tile width and height in voxels. They must be greater than or equal to the correlation kernel width and height. This parameter is used only in USER_DEFINED tiling mode. vector3u32 Any value [128, 128, 128]
input
cuda_context
The CUDA context information.
For more information: CudaContext 		cuda_context None
output
output_image
The correlation scores image. Its dimensions are forced to the same values as the input. Its data type is forced to floating point. image None
output
output_transform_index_image
The index image for transform. Its dimensions are forced to the same values as the input. Its data type is forced to unsigned integer. image None
Parameter Name Description Type Supported Values Default Value
input
inputImage
The input image where the template is searched. Image Grayscale null
input
inputTemplate
The template image. Its shape must be contained in the input image. Image Grayscale null
input
inputMask
The input mask. Its shape must be the same as the template image. This parameter is optional. Image Binary null
input
inputFilter
The input filter image used to correct the input template in the Fourier domain. Its spacing must be the same as the input image. This parameter is optional.
The image should correspond to a centered representation of a Fourier transform, the zero frequency (DC component) must be positioned at the center of the image. This ensures that the symmetry and frequency components are correctly interpreted. Furthermore, the dimensions of the image should be odd to allow for a true center pixel, which facilitates the proper alignment of the frequency components around this central point.
Since the correction process will be applied to the transformed templates, determining the minimum image size is complex and not straightforward. To simplify, we advise supplying an image with dimensions that are at least twice the size of the template's largest dimension. 		Image Binary or Grayscale null
input
rotateMask
The flag that indicates if the mask has to be rotated with the template.
It increases significantly the computation time but has to be set to True if the mask is not rotation invariant (not a sphere). This option can be used when only some rotations are applied. When some scale factors are provided in the transform table, it is recommended to set it to True. 		Bool false
input
transformTable
The data frame indicating the rotations and scales to apply.
The columns are (RZ1, RX2, RZ3, SX, SY, SZ), where (RZ1, RX2, RZ3) represents the rotation components with the proper Euler angles ZXZ convention, and (SX, SY, SZ), the scale factor for each axis.
Their default values are respectively (0, 0, 0, 1, 1, 1). If some columns are omitted, their default values are considered. If this parameter is omitted no transform is applied (default values). The output of RotationGenerator3d can be directly set for this parameter. 		DataFrameViewConst null
input
tilingMode
The way to manage the GPU memory. If the input image is already on GPU, this parameter is ignored.
NONE The entire input image is transferred to the GPU memory. If the total input, intermediate and output data size exceed the GPU memory, the computation will fail.
USER_DEFINED The input image is processed by tiles of a predefined size.
Enumeration NONE
input
tileSize
The tile width and height in voxels. They must be greater than or equal to the correlation kernel width and height. This parameter is used only in USER_DEFINED tiling mode. Vector3u32 Any value {128, 128, 128}
input
cudaContext
The CUDA context information.
For more information: CudaContext 		CudaContext null
output
outputImage
The correlation scores image. Its dimensions are forced to the same values as the input. Its data type is forced to floating point. Image null
output
outputTransformIndexImage
The index image for transform. Its dimensions are forced to the same values as the input. Its data type is forced to unsigned integer. Image null

Object Examples

auto fibers = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "fibers.vip" );
auto fibers_template = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "fibers_template.vip" );
auto fibers_template_mask = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "fibers_template_mask.vip" );

CudaTemplateMatching3d cudaTemplateMatching3dAlgo;
cudaTemplateMatching3dAlgo.setInputImage( fibers );
cudaTemplateMatching3dAlgo.setInputTemplate( fibers_template );
cudaTemplateMatching3dAlgo.setInputMask( fibers_template_mask );
cudaTemplateMatching3dAlgo.setInputFilter( nullptr );
cudaTemplateMatching3dAlgo.setRotateMask( false );
cudaTemplateMatching3dAlgo.setTransformTable( nullptr );
cudaTemplateMatching3dAlgo.setTilingMode( CudaTemplateMatching3d::TilingMode::NONE );
cudaTemplateMatching3dAlgo.setTileSize( {128, 128, 128} );
cudaTemplateMatching3dAlgo.setCudaContext( nullptr );
cudaTemplateMatching3dAlgo.setOutputImage( iolink::ImageViewFactory::allocate( iolink::VectorXu64( { 1, 1 } ), iolink::DataTypeId::UINT8 ) );
cudaTemplateMatching3dAlgo.setOutputTransformIndexImage( iolink::ImageViewFactory::allocate( iolink::VectorXu64( { 1, 1 } ), iolink::DataTypeId::UINT8 ) );
cudaTemplateMatching3dAlgo.execute();

std::cout << "outputImage:" << cudaTemplateMatching3dAlgo.outputImage()->toString();
std::cout << "outputTransformIndexImage:" << cudaTemplateMatching3dAlgo.outputTransformIndexImage()->toString();

fibers = imagedev.read_vip_image(imagedev_data.get_image_path("fibers.vip"))
fibers_template = imagedev.read_vip_image(imagedev_data.get_image_path("fibers_template.vip"))
fibers_template_mask = imagedev.read_vip_image(imagedev_data.get_image_path("fibers_template_mask.vip"))

cuda_template_matching_3d_algo = imagedev.CudaTemplateMatching3d()
cuda_template_matching_3d_algo.input_image = fibers
cuda_template_matching_3d_algo.input_template = fibers_template
cuda_template_matching_3d_algo.input_mask = fibers_template_mask
cuda_template_matching_3d_algo.input_filter = None
cuda_template_matching_3d_algo.rotate_mask = False
cuda_template_matching_3d_algo.transform_table = None
cuda_template_matching_3d_algo.tiling_mode = imagedev.CudaTemplateMatching3d.NONE
cuda_template_matching_3d_algo.tile_size = [128, 128, 128]
cuda_template_matching_3d_algo.cuda_context = None
cuda_template_matching_3d_algo.execute()

print("output_image:", str(cuda_template_matching_3d_algo.output_image))
print("output_transform_index_image:", str(cuda_template_matching_3d_algo.output_transform_index_image))

ImageView fibers = Data.ReadVipImage( @"Data/images/fibers.vip" );
ImageView fibers_template = Data.ReadVipImage( @"Data/images/fibers_template.vip" );
ImageView fibers_template_mask = Data.ReadVipImage( @"Data/images/fibers_template_mask.vip" );

CudaTemplateMatching3d cudaTemplateMatching3dAlgo = new CudaTemplateMatching3d
{
    inputImage = fibers,
    inputTemplate = fibers_template,
    inputMask = fibers_template_mask,
    inputFilter = null,
    rotateMask = false,
    transformTable = null,
    tilingMode = CudaTemplateMatching3d.TilingMode.NONE,
    tileSize = new uint[]{128, 128, 128},
    cudaContext = null
};
cudaTemplateMatching3dAlgo.Execute();

Console.WriteLine( "outputImage:" + cudaTemplateMatching3dAlgo.outputImage.ToString() );
Console.WriteLine( "outputTransformIndexImage:" + cudaTemplateMatching3dAlgo.outputTransformIndexImage.ToString() );

Function Examples

auto fibers = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "fibers.vip" );
auto fibers_template = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "fibers_template.vip" );
auto fibers_template_mask = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "fibers_template_mask.vip" );

auto result = cudaTemplateMatching3d( fibers, fibers_template, fibers_template_mask, nullptr, false, nullptr, CudaTemplateMatching3d::TilingMode::NONE, {128, 128, 128}, nullptr , iolink::ImageViewFactory::allocate( iolink::VectorXu64( { 1, 1 } ), iolink::DataTypeId::UINT8 ), iolink::ImageViewFactory::allocate( iolink::VectorXu64( { 1, 1 } ), iolink::DataTypeId::UINT8 ));

std::cout << "outputImage:" << result.outputImage->toString();
std::cout << "outputTransformIndexImage:" << result.outputTransformIndexImage->toString();

fibers = imagedev.read_vip_image(imagedev_data.get_image_path("fibers.vip"))
fibers_template = imagedev.read_vip_image(imagedev_data.get_image_path("fibers_template.vip"))
fibers_template_mask = imagedev.read_vip_image(imagedev_data.get_image_path("fibers_template_mask.vip"))

result_output_image, result_output_transform_index_image = imagedev.cuda_template_matching_3d(fibers, fibers_template, fibers_template_mask, None, False, None, imagedev.CudaTemplateMatching3d.NONE, [128, 128, 128], None)

print("output_image:", str(result_output_image))
print("output_transform_index_image:", str(result_output_transform_index_image))

ImageView fibers = Data.ReadVipImage( @"Data/images/fibers.vip" );
ImageView fibers_template = Data.ReadVipImage( @"Data/images/fibers_template.vip" );
ImageView fibers_template_mask = Data.ReadVipImage( @"Data/images/fibers_template_mask.vip" );

Processing.CudaTemplateMatching3dOutput result = Processing.CudaTemplateMatching3d( fibers, fibers_template, fibers_template_mask, null, false, null, CudaTemplateMatching3d.TilingMode.NONE, new uint[]{128, 128, 128}, null );

Console.WriteLine( "outputImage:" + result.outputImage.ToString() );
Console.WriteLine( "outputTransformIndexImage:" + result.outputTransformIndexImage.ToString() );





© 2025 Thermo Fisher Scientific Inc. All rights reserved.