A class for generating a 3D mesh from 2D image slices. This class acts as a wrapper to the CGAL, VTK, and ImageMagick++ libraries to read, build, and export tetrahedral meshes from a pixel image. The class is used by the v2m executable (Image Mesh Generation: v2m) and supports many of the features demonstrated in the CGAL documentation. More...

#include <vol2mesh/vol2mesh.h>

Collaboration diagram for SlaughterVol2mesh::Vol2mesh:

[legend]

List of all members.

Public Member Functions
	Vol2mesh (string infile)
	Class constructor.
void	set_voxel (int i, double vox)
	Sets the correct voxel size based on supplied value.
void	set_voxel (vector< double > vox)
	Sets the correct voxel size based on supplied vector.
void	set_dimension (int i, double dim)
	Sets the correct voxel size based on the overall image dimension.
void	set_dimension (vector< double > dim)
	Sets the correct voxel size based on vector of overall image dimensions.
void	set_output_file (string output_file)
	Sets the output file.
vector< int >	pixels ()
	Returns a vector of the image size in pixels.
vector< double >	voxels ()
	Returns a vector of the voxel dimensions.
void	set_default_criteria (Vol2meshMeshCriteria c)
	Set default CGAL meshing criteria parameters.
Vol2meshMeshCriteria &	get_default_criteria ()
	Return a reference to the default meshing criteria.
void	add_subdomain (int id, Vol2meshMeshCriteria c)
	Adds meshing criteria for a subdomain.
vector< Vol2meshMeshCriteria > &	get_subdomain_criteria ()
	Returns reference to vector of Vol2meshMeshCriteria.
void	normalize (bool value)
	Sets the mesh criterial normalization behavior.
void	disable_subdomains (bool value)
	Disable all subdomain behavior.
void	set_optimization (string type, bool value)
	Function for changing the mesh optimization settings.
CGAL::Image_3 &	image ()
	Returns a reference to the CGAL image object.
void	generate_mesh ()
	Generates the 3D mesh.
C3t3 &	c3t3 ()
	Returns a reference to the CGAL mesh.
void	write (string output_file)
	Exports the CGAL mesh to a file.
void	write ()
	Exports the CGAL mesh to a file.
void	print_results (double t, bool disable_screen=false, bool enable_file=false)
	Exports the meshing results to a file and/or screen.
Public Attributes
odt_lloyd_settings	odt
	Storage structure for Odt optimization settings.
odt_lloyd_settings	lloyd
	Storage structure for Lloyd optimization settings.
perturb_exude_settings	perturb
	Storage structure for Perturb optimization methods.
perturb_exude_settings	exude
	Storage structure for Exude optimization methods.

Detailed Description

A class for generating a 3D mesh from 2D image slices. This class acts as a wrapper to the CGAL, VTK, and ImageMagick++ libraries to read, build, and export tetrahedral meshes from a pixel image. The class is used by the v2m executable (Image Mesh Generation: v2m) and supports many of the features demonstrated in the CGAL documentation.

CGAL Documentation:
http://www.cgal.org/Manual/latest/doc_html/cgal_manual/Mesh_3/Chapter_main.html

See also:: v2m.cpp

Constructor & Destructor Documentation

SlaughterVol2mesh::Vol2mesh::Vol2mesh ( string infile )

Class constructor.

This constructor reads the image generating the CGAL::Image_3 object, which is available through the image() member of this class. It also sets the pixel dimensions which is available from the pixels() member of this class. It sets the default mesh criteria (see Vol2meshMeshCriteria) values to the values in the CGAL examples:

facet-angle = 30
facet-size = 6
facet-distance = 4
cell-radius-edge-ratio = 3
cell-size = 8

The normalization flag is set to false and the optimization flags are set to the default values of the CGAL Make_mesh_3 function (see the set_optimization member).

The output file name is also set to "output.ex2."

The default optimization parameters are set to that of the CGAL library, the optimization methods to be used may be set with the set_optimization function. The parameters for each method may be set with the corresponding data structure. Links to the settings are provided in the documentation for the storage structures: perturb_exude_settings and odt_lloyd_settings.

The optimization routines are implemented in order as done in the CGAl library: llyod, odt, perturb, exude.

Parameters:

infile A std::string containg the name of the image file to open; *.tiff, *.inr, and *.inr.gz files are supported

