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 the outputImage output parameter.

// 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 the outputImage output parameter.

// 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 the outputImage output parameter.

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

// Get method of the inputImage parameter.
std::shared_ptr< iolink::ImageView > inputImage() const;
// Set method of the inputImage parameter.
void setInputImage( std::shared_ptr< iolink::ImageView > inputImage );

// Get method of the inputSurface parameter.
std::shared_ptr<iolink::ArrayXd> inputSurface() const;
// Set method of the inputSurface parameter.
void setInputSurface( std::shared_ptr<iolink::ArrayXd> inputSurface );

// Get method of the directions parameter.
std::shared_ptr<iolink::ArrayXd> directions() const;
// Set method of the directions parameter.
void setDirections( std::shared_ptr<iolink::ArrayXd> directions );

// Get method of the thickness parameter.
double thickness() const;
// Set method of the thickness parameter.
void setThickness( const double& thickness );

// Get method of the size parameter.
iolink::Vector3u32 size() const;
// Set method of the size parameter.
void setSize( const iolink::Vector3u32& size );

// Get method of the interpolationType parameter.
SurfaceUnfolding3d::InterpolationType interpolationType() const;
// Set method of the interpolationType parameter.
void setInterpolationType( const SurfaceUnfolding3d::InterpolationType& interpolationType );

// Get method of the paddingValue parameter.
double paddingValue() const;
// Set method of the paddingValue parameter.
void setPaddingValue( const double& paddingValue );

// Get method of the outputImage parameter.
std::shared_ptr< iolink::ImageView > outputImage() const;
// Set method of the outputImage parameter.
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

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