SurfaceUnfolding3d

Extracts a flattened 3D image from an input 3D image mapped to a surface mesh.

Access to parameter description

The input 3D surface is unfolded in order to appear as a flat layer of the output 3D image. Actually, the unfolded surface is a thick surface defined by the thickness parameter.

Thus, the result of this algorithm is also a 3D image corresponding to the region of the input volume defined by the input surface and a given thickness. The dimensions in voxels of the output image are defined by the size parameter.
This size is independent of the number of voxels in the input image and of the number of vertices in the input surface.

By default the thickness of the output volume is taken in the direction of the normal vectors to each cell of the input mesh.
If this behavior is not desired, these directions can be redefined with the directions parameter.

Creating a human dental panoramic image is a typical use case of this engine, where:

The inputImage corresponds to a CT scan image of the head.
The inputSurface is a surface which is centered on the teeth, jaw and facial bones.
The thickness is usually 1 or 2 cm in order to fit the thickness of each tooth.

See also

Function Syntax

This function returns outputImage.

// Function prototype
std::shared_ptr< iolink::ImageView >
surfaceUnfolding3d( std::shared_ptr< iolink::ImageView > inputImage,
                    std::shared_ptr<iolink::ArrayXd> inputSurface,
                    std::shared_ptr<iolink::ArrayXd> directions,
                    double thickness,
                    iolink::Vector3u32 size,
                    SurfaceUnfolding3d::InterpolationType interpolationType,
                    double paddingValue,
                    std::shared_ptr< iolink::ImageView > outputImage = NULL );

This function returns outputImage.

// Function prototype.
surface_unfolding_3d( input_image,
                      input_surface,
                      directions,
                      thickness = 1,
                      size = [1024, 1024, 256],
                      interpolation_type = SurfaceUnfolding3d.InterpolationType.LINEAR,
                      padding_value = 0,
                      output_image = None )

This function returns outputImage.

// Function prototype.
public static IOLink.ImageView
SurfaceUnfolding3d( IOLink.ImageView inputImage,
                    IOLink.ArrayXd inputSurface,
                    IOLink.ArrayXd directions,
                    double thickness = 1,
                    uint[] size = null,
                    SurfaceUnfolding3d.InterpolationType interpolationType = ImageDev.SurfaceUnfolding3d.InterpolationType.LINEAR,
                    double paddingValue = 0,
                    IOLink.ImageView outputImage = null );

Class Syntax

// Command constructor.
SurfaceUnfolding3d();

/// Gets the inputImage parameter.
/// The input 3D image.
std::shared_ptr< iolink::ImageView > inputImage() const;
/// Sets the inputImage parameter.
/// The input 3D image.
void setInputImage( std::shared_ptr< iolink::ImageView > inputImage );

/// Gets the inputSurface parameter.
/// The input surface as a starting point for the process.
std::shared_ptr<iolink::ArrayXd> inputSurface() const;
/// Sets the inputSurface parameter.
/// The input surface as a starting point for the process.
void setInputSurface( std::shared_ptr<iolink::ArrayXd> inputSurface );

/// Gets the directions parameter.
/// Optional direction vectors used to unfold the surface.
std::shared_ptr<iolink::ArrayXd> directions() const;
/// Sets the directions parameter.
/// Optional direction vectors used to unfold the surface.
void setDirections( std::shared_ptr<iolink::ArrayXd> directions );

/// Gets the thickness parameter.
/// The output image thickness expressed in calibration unit.
double thickness() const;
/// Sets the thickness parameter.
/// The output image thickness expressed in calibration unit.
void setThickness( const double& thickness );

/// Gets the size parameter.
/// The dimensions of the output image in number of voxels, respectively in the X, Y, and Z directions.
iolink::Vector3u32 size() const;
/// Sets the size parameter.
/// The dimensions of the output image in number of voxels, respectively in the X, Y, and Z directions.
void setSize( const iolink::Vector3u32& size );

/// Gets the interpolationType parameter.
/// The interpolation mode.
SurfaceUnfolding3d::InterpolationType interpolationType() const;
/// Sets the interpolationType parameter.
/// The interpolation mode.
void setInterpolationType( const SurfaceUnfolding3d::InterpolationType& interpolationType );

/// Gets the paddingValue parameter.
/// The default output value.
double paddingValue() const;
/// Sets the paddingValue parameter.
/// The default output value.
void setPaddingValue( const double& paddingValue );

/// Gets the outputImage parameter.
/// The output image.
std::shared_ptr< iolink::ImageView > outputImage() const;
/// Sets the outputImage parameter.
/// The output image.
void setOutputImage( std::shared_ptr< iolink::ImageView > outputImage );


// Method to launch the command.
void execute();