Note, this class contains no public attributes, access to any attributes that are to be changed by the user is done with member functions designed to control the behavior correctly. All private attributes are labeled with "_" proceeding the name.

See also:: v2m.cpp; odt_lloyd_settings; perturb_exude_settings; set_optimization; Vol2meshMeshCriteria

Member Function Documentation

void SlaughterVol2mesh::Vol2mesh::add_subdomain	(	int	id,
		Vol2meshMeshCriteria	c
	)

Adds meshing criteria for a subdomain.

The actual values for each pixel (0 to 255) may be used to define subdomains within the image. This function allows the user to specify different meshing criteria for the subdomain.

Parameters:

id	A value identifing the subdomain (0 to 255)
c	The mesh criteria to use for this subdomain

See also:: Vol2meshMeshCriteria; disable_subdomains

C3t3 & SlaughterVol2mesh::Vol2mesh::c3t3 ( )

Returns a reference to the CGAL mesh.

The generate_mesh() function must be called prior to accessing the mesh.

Returns:: A reference to the CGAL::C3t3 object containing the generated mesh

See also:: generate_mesh()

void SlaughterVol2mesh::Vol2mesh::disable_subdomains ( bool value )

Disable all subdomain behavior.

Setting this value to true will eliminate all subdomain options and generate the mesh with all the same criteria as defined by the class defaults. The mesh will also be exported without defining subdomain parameters.

Parameters:

value A true/false value for disable/enabling subdomains

See also:: add_subdomian; set_default_criteria; get_default_criteria

void SlaughterVol2mesh::Vol2mesh::generate_mesh ( )

Generates the 3D mesh.

Until this function is called no mesh exists, as such the c3t3() function will return an empty reference. This function applies the defined mesh criteria and optimization to generate a mesh.

This function must also be called before the write() and print_results() members.

See also:: set_optimization; set_default_criteria; get_default_criteria; add_subdomain; write; print_results

Vol2meshMeshCriteria & SlaughterVol2mesh::Vol2mesh::get_default_criteria ( )

Return a reference to the default meshing criteria.

Returns:: Reference to the default meshing criteria, a Vol2meshMeshCriteria class

See also:: set_default_criteria; Vol2MeshCriteria

vector< Vol2meshMeshCriteria > & SlaughterVol2mesh::Vol2mesh::get_subdomain_criteria ( )

Returns reference to vector of Vol2meshMeshCriteria.

The mesh criteria for the various subdomains that were added to this class using the add_subdomain function are stored in a vector, a reference is returned here to provide access to these criteria.

Returns:: A vector of the subdomain mesh criteria

See also:: add_subdomain

CGAL::Image_3 & SlaughterVol2mesh::Vol2mesh::image ( )

Returns a reference to the CGAL image object.

The CGAL library coverts the image file into a Image_3 object, this function returns a reference to that object. See the CGAL documentation for more details regarind working with this object.

Returns:: Reference to CGAL::Image_3 object

See also:: Vol2mesh()

void SlaughterVol2mesh::Vol2mesh::normalize ( bool value )

Sets the mesh criterial normalization behavior.

The mesh criteria are defined with units that are proportional to the voxel size. This function will normalize the supplied mesh criteria base on the voxel size so that the criteria may be specified on a unit square basis, as such the criteria will behave similarily across images regardless of the pixel dimensions.

Parameters:

value A true/false value indicating to normalize or not

See also:: Vol2meshMeshCriteria

void SlaughterVol2mesh::Vol2mesh::print_results	(	double	t,
		bool	disable_screen = `false`,
		bool	enable_file = `false`
	)

Exports the meshing results to a file and/or screen.

The settings specified in the Vol2mesh class such as the filenames and mesh criteria may be exported to the screen and or file using this function.

Also, the quality of mesh statistics are reported by this function. These are computed using the VTK library

Parameters:

t	The execution time
disable_screen	Set this to true to exclude screen display
enable_file	Set this to true to print a information file, it uses the *.info extension appeneded to the output filename ("output.ex2" by default)

See also:: write

void SlaughterVol2mesh::Vol2mesh::set_default_criteria ( Vol2meshMeshCriteria c )

Set default CGAL meshing criteria parameters.

Replaces the existing default meshing criteria with those defined in the instance of the Vol2meshMeshCriteria class supplied.

