==================================
``grail.engines.dtb`` Module
==================================

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

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


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

A standard interface to the DTB (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:`dtb(pointLists, breaklines, rect, inside, outside, prm, debug)`

    Delaunay Triangulation triangulates survey data.  The function returns the triangulated solid/surface.

    Arguments:
      :a:`pointLists` : a list of coded_point_lists (see `Standard Definitions`_).
	The survey data which will be used to create the triangle mesh.
 
      :a:`breaklines` : integer
	Use breaklines. Set value to either `0` or `1`, where:
             0 = ignore breaklines;
             1 = use breaklines.

      :a:`rect` : integer
	Perform boundary rectification. Set value to 1 to turn on this option.

      :a:`inside` : integer
	Output surface Inside boundary. Set value to 1 to turn on this option.

      :a:`outside` : integer
	Output surface Outside boundary. Set value to 1 to turn on this option.

      :a:`prm` : string
	Parameter file path.  If not specified, a default 'survey code file' will be used.

      :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 dtb

         polygon1 = [[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]]
         codedPoints = ['none', polygon1]     #create a coded point_list
         
	 #function expects a list of coded point_lists
         points, faces = dtb.dtb(pointLists=[codedPoints], breaklines=1, inside=1)	#use keyword arguments in function call