Difference between revisions of "CRTC I2M"

From crtc.cs.odu.edu
Jump to: navigation, search
Line 1: Line 1:
−
__TOC__
+
<!DOCTYPE html>
−
 
+
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
−
 
+
<head>
−
-----
+
  <meta charset="utf-8" />
−
 
+
  <meta name="generator" content="pandoc" />
−
= Introduction =
+
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
−
 
+
  <meta name="author" content="CRTC Lab, Old Dominion University" />
−
This document 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].
+
  <meta name="dcterms.date" content="2020-03-20" />
−
 
+
  <title>CRTC Image-To-Mesh Conversion Software Documentation</title>
−
The suite contains three software components:
+
  <link href="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.1/styles/github.min.css" rel="stylesheet"/>
−
 
+
  <link rel="stylesheet" type="text/css" href="./assets/style.css">
−
# '''Tessellate3D (PODM 3D)''' (3D tessellation software)
+
  <!--[if lt IE 9]>
−
# '''Tessellate2D (Triangle)''' (2D tessellation software)
+
    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
−
# '''Convert Image''' (image format conversion software)
+
  <![endif]-->
−
# '''PartonsToNRRD''' (creation of image out of Partons data software)
+
</head>
−
 
+
<body>
−
= Problem Domains =
+
<header>
−
 
+
<h1 class="title">CRTC Image-To-Mesh Conversion Software Documentation</h1>
−
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.
+
<p class="author">CRTC Lab, Old Dominion University</p>
−
 
+
<p class="date">03/20/2020</p>
−
== Medical Image Computing ==
+
</header>
−
 
+
<nav id="TOC">
−
=== Tessellate3D ===
+
        <h2 id="toctitle">Contents</h2>
−
 
+
        <ul>
−
In Medical Image Computing, Tessellate3D can be used to generate meshes from multi-tissue segmented images.
+
        <li><a href="#introduction">Introduction</a></li>
−
 
+
        <li><a href="#problem-domains">Problem Domains</a>
−
==== Examples ====
+
        <ul>
−
 
+
        <li><a href="#medical-image-computing">Medical Image Computing</a>
−
 
+
        <ul>
−
Input image and clipped generated meshes
+
        <li><a href="#tessellate3d">Tessellate3D</a></li>
−
 
+
        </ul></li>
−
[[File:Head-Neck.png|1000px]]
+
        <li><a href="#computational-nuclear-femtography">Computational Nuclear Femtography</a>
−
 
+
        <ul>
−
* Input (left figure): Dimensions (255x255x229) with spacing (0.976562x0.976562x1.40002)
+
        <li><a href="#tessellate3d-1">Tessellate3D</a></li>
−
* Uniform with Delta = default (middle figure): 205,510 tetrahedra
+
        <li><a href="#tessellate2d">Tessellate2D</a></li>
−
* Uniform with Delta = 1.5 (right figure): 767,393 tetrahedra
+
        </ul></li>
−
 
+
        </ul></li>
−
Uniform with Delta = default (middle figure):
+
        <li><a href="#software-documentation">Software Documentation</a>
−
 
+
        <ul>
−
<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>
+
        <li><a href="#requirements">Requirements</a></li>
−
Uniform with Delta = 1.5 (right figure):
+
        <li><a href="#installing-docker">Installing Docker</a>
−
 
+
        <ul>
−
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./Medical_Imaging_Data/3D/Head-Neck.mha --delta 1.5 -output ./Head-Neck,d=1.5.vtk</pre>
+
        <li><a href="#note-for-running-on-windows">Note for Running on Windows</a></li>
