The 3-D CPT Driver

Introduction

The file stlib/examples/cpt/cpt3.cc shows how to call the CPT functions using each of the four interfaces. Below are the command line arguments.

  ./cpt3.exe [-unsigned] [-ascii] [-binary] [-noClipping] [-gradient]
    [-point] [-face] [-flood] [-sign] [-bbox] [-brute] geom brep [out]
  -unsigned: Compute unsigned distance.  (The default is signed distance.)
  -ascii: Write the output files in plain ascii format.
  -binary: Write the output files in binary format.
  -noClipping: Do not use the Cartesian domain to clip the b-rep.
  -gradient: Compute the gradient of the distance transform.
  -point: Compute the closest point transform.
  -face: Compute the closest face transform.
  -flood: Flood fill the distance transform.
  -sign: If all of the grid points are far away, find the correct sign of
     the distance.
  -bbox: Use the bounding box method.
  -brute: Use the brute force method.
  geom contains the domain and size of the grid.
  brep contains the b-rep, an indexed triangle face set.
  out specifies the base name for the output files.  The default output format
  is VTK XML.

This driver reads grid information and a triangle mesh from files, computes the closest point transform to that triangle mesh on the grid, and then writes the transforms to files. The driver checks the grids to ensure that the CPT was computed correctly. It will print warnings if there are errors. If you suspect that the CPT library is not computing the correct result for some mesh, you can use the driver to help dignose the problem. There are example mesh files in stlib/data/cpt/3.

Compiling.

Use gnu "make" on "Makefile". Edit "Makefile" to suit your preferences. This driver can be compiled into three executables which use the three interfaces to the cpt library. "cpt3" uses the standard interface. "cpt3_c" and "cpt3_f" use the C and fortran interfaces, respectively. By default, only "cpt3" is made. Use "make all" to make all the executables.

Input File Format

The geometry file contains information about the computational domain, the lattice, the grids, and options for the CPT.

  maximumDistance
  xmin   ymin   zmin   xmax   ymax   zmax
  lattice_extent_x   lattice_extent_y   lattice_extent_z
  num_grids
  grid_0_lb_x grid_0_lb_y grid_0_lb_z grid_0_ub_x grid_0_ub_y grid_0_ub_z 
  grid_1_lb_x grid_1_lb_y grid_1_lb_z grid_1_ub_x grid_1_ub_y grid_1_ub_z 
  ...

Description of fields:

The signed distance and closest point will be correctly computed up to maximumDistance from the surface. This number must be positive.
xmin, etc. describe the Cartesian domain spanned by the lattice.
lattice_extent_* are the number of grid points in each direction of the lattice.
num_grids is the number of grids.
grid_n_lb_* and grid_n_ub_* describe the lower and upper index bounds of the $\mathrm{n}^{\mathrm{th}}$ grid. The lower bounds are closed and the upper bounds are open.

The distance for any points farther away than maximumDistance is set to std::numeric_limits<number_type>::max(). If the -l option is given, the far away distances are set to $\pm$ maximumDistance. Each component of the gradient of the distance and closest point for far away grid points are set to std::numeric_limits<number_type>::max(). The closest face for far away grid points is set to -1.

The b-rep file contains a triangle mesh. (Specifically, an indexed triangle face set.) The first two fields specify the space dimension and the simplex dimension. These must be 3 and 2, respectively. num_vertices gives the number of vertices This is followed by the coordinates of the vertices. num_faces specifies the number of triangle faces in the mesh. Next the faces are enumerated. A face is specified by the indices of three vertices. (These indices are in the range [0..num_vertices-1].)

  space_dimension simplex_dimension
  num_vertices
  vertex_0_x    vertex_0_y	vertex_0_z
  vertex_1_x    vertex_1_y	vertex_1_z
  ...
  num_faces
  face_0_index_0	face_0_index_1		face_0_index_2
  face_1_index_0	face_1_index_1		face_1_index_2
  ...

Output File Formats

By default the output is written to a VTK XML file. You can visualize the distance and other fields using ParaView.

You can select a simple text output with the -ascii option. For the scalar fields of distance and closest face, the three grid extents are written first, followed by the grid elements. The last index varies slowest.

Distance:

  x_size y_size z_size
  distance(0,0,0)
  distance(1,0,0)
  distance(2,0,0)
  ...
  distance(l,m,n)

For the vector fields of gradient of distance and closest point, the three grid extents are written first, followed by the grid elements. The last index varies slowest.

Closest Point:

  x_size y_size z_size
  closest_point_x(0,0,0) closest_point_y(0,0,0) closest_point_z(0,0,0)
  closest_point_x(1,0,0) closest_point_y(1,0,0) closest_point_z(1,0,0)
  closest_point_x(2,0,0) closest_point_y(2,0,0) closest_point_z(2,0,0)
  ...
  closest_point_x(l,m,n) closest_point_y(l,m,n) closest_point_z(l,m,n)

Example

You can execute the following example in the directory stlib/examples/cpt. We copy the geometry and mesh files for a canister and generate a VTK unstructred grid file for the triangle mesh.

  cp ../../data/cpt/3/canister.geom .
  cp ../../data/cpt/3/canister.brep .
  ../geom/mesh/utility/iss2vtk32.exe canister.brep canister.vtu

Below is a visualization of the triangle mesh in ParaView. Open the file canister.vtu. Use the "extract edges" filter to get the triangle edges. Color the edges black and increase the edge thickness to 2 so they stand out from the triangle faces.

The triangle mesh.

The geometry file specifies that we will compute the distance up to 0.045 away from the surface on a single 100 x 100 x 100 grid. We compute the signed distance and flood fill it to aid in the visualization.

  ./cpt3.exe -flood canister.geom canister.brep canister

Open canister.vtr, a VTK rectilinear grid file, in ParaView. Hit the Contour button and set the iso-surface value to 0. Below we see that the zero iso-surface approximates the original triangle mesh.

The zero iso-surface.

Select the canister.vtu item in ParaView and color it by the distance field. You can hit the Clip button to visualize the volume data.