Difference between revisions of "CRTC I2M"

Revision as of 20:58, 29 August 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 :

• Microsoft Windows
• MacOS
• Linux
  • Ubuntu
  • Debian
  • CentOS
  • 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 tessellation tool (PODM) to 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.

--volume-grading (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.

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

--segment-image [0,1] (optional)

Enable automatic image segmentation. Defaults to 1 (true). When dealing with non-segmented data this option is required.

--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. (default: 0 ).

--linear-interpolation [0,1] (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.

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

For the graded case (down right)