−
More Detailed 3D examples of Medical Image Computing can be found [https://crtc.cs.odu.edu/Medical_Imaging_Example_Meshes#3D_Example_Meshes here].
+
        </ul></li>
−
 
+
        <li><a href="#getting-the-software">Getting The Software</a>
−
==== Parameters ====
+
        <ul>
−
 
+
        <li><a href="#docker-container-instructions">Docker Container Instructions</a></li>
−
 
+
        </ul></li>
−
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 of [[#tessellate3d-podm-3d|Tessellate3D]].
+
        <li><a href="#tessellate3d-podm-3d">Tessellate3D (PODM 3D)</a>
−
 
+
        <ul>
−
<code>-i, --input [filename]</code> (required)
+
        <li><a href="#io-parameters">I/O Parameters</a></li>
−
 
+
        <li><a href="#performance-parameters">Performance Parameters</a></li>
−
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].
+
        <li><a href="#geometry-parameters">Geometry Parameters</a></li>
−
 
+
        <li><a href="#pre-processing-parameters">Pre-processing Parameters</a></li>
−
<code>-o, --output [filename]</code> (optional)
+
        <li><a href="#mesh-sizing-parameters">Mesh Sizing Parameters</a></li>
−
 
+
        <li><a href="#post-processing-parameters">Post-processing Parameters</a></li>
−
The filename of the output mesh saved in VTK format. (Default: input filename + parameters.vtk).
+
        <li><a href="#statistics-parameters">Statistics Parameters</a></li>
−
 
+
        <li><a href="#special-parameters">Special Parameters</a></li>
−
<code>-c, --plc [filename]</code> (optional)
+
        <li><a href="#miscellaneous-parameters">Miscellaneous Parameters</a></li>
−
 
+
        </ul></li>
−
If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.
+
        <li><a href="#tessellate2d-triangle">Tessellate2D (Triangle)</a></li>
−
 
+
        <li><a href="#convert-image">Convert Image</a></li>
−
<code>-t, --threads [unsigned integer]</code> (optional)
+
        <li><a href="#partons-to-nrrd">Partons To NRRD</a></li>
−
 
+
        </ul></li>
−
Sets the number of threads to be utilized.<br />
+
        <li><a href="#appendix">Appendix</a>
−
(Default: 1).
+
        <ul>
−
 
+
        <li><a href="#how-mesh-size-relates-to-delta">How mesh size relates to delta</a></li>
−
<code>-d, --delta [unsigned real]</code> (optional)
+
        </ul></li>
−
 
+
        </ul>
−
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.
+
</nav>
−
 
+
<hr />
−
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 />
+
<h1 id="introduction">Introduction</h1>
−
(Default: ''1 / 100'' * ''minimum-physical-size'').
+
<p>This document contains instructions for downloading and using the <code>crtc_i2m</code> software suite developed by the <a href="https://crtc.cs.odu.edu/Main_Page">CRTC lab</a> at <a href="https://odu.edu/compsci">Old Dominion University</a>.</p>
−
 
+
<p>The suite contains three software components:</p>
−
<code>-g, --volume-grading</code> (optional)
+
<ol type="1">
−
 
+
<li><strong>Tessellate3D (PODM 3D)</strong> (3D tessellation software)</li>
−
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.
+
<li><strong>Tessellate2D (Triangle)</strong> (2D tessellation software)</li>
−
 
+
<li><strong>Convert Image</strong> (image format conversion software)</li>
−
<code>--include-labels [unsigned char list]</code> (optional)
+
<li><strong>PartonsToNRRD</strong> (creation of image out of Partons data software) </li>
−
 
+
</ol>
−
Labels that will be included in the mesh. If not specified, all labels will be included in the mesh. Cannot be used together with <code>--exclude-labels</code>.
+
<h1 id="problem-domains">Problem Domains</h1>
−
 
+
<p>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.</p>
−
<code>--exclude-labels [unsigned char list]</code> (optional)
+
<h2 id="medical-image-computing">Medical Image Computing</h2>
−
 
+
<h3 id="tessellate3d">Tessellate3D</h3>
−
Labels that will be excluded from the mesh. Keeps all labels in the mesh except the ones specified. If not specified, all labels will be included in the mesh. Cannot be used together with <code>--include-labels</code>.
+
<p>In Medical Image Computing, Tessellate3D can be used to generate meshes from multi-tissue segmented images.</p>
−
 
+
<h4 id="examples">Examples</h4>
−
== Computational Nuclear Femtography ==
+
<p>Input image and clipped generated meshes</p>
−
 
+
<p><img src="./assets/Head-Neck.png" style="width:100.0%" /></p>
−
A short presentation can be found [http://www.cs.odu.edu/crtc/cnf_project/assets/Imaging_Chrisochoides_ODU_04_30_19.pdf here].
+
<ul>
−
 
+
<li>Input (left figure): Dimensions (255x255x229) with spacing (0.976562x0.976562x1.40002)</li>
−
=== Tessellate3D ===
+
<li>Uniform with Delta = default (middle figure): 205,510 tetrahedra</li>
−
 
+
<li>Uniform with Delta = 1.5 (right figure): 767,393 tetrahedra</li>
−
==== Examples ====
+
</ul>
−
 
+
<p>Uniform with Delta = default (middle figure):</p>
−
 
+
<pre><code>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./Medical_Imaging_Data/3D/Head-Neck.mha --output ./Head-Neck,d=2.49023.vtk</code></pre>
−
Input image and clipped generated meshes
+
<p>Uniform with Delta = 1.5 (right figure):</p>
−
 
+
<pre><code>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./Medical_Imaging_Data/3D/Head-Neck.mha --delta 1.5 -output ./Head-Neck,d=1.5.vtk</code></pre>
−
[[File:NT_3D.png|1000px]]
+
<p>More Detailed 3D examples of Medical Image Computing can be found <a href="https://crtc.cs.odu.edu/Medical_Imaging_Example_Meshes#3D_Example_Meshes">here</a>.</p>
−
 
+
<h4 id="parameters">Parameters</h4>
−
* Input (left figure): Dimensions (100x100x100) with spacing (1x1x1), Voxels = 1,000,000
+
<p>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 of <a href="#tessellate3d-podm-3d">Tessellate3D</a>.</p>
−
* Uniform (middle figure): 768,033 tetrahedra
+
<p><code>-i, --input [filename]</code> (required)</p>
−
* Adaptive (right figure): 257,041 tetrahedra
+
<p>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 <a href="https://insightsoftwareconsortium.github.io/itk-js/docs/image_formats.html">here</a>.</p>
−
 
+
<p><code>-o, --output [filename]</code> (optional)</p>
−
Uniform (middle figure):
+
<p>The filename of the output mesh saved in VTK format. (Default: input filename + parameters.vtk).</p>
−
 
+
<p><code>-c, --plc [filename]</code> (optional)</p>
−
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./CNF_Data/3D/CFF_14052019/NT_140519.nrrd --cnf-uniform</pre>
+
<p>If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.</p>
−
Adaptive (right figure):
+
<p><code>-t, --threads [unsigned integer]</code> (optional)</p>
−
 
+
<p>Sets the number of threads to be utilized.<br />
−
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./CNF_Data/3D/CFF_14052019/NT_140519.nrrd --cnf-adaptive --weight-limit 0.07</pre>
+
(Default: 1).</p>
−
More Detailed 3D examples of Computational Nuclear Femtography can be found [https://crtc.cs.odu.edu/CNF_Example_Meshes#3D_Example_Meshes here].
+
<p><code>-d, --delta [unsigned real]</code> (optional)</p>
−
 
+
<p>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.</p>
−
==== Parameters ====
+
<p>The maximum suggested value for delta is <em>1 / 5</em> of the <em>minimum-physical-size</em> of the input image, where <em>minimum-physical-size</em> = min(spacing * size).<br />
−
 
+
(Default: <em>1 / 100</em> * <em>minimum-physical-size</em>).</p>
−
 
+
<p><code>-g, --volume-grading</code> (optional)</p>
−
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 of [[#tessellate3d-podm-3d|Tessellate3D]].
+
<p>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.</p>
−
 
+
<p><code>--include-labels [unsigned char list]</code> (optional)</p>
−
<code>-i, --input [filename]</code> (required)
+
<p>Labels that will be included in the mesh. If not specified, all labels will be included in the mesh. Cannot be used together with <code>--exclude-labels</code>.</p>
−
 
+
<p><code>--exclude-labels [unsigned char list]</code> (optional)</p>
−
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].
+
<p>Labels that will be excluded from the mesh. Keeps all labels in the mesh except the ones specified. If not specified, all labels will be included in the mesh. Cannot be used together with <code>--include-labels</code>.</p>
−
 
+
<h2 id="computational-nuclear-femtography">Computational Nuclear Femtography</h2>
−
<code>-o, --output [filename]</code> (optional)
+
<p>A short presentation can be found <a href="assets/Imaging_Chrisochoides_ODU_04_30_19.pdf">here</a>.</p>
−
 
+
<h3 id="tessellate3d-1">Tessellate3D</h3>
−
The filename of the output mesh saved in VTK format.<br />
+
<h4 id="examples-1">Examples</h4>
−
(Default: input filename + parameters.vtk).
+
<p>Input image and clipped generated meshes</p>
−
 
+
<p><img src="./assets/NT_3D.png" style="width:100.0%" /></p>
−
<code>-t, --threads [unsigned integer]</code> (optional)
+
<ul>
−
 
+
<li>Input (left figure): Dimensions (100x100x100) with spacing (1x1x1), Voxels = 1,000,000</li>
−
Sets the number of threads to be utilized.<br />
+
<li>Uniform (middle figure): 768,033 tetrahedra</li>
−
(Default: 1).
+
<li>Adaptive (right figure): 257,041 tetrahedra</li>
−
 
+
</ul>
−
<code>-d, --delta [unsigned real]</code> (optional)
+
<p>Uniform (middle figure):</p>
−
 
+
<pre><code>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./CNF_Data/3D/CFF_14052019/NT_140519.nrrd --cnf-uniform</code></pre>
−
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.
+
<p>Adaptive (right figure):</p>
−
 
+
<pre><code>docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./CNF_Data/3D/CFF_14052019/NT_140519.nrrd --cnf-adaptive --weight-limit 0.07</code></pre>
−
''minimum-physical-size'' of input image = min(spacing * size).<br />
+
<p>More Detailed 3D examples of Computational Nuclear Femtography can be found <a href="https://crtc.cs.odu.edu/CNF_Example_Meshes#3D_Example_Meshes">here</a>.</p>
−
(Default (if <code>--cnf-uniform</code> is specified): ''1 / 100'' * ''minimum-physical-size'').<br />
+
<h4 id="parameters-1">Parameters</h4>
−
(Default (if <code>--cnf-adaptive</code> is specified): ''1 / 20'' * ''minimum-physical-size'').
+
<p>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 of <a href="#tessellate3d-podm-3d">Tessellate3D</a>.</p>
−
 
+
<p><code>-i, --input [filename]</code> (required)</p>
−
<code>--cnf-uniform</code> (optional)
+
<p>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 <a href="https://insightsoftwareconsortium.github.io/itk-js/docs/image_formats.html">here</a>.</p>
−
 
+
<p><code>-o, --output [filename]</code> (optional)</p>
−
Produces uniform size meshes for CNF data. Size of elements is controlled by <code>--delta</code>.
+
<p>The filename of the output mesh saved in VTK format.<br />
−
 
+
(Default: input filename + parameters.vtk).</p>
−
<code>--cnf-adaptive</code> (optional)
+
<p><code>-t, --threads [unsigned integer]</code> (optional)</p>
−
 
+
<p>Sets the number of threads to be utilized.<br />
−
Produces adaptive meshes for CNF data. The level of adaptivity is controlled by <code>--weight-limit</code> and <code>--min-edge</code> (see below). For more details about how sizing works see the [[#note-sizing-function|note]] at the end of the section.
+
(Default: 1).</p>
−
 
+
<p><code>-d, --delta [unsigned real]</code> (optional)</p>
−
<code>-w, --weight-limit [unsigned real [0.000001, 1]]</code> (optional)
+
<p>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.</p>
−
 
+
<p><em>minimum-physical-size</em> of input image = min(spacing * size).<br />
−
Sets the element weight limit of the generated elements that will be used by the sizing function. Weight limit is used by the sizing function to control the gradation of the mesh based on the weights of the image.<br />
+
(Default (if <code>--cnf-uniform</code> is specified): <em>1 / 100</em> * <em>minimum-physical-size</em>).<br />
−
(Default: 0.1).
+
(Default (if <code>--cnf-adaptive</code> is specified): <em>1 / 20</em> * <em>minimum-physical-size</em>).</p>
−
 
+
<p><code>--cnf-uniform</code> (optional)</p>
−
<code>-m, --min-edge [unsigned real [0.000001, 7.5]]</code> (optional)
+
<p>Produces uniform size meshes for CNF data. Size of elements is controlled by <code>--delta</code>.</p>
−
 
+
<p><code>--cnf-adaptive</code> (optional)</p>
−
Sets the percentage of the diagonal of the box that will be used to define the minimum edge of an element. Minimum edge is used by the sizing function to reject the refinement of an element. (Default: ''1/ <math display="inline">\sqrt{3}</math> %'').
+
<p>Produces adaptive meshes for CNF data. The level of adaptivity is controlled by <code>--weight-limit</code> and <code>--min-edge</code> (see below). For more details about how sizing works see the <a href="#note-sizing-function">note</a> at the end of the section.</p>
−
 
+
<p><code>-w, --weight-limit [unsigned real [0.000001, 1]]</code> (optional)</p>
−
<code>-M, --max-edge [unsigned real [10.0, 50.0]]</code> (optional)
+
<p>Sets the element weight limit of the generated elements that will be used by the sizing function. Weight limit is used by the sizing function to control the gradation of the mesh based on the weights of the image.<br />
−
 
+
(Default: 0.1).</p>
−
Sets the percentage of the diagonal of the box that will be used to define the maximum edge of an element. Minimum edge is used by the sizing function to approve the refinement of an element. (Default: ''10 %'').
+
<p><code>-m, --min-edge [unsigned real [0.000001, 7.5]]</code> (optional)</p>
−
 
+
<p>Sets the percentage of the diagonal of the box that will be used to define the minimum edge of an element. Minimum edge is used by the sizing function to reject the refinement of an element. (Default: <em>1/ <span class="math inline">$\sqrt{3}$</span> %</em>).</p>
−
<code>-b, --background-value [signed real]</code> (optional)
+
<p><code>-M, --max-edge [unsigned real [10.0, 50.0]]</code> (optional)</p>
−
 
+
<p>Sets the percentage of the diagonal of the box that will be used to define the maximum edge of an element. Minimum edge is used by the sizing function to approve the refinement of an element. (Default: <em>10 %</em>).</p>
−
Sets the voxel value that will be treated as a background value during the 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 />
+
<p><code>-b, --background-value [signed real]</code> (optional)</p>
−
(Default: +oo).
+
<p>Sets the voxel value that will be treated as a background value during the 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).</p>
−
===== Note: Sizing Function =====
+
<h5 id="note-sizing-function">Note: Sizing Function</h5>
−
 
+
<p>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 <em>image-weight-range</em> along with the diagonal of the image are computed, The diagonal is used to define the <em>minimum-element-edge-length</em> and <em>maximum-element-edge-length</em> multiplied by the the user-defined <em>min-edge</em> and <em>max-edge</em> diagonal percentages. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the user constrains. Each time SF is called upon an element, it will check if it meets the size constrains <em>minimum-element-edge-length</em> and <em>maximum-element-edge-size</em>. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and midpoints of vertices and barycenter. 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 <em>element-weight-range</em> = abs(max(V) - min(V)) is evaluated. If <em>element-weight-range</em>/<em>image-weight-range</em> exceeds the user constraint <em>weight-limit</em>, the element is split.</p>
−
 
+
<h3 id="tessellate2d">Tessellate2D</h3>
−
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 ''image-weight-range'' along with the diagonal of the image are computed, The diagonal is used to define the ''minimum-element-edge-length'' and ''maximum-element-edge-length'' multiplied by the the user-defined ''min-edge'' and ''max-edge'' diagonal percentages. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the user constrains. Each time SF is called upon an element, it will check if it meets the size constrains ''minimum-element-edge-length'' and ''maximum-element-edge-size''. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and midpoints of vertices and barycenter. 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 ''element-weight-range'' = abs(max(V) - min(V)) is evaluated. If ''element-weight-range''/''image-weight-range'' exceeds the user constraint ''weight-limit'', the element is split.
+
<h4 id="examples-2">Examples</h4>
−
 
+
<p>Input image and generated meshes</p>
−
=== Tessellate2D ===
+
<p><img src="./assets/NT_2D.png" style="width:100.0%" /></p>
−
 
+
<ul>
−
==== Examples ====
+
<li>Input (left figure) : Dimensions (100x100) with spacing (1x1), Pixels = 10,000</li>
−
 
+
<li>Uniform (middle figure) : 7,587 triangles</li>
−
 
+
<li>Adaptive (right figure) : 1,038 triangles</li>
−
Input image and generated meshes
+
</ul>
−
 
+
<p>Uniform (middle figure):</p>
−
[[File:NT_2D.png|1000px]]
+
<pre><code>docker run -v $(pwd):/data/ crtc_i2m tessellate2d  --input ./CNF_Data/2D/NT_140519_50_X.vtk --min-edge=2 --uniform</code></pre>
−
 
+
<p>Adaptive (right figure):</p>
−
* Input (left figure) : Dimensions (100x100) with spacing (1x1), Pixels = 10,000
+
<pre><code>docker run -v $(pwd):/data/ crtc_i2m tessellate2d  --input ./CNF_Data/2D/NT_140519_50_X.vtk --min-edge=2 --weight-limit=0.1</code></pre>
−
* Uniform (middle figure) : 7,587 triangles
+
<p>More Detailed 2D examples of Computational Nuclear Femtography can be found <a href="https://crtc.cs.odu.edu/CNF_Example_Meshes#2D_Example_Meshes">here</a>.</p>
−
* Adaptive (right figure) : 1,038 triangles
+
<h4 id="parameters-2">Parameters</h4>
−
 
+
<p>Note: For the description of the employed sizing function please see the software documentation section of <a href="#mesh-sizing-parameters">Tessellate3D</a>.</p>
−
Uniform (middle figure):
+
<p><code>-i, --input [filename]</code> (required)</p>
−
 
+
<p>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 <a href="https://insightsoftwareconsortium.github.io/itk-js/docs/image_formats.html">here</a>.</p>
−
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate2d  --input ./CNF_Data/2D/NT_140519_50_X.vtk --min-edge=2 --uniform</pre>
+
<p><code>-o, --output [filename]</code> (optional)</p>
−
Adaptive (right figure):
+
<p>The filename of the output mesh saved in VTK format.<br />
−
 
+
(Default: <code>outputMesh.vtk</code>).</p>
−
<pre>docker run -v $(pwd):/data/ crtc_i2m tessellate2d  --input ./CNF_Data/2D/NT_140519_50_X.vtk --min-edge=2 --weight-limit=0.1</pre>
+
<p><code>-w,--weight-limit [unsigned real]</code> (optional)</p>
−
More Detailed 2D examples of Computational Nuclear Femtography can be found [https://crtc.cs.odu.edu/CNF_Example_Meshes#2D_Example_Meshes here].
+
<p>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)</p>
−
==== Parameters ====
+
<p><code>-e,--min-edge [unsigned real]</code> (optional)</p>
−
 
+
<p>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; <em>1</em> does not offer significant gain if the <em>pixel size</em> of the input image = <em>1</em>.</p>
−
 
+
<p><em>minimum-physical-size</em> of input image = min(spacing * size).<br />
−
Note: For the description of the employed sizing function please see the software documentation section of [[#mesh-sizing-parameters|Tessellate3D]].
+
(Default: <em>1 / 100</em> * <em>minimum-physical-size</em>)</p>
−
 
+
<p><code>-u,--uniform</code> (optional)</p>
−
<code>-i, --input [filename]</code> (required)
+
<p>Creates a uniform mesh instead of an adaptive one. Uses <code>--min-edge</code> value as a constant size constraint.</p>
−
 
+
<h1 id="software-documentation">Software Documentation</h1>
−
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].
+
<p>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.</p>
−
 
+
<h2 id="requirements">Requirements</h2>
−
<code>-o, --output [filename]</code> (optional)
+
<ul>
−
 
+
<li>OS: Linux, Windows 10 Pro/Enterprise, MacOS Sierra 10.12+</li>
−
The filename of the output mesh saved in VTK format.<br />
+
<li>Docker</li>
−
(Default: <code>outputMesh.vtk</code>).
+
</ul>
−
 
+
<h2 id="installing-docker">Installing Docker</h2>
−
<code>-w,--weight-limit [unsigned real]</code> (optional)
+
<p>Official documentation :</p>
−
 
+
<ul>
−
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 />
+
<li><a href="https://docs.docker.com/docker-for-windows/install">Microsoft Windows</a></li>
−
(Default: 0.1)
+
<li><a href="https://docs.docker.com/docker-for-mac/install/">MacOS</a></li>
−
 
+
<li>Linux
−
<code>-e,--min-edge [unsigned real]</code> (optional)
+
<ul>
−
 
+
<li><a href="https://docs.docker.com/install/linux/docker-ce/ubuntu/">Ubuntu</a></li>
−
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''.
+
<li><a href="https://docs.docker.com/install/linux/docker-ce/debian/">Debian</a></li>
−
 
+
<li><a href="https://docs.docker.com/install/linux/docker-ce/centos/">CentOS</a></li>
−
''minimum-physical-size'' of input image = min(spacing * size).<br />
+
<li><a href="https://docs.docker.com/install/linux/docker-ce/binaries">Other</a></li>
−
(Default: ''1 / 100'' * ''minimum-physical-size'')
+
</ul></li>
−
 
+
</ul>
−
<code>-u,--uniform</code> (optional)
+
<h3 id="note-for-running-on-windows">Note for Running on Windows</h3>
−
 
+
<p>Docker on Windows uses Hyper-V VMs to run Linux containers. By default, the spawned VMs use 2 vCPUs and 2 GB RAM.</p>
−
Creates a uniform mesh instead of an adaptive one. Uses <code>--min-edge</code> value as a constant size constraint.
+
<p>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.</p>
−
 
+
<h2 id="getting-the-software">Getting The Software</h2>
−
= Software Documentation =
+
<p>The docker image containing the <code>crtc_i2m</code> software suite is located <a href="https://odu.box.com/s/j754hazu7qjdcn2szxf8n9n5l5ekll2f">here</a> (restricted access).</p>
−
 
+
<h3 id="docker-container-instructions">Docker Container Instructions</h3>
−
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.
+
<ol type="1">
−
 
 
−
== Requirements ==
 
−
 
 
−
* OS: Linux, Windows 10 Pro/Enterprise, MacOS Sierra 10.12+
 
−
* Docker
 
−
 
 
−
== Installing Docker ==
 
−
 
 
−
Official documentation :
 
−
 
 
−
* [https://docs.docker.com/docker-for-windows/install Microsoft Windows]
 
−
* [https://docs.docker.com/docker-for-mac/install/ MacOS]
 
−
* Linux
 
−
** [https://docs.docker.com/install/linux/docker-ce/ubuntu/ Ubuntu]
 
−
** [https://docs.docker.com/install/linux/docker-ce/debian/ Debian]
 
−
** [https://docs.docker.com/install/linux/docker-ce/centos/ CentOS]
 
−
** [https://docs.docker.com/install/linux/docker-ce/binaries Other]
 
−
 
 
−
=== 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 <code>crtc_i2m</code> software suite is located [https://odu.box.com/s/j754hazu7qjdcn2szxf8n9n5l5ekll2f here] (restricted access).
 
−
 
 
−
=== Docker Container Instructions ===
 
−
 
 
−
<ol style="list-style-type: decimal;">
 
 
<li><p>Load the Docker Image.</p>
 
<li><p>Load the Docker Image.</p>
 
<p>First of all, the Docker image needs to be loaded. The following command must be used:</p>
 
<p>First of all, the Docker image needs to be loaded. The following command must be used:</p>
−
<pre>docker load --input [DOCKER_IMAGE_TAR]</pre>
+
<pre><code>docker load --input [DOCKER_IMAGE_TAR]</code></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><p>Running</p>
 
<ul>
 
<ul>
 
<li><p>On MacOS/Linux</p>
 
<li><p>On MacOS/Linux</p>
−
<pre>docker run -v $(pwd):/data/ crtc_i2m &lt;application&gt; [arguments]</pre></li>
+
<pre><code>docker run -v $(pwd):/data/ crtc_i2m &lt;application&gt; [arguments]</code></pre></li>
 
<li><p>On Windows with PowerShell (recommended)</p>
 
<li><p>On Windows with PowerShell (recommended)</p>
−
<pre>docker run -v ${PWD}:/data/ crtc_i2m &lt;application&gt; [arguments]</pre></li></ul>
+
<pre><code>docker run -v ${PWD}:/data/ crtc_i2m &lt;application&gt; [arguments]</code></pre></li>
−
 
+
</ul>
−
<p>'''Notice that in this case brackets {} are used instead of parenthesis ()'''</p>
+
<p><strong>Notice that in this case brackets {} are used instead of parenthesis ()</strong></p>
 
<ul>
 
<ul>
 
<li><p>On Windows with the command line (cmd)</p>
 
<li><p>On Windows with the command line (cmd)</p>
−
<pre>docker run -v %cd%:/data/ crtc_i2m &lt;application&gt; [arguments]</pre></li></ul>
+
<pre><code>docker run -v %cd%:/data/ crtc_i2m &lt;application&gt; [arguments]</code></pre></li>
−
</li></ol>
+
</ul></li>
−
 
+
</ol>
−
Where <code>&lt;application&gt;</code> is one of the currently available tools : <code>tessellate3d</code>, <code>tessellate2d</code>, <code>convert_image</code> or <code>partonsToNRRD</code>.
+
<p>Where <code>&lt;application&gt;</code> is one of the currently available tools : <code>tessellate3d</code>, <code>tessellate2d</code>, <code>convert_image</code> or <code>partonsToNRRD</code>.</p>
−
 
+
<h2 id="tessellate3d-podm-3d">Tessellate3D (PODM 3D)</h2>
−
== Tessellate3D (PODM 3D) ==
+
<p>The main component of the software suite is a 3D tessellation software called <strong>PODM3D</strong>, 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.</p>
−
 
+
<p>The output meshes are in the <a href="https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf">VTK format</a> and can be visualized using the open-source software <a href="https://www.paraview.org">Paraview</a>.</p>
−
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.
+
<p>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>.</p>
−
 
+
<p>Below is the detailed information about the parameters of <code>tessellate3d</code>:</p>
−
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].
+
<h3 id="io-parameters">I/O Parameters</h3>
−
 
+
<p><code>-i, --input [filename]</code> (required)</p>
−
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>.
+
<p>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 <a href="https://insightsoftwareconsortium.github.io/itk-js/docs/image_formats.html">here</a>.</p>
−
 
+
<p><code>-o, --output [filename]</code> (optional)</p>
−
Below is the detailed information about the parameters of <code>tessellate3d</code>:
+
<p>The filename of the output mesh saved in VTK format.<br />
−
 
+
(Default: input filename + parameters.vtk).</p>
−
=== I/O Parameters ===
+
<p><code>-c, --plc [filename]</code> (optional)</p>
−
 
+
<p>If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.</p>
−
<code>-i, --input [filename]</code> (required)
+
<p><code>-r, --file-format {0,1}</code> (optional)</p>
−
 
+
<p>Sets file format of outputFiles. <code>0</code> for ASCII, and <code>1</code> for BINARY.<br />
−
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].
+
(Default: BINARY).</p>
−
 
+
<h3 id="performance-parameters">Performance Parameters</h3>
−
<code>-o, --output [filename]</code> (optional)
+
<p><code>-t, --threads [unsigned integer]</code> (optional)</p>
−
 
+
<p>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 />
−
The filename of the output mesh saved in VTK format.<br />
+
(Default: 1).</p>
−
(Default: input filename + parameters.vtk).
+
<p><code>-p, --thread-pinning {0, 1}</code> (optional)</p>
−
 
+
<p>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 />
−
<code>-c, --plc [filename]</code> (optional)
+
(Default: 1).</p>
−
 
+
<p><code>--memory-limit [unsinged integer in MB]</code> (optional)</p>
−
If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.
+
<p>Constrains the amount of memory in MB that will be used.<br />
−
 
+
(Default: 80% of the free memory).</p>
−
<code>-r, --file-format {0,1}</code> (optional)
+
<h3 id="geometry-parameters">Geometry Parameters</h3>
−
 
+
<p><code>-d, --delta [unsigned real]</code> (optional)</p>
−
Sets file format of outputFiles. <code>0</code> for ASCII, and <code>1</code> for BINARY.<br />
+
<p>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. For uniform meshes (i.e. no <code>--volume-grading</code>), the total number of elements is related to delta through an inverse cubic law (approximately):</p>
−
(Default: BINARY).
+
<p>The maximum suggested value for delta is <em>1 / 5</em> of the <em>minimum-physical-size</em> of the input image, where <em>minimum-physical-size</em> = min(spacing * size).<br />
−
 
+
(Default (if <code>--sizing-function</code> is not specified): <em>1 / 100</em> * <em>minimum-physical-size</em>).<br />
−
=== Performance Parameters ===
+
(Default (if <code>--sizing-function</code> is specified): <em>1 / 20</em> * <em>minimum-physical-size</em>).</p>
−
 
+
<p>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. If using <em>d_1</em> creates <em>N_1</em> elements then <em>d_1/2</em> will create (approximately) <em>8</em> = <em>2^3</em> times more elements while <em>2</em> * <em>d_1</em> will generate <em>1/8N_1</em> elements. A table which shows the relation between delta and mesh size can be found in the <a href="#how-mesh-size-relates-to-delta">Appendix</a>. For more information on how delta affects the density of the sampling, see <a href="https://crtc.cs.odu.edu/pub/papers/journal_58.pdf">Guaranteed Quality Tetrahedral Delaunay Meshing for Medical Images</a>.</p>
−
<code>-t, --threads [unsigned integer]</code> (optional)
+
<p><code>-g, --volume-grading</code> (optional)</p>
−
 
+
<p>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.</p>
−
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 />
+
<h3 id="pre-processing-parameters">Pre-processing Parameters</h3>
−
(Default: 1).
+
<p><code>-s, --image-segmentation</code> (optional)</p>
−
 
+
<p>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.</p>
−
<code>-p, --thread-pinning {0, 1}</code> (optional)
+
<p><code>-b, --background-value [signed real]</code> (optional)</p>
−
 
+
<p>Sets the voxel value that will be treated as a background value during the 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 />
−
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: +oo).</p>
−
(Default: 1).
+
<p><code>--include-labels [unsigned char list]</code> (optional)</p>
−
 
+
<p>Labels that will be included in the mesh. If not specified, all labels will be included in the mesh. Cannot be used together with <code>--exclude-labels</code>.</p>
−
<code>--memory-limit [unsinged integer in MB]</code> (optional)
+
<p><code>--exclude-labels [unsigned char list]</code> (optional)</p>
−
 
+
<p>Labels that will be excluded from the mesh. Keeps all labels in the mesh except the ones specified. If not specified, all labels will be included in the mesh. Cannot be used together with <code>--include-labels</code>.</p>
−
Constrains the amount of memory in MB that will be used.<br />
+
<h3 id="mesh-sizing-parameters">Mesh Sizing Parameters</h3>
−
(Default: 80% of the free memory).
+
<p><code>-f, --sizing-function</code> (optional)</p>
−
 
+
<p>Enables the sizing-function that is described below. Uses <code>--weight-limit</code> and <code>--min-edge</code> as optional parameters.<br />
−
=== Geometry Parameters ===
+
<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.</p>
−
 
+
<p>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 <em>image-weight-range</em> along with the diagonal of the image are computed, The diagonal is used to define the <em>minimum-element-edge-length</em> and <em>maximum-element-edge-length</em> multiplied by the the user-defined <em>min-edge</em> and <em>max-edge</em> diagonal percentages. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the user constrains. Each time SF is called upon an element, it will check if it meets the size constrains <em>minimum-element-edge-length</em> and <em>maximum-element-edge-size</em>. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and midpoints of vertices and barycenter. 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 <em>element-weight-range</em> = abs(max(V) - min(V)) is evaluated. If <em>element-weight-range</em>/<em>image-weight-range</em> exceeds the user constraint <em>weight-limit</em>, the element is split.</p>
−
<code>-d, --delta [unsigned real]</code> (optional)
+
<p>The described sizing function was designed for the Computational Nuclear Femtography data. Nonetheless, another sizing function could be designed and employed if requested.</p>
−
 
+
<p><code>-w, --weight-limit [unsigned real [0.000001, 1]]</code> (optional)</p>
−
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. For uniform meshes (i.e. no <code>--volume-grading</code>), the total number of elements is related to delta through an inverse cubic law (approximately):
+
<p>Sets the element weight limit of the generated elements that will be used by the sizing function. Weight limit is used by the sizing function to control the gradation of the mesh based on the weights of the image.<br />
−
 
+
(Default: 0.1).</p>
−
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 />
+
<p><code>-m, --min-edge [unsigned real [0.000001, 7.5]]</code> (optional)</p>
−
(Default (if <code>--sizing-function</code> is not specified): ''1 / 100'' * ''minimum-physical-size'').<br />
+
<p>Sets the percentage of the diagonal of the box that will be used to define the minimum edge of an element. Minimum edge is used by the sizing function to reject the refinement of an element.<br />
−
(Default (if <code>--sizing-function</code> is specified): ''1 / 20'' * ''minimum-physical-size'').
+
(Default: <em>1/ <span class="math inline">$\sqrt{3}$</span> %</em>).</p>
−
 
+
<p><code>-M, --max-edge [unsigned real [10.0, 50.0]]</code> (optional)</p>
−
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. If using ''d_1'' creates ''N_1'' elements then ''d_1/2'' will create (approximately) ''8'' = ''2^3'' times more elements while ''2'' * ''d_1'' will generate ''1/8N_1'' elements. A table which shows the relation between delta and mesh size can be found in the [[#how-mesh-size-relates-to-delta|Appendix]]. 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].
+
<p>Sets the percentage of the diagonal of the box that will be used to define the maximum edge of an element. Minimum edge is used by the sizing function to approve the refinement of an element.<br />
−
 
+
(Default: <em>10 %</em>).</p>
−
<code>-g, --volume-grading</code> (optional)
+
<h3 id="post-processing-parameters">Post-processing Parameters</h3>
−
 
+
<p><code>-l, --linear-interpolation</code> (optional)</p>
−
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.
+
<p>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.</p>
−
 
+
<h3 id="statistics-parameters">Statistics Parameters</h3>
−
=== Pre-processing Parameters ===
+
<p><code>--thread-statistics</code> (optional)</p>
−
 
+
<p>Computes and prints thread statistics.</p>
−
<code>-s, --image-segmentation</code> (optional)
+
<p><code>--mesh-statistics</code> (optional)</p>
−
 
+
<p>Computes and prints mesh statistics.</p>
−
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.
+
<p><code>--all-statistics</code> (optional)</p>
−
 
+
<p>Computes and prints all statistics (thread and mesh).</p>
−
<code>-b, --background-value [signed real]</code> (optional)
+
<h3 id="special-parameters">Special Parameters</h3>
−
 
+
<p><code>--cnf-uniform</code> (optional)</p>
−
Sets the voxel value that will be treated as a background value during the 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 />
+
<p>Activates the flags <code>--image-segmentation</code>, and <code>--linear-interpolation</code> which are required for producing uniform size meshes for CNF data. Size of elements is controlled by <code>--delta</code>.</p>
−
(Default: +oo).
+
<p><code>--cnf-adaptive</code> (optional)</p>
−
 
+
<p>Activates the flags <code>--image-segmentation</code>, <code>--volume-grading</code>, <code>--sizing-function</code>, and <code>--linear-interpolation</code> which are required for producing adaptive meshes for CNF data. The level of adaptivity is controlled by <code>--weight-limit</code>, <code>--min-edge</code>, <code>--max-edge</code>.</p>
−
<code>--include-labels [unsigned char list]</code> (optional)
+
<h3 id="miscellaneous-parameters">Miscellaneous Parameters</h3>
−
 
+
<p><code>-v, --verbosity-level {0, 1, 2}</code> (optional)</p>
−
Labels that will be included in the mesh. If not specified, all labels will be included in the mesh. Cannot be used together with <code>--exclude-labels</code>.
+
<p>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).</p>
−
<code>--exclude-labels [unsigned char list]</code> (optional)
+
<p><code>--version</code> (optional)</p>
−
 
+
<p>Show PODM3D version and exit.</p>
−
Labels that will be excluded from the mesh. Keeps all labels in the mesh except the ones specified. If not specified, all labels will be included in the mesh. Cannot be used together with <code>--include-labels</code>.
+
<h2 id="tessellate2d-triangle">Tessellate2D (Triangle)</h2>
−
 
+
<p>Tessellate2D is a modified version of the <a href="https://www.cs.cmu.edu/~quake/triangle.html"><em>Triangle</em></a> software for 2D tessellation.</p>
−
=== Mesh Sizing Parameters ===
+
<p>The output meshes are in the <a href="https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf">VTK format</a> and can be visualized using the open-source software <a href="https://www.paraview.org">Paraview</a>.</p>
−
 
+
<p>Note: For the description of the employed sizing function please see the software documentation section of <a href="#mesh-sizing-parameters">Tessellate3D</a>.</p>
−
<code>-f, --sizing-function</code> (optional)
+
<p>Below is the detailed information about the parameters of <code>tessellate2d</code>:</p>
−
 
+
<p><code>-i, --input [filename]</code> (required)</p>
−
Enables the sizing-function that is described below. Uses <code>--weight-limit</code> and <code>--min-edge</code> as optional parameters.<br />
+
<p>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 <a href="https://insightsoftwareconsortium.github.io/itk-js/docs/image_formats.html">here</a>.</p>
−
<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.
+
<p><code>-o, --output [filename]</code> (optional)</p>
−
 
+
<p>The filename of the output mesh saved in VTK format.<br />
−
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 ''image-weight-range'' along with the diagonal of the image are computed, The diagonal is used to define the ''minimum-element-edge-length'' and ''maximum-element-edge-length'' multiplied by the the user-defined ''min-edge'' and ''max-edge'' diagonal percentages. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the user constrains. Each time SF is called upon an element, it will check if it meets the size constrains ''minimum-element-edge-length'' and ''maximum-element-edge-size''. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and midpoints of vertices and barycenter. 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 ''element-weight-range'' = abs(max(V) - min(V)) is evaluated. If ''element-weight-range''/''image-weight-range'' exceeds the user constraint ''weight-limit'', the element is split.
+
(Default: <code>outputMesh.vtk</code>). </p>
−
 
+
<p><code>-r, --file-format {0,1}</code> (optional)</p>
−
The described sizing function was designed for the Computational Nuclear Femtography data. Nonetheless, another sizing function could be designed and employed if requested.
+
<p>Sets file format of outputFiles. <code>0</code> for ASCII, and <code>1</code> for BINARY.<br />
−
 
+
(Default: ASCII).</p>
−
<code>-w, --weight-limit [unsigned real [0.000001, 1]]</code> (optional)
+
<p><code>-w,--weight-limit [unsigned real]</code> (optional)</p>
−
 
+
<p>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 />
−
Sets the element weight limit of the generated elements that will be used by the sizing function. Weight limit is used by the sizing function to control the gradation of the mesh based on the weights of the image.<br />
+
(Default: 0.1)</p>
−
(Default: 0.1).
+
<p><code>-e,--min-edge [unsigned real]</code> (optional)</p>
−
 
+
<p>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; <em>1</em> does not offer significant gain if the <em>pixel size</em> of the input image = <em>1</em>.</p>
−
<code>-m, --min-edge [unsigned real [0.000001, 7.5]]</code> (optional)
+
<p><em>minimum-physical-size</em> of input image = min(spacing * size).<br />
−
 
+
(Default: <em>1 / 100</em> * <em>minimum-physical-size</em>)</p>
−
Sets the percentage of the diagonal of the box that will be used to define the minimum edge of an element. Minimum edge is used by the sizing function to reject the refinement of an element.<br />
+
<p><code>-u,--uniform</code> (optional)</p>
−
(Default: ''1/ <math display="inline">\sqrt{3}</math> %'').
+
<p>Creates a uniform mesh instead of an adaptive one. Uses <code>--min-edge</code> value as a constant size constraint.</p>
−
 
+
<p><code>-v,--verbose-level [0,1]</code> (optional)</p>
−
<code>-M, --max-edge [unsigned real [10.0, 50.0]]</code> (optional)
+
<p>Controls the level of output text verbosity. <code>0</code> produces no output, and <code>1</code> produces standard output.<br />
−
 
+
(Default: 1).</p>
−
Sets the percentage of the diagonal of the box that will be used to define the maximum edge of an element. Minimum edge is used by the sizing function to approve the refinement of an element.<br />
+
<h2 id="convert-image">Convert Image</h2>
−
(Default: ''10 %'').
+
<p><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. </p>
−
 
+
<pre><code>docker run -v $(pwd):/data/ crtc_i2m convert_image input_image.nrrd output_image.vtk</code></pre>
−
=== Post-processing Parameters ===
+
<h2 id="partons-to-nrrd">Partons To NRRD</h2>
−
 
+
<p><code>partonsToNRRD</code> serves as a utility to create images out of partons data. </p>
−
<code>-l, --linear-interpolation</code> (optional)
+
<pre><code>docker run -v $(pwd):/data/ crtc_i2m partonsToNRRD partonsFile.dat columnId xBins yBins zBins</code></pre>
−
 
+
<h1 id="appendix">Appendix</h1>
−
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.
+
<h2 id="how-mesh-size-relates-to-delta">How mesh size relates to delta</h2>
−
 
+
<p>Input Image: NT_140519.nrrd</p>
−
=== Statistics Parameters ===
+
<ul>
−
 
+
<li>The size of the input image is: (100x100x100)</li>
−
<code>--thread-statistics</code> (optional)
+
<li>Spacing of the input image: (1x1x1)</li>
−
 
+
<li>MinimumPhysicalSize = 100 * 1 = 100</li>
−
Computes and prints thread statistics.
+
<li>Maximum suggested delta value is: 100 / 5 = 20</li>
−
 
+
</ul>
−
<code>--mesh-statistics</code> (optional)
+
<table>
−
 
+
<thead>
−
Computes and prints mesh statistics.
+
<tr class="header">
−
 
+
<th style="text-align: center;">Delta</th>
−
<code>--all-statistics</code> (optional)
+
<th style="text-align: center;"># Vertices</th>
−
 
+
<th style="text-align: center;"># Tetrahedra</th>
−
Computes and prints all statistics (thread and mesh).
+
</tr>
−
 
+
</thead>
−
=== Special Parameters ===
+
<tbody>
−
 
+
<tr class="odd">
−
<code>--cnf-uniform</code> (optional)
+
<td style="text-align: center;">20</td>
−
 
+
<td style="text-align: center;">147</td>
−
Activates the flags <code>--image-segmentation</code>, and <code>--linear-interpolation</code> which are required for producing uniform size meshes for CNF data. Size of elements is controlled by <code>--delta</code>.
+
<td style="text-align: center;">430</td>
−
 
+
</tr>
−
<code>--cnf-adaptive</code> (optional)
+
<tr class="even">
−
 
+
<td style="text-align: center;">10</td>
−
Activates the flags <code>--image-segmentation</code>, <code>--volume-grading</code>, <code>--sizing-function</code>, and <code>--linear-interpolation</code> which are required for producing adaptive meshes for CNF data. The level of adaptivity is controlled by <code>--weight-limit</code>, <code>--min-edge</code>, <code>--max-edge</code>.
+
<td style="text-align: center;">563</td>
−
 
+
<td style="text-align: center;">1,780</td>
−
=== Miscellaneous Parameters ===
+
</tr>
−
 
+
<tr class="odd">
−
<code>-v, --verbosity-level {0, 1, 2}</code> (optional)
+
<td style="text-align: center;">5</td>
−
 
+
<td style="text-align: center;">2,686</td>
−
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 />
+
<td style="text-align: center;">10,210</td>
−
(Default: 1).
+
</tr>
−
 
+
<tr class="even">
−
<code>--version</code> (optional)
+
<td style="text-align: center;">2.5</td>
−
 
+
<td style="text-align: center;">13,366</td>
−
Show PODM3D version and exit.
+
<td style="text-align: center;">56,274</td>
−
 
+
</tr>
−
== Tessellate2D (Triangle) ==
+
<tr class="odd">
−
 
+
<td style="text-align: center;">1.25</td>
−
Tessellate2D is a modified version of the [https://www.cs.cmu.edu/~quake/triangle.html ''Triangle''] software for 2D tessellation.
+
<td style="text-align: center;">79,086</td>
−
 
+
<td style="text-align: center;">401,610</td>
−
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].
+
</tr>
−
 
+
<tr class="even">
−
Note: For the description of the employed sizing function please see the software documentation section of [[#mesh-sizing-parameters|Tessellate3D]].
+
<td style="text-align: center;">0.625</td>
−
 
+
<td style="text-align: center;">520,538</td>
−
Below is the detailed information about the parameters of <code>tessellate2d</code>:
+
<td style="text-align: center;">2,922,427</td>
−
 
+
</tr>
−
<code>-i, --input [filename]</code> (required)
+
</tbody>
−
 
+
</table>
−
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].
+
</body>
−
 
+
</html>
−
<code>-o, --output [filename]</code> (optional)
 
−
 
 
−
The filename of the output mesh saved in VTK format.<br />
 
−
(Default: <code>outputMesh.vtk</code>).  
 
−
 
 
−
<code>-r, --file-format {0,1}</code> (optional)
 
−
 
 
−
Sets file format of outputFiles. <code>0</code> for ASCII, and <code>1</code> for BINARY.<br />
 
−
(Default: ASCII).
 
−
 
 
−
<code>-w,--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>-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 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''.
 
−
 
 
−
''minimum-physical-size'' of input image = min(spacing * size).<br />
 
−
(Default: ''1 / 100'' * ''minimum-physical-size'')
 
−
 
 
−
<code>-u,--uniform</code> (optional)
 
−
 
 
−
Creates a uniform mesh instead of an adaptive one. Uses <code>--min-edge</code> value as a constant size constraint.
 
−
 
 
−
<code>-v,--verbose-level [0,1]</code> (optional)
 
−
 
 
−
Controls the level of output text verbosity. <code>0</code> produces no output, and <code>1</code> produces standard output.<br />
 
−
(Default: 1).
 
−
 
 
−
== Convert Image ==
 
−
 
 
−
<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.  
 
−
 
 
−
<pre>docker run -v $(pwd):/data/ crtc_i2m convert_image input_image.nrrd output_image.vtk</pre>
 
−
== Partons To NRRD ==
 
−
 
 
−
<code>partonsToNRRD</code> serves as a utility to create images out of partons data.  
 
−
 
 
−
<pre>docker run -v $(pwd):/data/ crtc_i2m partonsToNRRD partonsFile.dat columnId xBins yBins zBins</pre>
 
−
 
 
−
= Appendix =
 
−
 
 
−
== How mesh size relates to delta ==
 
−
 
 
−
Input Image: NT_140519.nrrd
 
−
 
 
−
* The size of the input image is: (100x100x100)
 
−
* Spacing of the input image: (1x1x1)
 
−
* MinimumPhysicalSize = 100 * 1 = 100
 
−
* Maximum suggested delta value is: 100 / 5 = 20
 
−
 
 
−
{|
 
−
!align="center"| Delta
 
−
!align="center"| # Vertices
 
−
!align="center"| # Tetrahedra
 
−
|-
 
−
|align="center"| 20
 
−
|align="center"| 147
 
−
|align="center"| 430
 
−
|-
 
−
|align="center"| 10
 
−
|align="center"| 563
 
−
|align="center"| 1,780
 
−
|-
 
−
|align="center"| 5
 
−
|align="center"| 2,686
 
−
|align="center"| 10,210
 
−
|-
 
−
|align="center"| 2.5
 
−
|align="center"| 13,366
 
−
|align="center"| 56,274
 
−
|-
 
−
|align="center"| 1.25
 
−
|align="center"| 79,086
 
−
|align="center"| 401,610
 
−
|-
 
−
|align="center"| 0.625
 
−
|align="center"| 520,538
 
−
|align="center"| 2,922,427
 
−
|}
 

Revision as of 21:06, 23 July 2020

<!DOCTYPE html> CRTC Image-To-Mesh Conversion Software Documentation

CRTC Image-To-Mesh Conversion Software Documentation

CRTC Lab, Old Dominion University

03/20/2020

Introduction

This document 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)
  4. PartonsToNRRD (creation of image out of Partons data 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 from multi-tissue segmented images.

Examples

Input image and clipped generated meshes

  • Input (left figure): Dimensions (255x255x229) with spacing (0.976562x0.976562x1.40002)
  • Uniform with Delta = default (middle figure): 205,510 tetrahedra
  • Uniform with Delta = 1.5 (right figure): 767,393 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 -output ./Head-Neck,d=1.5.vtk

More Detailed 3D examples of Medical Image Computing can be found here.

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 of 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. For more information regarding the file formats supported by the ITK library, see here.

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

The filename of the output mesh saved in VTK format. (Default: input filename + parameters.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.

--include-labels [unsigned char list] (optional)

Labels that will be included in the mesh. If not specified, all labels will be included in the mesh. Cannot be used together with --exclude-labels.

--exclude-labels [unsigned char list] (optional)

Labels that will be excluded from the mesh. Keeps all labels in the mesh except the ones specified. If not specified, all labels will be included in the mesh. Cannot be used together with --include-labels.

Computational Nuclear Femtography

A short presentation can be found here.

Tessellate3D

Examples

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): 257,041 tetrahedra

Uniform (middle figure):

docker run -v $(pwd):/data/ crtc_i2m tessellate3d --input ./CNF_Data/3D/CFF_14052019/NT_140519.nrrd --cnf-uniform

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

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

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 of 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. For more information regarding the file formats supported by the ITK library, see here.

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

The filename of the output mesh saved in VTK format.
(Default: input filename + parameters.vtk).

-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.

minimum-physical-size of input image = min(spacing * size).
(Default (if --cnf-uniform is specified): 1 / 100 * minimum-physical-size).
(Default (if --cnf-adaptive is specified): 1 / 20 * minimum-physical-size).

--cnf-uniform (optional)

Produces uniform size meshes for CNF data. Size of elements is controlled by --delta.

--cnf-adaptive (optional)

Produces adaptive meshes for CNF data. The level of adaptivity is controlled by --weight-limit and --min-edge (see below). For more details about how sizing works see the note at the end of the section.

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

Sets the element weight limit of the generated elements that will be used by the sizing function. Weight limit is used by the sizing function to control the gradation of the mesh based on the weights of the image.
(Default: 0.1).

-m, --min-edge [unsigned real [0.000001, 7.5]] (optional)

Sets the percentage of the diagonal of the box that will be used to define the minimum edge of an element. Minimum edge is used by the sizing function to reject the refinement of an element. (Default: 1/ $\sqrt{3}$ %).

-M, --max-edge [unsigned real [10.0, 50.0]] (optional)

Sets the percentage of the diagonal of the box that will be used to define the maximum edge of an element. Minimum edge is used by the sizing function to approve the refinement of an element. (Default: 10 %).

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

Sets the voxel value that will be treated as a background value during the 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).

Note: 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 image-weight-range along with the diagonal of the image are computed, The diagonal is used to define the minimum-element-edge-length and maximum-element-edge-length multiplied by the the user-defined min-edge and max-edge diagonal percentages. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the user constrains. Each time SF is called upon an element, it will check if it meets the size constrains minimum-element-edge-length and maximum-element-edge-size. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and midpoints of vertices and barycenter. 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 element-weight-range = abs(max(V) - min(V)) is evaluated. If element-weight-range/image-weight-range exceeds the user constraint weight-limit, the element is split.

Tessellate2D

Examples

Input image and generated meshes

  • 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 --min-edge=2 --uniform

Adaptive (right figure):

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

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

Parameters

Note: For the description of the employed sizing function please see the software documentation section of 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. For more information regarding the file formats supported by the ITK library, see here.

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

The filename of the output mesh saved in VTK format.
(Default: outputMesh.vtk).

-w,--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)

-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 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.

minimum-physical-size of input image = min(spacing * size).
(Default: 1 / 100 * minimum-physical-size)

-u,--uniform (optional)

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

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, convert_image or partonsToNRRD.

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:

I/O 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 saved in VTK format.
(Default: input filename + parameters.vtk).

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

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

-r, --file-format {0,1} (optional)

Sets file format of outputFiles. 0 for ASCII, and 1 for BINARY.
(Default: BINARY).

Performance 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).

--memory-limit [unsinged integer in MB] (optional)

Constrains the amount of memory in MB that will be used.
(Default: 80% 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. For uniform meshes (i.e. no --volume-grading), the total number of elements is related to delta through an inverse cubic law (approximately):

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. If using d_1 creates N_1 elements then d_1/2 will create (approximately) 8 = 2^3 times more elements while 2 * d_1 will generate 1/8N_1 elements. A table which shows the relation between delta and mesh size can be found in the Appendix. 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 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 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).

--include-labels [unsigned char list] (optional)

Labels that will be included in the mesh. If not specified, all labels will be included in the mesh. Cannot be used together with --exclude-labels.

--exclude-labels [unsigned char list] (optional)

Labels that will be excluded from the mesh. Keeps all labels in the mesh except the ones specified. If not specified, all labels will be included in the mesh. Cannot be used together with --include-labels.

Mesh Sizing 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 image-weight-range along with the diagonal of the image are computed, The diagonal is used to define the minimum-element-edge-length and maximum-element-edge-length multiplied by the the user-defined min-edge and max-edge diagonal percentages. The refinement algorithm queries the sizing function (SF) to verify whether each element satisfies the user constrains. Each time SF is called upon an element, it will check if it meets the size constrains minimum-element-edge-length and maximum-element-edge-size. Consequently, it will create a set SP of sampling points out of the element. This set consists of the element’s vertices, barycenter, and midpoints of vertices and barycenter. 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 element-weight-range = abs(max(V) - min(V)) is evaluated. If element-weight-range/image-weight-range exceeds the user constraint weight-limit, the element is split.

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

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

Sets the element weight limit of the generated elements that will be used by the sizing function. Weight limit is used by the sizing function to control the gradation of the mesh based on the weights of the image.
(Default: 0.1).

-m, --min-edge [unsigned real [0.000001, 7.5]] (optional)

Sets the percentage of the diagonal of the box that will be used to define the minimum edge of an element. Minimum edge is used by the sizing function to reject the refinement of an element.
(Default: 1/ $\sqrt{3}$ %).

-M, --max-edge [unsigned real [10.0, 50.0]] (optional)

Sets the percentage of the diagonal of the box that will be used to define the maximum edge of an element. Minimum edge is used by the sizing function to approve the refinement of an element.
(Default: 10 %).

Post-processing 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.

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).

Special Parameters

--cnf-uniform (optional)

Activates the flags --image-segmentation, and --linear-interpolation which are required for producing uniform size meshes for CNF data. Size of elements is controlled by --delta.

--cnf-adaptive (optional)

Activates the flags --image-segmentation, --volume-grading, --sizing-function, and --linear-interpolation which are required for producing adaptive meshes for CNF data. The level of adaptivity is controlled by --weight-limit, --min-edge, --max-edge.

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).

--version (optional)

Show PODM3D version and exit.

Tessellate2D (Triangle)

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.

Note: For the description of the employed sizing function please see the software documentation section of Tessellate3D.

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 saved in VTK format.
(Default: outputMesh.vtk).

-r, --file-format {0,1} (optional)

Sets file format of outputFiles. 0 for ASCII, and 1 for BINARY.
(Default: ASCII).

-w,--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)

-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 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.

minimum-physical-size of input image = min(spacing * size).
(Default: 1 / 100 * minimum-physical-size)

-u,--uniform (optional)

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

-v,--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

Partons To NRRD

partonsToNRRD serves as a utility to create images out of partons data. 

docker run -v $(pwd):/data/ crtc_i2m partonsToNRRD partonsFile.dat columnId xBins yBins zBins

Appendix

How mesh size relates to delta

Input Image: NT_140519.nrrd

  • The size of the input image is: (100x100x100)
  • Spacing of the input image: (1x1x1)
  • MinimumPhysicalSize = 100 * 1 = 100
  • Maximum suggested delta value is: 100 / 5 = 20
Delta # Vertices # Tetrahedra
20 147 430
10 563 1,780
5 2,686 10,210
2.5 13,366 56,274
1.25 79,086 401,610
0.625 520,538 2,922,427

Retrieved from "https://crtc.cs.odu.edu/index.php?title=CRTC_I2M&oldid=7115"