ImageDev

DistanceMap3d

Computes the distance map of objects in a three-dimensional binary image.

Access to parameter description

A distance map, also known as distance transform, is a representation of an image where each voxel value corresponds to its distance to the nearest boundary voxel in a given metric.

Two metrics are commonly used:
In the output image $O$, a voxel $x$ belonging to a particle $X$, takes an intensity $I$ equal to the distance to the boundary.

In the case of the Chessboard metric, the distance is given by: $$ I=d_C(x,\delta(X)) $$ Where: $$ d_C((i,j,k),(l,m,n))=max(|l-i|,|m-j|,|n-k|) $$ The weight used for each neighbor configuration can be user defined. Some optimizations are automatically performed when the weights set correspond to a Chamfer or a Chessboard distance map.

Distance maps are computed on binary images either on object voxels (foreground) or on the background. The output image can have either a 16-bit signed integer or a 32-bit float type.

Note: This algorithm does not take into account the input image calibration. The output values are systematically indicating distance in voxel units.

See also

Function Syntax

This function returns outputMapImage. 
// Function prototype
std::shared_ptr< iolink::ImageView >
distanceMap3d( std::shared_ptr< iolink::ImageView > inputBinaryImage,
               DistanceMap3d::MappingMode mappingMode,
               DistanceMap3d::BorderCondition borderCondition,
               double faceDistance,
               double edgeDistance,
               double cornerDistance,
               DistanceMap3d::OutputType outputType,
               std::shared_ptr< iolink::ImageView > outputMapImage = nullptr );
This function returns outputMapImage. 
// Function prototype.
distance_map_3d(input_binary_image: idt.ImageType,
                mapping_mode: DistanceMap3d.MappingMode = DistanceMap3d.MappingMode.INSIDE,
                border_condition: DistanceMap3d.BorderCondition = DistanceMap3d.BorderCondition.MIRROR,
                face_distance: float = 1,
                edge_distance: float = 1.41421,
                corner_distance: float = 1.73205,
                output_type: DistanceMap3d.OutputType = DistanceMap3d.OutputType.SIGNED_INTEGER_16_BIT,
                output_map_image: idt.ImageType = None) -> idt.ImageType
This function returns outputMapImage. 
// Function prototype.
public static IOLink.ImageView
DistanceMap3d( IOLink.ImageView inputBinaryImage,
               DistanceMap3d.MappingMode mappingMode = ImageDev.DistanceMap3d.MappingMode.INSIDE,
               DistanceMap3d.BorderCondition borderCondition = ImageDev.DistanceMap3d.BorderCondition.MIRROR,
               double faceDistance = 1,
               double edgeDistance = 1.41421,
               double cornerDistance = 1.73205,
               DistanceMap3d.OutputType outputType = ImageDev.DistanceMap3d.OutputType.SIGNED_INTEGER_16_BIT,
               IOLink.ImageView outputMapImage = null );

Class Syntax

Parameters