This is useful when using different criteria on sub domains, if the criteria are not defined on a subdomain with the add_subdomain member function then the default values are used, this allows the user to change them from what was defined in the constructor.

If no subdomains this function is used to set the desired mesh criteria desired.

Parameters:

c	Vol2meshMeshCriteria instance to replace the default mesh criteria

See also:: get_default_criteria; Vol2meshMeshCriteria

void SlaughterVol2mesh::Vol2mesh::set_dimension	(	int	i,
		double	dim
	)

Sets the correct voxel size based on the overall image dimension.

The mesh dimensions are based on the dimensions of the image voxels (pixel). This function sets the image voxel size for based on the supplied image dimension

Parameters:

i	The direction of interest: 0 = x; 1 = y; 2 = z
dim	The dimension of the image in specified direction

See also:: set_dimension(vector<double> vox); set_voxel(vector<double> vox); set_voxel(int i, double vox)

void SlaughterVol2mesh::Vol2mesh::set_dimension ( vector< double > dim )

Sets the correct voxel size based on vector of overall image dimensions.

The mesh dimensions are based on the dimensions of the image voxels (pixel). This function sets the image voxel size for based on the supplied vector of image dimensions

Parameters:

dim	The dimension of the image in vector format

See also:: set_dimension(int i, double dim); set_voxel(vector<double> vox); set_voxel(int i, double vox)

void SlaughterVol2mesh::Vol2mesh::set_optimization	(	string	type,
		bool	value
	)

Function for changing the mesh optimization settings.

CGAL defines four methods for performing mesh optimization, this function allows the useage of these tools to be toggled on or off.

Details of the optimization may be found in the CGAL documentation: http://www.cgal.org/Manual/latest/doc_html/cgal_manual/Mesh_3/Chapter_main.html#Section_50.2

Parameters:

type	A std::string that may be one of four values: "lloyd", "odt", "perturb", or "exude"
value	A boolean indicating whether the specified optimization should be used.

void SlaughterVol2mesh::Vol2mesh::set_output_file ( string output_file )

Sets the output file.

Allows the user to specify the output file seperate from the write function. Note, that the name given in the write function overwrites this value.

Parameters:

output_file the output filename

See also:: write(); write(string output_file)

void SlaughterVol2mesh::Vol2mesh::set_voxel	(	int	i,
		double	vox
	)

Sets the correct voxel size based on supplied value.

The mesh dimensions are based on the dimensions of the image voxels (pixel). This function sets the image voxel size for the desired dimension.

Parameters:

i	The direction of interest: 0 = x; 1 = y; 2 = z
vox	The dimension of the pixel in specified direction

See also:: set_voxel(vector<double> vox); voxels()

void SlaughterVol2mesh::Vol2mesh::set_voxel ( vector< double > vox )

Sets the correct voxel size based on supplied vector.

The mesh dimensions are based on the dimensions of the image voxels (pixel). This function sets the image voxel size for based on the supplied vector of dimensions

Parameters:

vox	The dimensions of the pixel in vector format

See also:: set_voxel(int i, double vox)

vector< double > SlaughterVol2mesh::Vol2mesh::voxels ( )

Returns a vector of the voxel dimensions.

The voxel dimension dictate the dimensions of the image, this provides access to the current values.

Returns:: A vector containg the dimensions of the image in pixels

See also:: set_voxel(vector<double> vox); set_voxel(int i, double vox)

void SlaughterVol2mesh::Vol2mesh::write ( string output_file )

Exports the CGAL mesh to a file.

This generate_mesh function must be called prior to writing the mesh to a file. Three file types are supported:

*.medit - This is the only file format natively supported by the CGAL library, the following three types are all generated by convering the CGAL mesh to a VTK mesh.
*.vtk - The legacy version of the VTK format
*.vtu - The XML format of the VTK format
*.ex2 - An Exodus II file.

Parameters:

output_file A string containg the filename to which the mesh will be exported, the extension dictates the format

See also:: write(); set_input_file; generate_mesh

void SlaughterVol2mesh::Vol2mesh::write ( )

Exports the CGAL mesh to a file.

This generate_mesh function must be called prior to writing the mesh to a file. Three file types are supported:

*.medit - This is the only file format natively supported by the CGAL library, the following three types are all generated by convering the CGAL mesh to a VTK mesh.
*.vtk - The legacy version of the VTK format
*.vtu - The XML format of the VTK format
*.ex2 - An Exodus II file.