ImageDev

CudaTemplateMatching3d

Performs a correlation by convolution between a three-dimensional grayscale image and a grayscale kernel.

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.

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.
    std::shared_ptr< iolink::ImageView > outputImage;
    /// The index image for transform.
    std::shared_ptr< iolink::ImageView > outputTransformIndexImage;
    /// The dataframe indicating the rotations and scale 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,
                        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.
    public IOLink.ImageView outputImage;
    /// The index image for transform.
    public IOLink.ImageView outputTransformIndexImage;
    /// The dataframe indicating the rotations and scale 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
Optional: The input mask. Its shape must be the same as the template image. Image Binary or Grayscale nullptr
input
inputFilter
Optional: The input filter image used to correct the input template in the Fourier domain. Its shape must be the same as the input reference image. Image 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). 		Bool false
input
transformTable
The dataframe indicating the rotations and scale to apply.
Columns: Rx (def 0), Ry (def 0), Rz (def 0), Sx (def 1), Sy (def 1), Sz (def 1). If columns are omitted default value are considered. If parameter is omitted no transform is applied (default values). The output of RotationGenreator3d 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 pixels. 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
CUDA context information. CudaContext nullptr
output
outputImage
The correlation scores image. Image nullptr
output
outputTransformIndexImage
The index image for transform. 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
Optional: The input mask. Its shape must be the same as the template image. image Binary or Grayscale None
input
input_filter
Optional: The input filter image used to correct the input template in the Fourier domain. Its shape must be the same as the input reference image. image 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). 		bool False
input
transform_table
The dataframe indicating the rotations and scale to apply.
Columns: Rx (def 0), Ry (def 0), Rz (def 0), Sx (def 1), Sy (def 1), Sz (def 1). If columns are omitted default value are considered. If parameter is omitted no transform is applied (default values). The output of RotationGenreator3d 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 pixels. 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
CUDA context information. cuda_context None
output
output_image
The correlation scores image. image None
output
output_transform_index_image
The index image for transform. 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
Optional: The input mask. Its shape must be the same as the template image. Image Binary or Grayscale null
input
inputFilter
Optional: The input filter image used to correct the input template in the Fourier domain. Its shape must be the same as the input reference image. Image 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). 		Bool false
input
transformTable
The dataframe indicating the rotations and scale to apply.
Columns: Rx (def 0), Ry (def 0), Rz (def 0), Sx (def 1), Sy (def 1), Sz (def 1). If columns are omitted default value are considered. If parameter is omitted no transform is applied (default values). The output of RotationGenreator3d 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 pixels. 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
CUDA context information. CudaContext null
output
outputImage
The correlation scores image. Image null
output
outputTransformIndexImage
The index image for transform. 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.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 );

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() );