ImageDev

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: 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 = nullptr );
This function returns outputImage. 
// Function prototype.
surface_unfolding_3d(input_image: idt.ImageType,
                     input_surface: Union[idt.NDArrayFloat, None],
                     directions: Union[idt.NDArrayFloat, None],
                     thickness: float = 1,
                     size: Iterable[int] = [1024, 1024, 256],
                     interpolation_type: SurfaceUnfolding3d.InterpolationType = SurfaceUnfolding3d.InterpolationType.LINEAR,
                     padding_value: float = 0,
                     output_image: idt.ImageType = None) -> idt.ImageType
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

Parameters

Parameter Name Description Type Supported Values Default Value
input
inputImage
The input 3D image. Image Grayscale nullptr
input
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
input
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
input
thickness
The output image thickness expressed in calibration unit. Float64 >=0 1
input
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}
input
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
input
paddingValue
The default output value.
This value is used to fill output regions having no correspondence in the input image. 		Float64 Any value 0
output
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
Parameter Name Description Type Supported Values Default Value
input
input_image
The input 3D image. image Grayscale None
input
input_surface
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
input
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
input
thickness
The output image thickness expressed in calibration unit. float64 >=0 1
input
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]
input
interpolation_type
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
input
padding_value
The default output value.
This value is used to fill output regions having no correspondence in the input image. 		float64 Any value 0
output
output_image
The output image.
Its dimensions are defined by the size parameter. Its type, calibration, and interpretation are the same as the input image. 		image None
Parameter Name Description Type Supported Values Default Value
input
inputImage
The input 3D image. Image Grayscale null
input
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
input
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
input
thickness
The output image thickness expressed in calibration unit. Float64 >=0 1
input
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}
input
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
input
paddingValue
The default output value.
This value is used to fill output regions having no correspondence in the input image. 		Float64 Any value 0
output
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 null

Object Examples

auto 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

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