====================================
``grail.data.pcfgenerator`` Module
====================================

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

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

--------
Overview
--------

This module provides the ability to create and initialize a Project Control File (3D Block Model only).

Project initialization consists of building a master file of parameters (the Project Control 
File or PCF) and the Project History File that audits the computer runs. All programs within
MineSightŪ access the PCF for parameters and control data. All programs also write summary 
information to the History File.

--------
Examples
--------

The following snippet illustrates how to create a regular 3DBM PCF:

.. Python::

	#create and set a new instance of the pcfparameters structure
        params = pcfgenerator.pcfparameters()
        params.pcfPath = "C:/TEST10.dat"
        params.systemName = "TEST"
        params.units = 3
        params.xmin = 0.0
        params.xmax = 1000.0
        params.ymin = 0.0
        params.ymax = 1000.0
        params.zmin = 0.0
        params.zmax = 1000.0
        params.dx = 10.0
        params.dy = 10.0
        params.dz = 10.0

	pcfgenerator.createPCF(params)


The following snippet illustrates how to create a 3DBM PCF with variable bench heights:

.. Python::

	#create and set a new instance of the pcfparameters structure
        params = pcfgenerator.pcfparameters()
        params.pcfPath = "C:/TEST10.dat"
        params.systemName = "TEST"
        params.units = 3
        params.xmin = 0.0
        params.xmax = 1000.0
        params.ymin = 0.0
        params.ymax = 1000.0
        params.zmin = 0.0
        params.zmax = 1000.0
        params.dx = 10.0
        params.dy = 10.0
        params.dz = -1		#indicates variable bench heights

	#create list of toe elevations
        topList=range(1000,500,-5)      #top benches are 5m
        bottomList=range(500,-10,-10)   #bottom benches are 10m
        params.elevList = topList + bottomList

	pcfgenerator.createPCF(params)


--------
Classes
--------

class :dc:`pcfparameters()`

   This object provides a convenient structure for storing the parameters used by the createPCF function. Constructor takes no arguments.

   **Members**

      :a:`pcfPath` : string
	The full path to the new PCF file which will be created. File names can contain up to 10 characters in the general form of `'XXXX10.EXT'` 

      :a:`systemName` : string
	Standard system names are METL, COAL or URAN but you may specify any four-character name.
        
      :a:`units` : integer
        Units must be either 1 (Imperial), 2 (Pseudo-metric), or 3 (Metric).

      :a:`ProjDescription` : string
	An optional project description string (enter empty string if a description is not needed).

      :a:`xmin` : float
	Minimum X (easting) of the model.

      :a:`xmax` : float
	Maximum X (easting) of the model.

      :a:`ymin` : float
	Minimum Y (northing) of the model.

      :a:`ymax` : float
	Maximum Y (northing) of the model.

      :a:`zmin` : float
	Minimum Z (elevation) of the model.

      :a:`zmax` : float
	Maximum Z (elevation) of the model.

      :a:`dx` : float
	Width of mine model block along X (easting) axis. `NOTE: dx must evenly divide xmax-xmin (E-W PCF distance).`

      :a:`dy` : float
	Width of mine model block along Y (northing) axis. `NOTE: dy must evenly divide ymax-ymin (N-S PCF distance).`

      :a:`dz` : float
	Vertical bench height. `NOTE: dz must evenly divide zmax-zmin.` (use -1 for variable bench heights)

      :a:`elevList` : list of floats
        A list of toe elevations.  List must begin with zmax (crest of top bench) and end with zmin. `Default is empty list [ ].`

      :a:`rotOrigin` : Point
        Rotation Origin.  It's helpful to think of this as the point to which the lower-left corner of the model is translated 
        after it has been created and rotated around the true origin `(0.0, 0.0, 0.0)`. 
      
      :a:`azim` : float
        Azimuth of model rotation. `Default value of 0.0.`
      
      :a:`dip` : float
        Dip of model rotation. `Default value of 0.0.`
      
      :a:`plunge` : float
        Plunge of model rotation.  `Default value of 0.0.`
      
      :a:`reflectZ` : integer
        For vertically dipping models, this specifies which way to increase the Z-value.  Value must be either 0 (towards the origin), 
        or 1 (mirror the Z value away from the origin).  `Default value of 0.`

      :a:`addfile11` : integer
	Set value to 1 to add a default/empty file 11 to the PCF. Set value to 0 for no additional auxillary files. `Default value of 1.`



---------
Functions
---------

:df:`createPCF(params)`

   Creates a new Project Control File (M100TS) and initializes the project coordinate parameters (M101V1).  This function
   also creates a Project History File in the same directory.  Note that both the PCF and associated history file must NOT 
   previously exist in the specified directory (otherwise an IOError exception will be raised).

   Arguments:

      :a:`params` : a pcfparameters object