==================================
``grail.engines.voxel`` Module
==================================

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

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

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

A standard interface to the voxel 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:`voxel(pointList, faceList, prt, xmin, ymin, zmin, rot1, rot2, rot3, nx, ny, nz, dx, dy, dz, sb, real, debug)`
    
    Calculates block partials from solids.  This function creates a partials file.

    Arguments:
      :a:`pointList` : point_list  (see `Standard Definitions`_).
	Points of the solid.

      :a:`faceList` : face_list  (see `Standard Definitions`_).
	Faces of the solid.
  
      :a:`prt` : string
         The path to the output partials file

      :a:`xmin/ymin/zmin` : integer
         Coordinates of the minimum corner of the block model. If the block model is rotated, you must supply the rotated minimum coordinates.

      :a:`rot1/rot2/rot3` : integer
         rotation angles (degrees) of the block

      :a:`nx/ny/nz` : integer
         number of blocks in x,y,z

      :a:`dx/dy/dz` : integer
         size of the block

      :a:`sb` : integer
         number of sub-blocks in a block

      :a:`real` : integer
         output partials as floating point values, otherwise integers are used.   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.

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

	 #use keyword arguments in function call
         voxel.voxel(pointList=pts, 
                       faceList=fcs, 
                       prt="C:/out.prt", 
                       xmin=0, ymin=0, zmin=0, 
                       nx=10, ny=10, nz=10, 
                       dx=10, dy=10, dz=10, 
                       sb=1)