Difference between revisions of "CRTC I2M"
(→Tessellate2D) |
|||
Line 147: | Line 147: | ||
=== Tessellate2D === | === Tessellate2D === | ||
+ | **add also image and numbers** | ||
+ | |||
“[[File:NT_2D.png|900px]]” | “[[File:NT_2D.png|900px]]” | ||
Line 156: | Line 158: | ||
<pre>docker run -v $(pwd):/data/ cnf_tools tessellate2d --input ./CNF_SHARE/2d_wiki_examples/input/NT_140519_50_X.vtk --output NT_140519_X50_me_2_wl_1e-1.vtk --min-edge=2 --weight-limit=0.1</pre> | <pre>docker run -v $(pwd):/data/ cnf_tools tessellate2d --input ./CNF_SHARE/2d_wiki_examples/input/NT_140519_50_X.vtk --output NT_140519_X50_me_2_wl_1e-1.vtk --min-edge=2 --weight-limit=0.1</pre> | ||
+ | |||
=== Tessellate3D === | === Tessellate3D === | ||
Revision as of 16:38, 25 November 2019
Contents
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 in order to allow the tessellation tool (PODM) to to use more threads.
Getting the software
The docker image is located here (restricted access).
Docker Container Instructions
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, prependingsudo
to the above command is necessary.Running
On MacOS/Linux
docker run -v $(pwd):/data/ cnf_tools <application> [arguments]
On Windows with Powershell (recommended)
docker run -v ${PWD}:/data/ cnf_tools <application> [arguments]
Notice that in this case brackets {} are used instead of parenthesis ()
On Windows with command line (cmd)
docker run -v %cd%:/data/ cnf_tools <application> [arguments]
Where <application>
is one of the currently available tools : tessellate2d
,tessellate3d
or convert_image
.
Tessellation Parameters
A quick way to view all available parameters and brief descriptions for them is to pass the --help
flag to tessellate2d
/tessellate3d
.
Below are more detailed descriptions of the tessellate2d
/tessellate3d
parameters:
The common parameters for both versions are :
--input [filename]
(required)
Input CNF data. Could be ascii/binary NRRD file, an image saved in .vtk format or any other format supported by the ITK library. For more on ITK-supported file formats see here.
--output [filename]
(optional)
The filename of the output mesh. (Default: outputMesh.vtk
).
--weight-limit [real]
(optional)
Set a weight limit for the generated elements that will be used from the sizing function This parameter limits the difference among the weights within one element. It is designed to give some control on the discretization error with respect to the input data.
(Default: 0.1)
--min-edge [real]
(optional)
Set the minimum edge size of generated elements that will be used for the sizing function (default: 1). It is designed to be used together with weight-limit
controlling the size of the generated mesh. (Default: 1)
Tessellate3D Specific Parameters
--delta [real]
(optional)
Controls the size of the elements nearby the boundary. Smaller values will lead to finer detail close to the boundary (and often to a more accurate boundary representation) but will also lead to a greater mesh size. The default value is based on the input size and spacing of the input image.
--threads [int]
(optional)
How many threads to use. (Default: 1)
--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 exists in the dataset. In practice, a background value is a value that is ignored from the tessellation procedure. Regions of the tessellation corresponding to the background value will have no elements. (Default: +inf)
--all-statistics
(optional)
Output all statistics (thread and mesh).
--thread-statistics
(optional)
Output thread statistics.
--mesh-statistics
(optional)
Output mesh statistics.
Tessellate2D Specific Parameters
--uniform
(optional)
Create a uniform mesh instead of an adaptive one. --min-edge
value will be used as a constant size constraint
--verbose-level [0,1]
(optional)
Control the level of verbosity. 0 produces no text output while 1 produces the standard amount of information (Default: 1).
convert_image
parameters
convert_image
serves as a utility to convert input data between different kinds of image formats. For example the .nrrd
images acquired from Jefferson lab cannot be used with Paraview in order to create contour-plots (unknown why). However, converting them using
docker run -v $(pwd):/data/ cnf_tools convert_image input_image.nrrd output_image.vtk
enables all relevant image filters in Paraview.
Example Dataset
Tessellate2D
- add also image and numbers**
Uniform (left figure):
docker run -v $(pwd):/data/ cnf_tools tessellate2d --input ./CNF_SHARE/2d_wiki_examples/input/NT_140519_50_X.vtk --output NT_140519_X50_me_2_uniform.vtk --min-edge=2 --uniform
Adaptive (right figure):
docker run -v $(pwd):/data/ cnf_tools tessellate2d --input ./CNF_SHARE/2d_wiki_examples/input/NT_140519_50_X.vtk --output NT_140519_X50_me_2_wl_1e-1.vtk --min-edge=2 --weight-limit=0.1
Tessellate3D
Uniform (left figure):
docker run -v $(pwd):/data/ cnf_tools tessellate3d --input ./CNF_SHARE/CFF_14052019/NT_140519.nrrd --uniform --delta 1 --output ./NT_uniform.vtk
Adaptive (right figure):
docker run -v $(pwd):/data/ cnf_tools tessellate3d --input ./CNF_SHARE/CFF_14052019/NT_140519.nrrd --weight-limit 0.07 --output ./NT_adapted.vtk
More examples can be found here .