Difference between revisions of "CRTC I2M"

From crtc.cs.odu.edu
Jump to: navigation, search
(Example Dataset)
Line 35: Line 35:
 
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 tessellation tool (PODM) to 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 to allow the tessellation tool (PODM) to use more threads.
  
 
== Getting the software ==
 
== Getting the software ==
Line 85: Line 85:
  
 
If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.
 
If given, the surface of the produced mesh will be saved into <code>filename</code> in the VTK format.
 
<code>--volume-grading</code> (optional)
 
 
Created a volume graded mesh. In this case the size of the tetrahedra is small (controlled by delta) close to the boundary while bigger inside.
 
  
 
<code>--memory-limit [int in MB]</code> (optional)
 
<code>--memory-limit [int in MB]</code> (optional)
  
Constrain the amount of memory that will be used (default : 70% of the free memory).
+
Constrain the amount of memory that will be used (default: 70% of the free memory).
  
 
<code>--verbose-level [0,1,2]</code> (optional)
 
<code>--verbose-level [0,1,2]</code> (optional)
Line 98: Line 94:
 
Control the level of verbosity. 0 produces no text output while 2 enables extra information (default 1).
 
Control the level of verbosity. 0 produces no text output while 2 enables extra information (default 1).
  
<code>--segment-image [0,1]</code> (optional)
+
<code>--background-value [real]</code> (optional)
  
Enable automatic image segmentation. Defaults to 1 (true). When dealing with non-segmented data this option is required.
+
Which voxel value to treat as background value. If none is desired, enter a value that does not exist in the dataset. (default: +∞).
  
<code>--background-value [real]</code> (optional)
+
<code>--weight-limit [real]</code> (optional)
  
Which voxel value to treat as background value. If none is desired, enter a value that does not exists in the dataset. (default: 0 ).
+
Set the minimum edge size of the element that will be used from the sizing function (default 1).
  
<code>--linear-interpolation [0,1]</code> (optional)
+
<code>--min-edge [real]</code> (optional)
  
Interpolate the image values on the centroids of the final volume mesh. Defaults to 1 (true). It is strongly recommended not to disable this.
+
Set the weight limit of the element that will be used from the sizing function (default 0.1).
  
 
<code>--all-statistics</code> (optional)
 
<code>--all-statistics</code> (optional)
Line 126: Line 122:
 
Example dataset can be found [https://odu.box.com/s/ce6wc1ht1f96jx7lpafys1ue1piiyekc here] (restricted access)
 
Example dataset can be found [https://odu.box.com/s/ce6wc1ht1f96jx7lpafys1ue1piiyekc here] (restricted access)
  
[[Image:Tesselate example0.png|800px]]
+
[[File:./assets/tesselate_example0.png]]
 
 
  
 
Generated using :
 
Generated using :
Line 134: Line 129:
 
For the uniform case (up right)
 
For the uniform case (up right)
  
<pre>docker run -v $(pwd):/data/ cnf_tools tessellate --input ./CNF_SHARE/DATA_04252019/OBS_ALU.nrrd --delta 1 --output mesh1.vtk --volume_grading</pre>
+
<pre>docker run -v $(pwd):/data/ cnf_tools tessellate --input ./CNF_SHARE/DATA_04252019/OBS_ALU.nrrd --delta 1 --output mesh1.vtk </pre>
 
For the graded case (down right)
 
For the graded case (down right)

Revision as of 14:12, 8 November 2019



This page contains instructions for downloading and using the CNF_tools suite developed at CRTC lab in Old Dominion University in collaboration with Jefferson Lab.

This project corresponds to Proposal No.: CNF19-04 (FEMT-002)

A short presentation can be found here

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 output meshes are in the VTK format and can be visualized using the opensource software Paraview. A short video demo exploring the data can be found here.

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 to allow the tessellation tool (PODM) to use more threads.

Getting the software

The docker image 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 Currently the docker image includes two tools tessellate and convert_image To use the tessellation tool use:

  • On MacOS/Linux

    docker run -v $(pwd):/data/ cnf_tools tessellate [arguments]
  • On Windows with Powershell (recommended)

    docker run -v ${PWD}:/data/ cnf_tools tessellate [arguments]
  • On Windows with command line (cmd)

    docker run -v %cd%:/data/ cnf_tools tessellate [arguments]

To use the convert_image tool replace tessellate with convert_image in the commands above

Tessellation Parameters

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

Below are more detailed descriptions of the tessellate parameters:

--input [filename] (required)

Input file (3D image). Can be in nrrd format.

--delta [real] (required)

Controls the size of the tetrahedrons. Smaller values will lead to finer detail (and often to a more accurate mesh) using more tetrahedrons but will also lead to a greater mesh size.

--threads [int] (optional)

How many threads to use.

--output [filename] (optional)

The filename of the output mesh. Defaults to outputMesh.vtk.

--plc [filename] (optional)

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

--memory-limit [int in MB] (optional)

Constrain the amount of memory that will be used (default: 70% of the free memory).

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

Control the level of verbosity. 0 produces no text output while 2 enables extra information (default 1).

--background-value [real] (optional)

Which voxel value to treat as background value. If none is desired, enter a value that does not exist in the dataset. (default: +∞).

--weight-limit [real] (optional)

Set the minimum edge size of the element that will be used from the sizing function (default 1).

--min-edge [real] (optional)

Set the weight limit of the element that will be used from the sizing function (default 0.1).

--all-statistics (optional)

Output all statistics (thread and mesh).

--thread-statistics (optional)

Output thread statistics.

--mesh-statistics (optional)

Output mesh statistics.

Example Dataset

Example dataset can be found here (restricted access)

[[File:./assets/tesselate_example0.png]]

Generated using :

docker run -v $(pwd):/data/ cnf_tools  tessellate --input ./CNF_SHARE/DATA_04252019/OBS_ALU.nrrd --delta 1 --output mesh0.vtk

For the uniform case (up right)

docker run -v $(pwd):/data/ cnf_tools tessellate --input ./CNF_SHARE/DATA_04252019/OBS_ALU.nrrd --delta 1 --output mesh1.vtk 

For the graded case (down right)