========================= ``grail.data.pcf`` module ========================= .. include:: ../../version.h .. contents:: Table of Contents :backlinks: top -------- Overview -------- This module provides read only access to the Project Control File Data (PCF) data. This includes the project units, extent, location, block sizes, levels, rotation parameters, and seam names. File information is also available from the PCF including file names, types, items and corresponding item parameters. In addition, this module provides some helper functions that make working with rotation coordinates a bit easier (see `Working with Rotation Information`_). .. Note:: Currently there is no access to Dipper file parameters. Common Terms ------------ Some common terms and acronyms used throughout. ============= ======================================== Term Description ============= ======================================== 3DBM 3-D Block Model. GSM Gridded Seam Model. PCF Project Control File. Model Space The 3-D space that a Model is defined within (for use with Rotations). Project Space The 3-D space that the Project is defined within (for use with Rotations). ============= ======================================== --------------------------------- Working with Rotation Information --------------------------------- Working with rotational matrices is sometimes a difficult and arduous task. It is much easier to take the :c:`Pcf` object and use some helper functions to help you transfer points and vectors to and from Model Space to Project Space and back again. The functions that are useful for performing the appropriate conversions are defined in Functions_, and are as below, - For converting from Model Space to Project Space, * :f:`frommodelcoord()` * :f:`frommodelcoordlist()` * :f:`frommodelvector()` * :f:`frommodelvectorlist()` - For converting from Project Space to Model Space, * :f:`tomodelcoord()` * :f:`tomodelcoordlist()` * :f:`tomodelvector()` * :f:`tomodelvectorlist()` As an example, consider that you have the point, p, defined as x, y, and z in Project Space. You can determine p' in Model Space by using the :c:`Pcf` object. In code, this would look something like, .. Python:: from grail.data import pcf pcfobj = pcf.Pcf("rot10.dat") mpoint = [10., 20., 30.] ppoint = pcf.frommodelcoord(pcfobj, mpoint) In the above example, the value of :a:`ppoint` will be defined as the the Project Space's equivalent to the :a:`mpoint`. -------------------------------- Project Control File (PCF) Class -------------------------------- class :dc:`Pcf(path)` This class provides read-only access to the internal structure of the Project Control File (PCF). You can create a :c:`Pcf` object by passing in the name of the PCF that you wish to read. For example, .. Python:: from grail.data import pcf p = pcf.Pcf("samp10.dat") :df:`benchcrest(elevation, epsilon)` Given an elevation, this function returns the crest elevation as a float. If the requested elevation falls outside of the valid range of PCF values, then we clamp the requested elevation to the minimum or maximum values for a bench. Arguments: :a:`elevation` : float The given elevation. :a:`epsilon` : float If the elevation is within epsilon of a bench toe, the corresponding bench crest will be returned. :df:`compositeitem()` Returns the controlling z-item (string). :df:`compositetype()` Returns the composite type (string). :df:`dx()` Returns the block width in the x-direction (float). :df:`dy()` Returns the block width in the y-direction (float). :df:`dz()` Returns the block width in the z-direction (float). :df:`filelist()` Returns the files in the PCF (list of strings). :df:`filelistbytype(type)` Returns the files of a particular type (list of strings) Arguments: :a:`type` : integer The file type (for example, 11 or 15). :df:`free()` Currently this will do nothing, it only remains for backwards compability. The current recommeded practice is to delete your object with the python "del" command, as in, .. python:: pcf = pcf.Pcf("msop10.dat") # do stuff... del pcf The "del" command will delete any internal memory. :df:`is3dbm()` Returns true is this project is a 3DBM. :df:`isgsm()` Returns true is this project is a GSM. :df:`isimperial()` Returns true is this project is in imperial units. :df:`isitemalpha(file, item)` Returns true if the specified file item is alpha. Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. :df:`isitemfloat(file, item)` Returns true if the specified file item is a float. Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. :df:`isitemfullword(file, item)` Returns true if the value for the specified file item is not packed. For example, it occupies a full word in the file. Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. :df:`isitemint(file, item)` Returns true if the file item has integer precision. Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. .. Note:: All file item values are either floats or alphas. This function merely determines if the item is a float value with integer precision. The item value is stored and retrieved as a float. :df:`isitempct(file, item)` Returns true if the specified file item could be a percentage item. An item could be a percentage item if it's a float item with min=0 and max=1 or 100. Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. :df:`isitemsixbit(file, item)` Returns true if: 1. The specified file is a composite file (file 9), *and* 2. The item is full-word and has integer precision Such items *could* be used as special sixbit items for specifying drillhole names (see grail.data.dh_). .. _grail.data.dh: ../grail.data/lib-grail-data-dh.html It's important to note that there is no programmatic way to distinguish between a sixbit item and a legitimate full-word float item with integer precision. The user will have to know if a potential sixbit item does indeed have sixbit character values. Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. :df:`ismetric()` Returns true is this project is in metric units. :df:`isplotimperial()` Returns true is plotter units are in imperial. :df:`isplotmetric()` Returns true is plotter units are in metric units. :df:`isrotated()` Returns true if the project is rotated. :df:`itemflag()` *Unused*. :df:`itemlist(file)` Returns a list of strings containing a file's items. Arguments: :a:`file` : string Name of the file containing the item. :df:`itemmax(file, item)` Returns the maximum value (float) of the item as specified when the item was initialized (see :f:`itemrealmax`). For full word or alpha items, the max value is :d:`pcf.PCFITEM_MAX`. Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. :df:`itemmin(file, item)` Returns the minimum value of the item (float). For full word or alpha items, the min value is :d:`pcf.PCFITEM_MIN`. Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. :df:`itemprecision(file, item)` Returns the item precision (float). Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. :df:`itemrealmax(file, item)` Returns the maximum storable value for the item (float). For full word or alpha items, the max storable value is :d:`pcf.PCFITEM_MAX`. Because of the item packing scheme, it's possible the maximum storable value is slightly larger than the maximum initialized value Arguments: :a:`file` : string Name of the file containing the item. :a:`item` : string Item name of the item. :df:`levelcount()` Returns the number of levels (int) in the project. :df:`levellist()` Returns a list of floats containing either the project's toe elevations for a 3DBM or seam numbers for a GSM :df:`nx()` Returns the number of blocks (int) in the x-direction. :df:`ny()` Returns the number of blocks (int) in the y-direction. :df:`nz()` Returns the number of blocks (int) in the z-direction. :df:`path()` Returns the path of the PCF file (string). :df:`pctitemlist(file)` Returns a list of strings containing a file's percent items. Arguments: :a:`file` : string Name of the file containing the item. :df:`projid()` Returns the Project ID (string). :df:`projxmax()` Returns max project extent in the x-direction. :df:`projxmin()` Returns min project extent in the x-direction. :df:`projymax()` Returns max project extent in the y-direction. :df:`projymin()` Returns min project extent in the y-direction. :df:`projzmax()` Returns max project extent in the z-direction. :df:`projzmin()` Returns min project extent in the z-direction. :df:`rotationazimuth()` Returns project rotation azimuth (float). :df:`rotationdip()` Returns project rotation dip (float). :df:`rotationisreflected()` Returns true if the project rotation is reflected. :df:`rotationmatrixfrommodel()` Returns 4x4 matrix of rotation from Model to Project coordinates. Prefer to use the helper functions defined in the Functions_ section. :df:`rotationmatrixtomodel()` Returns 4x4 matrix of rotation from Project to Model coordinates Prefer to use the helper functions defined in the Functions_ section. :df:`rotationplunge()` Returns project rotation plunge (float). :df:`rotationtype()` Returns project rotation type (int). ================= ===== ==================== Rotation Type Value Meaning ================= ===== ==================== :d:`pcf.ROT_NONE` 0 No rotation :d:`pcf.ROT_HOR` 1 Horizontal rotation :d:`pcf.ROT_3D` 2 3D rotation ================= ===== ==================== :df:`rotationxorigin()` Returns project rotation x-origin (float). :df:`rotationyorigin()` Returns project rotation y-origin (float). :df:`rotationzorigin()` Returns project rotation z-origin (float). :df:`seamlist()` Returns a list of strings containing the project's seam names. Returns empty list (:a:`[]`) if the project has no seams (for example, a 3DBM). :df:`seamnumberlist()` Returns a list of floats containing the project's seam numbers. Returns empty list (:a:`[]`) if the project has no seams (for example, a 3DBM). For a GSM project, this function is equivalent to :f:`levellist()`. :df:`units()` Returns the project units type (int) ============ ========================================== Return Value Meaning ============ ========================================== 1 Imperial 2 Metric project / Imperial plot dimensions 3 Metric ============ ========================================== You can use this method in conjunction with the helper function, :f:`pcf.determineunitstring()` (see Functions_). :df:`xmax()` Returns max model limit in the x-direction (float). :df:`xmin()` Returns min model limit in the x-direction (float). :df:`ymax()` Returns max model limit in the y-direction (float). :df:`ymin()` Returns min model limit in the y-direction (float). :df:`zcrest()` Returns the crest elevation at the top of the project (float) :df:`zmax()` Returns max model limit in the z-direction (float). :df:`zmin()` Returns min model limit in the z-direction (float). .. Functions: --------- Functions --------- :df:`determineunitstring(pcfobj[, imperialstr, metricstr])` Examines the :c:`Pcf` object's units and returns a string representation. Allows you to easily get a 'imperial' or 'metric' string based on the status of the :a:`pcfobj`. If the :a:`pcfobj` :f:`isimperial()` then :a:`imperialstr` is returned. If the :a:`pcfobj` :f:`ismetric()` then the :a:`metricstr` is returned. :df:`frommodelcoord(pcfobj, coor)` Takes a point defined in Model coordinates and returns that point in Project coordinates. The point coordinates are defined as: [x,y,z]. :df:`frommodelcoordlist(pcfobj, coordlist)` Takes a list of points in Model coordinates and returns a list of points in Project coordinates. A point list is defined as a list of lists, such as, [[x0, y0, z0], ..., [xN, yN, zN]] :df:`frommodelvector(pcfobj, vector)` Takes a the directional vector defined in Model coordinates and returns a directional vector defined in Project coordinates. The directional vector is defined as a 3 point list, such as, [i, j, k] :df:`frommodelvectorlist(pcfobj, vectorlist)` Takes each vector in the :a:`vectorlist` defined in Model coordinates and returns a new list of vectors that are defined in the Project coordinates. The vector list is defined as a collection of vectors, such as, [[i0, j0, k0], ..., [iN, jN, kN]] :df:`tomodelcoord(pcfobj, coord)` Takes a point defined in Project coordinates and returns that point in Model coordinates. The point coordinates are defined as: [x,y,z]. :df:`tomodelcoordlist(pcfobj, coordlist)` Takes a list of points in Project coordinates and returns a list of points in Model coordinates. A point list is defined as a list of lists, such as, [[x0, y0, z0], ..., [xN, yN, zN]] :df:`tomodelvector(pcfobj, vector)` Takes a the directional vector defined in Project coordinates and returns a directional vector defined in Model coordinates. The directional vector is defined as a 3 point list, such as, [i, j, k] :df:`tomodelvectorlist(pcfobj, vectorlist)` Takes each vector in the :a:`vectorlist` defined in Project coordinates and returns a new list of vectors that are defined in the Model coordinates. The vector list is defined as a collection of vectors, such as, [[i0, j0, k0], ..., [iN, jN, kN]] --------- Exception --------- exception :de:`PcfError` Generic exception for all errors generated from this module. ---- Data ---- :dd:`FALSE` :dd:`TRUE` Defines TRUE (1) and FALSE (0). :dd:`MISSING` Defines a missing value. :dd:`PCFITEM_MAX` :dd:`PCFITEM_MIN` Defines a maximum and minimum item. :dd:`ROT_3D` :dd:`ROT_HOR` :dd:`ROT_NONE` Defines the different types of rotation types.