==================================
``grail.engines.cdt`` Module
==================================

.. include:: ..\..\version.h

.. contents:: Table of Contents
   :backlinks: top


-----------
Description
-----------

A standard interface to the CDT (Correcting Delaunay Triangulation) standalone engine executable.

--------------------
Standard Definitions
--------------------

point_list:
   A list of points, defined as: [[x0, y0, z0], ..., [xN, yN, zN]].

coded_point_list:
   A tuple containing two items: the first item is a code (string), the second is the corresponding point_list.  This data type
   is intended to mimic the srv file format.  The code should match with an accompanying parameter file (survey code file).
   For example, ['BENCH', [[x0, y0, z0], ..., [xN, yN, zN]]] 


face_list:
   All face lists are described such that the first index indicates
   how many faces are in the face. For example,
    
      [**3**, 1, 2, **3**, 3, 4, 5, 6]

   States that there are 3 vertexes in the first face, and those
   vertexes are 1, 2, 3. Then the next face contains 3 vertexes, which
   are 4, 5, 6.  This may seem a bit confusing, but using this structure
   buys us some definite efficiencies.  Note that all faces in MineSightŪ products have 3 vertexes.


---------
Functions
---------
    
.. Note::
	Be careful with the filepath strings used in these functions. Since the backslash character is 
	used in Python as an escape character, it is best to use forward slashes (or two backslashes)
	in the filepaths.   

	Most arguments in these functions correspond to an option in the Standalone engine.
	All arguments in these functions have a default value of `'None'`, which makes the arguments optional.
	If left unspecified, the option will **not** be included in the call to the engine executable. Calls to 
	these functions must use **`keyword arguments`** (keywords are the formal parameter names).  See the 
	examples below for more details.


:df:`cdt(pointList, faceList, prm, contourPointLists, dir, width, contour, boundary, grid, debug)`

    Correcting Delaunay Triangulation corrects triangulated contour strings.  The function returns the corrected solid/surface.

    Arguments:

      :a:`pointList` : point_list (see `Standard Definitions`_).
	Points of the triangulated surface.

      :a:`faceList` : face_list (see `Standard Definitions`_).
	Faces of the triangulated surface.

      :a:`prm` : string
	Parameter file path (for contour data).

      :a:`contourPointLists` : a list of coded_point_lists (see `Standard Definitions`_).
	Point lists for contour strings.

      :a:`dir` : string
	Define a directory with input files.

      :a:`width` : integer
	Maximal vertical width of a contour string.

      :a:`contour` : integer
	Correct triangulated contour strings. Set value to 1 to turn on this option.

      :a:`boundary` : integer
	Correct triangulated 2D boundary strings. Set value to 1 to turn on this option.

      :a:`grid` : integer
	Correct triangulated grid. Set value to 1 to turn on this option.

      :a:`debug` : integer
	Debug option will output the command string used to call the engine executable and will relay any output messages from the engine. Set value to 1 to turn on this option.

    Returns:
	A tuple containing:  point_list, face_list (see `Standard Definitions`_).

    Example:
      .. Python:: 
   
	 from grail.engines import cdt

         pts = [[2.0, 0.0, 3895.0],[4.0, 0.0, 3895.0],[4.0, 2.0, 3895.0],[2.0, 2.0, 3895.0],[2.0, 0.0, 3895.0]]
	 fcs = [3, 3, 2, 1, 3, 3, 1, 0]
         
	 #use keyword arguments in function call
  	 points, faces = cdt.cdt(pointList=pts, faceList=fcs, grid=1)