Parameter Name Description Type Supported Values Default Value
input
inputBinaryImage
The binary input image.
Background is represented by zero values while objects are represented by one values. 		Image Binary nullptr
input
mappingMode
The mode defining where the distance field is computed.
INSIDE Distances are computed for voxels inside the objects (having an intensity equal to 1). Outside voxels remain to zero.
OUTSIDE Distances are computed for voxels outside of objects (having an intensity equal to 0). Inside voxels are set to zero.
Enumeration INSIDE
input
borderCondition
The mode defining the border conditions.
ZERO Voxels outside of the image are considered to have the value 0.
MIRROR Voxels outside of the image are considered as an extrapolation of the image voxels with a mirror border condition.
Enumeration MIRROR
input
faceDistance
The distance weight between 2 voxels having a face connection.
The value must be strictly positive. 		Float64 >0 1
input
edgeDistance
The distance weight between 2 voxels having an edge connection.
The value must be greater than or equal to faceDistance. 		Float64 Any value 1.41421
input
cornerDistance
The distance weight between 2 voxels having a corner connection.
The value must be greater than or equal to edgeDistance. 		Float64 Any value 1.73205
input
outputType
The output image type to provide.
SIGNED_INTEGER_16_BIT The output image type is 16-bit signed integer.
FLOAT_32_BIT The output image type is 32-bit float.
Enumeration SIGNED_INTEGER_16_BIT
output
outputMapImage
The output distance map image.
The distance map of the shape represented by the input image. Each voxel is assigned to a value corresponding to the distance to the nearest object boundary. Its dimensions are forced to the same values as the input. Its data type is defined by the outputType parameter. 		Image nullptr
Parameter Name Description Type Supported Values Default Value
input
input_binary_image
The binary input image.
Background is represented by zero values while objects are represented by one values. 		image Binary None
input
mapping_mode
The mode defining where the distance field is computed.
INSIDE Distances are computed for voxels inside the objects (having an intensity equal to 1). Outside voxels remain to zero.
OUTSIDE Distances are computed for voxels outside of objects (having an intensity equal to 0). Inside voxels are set to zero.
enumeration INSIDE
input
border_condition
The mode defining the border conditions.
ZERO Voxels outside of the image are considered to have the value 0.
MIRROR Voxels outside of the image are considered as an extrapolation of the image voxels with a mirror border condition.
enumeration MIRROR
input
face_distance
The distance weight between 2 voxels having a face connection.
The value must be strictly positive. 		float64 >0 1
input
edge_distance
The distance weight between 2 voxels having an edge connection.
The value must be greater than or equal to faceDistance. 		float64 Any value 1.41421
input
corner_distance
The distance weight between 2 voxels having a corner connection.
The value must be greater than or equal to edgeDistance. 		float64 Any value 1.73205
input
output_type
The output image type to provide.
SIGNED_INTEGER_16_BIT The output image type is 16-bit signed integer.
FLOAT_32_BIT The output image type is 32-bit float.
enumeration SIGNED_INTEGER_16_BIT
output
output_map_image
The output distance map image.
The distance map of the shape represented by the input image. Each voxel is assigned to a value corresponding to the distance to the nearest object boundary. Its dimensions are forced to the same values as the input. Its data type is defined by the outputType parameter. 		image None
Parameter Name Description Type Supported Values Default Value
input
inputBinaryImage
The binary input image.
Background is represented by zero values while objects are represented by one values. 		Image Binary null
input
mappingMode
The mode defining where the distance field is computed.
INSIDE Distances are computed for voxels inside the objects (having an intensity equal to 1). Outside voxels remain to zero.
OUTSIDE Distances are computed for voxels outside of objects (having an intensity equal to 0). Inside voxels are set to zero.
Enumeration INSIDE
input
borderCondition
The mode defining the border conditions.
ZERO Voxels outside of the image are considered to have the value 0.
MIRROR Voxels outside of the image are considered as an extrapolation of the image voxels with a mirror border condition.
Enumeration MIRROR
input
faceDistance
The distance weight between 2 voxels having a face connection.
The value must be strictly positive. 		Float64 >0 1
input
edgeDistance
The distance weight between 2 voxels having an edge connection.
The value must be greater than or equal to faceDistance. 		Float64 Any value 1.41421
input
cornerDistance
The distance weight between 2 voxels having a corner connection.
The value must be greater than or equal to edgeDistance. 		Float64 Any value 1.73205
input
outputType
The output image type to provide.
SIGNED_INTEGER_16_BIT The output image type is 16-bit signed integer.
FLOAT_32_BIT The output image type is 32-bit float.
Enumeration SIGNED_INTEGER_16_BIT
output
outputMapImage
The output distance map image.
The distance map of the shape represented by the input image. Each voxel is assigned to a value corresponding to the distance to the nearest object boundary. Its dimensions are forced to the same values as the input. Its data type is defined by the outputType parameter. 		Image null

