Difference between revisions of "CRTC I2M"

From crtc.cs.odu.edu
Jump to: navigation, search
(→‎Note for Running on Windows)
Line 1: Line 1:
 +
__TOC__
 
__TOC__
 
__TOC__
  
Line 4: Line 5:
 
-----
 
-----
  
−
This page contains instructions for downloading and using the CNF_tools suite developed at [https://cepm.cs.odu.edu/Main_Page CRTC lab] in [https://odu.edu/compsci Old Dominion University] in collaboration with Jefferson Lab.
 
  
−
This project corresponds to Proposal No.: ''CNF19-04 (FEMT-002)''
+
= Introduction =
  
−
A short presentation can be found [http://www.cs.odu.edu/crtc/cnf_project/assets/Imaging_Chrisochoides_ODU_04_30_19.pdf here]
+
This page contains instructions for downloading and using the <code>crtc_i2m</code> software suite developed by the [https://crtc.cs.odu.edu/Main_Page CRTC lab] at [https://odu.edu/compsci Old Dominion University].
  
−
The main component of the software suite is a 3D tessellation software called '''PODM''' capable of generating unstructured tetrahedral meshes out of 3D structured data.
+
The suite contains three software components:
  
−
The output meshes are in the [https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf VTK format] and can be visualized using the opensource software [https://www.paraview.org Paraview]. A short video demo exploring the data can be found [http://www.cs.odu.edu/crtc/videos/paraview.html here].
+
# '''Tessellate3D (PODM 3D)''' (3D tessellation software)
 +
# '''Tessellate2D (Triangle)''' (2D tessellation software)
 +
# '''Convert Image''' (image format conversion software)
 +
 
 +
= Problem Domains =
 +
 
 +
The image-to-mesh conversion software suite that the CRTC has developed can be used in many different problem domains such as Medical Image Computing and Computational Nuclear Femtography. Specific instructions on how to use the software are described below.
 +
 
 +
== Medical Image Computing ==
 +
 
 +
=== Tessellate3D ===
 +
 
 +
In Medical Image Computing, Tessellate3D can be used to generate meshes for many different objects, such as brains and other organs and tissues.
 +
 
 +
==== Parameters ====
 +
 
 +
In this domain, some of the parameters of Tessellate3D take on different meanings. For the full range and descriptions of parameters please see the software documentation section for Tessellate3D.
 +
 
 +
<code>-i, --input [filename]</code> (required)
 +
 
 +
Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library.
 +
 
 +
<code>-o, --output [filename]</code> (optional)
 +
 
 +
The filename of the output mesh. (Default: <code>outputMesh.vtk</code>).
 +
 
 +
<code>-c, --plc [filename]</code> (optional)
 +
 
 +
If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.
 +
 
 +
<code>-t, --threads [unsigned integer]</code> (optional)
 +
 
 +
Sets the number of threads to be utilized.<br />
 +
(Default: 1).
 +
 
 +
<code>-d, --delta [unsigned real]</code> (optional)
 +
 
 +
Controls the density of surface approximation. Smaller values will lead to denser approximation close to the surface (and often to a more accurate surface representation), but will also lead to greater mesh size. The same delta value is used for every tissue of interest. A smaller delta value should be used if at least one of the tissues of interest is not recovered after the Meshing Procedure.
 +
 
 +
The maximum suggested value for delta is ''1 / 5'' of the ''minimum-physical-size'' of the input image, where ''minimum-physical-size'' = min(spacing * size).<br />
 +
(Default: ''1 / 100'' * ''minimum-physical-size'').
 +
 
 +
<code>-g, --volume-grading</code> (optional)
 +
 
 +
Enables the grading of the volume of the mesh. By default, the value of delta controls both the surface approximation and the size of the elements. Using this flag the value of delta will control only the surface approximation resulting in elements of higher volume inside the domain.
 +
 
 +
==== Examples ====
 +
 
 +
Input image and clipped generated meshes
 +
 
 +
[[File:Head-Neck.png|1000px]]
 +
 
 +
* Input (left figure): Dimensions (255x255x229) with spacing (0.976562x0.976562x1.40002)
 +
* Uniform with Delta = default (middle figure): 205,416 tetrahedra
 +
* Uniform with Delta = 1.5 (right figure): 770,853 tetrahedra
 +
 
 +
Uniform with Delta = default (middle figure):
 +
 
 +
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./Medical_Imaging_Data/3D/Head-Neck.mha --output ./Head-Neck,d=2.49023.vtk</pre>
 +
Uniform with Delta = 1.5 (right figure):
 +
 
 +
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./Medical_Imaging_Data/3D/Head-Neck.mha --delta 1.5 -o ./Head-Neck,d=1.5.vtk</pre>
 +
More Medical Image Computing examples can be found [https://crtc.cs.odu.edu/Medical_Imaging_Example_Meshes here].
 +
 
 +
== Computational Nuclear Femtography ==
 +
 
 +
A short presentation can be found [http://www.cs.odu.edu/crtc/cnf_project/assets/Imaging_Chrisochoides_ODU_04_30_19.pdf here].
 +
 
 +
=== Tessellate3D ===
 +
 
 +
==== Parameters ====
 +
 
 +
In this domain, some of the parameters of Tessellate3D take on different meanings. For the full range and descriptions of parameters please see the software documentation section for Tessellate3D.
 +
 
 +
<code>-i, --input [filename]</code> (required)
 +
 
 +
Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library.
 +
 
 +
<code>-o, --output [filename]</code> (optional)
 +
 
 +
The filename of the output mesh.<br />
 +
(Default: <code>outputMesh.vtk</code>).
 +
 
 +
<code>-c, --plc [filename]</code> (optional)
 +
 
 +
If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.
 +
 
 +
<code>-t, --threads [unsigned integer]</code> (optional)
 +
 
 +
Sets the number of threads to be utilized.<br />
 +
(Default: 1).
 +
 
 +
<code>-d, --delta [unsigned real]</code> (optional)
 +
 
 +
Controls the size of the elements near the boundary. Smaller values will lead to finer detail close to the boundary (and often to a more accurate boundary representation) but will also lead to a greater mesh size.
 +
 
 +
(Default (if <code>--sizing-function</code> is not specified): ''1 / 100'' * ''minimum-physical-size'').<br />
 +
(Default (if <code>--sizing-function</code> is specified): ''1 / 20'' * ''minimum-physical-size'').
 +
 
 +
<code>-g, --volume-grading</code> (optional)
 +
 
 +
Enables the grading of the volume of the mesh. By default, the value of delta controls both the surface approximation and the size of the elements. Using this flag the value of delta will control only the surface approximation resulting in elements of higher volume inside the domain.
 +
 
 +
<code>-s, --image-segmentation</code> (optional)
 +
 
 +
Performs Image Segmentation using a given background value. Uses <code>--background-value</code> as an optional parameter.
 +
 
 +
<code>-b, --background-value [signed real]</code> (optional)
 +
 
 +
Sets the voxel value that will be treated as a background value during the automatic image segmentation. If none is desired, enter a value that does not exist in the dataset. In practice, a background value is a value that is ignored by the tessellation procedure. Regions of the tessellation corresponding to the background value will have no elements.<br />
 +
(Default: +oo).
 +
 
 +
<code>-f, --sizing-function</code> (optional)
 +
 
 +
Enables the sizing-function that is described below. Uses <code>--weight-limit</code> and <code>--min-edge</code> as optional parameters.<br />
 +
<code>--sizing-function</code> needs to be used in conjunction with <code>--volume-grading</code> so that the volume’s refinement will be mainly controlled by the sizing-function.
 +
 
 +
The input image is used as a background(BG) mesh while refining the mesh. Before the beginning of the refinement, the input image is analyzed, and the global constraints of ''maximum-element-edge-size'' and ''element-weight-range'' are computed. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the global and user constraints. Each time SF is called upon an element, it will check if its size meets the global (''maximum-element-edge-size'') and user (''min-edge'') constraints. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and edge midpoints. The sampling points that are preserved out of SP are those that lie within the BG mesh. Using the BG mesh, a set V of the values of SP is created. Subsequently, the quantity max(V) - min(V) is evaluated. If abs(max(V) - min(V))/''element-weight-range'' exceeds the user constraint ''weight-limit'', the element is split.
 +
 
 +
<code>-w, --weight-limit [unsigned real]</code> (optional)
 +
 
 +
Sets the element weight limit of the generated elements that will be used by the sizing function. This parameter limits the difference among the weights within one element. It is designed to give some control of the discretization error with respect to the input data.<br />
 +
(Default: 0.1).
 +
 
 +
<code>-e, --min-edge [unsigned real]</code> (optional)
 +
 
 +
Sets the minimum element edge size of the generated elements that will be used by the sizing function. It is designed to give some control over the size of the generated mesh. Using <code>--min-edge</code> &lt; ''1'' does not offer significant gain if the ''voxel size'' of the input image = ''1''.  (Default: ''1 / 100'' * ''minimum-physical-size'').
 +
 
 +
<code>-l, --linear-interpolation</code> (optional)
 +
 
 +
Performs Linear Interpolation over the points of the produced mesh using the input image.
 +
 
 +
<code>--cnf-uniform</code> (optional)
 +
 
 +
Activates the flags <code>--image-segmentation</code>, and <code>--linear-interpolation</code> which are required by the CNF uniform case.
 +
 
 +
<code>--cnf-adaptive</code> (optional)
 +
 
 +
Activates the flags <code>--image-segmentation</code>, <code>--volume-grading</code>, <code>--sizing-function</code>, and <code>--linear-interpolation</code> which are required by the CNF adaptive case.
 +
 
 +
==== Examples ====
 +
 
 +
[[File:NT_3D.png|1000px]]
 +
 
 +
Input image and clipped generated meshes
 +
 
 +
* Input (left figure): Dimensions (100x100x100) with spacing (1x1x1), Voxels = 1,000,000
 +
* Uniform (middle figure): 768,033 tetrahedra
 +
* Adaptive (right figure): 253,516 tetrahedra
 +
 
 +
Uniform (middle figure):
 +
 
 +
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./CNF_Data/3D/CFF_14052019/NT_140519.nrrd --cnf-uniform --output ./NT_140519,d=1,uniform.vtk</pre>
 +
Adaptive (right figure):
 +
 
 +
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./CNF_Data/3D/CFF_14052019/NT_140519.nrrd --cnf-adaptive --weight-limit 0.07 --output ./NT_140519,d=5,wl=0.07,me=1.vtk</pre>
 +
More Computational Nuclear Femtography 3D examples can be found [https://crtc.cs.odu.edu/CNF_Example_Meshes#3D_Example_Meshes here].
 +
 
 +
=== Tessellate2D ===
 +
 
 +
==== Parameters ====
 +
 
 +
For the full range and descriptions of parameters please see the software documentation section for Tessellate2D.
 +
 
 +
<code>-i, --input [filename]</code> (required)
 +
 
 +
Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library.
 +
 
 +
<code>-o, --output [filename]</code> (optional)
 +
 
 +
The filename of the output mesh.<br />
 +
(Default: <code>outputMesh.vtk</code>).
 +
 
 +
<code>--weight-limit [unsigned real]</code> (optional)
 +
 
 +
Sets the element weight limit for the generated elements that will be used by the sizing function. This parameter limits the difference among the weights within one element. It is designed to give some control of the discretization error with respect to the input data.<br />
 +
(Default: 0.1)
 +
 
 +
<code>--min-edge [unsigned real]</code> (optional)
 +
 
 +
Sets the minimum element edge size of the generated elements that will be used by the sizing function. It is designed to be used in conjunction with <code>--weight-limit</code> controlling the size of the generated mesh. Using <code>--min-edge</code> &lt; ''1'' does not offer significant gain if the ''pixel size'' of the input image = ''1''.<br />
 +
(Default: 1)
 +
 
 +
<code>--uniform</code> (optional)
 +
 
 +
Create a uniform mesh instead of an adaptive one. Uses <code>--min-edge</code> value as a constant size constraint.
 +
 
 +
==== Examples ====
 +
 
 +
[[File:NT_2D.png|1000px]]
 +
 
 +
Input image and generated meshes
 +
 
 +
Sizes:
 +
 
 +
* Input (left figure) : Dimensions (100x100) with spacing (1x1), Pixels = 10,000
 +
* Uniform (middle figure) : 7,587 triangles
 +
* Adaptive (right figure) : 1,038 triangles
 +
 
 +
Uniform (middle figure):
 +
 
 +
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate2d  --input ./CNF_Data/2D/NT_140519_50_X.vtk  --output NT_140519_X50_me_2_uniform.vtk --min-edge=2 --uniform</pre>
 +
Adaptive (right figure):
 +
 
 +
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate2d  --input ./CNF_Data/2D/NT_140519_50_X.vtk  --output NT_140519_X50_me_2_wl_1e-1.vtk --min-edge=2 --weight-limit=0.1</pre>
 +
More Computational Nuclear Femtography 2D examples can be found [https://crtc.cs.odu.edu/CNF_Example_Meshes#2D_Example_Meshes here].
 +
 
 +
 
 +
= Software Documentation =
 +
 
 +
The CRTC’s image-to-mesh software suite has been packaged into a Docker image for easy distribution and portability across multiple platforms. All that is needed to use it is an OS supporting Docker.
  
 
== Requirements ==
 
== Requirements ==
Line 35: Line 245:
 
Docker on Windows uses Hyper-V VMs to run Linux containers. By default, the spawned VMs use 2 vCPUs and 2 GB RAM.
 
Docker on Windows uses Hyper-V VMs to run Linux containers. By default, the spawned VMs use 2 vCPUs and 2 GB RAM.
  
−
If performance is a concern, it is recommended to edit the Docker settings via the GUI to increase the resource allocation for the VMs in order to allow the 3D tessellation tool to use more threads.
+
If performance is a concern, it is recommended to edit the Docker settings via the GUI to increase the resource allocation for the VMs in order to allow the tessellation3D tool to use more threads.
  
−
== Getting the software ==
+
== Getting The Software ==
  
−
The docker image is located [https://odu.box.com/s/sjt7y87q9saxjqovhi93l0ob5jg3tvv3 here] (restricted access).
+
The docker image containing the <code>crtc_i2m</code> software suite is located [https://odu.box.com/s/j754hazu7qjdcn2szxf8n9n5l5ekll2f here] (restricted access).
  
−
== Docker Container Instructions ==
+
=== Docker Container Instructions ===
  
 
<ol style="list-style-type: decimal;">
 
<ol style="list-style-type: decimal;">
Line 48: Line 258:
 
<pre>docker load --input [DOCKER_IMAGE_TAR]</pre>
 
<pre>docker load --input [DOCKER_IMAGE_TAR]</pre>
 
<p>Note: If the user is not in the <code>docker</code> group, prepending <code>sudo</code> to the above command is necessary.</p></li>
 
<p>Note: If the user is not in the <code>docker</code> group, prepending <code>sudo</code> to the above command is necessary.</p></li>
−
<li><p>Running</p></li></ol>
+
<li><p>Running</p>
 +
<ul>
 +
<li><p>On MacOS/Linux</p>
 +
<pre>docker run -v $(pwd):/data/ crtc_i2m &lt;application&gt; [arguments]</pre></li>
 +
<li><p>On Windows with PowerShell (recommended)</p>
 +
<pre>docker run -v ${PWD}:/data/ crtc_i2m &lt;application&gt; [arguments]</pre></li></ul>
  
 +
<p>'''Notice that in this case brackets {} are used instead of parenthesis ()'''</p>
 
<ul>
 
<ul>
−
<li><p>On MacOS/Linux</p>
+
<li><p>On Windows with the command line (cmd)</p>
−
<pre>docker run -v $(pwd):/data/ cnf_tools &lt;application&gt; [arguments]</pre></li>
+
<pre>docker run -v %cd%:/data/ crtc_i2m &lt;application&gt; [arguments]</pre></li></ul>
−
<li><p>On Windows with Powershell (recommended)</p>
+
</li></ol>
−
<pre>docker run -v ${PWD}:/data/ cnf_tools &lt;application&gt; [arguments]</pre></li></ul>
+
 
 +
Where <code>&lt;application&gt;</code> is one of the currently available tools : <code>tessellate3d</code>, <code>tessellate2d</code>, or <code>convert_image</code>.
 +
 
 +
== Tessellate3D (PODM 3D) ==
 +
 
 +
The main component of the software suite is a 3D tessellation software called '''PODM3D''', which is a parallel Image-to-Mesh conversion algorithm with quality and fidelity guarantees and is capable of generating unstructured tetrahedral meshes out of 3D structured data.
 +
 
 +
The output meshes are in the [https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf VTK format] and can be visualized using the open-source software [https://www.paraview.org Paraview].
 +
 
 +
A quick way to view all available parameters and brief descriptions for them is to pass the <code>-h, --help</code> flag to <code>tessellate3d</code>.
 +
 
 +
Below is the detailed information about the parameters of <code>tessellate3d</code>:
 +
 
 +
=== Input / Output Parameters ===
 +
 
 +
<code>-i, --input [filename]</code> (required)
 +
 
 +
Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library. For more information regarding the file formats supported by the ITK library, see [https://insightsoftwareconsortium.github.io/itk-js/docs/image_formats.html here].
 +
 
 +
<code>-o, --output [filename]</code> (optional)
 +
 
 +
The filename of the output mesh.<br />
 +
(Default: <code>outputMesh.vtk</code>).
 +
 
 +
<code>-c, --plc [filename]</code> (optional)
 +
 
 +
If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.
 +
 
 +
=== Hardware Parameters ===
 +
 
 +
<code>-t, --threads [unsigned integer]</code> (optional)
 +
 
 +
Sets the number of threads to be utilized. The upper bound of the number of threads that should be utilized is equal to the number of cores that you have. If the number of threads is greater than 1, the produced meshes may differ in terms of the number of elements up to 3% due to the nature of the employed parallelism technique.<br />
 +
(Default: 1).
 +
 
 +
<code>-p, --thread-pinning {0, 1}</code> (optional)
 +
 
 +
Controls the pinning of threads to cores. <code>0</code> doesn’t pin threads to cores (experimental), and <code>1</code> pins threads to cores.<br />
 +
(Default: 1).
 +
 
 +
<code>-m, --memory-limit [Unsinged integer in MB]</code> (optional)
 +
 
 +
Constrains the amount of memory in MB that will be used.<br />
 +
(Default: 70% of the free memory).
  
−
'''Notice that in this case brackets {} are used instead of parenthesis ()'''
+
=== Geometry Parameters ===
  
−
<ul>
+
<code>-d, --delta [unsigned real]</code> (optional)
−
<li><p>On Windows with command line (cmd)</p>
 
−
<pre>docker run -v %cd%:/data/ cnf_tools &lt;application&gt; [arguments]</pre></li></ul>
 
  
−
Where <code>&lt;application&gt;</code> is one of the currently available tools : <code>tessellate2d</code> ,<code>tessellate3d</code> or <code>convert_image</code>.
+
Controls the density of surface approximation. Smaller values will lead to denser approximation close to the surface (and often to a more accurate surface representation), but will also lead to greater mesh size. The same delta value is used for every tissue of interest. A smaller delta value should be used if at least one of the tissues of interest is not recovered after the Meshing Procedure.
  
−
== Tessellation Parameters ==
+
The maximum suggested value for delta is ''1 / 5'' of the ''minimum-physical-size'' of the input image, where ''minimum-physical-size'' = min(spacing * size).<br />
 +
(Default (if <code>--sizing-function</code> is not specified): ''1 / 100'' * ''minimum-physical-size'').<br />
 +
(Default (if <code>--sizing-function</code> is specified): ''1 / 20'' * ''minimum-physical-size'').
  
−
A quick way to view all available parameters and brief descriptions for them is to pass the <code>--help</code> flag to <code>tessellate2d</code>/<code>tessellate3d</code>.
+
Delta is an essential parameter that is involved in every step of the PODM algorithm and guarantees the quality and fidelity of the produced mesh. For more information on how delta affects the density of the sampling, see [https://crtc.cs.odu.edu/pub/papers/journal_58.pdf Guaranteed Quality Tetrahedral Delaunay Meshing for Medical Images].  
  
−
Below are more detailed descriptions of the <code>tessellate2d</code>/<code>tessellate3d</code> parameters:
+
<code>-g, --volume-grading</code> (optional)
  
−
The common parameters for both versions are :
+
Enables the grading of the volume of the mesh. By default, the value of delta controls both the surface approximation and the size of the elements. Using this flag the value of delta will control only the surface approximation resulting in elements of higher volume inside the domain.
  
−
<code>--input [filename]</code> (required)
+
=== Pre-processing filters’ parameters ===
  
−
Input CNF data. Could be ascii/binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library. For more on ITK-supported file formats see [https://insightsoftwareconsortium.github.io/itk-js/docs/image_formats.html here].
+
<code>-s, --image-segmentation</code> (optional)
  
−
<code>--output [filename]</code> (optional)
+
Performs Image Segmentation on non-segmented/unlabeled images using a given background value. It should not be used for input images that are already segmented/labeled. Uses <code>--background-value</code> as an optional parameter.
  
−
The filename of the output mesh. (Default: <code>outputMesh.vtk</code>).
+
<code>-b, --background-value [signed real]</code> (optional)
  
−
<code>--weight-limit [real]</code> (optional)
+
Sets the voxel value that will be treated as a background value during the automatic image segmentation. If none is desired, enter a value that does not exist in the dataset. In practice, a background value is a value that is ignored by the tessellation procedure. Regions of the tessellation corresponding to the background value will have no elements.<br />
 +
(Default: +oo).
  
−
Set a weight limit for the generated elements that will be used from the sizing function This parameter limits the difference among the weights within one element. It is designed to give some control on the discretization error with respect to the input data.<br />
+
=== Sizing Function parameters ===
−
(Default: 0.1)
 
  
−
<code>--min-edge [real]</code> (optional)
+
<code>-f, --sizing-function</code> (optional)
  
−
Set the minimum edge size of generated elements that will be used for the sizing function (default: 1). It is designed to be used together with <code>weight-limit</code> controlling the size of the generated mesh. (Default: 1)
+
Enables the sizing-function that is described below. Uses <code>--weight-limit</code> and <code>--min-edge</code> as optional parameters.<br />
 +
<code>--sizing-function</code> needs to be used in conjunction with <code>--volume-grading</code> so that the volume’s refinement will be mainly controlled by the sizing-function.
  
−
=== Tessellate3D Specific Parameters ===
+
The input image is used as a background(BG) mesh while refining the mesh. Before the beginning of the refinement, the input image is analyzed, and the global constraints of ''maximum-element-edge-size'' and ''element-weight-range'' are computed. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the global and user constraints. Each time SF is called upon an element, it will check if its size meets the global (''maximum-element-edge-size'') and user (''min-edge'') constraints. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and edge midpoints. The sampling points that are preserved out of SP are those that lie within the BG mesh. Using the BG mesh, a set V of the values of SP is created. Subsequently, the quantity max(V) - min(V) is evaluated. If abs(max(V) - min(V))/''element-weight-range'' exceeds the user constraint ''weight-limit'', the element is split.
  
−
<code>--delta [real]</code> (optional)
+
The described sizing function was designed specifically for the Computational Nuclear Femtography data. Nonetheless, another sizing function could be designed and employed if requested.
  
−
Controls the size of the elements nearby the boundary. Smaller values will lead to finer detail close to the boundary (and often to a more accurate boundary representation) but will also lead to a greater mesh size. The default value is based on the input size and spacing of the input image.
+
<code>-w, --weight-limit [unsigned real]</code> (optional)
  
−
<code>--threads [int]</code> (optional)
+
Sets the element weight limit of the generated elements that will be used by the sizing function. This parameter limits the difference among the weights within one element. It is designed to give some control of the discretization error with respect to the input data.<br />
 +
(Default: 0.1).
  
−
How many threads to use. (Default: 1)
+
<code>-e, --min-edge [unsigned real]</code> (optional)
  
−
<code>--plc [filename]</code> (optional)
+
Sets the minimum element edge size of the generated elements that will be used by the sizing function. It is designed to give some control over the size of the generated mesh. Using <code>--min-edge</code> &lt; ''1'' does not offer significant gain if the ''voxel size'' of the input image = ''1''.  (Default: ''1 / 100'' * ''minimum-physical-size'').
  
−
If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.
+
=== Post-processing filters’ parameters ===
  
−
<code>--memory-limit [int in MB]</code> (optional)
+
<code>-l, --linear-interpolation</code> (optional)
  
−
Constrain the amount of memory that will be used. (Default : 70% of the free memory).
+
Performs Linear Interpolation over the points of the produced mesh using the input image. It should not be used for input images that are already segmented/labeled.
  
−
<code>--verbose-level [0,1,2]</code> (optional)
+
=== Special Parameters ===
  
−
Control the level of verbosity. 0 produces no text output while 2 enables extra information. (Default: 1).
+
<code>--cnf-uniform</code> (optional)
  
−
<code>--background-value [real]</code> (optional)
+
Activates the flags <code>--image-segmentation</code>, and <code>--linear-interpolation</code> which are required by the CNF uniform case.
  
−
Which voxel value to treat as background value. If none is desired, enter a value that does not exists in the dataset. In practice, a background value is a value that is ignored from the tessellation procedure. Regions of the tessellation corresponding to the background value will have no elements. (Default: +inf)
+
<code>--cnf-adaptive</code> (optional)
  
−
<code>--all-statistics</code> (optional)
+
Activates the flags <code>--image-segmentation</code>, <code>--volume-grading</code>, <code>--sizing-function</code>, and <code>--linear-interpolation</code> which are required by the CNF adaptive case.
  
−
Output all statistics (thread and mesh).
+
=== Statistics Parameters ===
  
 
<code>--thread-statistics</code> (optional)
 
<code>--thread-statistics</code> (optional)
  
−
Output thread statistics.
+
Computes and prints thread statistics.
  
 
<code>--mesh-statistics</code> (optional)
 
<code>--mesh-statistics</code> (optional)
  
−
Output mesh statistics.
+
Computes and prints mesh statistics.
  
−
=== Tessellate2D Specific Parameters ===
+
<code>--all-statistics</code> (optional)
  
−
<code>--uniform</code> (optional)
+
Computes and prints all statistics (thread and mesh).
 +
 
 +
=== Miscellaneous Parameters ===
 +
 
 +
<code>-v, --verbosity-level {0, 1, 2}</code> (optional)
 +
 
 +
Controls the level of output text verbosity. <code>0</code> produces no output, <code>1</code> produces standard output, and <code>2</code> produces extensive output.<br />
 +
(Default: 1).
 +
 
 +
== Tessellate2D ==
 +
 
 +
Tessellate2D is a modified version of the [https://www.cs.cmu.edu/~quake/triangle.html ''Triangle''] software for 2D tessellation.
  
−
Create a uniform mesh instead of an adaptive one. <code>--min-edge</code> value will be used as a constant size constraint
+
The output meshes are in the [https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf VTK format] and can be visualized using the open-source software [https://www.paraview.org Paraview].
  
−
<code>--verbose-level [0,1]</code> (optional)
+
Below is the detailed information about the parameters of <code>tessellate2d</code>:
  
−
Control the level of verbosity. 0 produces no text output while 1 produces the standard amount of information (Default: 1).
+
<code>-i, --input [filename]</code> (required)
  
−
== <code>convert_image</code> parameters ==
+
Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library. For more information regarding the file formats supported by the ITK library, see [https://insightsoftwareconsortium.github.io/itk-js/docs/image_formats.html here].
  
−
<code>convert_image</code> serves as a utility to convert input data between different kinds of image formats. For example the <code>.nrrd</code> images acquired from Jefferson lab cannot be used with Paraview in order to create contour-plots (unknown why). However, converting them using
+
<code>-o, --output [filename]</code> (optional)
  
−
<pre>docker run -v $(pwd):/data/ cnf_tools convert_image input_image.nrrd output_image.vtk </pre>
+
The filename of the output mesh.<br />
−
enables all relevant image filters in Paraview.
+
(Default: <code>outputMesh.vtk</code>).
  
−
== Example Dataset ==
+
<code>--weight-limit [unsigned real]</code> (optional)
  
−
=== Tessellate2D ===
+
Sets the element weight limit for the generated elements that will be used by the sizing function. This parameter limits the difference among the weights within one element. It is designed to give some control of the discretization error with respect to the input data.<br />
 +
(Default: 0.1)
  
−
[[File:NT_2D.png|1000px]]
+
<code>--min-edge [unsigned real]</code> (optional)
  
−
Input image and generated meshes
+
Sets the minimum element edge size of the generated elements that will be used by the sizing function. It is designed to be used in conjunction with <code>--weight-limit</code> controlling the size of the generated mesh. Using <code>--min-edge</code> &lt; ''1'' does not offer significant gain if the ''pixel size'' of the input image = ''1''.<br />
 +
(Default: 1)
  
−
Sizes:
+
<code>--uniform</code> (optional)
  
−
* Input (left figure) : 100x100 (10,000) pixels
+
Create a uniform mesh instead of an adaptive one. Uses <code>--min-edge</code> value as a constant size constraint.
−
* Uniform (middle figure) : 7,587 triangles
 
−
* Adaptive (right figure) : 1,038 triangles
 
  
−
Uniform (middle figure):
+
<code>--verbose-level [0,1]</code> (optional)
  
−
<pre>docker run -v $(pwd):/data/ cnf_tools tessellate2d  --input ./CNF_SHARE/2d_wiki_examples/input/NT_140519_50_X.vtk  --output NT_140519_X50_me_2_uniform.vtk --min-edge=2 --uniform</pre>
+
Controls the level of output text verbosity. <code>0</code> produces no output, and <code>1</code> produces standard output.<br />
−
Adaptive (right figure):
+
(Default: 1).
  
−
<pre>docker run -v $(pwd):/data/ cnf_tools tessellate2d  --input ./CNF_SHARE/2d_wiki_examples/input/NT_140519_50_X.vtk  --output NT_140519_X50_me_2_wl_1e-1.vtk --min-edge=2 --weight-limit=0.1</pre>
+
== Convert Image ==
−
=== Tessellate3D ===
 
  
−
[[File:NT_3D.png|1000px]]
+
<code>convert_image</code> serves as a utility to convert input data between different types of image formats. It allows converting the input data between different image types supported by ITK enabling in some cases more post-processing filters in Paraview (e.g. contour plots). However, converting them using the following command enables all relevant image filters in Paraview.
  
−
Input image and clipped generated meshes
+
<pre>docker run -v $(pwd):/data/ crtc_i2m convert_image input_image.nrrd output_image.vtk</pre>
 +
= Appendix =
  
−
* Input (left figure) : 100x100x100 (1,000,000) pixels
+
== How mesh size relates to delta ==
−
* Uniform (middle figure) : 768,033 tetrahedra
 
−
* Adaptive (right figure) : 253,516 tetrahedra
 
  
−
Uniform (middle figure):
+
Input Image: Knee-Char.mha
  
−
<pre>docker run -v $(pwd):/data/ cnf_tools tessellate3d --input ./CNF_SHARE/CFF_14052019/NT_140519.nrrd  --uniform --delta 1 --output ./NT_uniform.vtk</pre>
+
* The size of the input image is: (512x512x119)
−
Adaptive (right figure):
+
* Spacing of the input image: (0.27734,0.27734,1)
 +
* MinimumPhysicalSize = 119 * 1 = 119
 +
* Maximum suggested delta value is: 119 / 5 = 23.8
  
−
<pre>docker run -v $(pwd):/data/ cnf_tools tessellate3d --input ./CNF_SHARE/CFF_14052019/NT_140519.nrrd  --weight-limit 0.07  --output ./NT_adapted.vtk </pre>
+
{|
−
More examples can be found [https://crtc.cs.odu.edu/CNF_Example_Meshes here] .
+
!align="center"| Delta
 +
!align="center"| # Vertices
 +
!align="center"| # Tetrahedra
 +
|-
 +
|align="center"| 23.8
 +
|align="center"| 70
 +
|align="center"| 153
 +
|-
 +
|align="center"| 20
 +
|align="center"| 87
 +
|align="center"| 222
 +
|-
 +
|align="center"| 15
 +
|align="center"| 219
 +
|align="center"| 668
 +
|-
 +
|align="center"| 10
 +
|align="center"| 551
 +
|align="center"| 1580
 +
|-
 +
|align="center"| 5
 +
|align="center"| 2858
 +
|align="center"| 10073
 +
|-
 +
|align="center"| 4
 +
|align="center"| 4544
 +
|align="center"| 16569
 +
|-
 +
|align="center"| 3
 +
|align="center"| 9276
 +
|align="center"| 35131
 +
|-
 +
|align="center"| 2
 +
|align="center"| 24631
 +
|align="center"| 98822
 +
|-
 +
|align="center"| 1.5
 +
|align="center"| 50371
 +
|align="center"| 209659
 +
|-
 +
|align="center"| 1
 +
|align="center"| 139515
 +
|align="center"| 613799
 +
|-
 +
|align="center"| 0.5
 +
|align="center"| 830423
 +
|align="center"| 3999734
 +
|}

Revision as of 21:58, 4 March 2020



Introduction

This page contains instructions for downloading and using the crtc_i2m software suite developed by the CRTC lab at Old Dominion University.

The suite contains three software components:

  1. Tessellate3D (PODM 3D) (3D tessellation software)
  2. Tessellate2D (Triangle) (2D tessellation software)
  3. Convert Image (image format conversion software)

Problem Domains

The image-to-mesh conversion software suite that the CRTC has developed can be used in many different problem domains such as Medical Image Computing and Computational Nuclear Femtography. Specific instructions on how to use the software are described below.

Medical Image Computing

Tessellate3D

In Medical Image Computing, Tessellate3D can be used to generate meshes for many different objects, such as brains and other organs and tissues.

Parameters

In this domain, some of the parameters of Tessellate3D take on different meanings. For the full range and descriptions of parameters please see the software documentation section for Tessellate3D.

-i, --input [filename] (required)

Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library.

-o, --output [filename] (optional)

The filename of the output mesh. (Default: outputMesh.vtk).

-c, --plc [filename] (optional)

If given, the surface of the produced mesh will be saved into filename in the VTK format.

-t, --threads [unsigned integer] (optional)

Sets the number of threads to be utilized.
(Default: 1).

-d, --delta [unsigned real] (optional)

Controls the density of surface approximation. Smaller values will lead to denser approximation close to the surface (and often to a more accurate surface representation), but will also lead to greater mesh size. The same delta value is used for every tissue of interest. A smaller delta value should be used if at least one of the tissues of interest is not recovered after the Meshing Procedure.

The maximum suggested value for delta is 1 / 5 of the minimum-physical-size of the input image, where minimum-physical-size = min(spacing * size).
(Default: 1 / 100 * minimum-physical-size).

-g, --volume-grading (optional)

Enables the grading of the volume of the mesh. By default, the value of delta controls both the surface approximation and the size of the elements. Using this flag the value of delta will control only the surface approximation resulting in elements of higher volume inside the domain.

Examples

Input image and clipped generated meshes

Head-Neck.png

  • Input (left figure): Dimensions (255x255x229) with spacing (0.976562x0.976562x1.40002)
  • Uniform with Delta = default (middle figure): 205,416 tetrahedra
  • Uniform with Delta = 1.5 (right figure): 770,853 tetrahedra

Uniform with Delta = default (middle figure): 

docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./Medical_Imaging_Data/3D/Head-Neck.mha --output ./Head-Neck,d=2.49023.vtk

Uniform with Delta = 1.5 (right figure): 

docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./Medical_Imaging_Data/3D/Head-Neck.mha --delta 1.5 -o ./Head-Neck,d=1.5.vtk

More Medical Image Computing examples can be found here.

Computational Nuclear Femtography

A short presentation can be found here.

Tessellate3D

Parameters

In this domain, some of the parameters of Tessellate3D take on different meanings. For the full range and descriptions of parameters please see the software documentation section for Tessellate3D.

-i, --input [filename] (required)

Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library.

-o, --output [filename] (optional)

The filename of the output mesh.
(Default: outputMesh.vtk).

-c, --plc [filename] (optional)

If given, the surface of the produced mesh will be saved into filename in the VTK format.

-t, --threads [unsigned integer] (optional)

Sets the number of threads to be utilized.
(Default: 1).

-d, --delta [unsigned real] (optional)

Controls the size of the elements near the boundary. Smaller values will lead to finer detail close to the boundary (and often to a more accurate boundary representation) but will also lead to a greater mesh size.

(Default (if --sizing-function is not specified): 1 / 100 * minimum-physical-size).
(Default (if --sizing-function is specified): 1 / 20 * minimum-physical-size).

-g, --volume-grading (optional)

Enables the grading of the volume of the mesh. By default, the value of delta controls both the surface approximation and the size of the elements. Using this flag the value of delta will control only the surface approximation resulting in elements of higher volume inside the domain.

-s, --image-segmentation (optional)

Performs Image Segmentation using a given background value. Uses --background-value as an optional parameter.

-b, --background-value [signed real] (optional)

Sets the voxel value that will be treated as a background value during the automatic image segmentation. If none is desired, enter a value that does not exist in the dataset. In practice, a background value is a value that is ignored by the tessellation procedure. Regions of the tessellation corresponding to the background value will have no elements.
(Default: +oo).

-f, --sizing-function (optional)

Enables the sizing-function that is described below. Uses --weight-limit and --min-edge as optional parameters.
--sizing-function needs to be used in conjunction with --volume-grading so that the volume’s refinement will be mainly controlled by the sizing-function.

The input image is used as a background(BG) mesh while refining the mesh. Before the beginning of the refinement, the input image is analyzed, and the global constraints of maximum-element-edge-size and element-weight-range are computed. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the global and user constraints. Each time SF is called upon an element, it will check if its size meets the global (maximum-element-edge-size) and user (min-edge) constraints. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and edge midpoints. The sampling points that are preserved out of SP are those that lie within the BG mesh. Using the BG mesh, a set V of the values of SP is created. Subsequently, the quantity max(V) - min(V) is evaluated. If abs(max(V) - min(V))/element-weight-range exceeds the user constraint weight-limit, the element is split.

-w, --weight-limit [unsigned real] (optional)

Sets the element weight limit of the generated elements that will be used by the sizing function. This parameter limits the difference among the weights within one element. It is designed to give some control of the discretization error with respect to the input data.
(Default: 0.1).

-e, --min-edge [unsigned real] (optional)

Sets the minimum element edge size of the generated elements that will be used by the sizing function. It is designed to give some control over the size of the generated mesh. Using --min-edge < 1 does not offer significant gain if the voxel size of the input image = 1.  (Default: 1 / 100 * minimum-physical-size).

-l, --linear-interpolation (optional)

Performs Linear Interpolation over the points of the produced mesh using the input image.

--cnf-uniform (optional)

Activates the flags --image-segmentation, and --linear-interpolation which are required by the CNF uniform case.

--cnf-adaptive (optional)

Activates the flags --image-segmentation, --volume-grading, --sizing-function, and --linear-interpolation which are required by the CNF adaptive case.

Examples

NT 3D.png

Input image and clipped generated meshes

  • Input (left figure): Dimensions (100x100x100) with spacing (1x1x1), Voxels = 1,000,000
  • Uniform (middle figure): 768,033 tetrahedra
  • Adaptive (right figure): 253,516 tetrahedra

Uniform (middle figure): 

docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./CNF_Data/3D/CFF_14052019/NT_140519.nrrd --cnf-uniform --output ./NT_140519,d=1,uniform.vtk

Adaptive (right figure): 

docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./CNF_Data/3D/CFF_14052019/NT_140519.nrrd --cnf-adaptive --weight-limit 0.07 --output ./NT_140519,d=5,wl=0.07,me=1.vtk

More Computational Nuclear Femtography 3D examples can be found here.

Tessellate2D

Parameters

For the full range and descriptions of parameters please see the software documentation section for Tessellate2D.

-i, --input [filename] (required)

Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library.

-o, --output [filename] (optional)

The filename of the output mesh.
(Default: outputMesh.vtk).

--weight-limit [unsigned real] (optional)

Sets the element weight limit for the generated elements that will be used by the sizing function. This parameter limits the difference among the weights within one element. It is designed to give some control of the discretization error with respect to the input data.
(Default: 0.1)

--min-edge [unsigned real] (optional)

Sets the minimum element edge size of the generated elements that will be used by the sizing function. It is designed to be used in conjunction with --weight-limit controlling the size of the generated mesh. Using --min-edge < 1 does not offer significant gain if the pixel size of the input image = 1.
(Default: 1)

--uniform (optional)

Create a uniform mesh instead of an adaptive one. Uses --min-edge value as a constant size constraint.

Examples

NT 2D.png

Input image and generated meshes

Sizes:

  • Input (left figure) : Dimensions (100x100) with spacing (1x1), Pixels = 10,000
  • Uniform (middle figure) : 7,587 triangles
  • Adaptive (right figure) : 1,038 triangles

Uniform (middle figure): 

docker run -v $(pwd):/data/ crtc_i2m tessellate2d  --input ./CNF_Data/2D/NT_140519_50_X.vtk  --output NT_140519_X50_me_2_uniform.vtk --min-edge=2 --uniform

Adaptive (right figure): 

docker run -v $(pwd):/data/ crtc_i2m tessellate2d  --input ./CNF_Data/2D/NT_140519_50_X.vtk  --output NT_140519_X50_me_2_wl_1e-1.vtk --min-edge=2 --weight-limit=0.1

More Computational Nuclear Femtography 2D examples can be found here.


Software Documentation

The CRTC’s image-to-mesh software suite has been packaged into a Docker image for easy distribution and portability across multiple platforms. All that is needed to use it is an OS supporting Docker.

Requirements

  • OS: Linux, Windows 10 Pro/Enterprise, MacOS Sierra 10.12+
  • Docker

Installing Docker

Official documentation :

Note for Running on Windows

Docker on Windows uses Hyper-V VMs to run Linux containers. By default, the spawned VMs use 2 vCPUs and 2 GB RAM.

If performance is a concern, it is recommended to edit the Docker settings via the GUI to increase the resource allocation for the VMs in order to allow the tessellation3D tool to use more threads.

Getting The Software

The docker image containing the crtc_i2m software suite is located here (restricted access).

Docker Container Instructions

  1. Load the Docker Image.

    First of all, the Docker image needs to be loaded. The following command must be used:

    docker load --input [DOCKER_IMAGE_TAR]

    Note: If the user is not in the docker group, prepending sudo to the above command is necessary.

  2. Running

    • On MacOS/Linux

      docker run -v $(pwd):/data/ crtc_i2m <application> [arguments]

    • On Windows with PowerShell (recommended)

      docker run -v ${PWD}:/data/ crtc_i2m <application> [arguments]

    Notice that in this case brackets {} are used instead of parenthesis ()

    • On Windows with the command line (cmd)

      docker run -v %cd%:/data/ crtc_i2m <application> [arguments]

Where <application> is one of the currently available tools : tessellate3d, tessellate2d, or convert_image.

Tessellate3D (PODM 3D)

The main component of the software suite is a 3D tessellation software called PODM3D, which is a parallel Image-to-Mesh conversion algorithm with quality and fidelity guarantees and is capable of generating unstructured tetrahedral meshes out of 3D structured data.

The output meshes are in the VTK format and can be visualized using the open-source software Paraview.

A quick way to view all available parameters and brief descriptions for them is to pass the -h, --help flag to tessellate3d.

Below is the detailed information about the parameters of tessellate3d:

Input / Output Parameters

-i, --input [filename] (required)

Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library. For more information regarding the file formats supported by the ITK library, see here.

-o, --output [filename] (optional)

The filename of the output mesh.
(Default: outputMesh.vtk).

-c, --plc [filename] (optional)

If given, the surface of the produced mesh will be saved into filename in the VTK format.

Hardware Parameters

-t, --threads [unsigned integer] (optional)

Sets the number of threads to be utilized. The upper bound of the number of threads that should be utilized is equal to the number of cores that you have. If the number of threads is greater than 1, the produced meshes may differ in terms of the number of elements up to 3% due to the nature of the employed parallelism technique.
(Default: 1).

-p, --thread-pinning {0, 1} (optional)

Controls the pinning of threads to cores. 0 doesn’t pin threads to cores (experimental), and 1 pins threads to cores.
(Default: 1).

-m, --memory-limit [Unsinged integer in MB] (optional)

Constrains the amount of memory in MB that will be used.
(Default: 70% of the free memory).

Geometry Parameters

-d, --delta [unsigned real] (optional)

Controls the density of surface approximation. Smaller values will lead to denser approximation close to the surface (and often to a more accurate surface representation), but will also lead to greater mesh size. The same delta value is used for every tissue of interest. A smaller delta value should be used if at least one of the tissues of interest is not recovered after the Meshing Procedure.

The maximum suggested value for delta is 1 / 5 of the minimum-physical-size of the input image, where minimum-physical-size = min(spacing * size).
(Default (if --sizing-function is not specified): 1 / 100 * minimum-physical-size).
(Default (if --sizing-function is specified): 1 / 20 * minimum-physical-size).

Delta is an essential parameter that is involved in every step of the PODM algorithm and guarantees the quality and fidelity of the produced mesh. For more information on how delta affects the density of the sampling, see Guaranteed Quality Tetrahedral Delaunay Meshing for Medical Images.

-g, --volume-grading (optional)

Enables the grading of the volume of the mesh. By default, the value of delta controls both the surface approximation and the size of the elements. Using this flag the value of delta will control only the surface approximation resulting in elements of higher volume inside the domain.

Pre-processing filters’ parameters

-s, --image-segmentation (optional)

Performs Image Segmentation on non-segmented/unlabeled images using a given background value. It should not be used for input images that are already segmented/labeled. Uses --background-value as an optional parameter.

-b, --background-value [signed real] (optional)

Sets the voxel value that will be treated as a background value during the automatic image segmentation. If none is desired, enter a value that does not exist in the dataset. In practice, a background value is a value that is ignored by the tessellation procedure. Regions of the tessellation corresponding to the background value will have no elements.
(Default: +oo).

Sizing Function parameters

-f, --sizing-function (optional)

Enables the sizing-function that is described below. Uses --weight-limit and --min-edge as optional parameters.
--sizing-function needs to be used in conjunction with --volume-grading so that the volume’s refinement will be mainly controlled by the sizing-function.

The input image is used as a background(BG) mesh while refining the mesh. Before the beginning of the refinement, the input image is analyzed, and the global constraints of maximum-element-edge-size and element-weight-range are computed. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the global and user constraints. Each time SF is called upon an element, it will check if its size meets the global (maximum-element-edge-size) and user (min-edge) constraints. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and edge midpoints. The sampling points that are preserved out of SP are those that lie within the BG mesh. Using the BG mesh, a set V of the values of SP is created. Subsequently, the quantity max(V) - min(V) is evaluated. If abs(max(V) - min(V))/element-weight-range exceeds the user constraint weight-limit, the element is split.

The described sizing function was designed specifically for the Computational Nuclear Femtography data. Nonetheless, another sizing function could be designed and employed if requested.

-w, --weight-limit [unsigned real] (optional)

Sets the element weight limit of the generated elements that will be used by the sizing function. This parameter limits the difference among the weights within one element. It is designed to give some control of the discretization error with respect to the input data.
(Default: 0.1).

-e, --min-edge [unsigned real] (optional)

Sets the minimum element edge size of the generated elements that will be used by the sizing function. It is designed to give some control over the size of the generated mesh. Using --min-edge < 1 does not offer significant gain if the voxel size of the input image = 1.  (Default: 1 / 100 * minimum-physical-size).

Post-processing filters’ parameters

-l, --linear-interpolation (optional)

Performs Linear Interpolation over the points of the produced mesh using the input image. It should not be used for input images that are already segmented/labeled.

Special Parameters

--cnf-uniform (optional)

Activates the flags --image-segmentation, and --linear-interpolation which are required by the CNF uniform case.

--cnf-adaptive (optional)

Activates the flags --image-segmentation, --volume-grading, --sizing-function, and --linear-interpolation which are required by the CNF adaptive case.

Statistics Parameters

--thread-statistics (optional)

Computes and prints thread statistics.

--mesh-statistics (optional)

Computes and prints mesh statistics.

--all-statistics (optional)

Computes and prints all statistics (thread and mesh).

Miscellaneous Parameters

-v, --verbosity-level {0, 1, 2} (optional)

Controls the level of output text verbosity. 0 produces no output, 1 produces standard output, and 2 produces extensive output.
(Default: 1).

Tessellate2D

Tessellate2D is a modified version of the Triangle software for 2D tessellation.

The output meshes are in the VTK format and can be visualized using the open-source software Paraview.

Below is the detailed information about the parameters of tessellate2d:

-i, --input [filename] (required)

Input data. It could be an ASCII/Binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library. For more information regarding the file formats supported by the ITK library, see here.

-o, --output [filename] (optional)

The filename of the output mesh.
(Default: outputMesh.vtk).

--weight-limit [unsigned real] (optional)

Sets the element weight limit for the generated elements that will be used by the sizing function. This parameter limits the difference among the weights within one element. It is designed to give some control of the discretization error with respect to the input data.
(Default: 0.1)

--min-edge [unsigned real] (optional)

Sets the minimum element edge size of the generated elements that will be used by the sizing function. It is designed to be used in conjunction with --weight-limit controlling the size of the generated mesh. Using --min-edge < 1 does not offer significant gain if the pixel size of the input image = 1.
(Default: 1)

--uniform (optional)

Create a uniform mesh instead of an adaptive one. Uses --min-edge value as a constant size constraint.

--verbose-level [0,1] (optional)

Controls the level of output text verbosity. 0 produces no output, and 1 produces standard output.
(Default: 1).

Convert Image

convert_image serves as a utility to convert input data between different types of image formats. It allows converting the input data between different image types supported by ITK enabling in some cases more post-processing filters in Paraview (e.g. contour plots). However, converting them using the following command enables all relevant image filters in Paraview. 

docker run -v $(pwd):/data/ crtc_i2m convert_image input_image.nrrd output_image.vtk

Appendix

How mesh size relates to delta

Input Image: Knee-Char.mha

  • The size of the input image is: (512x512x119)
  • Spacing of the input image: (0.27734,0.27734,1)
  • MinimumPhysicalSize = 119 * 1 = 119
  • Maximum suggested delta value is: 119 / 5 = 23.8
Delta # Vertices # Tetrahedra
23.8 70 153
20 87 222
15 219 668
10 551 1580
5 2858 10073
4 4544 16569
3 9276 35131
2 24631 98822
1.5 50371 209659
1 139515 613799
0.5 830423 3999734
Retrieved from "https://crtc.cs.odu.edu/index.php?title=CRTC_I2M&oldid=5207"