# Property of the inputImage parameter.
SurfaceUnfolding3d.input_image
# Property of the inputSurface parameter.
SurfaceUnfolding3d.input_surface
# Property of the directions parameter.
SurfaceUnfolding3d.directions
# Property of the thickness parameter.
SurfaceUnfolding3d.thickness
# Property of the size parameter.
SurfaceUnfolding3d.size
# Property of the interpolationType parameter.
SurfaceUnfolding3d.interpolation_type
# Property of the paddingValue parameter.
SurfaceUnfolding3d.padding_value
# Property of the outputImage parameter.
SurfaceUnfolding3d.output_image

// Method to launch the command.
execute()

// Command constructor.
SurfaceUnfolding3d()

// Property of the inputImage parameter.
SurfaceUnfolding3d.inputImage
// Property of the inputSurface parameter.
SurfaceUnfolding3d.inputSurface
// Property of the directions parameter.
SurfaceUnfolding3d.directions
// Property of the thickness parameter.
SurfaceUnfolding3d.thickness
// Property of the size parameter.
SurfaceUnfolding3d.size
// Property of the interpolationType parameter.
SurfaceUnfolding3d.interpolationType
// Property of the paddingValue parameter.
SurfaceUnfolding3d.paddingValue
// Property of the outputImage parameter.
SurfaceUnfolding3d.outputImage

// Method to launch the command.
Execute()

Parameters

Class Name	SurfaceUnfolding3d

Parameter Name

Description

Type

Supported Values

Default Value

inputImage

The input 3D image.

Image

Grayscale

nullptr

inputSurface

The input surface as a starting point for the process.
The dimensions of the ArrayXd must be [3, n, m] with :

3, the number of coordinates of a 3d point respectively corresponding to X, Y, and Z expressed in the calibration unit.
n, the number of columns of the mesh corresponding to the X axis of the output image.
m, the number of rows of the mesh corresponding to the Y axis of the output image.

ArrayXd

nullptr

directions

Optional direction vectors used to unfold the surface.
By default this field does not contain any data, which means that the algorithm will compute direction vectors as the normal vector to each vertex of the input surface inSurface.
If this field is set, it must contain as many vectors as the number of vertices in inputSurface.
If provided, the dimensions must be equivalent to the dimension of inputSurface.

ArrayXd

nullptr

thickness

The output image thickness expressed in calibration unit.

Float64

>=0

size

The dimensions of the output image in number of voxels, respectively in the X, Y, and Z directions.
This parameter defines the resolution of the output image. It is recommended to set this size in order to obtain a voxel size close to that of the input image.

Vector3u32

!= 0

{1024, 1024, 256}

interpolationType

The interpolation mode.
Method used to calculate the intensity of each pixel in the result image.

NEAREST_NEIGHBOR	The value of the intensity is equal to the nearest intensity.
LINEAR	The value of the intensity is linearly interpolated in all directions.

Enumeration

LINEAR

paddingValue

The default output value.
This value is used to fill output regions having no correspondence in the input image.

Float64

Any value

outputImage

The output image.
Its dimensions are defined by the size parameter. Its type, calibration, and interpretation are the same as the input image.

Image

nullptr

Object Examples

std::shared_ptr< iolink::ImageView > polystyrene = ioformat::readImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "polystyrene.tif" );
std::shared_ptr< iolink::ArrayXd> surfaceMesh( new iolink::ArrayXd( { 0 } ) );
readArrayXd( std::string( IMAGEDEVDATA_OBJECTS_FOLDER ) + "surfaceMesh.arrayxd", surfaceMesh);
std::shared_ptr< iolink::ArrayXd> surfaceNormals( new iolink::ArrayXd( { 0 } ) );
readArrayXd( std::string( IMAGEDEVDATA_OBJECTS_FOLDER ) + "surfaceNormals.arrayxd", surfaceNormals);

SurfaceUnfolding3d surfaceUnfolding3dAlgo;
surfaceUnfolding3dAlgo.setInputImage( polystyrene );
surfaceUnfolding3dAlgo.setInputSurface( surfaceMesh );
surfaceUnfolding3dAlgo.setDirections( surfaceNormals );
surfaceUnfolding3dAlgo.setThickness( 1 );
surfaceUnfolding3dAlgo.setSize( {50, 40, 20} );
surfaceUnfolding3dAlgo.setInterpolationType( SurfaceUnfolding3d::InterpolationType::LINEAR );
surfaceUnfolding3dAlgo.setPaddingValue( 0 );
surfaceUnfolding3dAlgo.execute();

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

polystyrene = ioformat.read_image(imagedev_data.get_image_path("polystyrene.tif"))
surface_mesh = np.zeros(0, dtype=np.double)
surface_mesh = imagedev.read_array_xd(imagedev_data.get_object_path("surfaceMesh.arrayxd"), surface_mesh)
surface_normals = np.zeros(0, dtype=np.double)
surface_normals = imagedev.read_array_xd(imagedev_data.get_object_path("surfaceNormals.arrayxd"), surface_normals)