Object Examples

auto foam_sep = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam_sep.vip" );

DistanceMap3d distanceMap3dAlgo;
distanceMap3dAlgo.setInputBinaryImage( foam_sep );
distanceMap3dAlgo.setMappingMode( DistanceMap3d::MappingMode::INSIDE );
distanceMap3dAlgo.setBorderCondition( DistanceMap3d::BorderCondition::MIRROR );
distanceMap3dAlgo.setFaceDistance( 1 );
distanceMap3dAlgo.setEdgeDistance( 1.4142135623730951 );
distanceMap3dAlgo.setCornerDistance( 1.7320508075688772 );
distanceMap3dAlgo.setOutputType( DistanceMap3d::OutputType::SIGNED_INTEGER_16_BIT );
distanceMap3dAlgo.execute();

std::cout << "outputMapImage:" << distanceMap3dAlgo.outputMapImage()->toString();

foam_sep = imagedev.read_vip_image(imagedev_data.get_image_path("foam_sep.vip"))

distance_map_3d_algo = imagedev.DistanceMap3d()
distance_map_3d_algo.input_binary_image = foam_sep
distance_map_3d_algo.mapping_mode = imagedev.DistanceMap3d.INSIDE
distance_map_3d_algo.border_condition = imagedev.DistanceMap3d.MIRROR
distance_map_3d_algo.face_distance = 1
distance_map_3d_algo.edge_distance = 1.4142135623730951
distance_map_3d_algo.corner_distance = 1.7320508075688772
distance_map_3d_algo.output_type = imagedev.DistanceMap3d.SIGNED_INTEGER_16_BIT
distance_map_3d_algo.execute()

print("output_map_image:", str(distance_map_3d_algo.output_map_image))

ImageView foam_sep = Data.ReadVipImage( @"Data/images/foam_sep.vip" );

DistanceMap3d distanceMap3dAlgo = new DistanceMap3d
{
    inputBinaryImage = foam_sep,
    mappingMode = DistanceMap3d.MappingMode.INSIDE,
    borderCondition = DistanceMap3d.BorderCondition.MIRROR,
    faceDistance = 1,
    edgeDistance = 1.4142135623730951,
    cornerDistance = 1.7320508075688772,
    outputType = DistanceMap3d.OutputType.SIGNED_INTEGER_16_BIT
};
distanceMap3dAlgo.Execute();

Console.WriteLine( "outputMapImage:" + distanceMap3dAlgo.outputMapImage.ToString() );

Function Examples

auto foam_sep = readVipImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "foam_sep.vip" );

auto result = distanceMap3d( foam_sep, DistanceMap3d::MappingMode::INSIDE, DistanceMap3d::BorderCondition::MIRROR, 1, 1.4142135623730951, 1.7320508075688772, DistanceMap3d::OutputType::SIGNED_INTEGER_16_BIT );

std::cout << "outputMapImage:" << result->toString();

foam_sep = imagedev.read_vip_image(imagedev_data.get_image_path("foam_sep.vip"))

result = imagedev.distance_map_3d(foam_sep, imagedev.DistanceMap3d.INSIDE, imagedev.DistanceMap3d.MIRROR, 1, 1.4142135623730951, 1.7320508075688772, imagedev.DistanceMap3d.SIGNED_INTEGER_16_BIT)

print("output_map_image:", str(result))

ImageView foam_sep = Data.ReadVipImage( @"Data/images/foam_sep.vip" );

IOLink.ImageView result = Processing.DistanceMap3d( foam_sep, DistanceMap3d.MappingMode.INSIDE, DistanceMap3d.BorderCondition.MIRROR, 1, 1.4142135623730951, 1.7320508075688772, DistanceMap3d.OutputType.SIGNED_INTEGER_16_BIT );

Console.WriteLine( "outputMapImage:" + result.ToString() );