surface_unfolding_3d_algo = imagedev.SurfaceUnfolding3d()
surface_unfolding_3d_algo.input_image = polystyrene
surface_unfolding_3d_algo.input_surface = surface_mesh
surface_unfolding_3d_algo.directions = surface_normals
surface_unfolding_3d_algo.thickness = 1
surface_unfolding_3d_algo.size = [50, 40, 20]
surface_unfolding_3d_algo.interpolation_type = imagedev.SurfaceUnfolding3d.LINEAR
surface_unfolding_3d_algo.padding_value = 0
surface_unfolding_3d_algo.execute()

print( "output_image:", str( surface_unfolding_3d_algo.output_image ) )

ImageView polystyrene = ViewIO.ReadImage( @"Data/images/polystyrene.tif" );
IOLink.ArrayXd surfaceMesh = new IOLink.ArrayXd(new IOLink.VectorXu64( 0 ) ) ;
surfaceMesh = Data.ReadArrayXd( @"Data/objects/surfaceMesh.arrayxd", surfaceMesh );
IOLink.ArrayXd surfaceNormals = new IOLink.ArrayXd(new IOLink.VectorXu64( 0 ) ) ;
surfaceNormals = Data.ReadArrayXd( @"Data/objects/surfaceNormals.arrayxd", surfaceNormals );

SurfaceUnfolding3d surfaceUnfolding3dAlgo = new SurfaceUnfolding3d
{
    inputImage = polystyrene,
    inputSurface = surfaceMesh,
    directions = surfaceNormals,
    thickness = 1,
    size = new uint[]{50, 40, 20},
    interpolationType = SurfaceUnfolding3d.InterpolationType.LINEAR,
    paddingValue = 0
};
surfaceUnfolding3dAlgo.Execute();

Console.WriteLine( "outputImage:" + surfaceUnfolding3dAlgo.outputImage.ToString() );

Function Examples

std::shared_ptr< iolink::ImageView > polystyrene = ioformat::readImage( std::string( IMAGEDEVDATA_IMAGES_FOLDER ) + "polystyrene.tif" );
std::shared_ptr< iolink::ArrayXd> surfaceMesh( new iolink::ArrayXd( { 0 } ) );
readArrayXd( std::string( IMAGEDEVDATA_OBJECTS_FOLDER ) + "surfaceMesh.arrayxd", surfaceMesh);
std::shared_ptr< iolink::ArrayXd> surfaceNormals( new iolink::ArrayXd( { 0 } ) );
readArrayXd( std::string( IMAGEDEVDATA_OBJECTS_FOLDER ) + "surfaceNormals.arrayxd", surfaceNormals);

auto result = surfaceUnfolding3d( polystyrene, surfaceMesh, surfaceNormals, 1, {50, 40, 20}, SurfaceUnfolding3d::InterpolationType::LINEAR, 0 );

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

polystyrene = ioformat.read_image(imagedev_data.get_image_path("polystyrene.tif"))
surface_mesh = np.zeros(0, dtype=np.double)
surface_mesh = imagedev.read_array_xd(imagedev_data.get_object_path("surfaceMesh.arrayxd"), surface_mesh)
surface_normals = np.zeros(0, dtype=np.double)
surface_normals = imagedev.read_array_xd(imagedev_data.get_object_path("surfaceNormals.arrayxd"), surface_normals)

result = imagedev.surface_unfolding_3d( polystyrene, surface_mesh, surface_normals, 1, [50, 40, 20], imagedev.SurfaceUnfolding3d.LINEAR, 0 )

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

ImageView polystyrene = ViewIO.ReadImage( @"Data/images/polystyrene.tif" );
IOLink.ArrayXd surfaceMesh = new IOLink.ArrayXd(new IOLink.VectorXu64( 0 ) ) ;
surfaceMesh = Data.ReadArrayXd( @"Data/objects/surfaceMesh.arrayxd", surfaceMesh );
IOLink.ArrayXd surfaceNormals = new IOLink.ArrayXd(new IOLink.VectorXu64( 0 ) ) ;
surfaceNormals = Data.ReadArrayXd( @"Data/objects/surfaceNormals.arrayxd", surfaceNormals );

IOLink.ImageView result = Processing.SurfaceUnfolding3d( polystyrene, surfaceMesh, surfaceNormals, 1, new uint[]{50, 40, 20}, SurfaceUnfolding3d.InterpolationType.LINEAR, 0 );

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

SurfaceUnfolding3d

- Function Syntax

+ Class Syntax

Parameters

Object Examples

Function Examples

Function Syntax

Class Syntax