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).

Working with Rotation Information

Working with rotational matrices is sometimes a difficult and arduous task. It is much easier to take the 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,

  • frommodelcoord()
  • frommodelcoordlist()
  • frommodelvector()
  • frommodelvectorlist()

• For converting from Project Space to Model Space,

  • tomodelcoord()
  • tomodelcoordlist()
  • tomodelvector()
  • 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 Pcf object. In code, this would look something like,

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 ppoint will be defined as the the Project Space's equivalent to the mpoint.

Project Control File (PCF) Class

class Pcf(path)

This class provides read-only access to the internal structure of the Project Control File (PCF).

You can create a Pcf object by passing in the name of the PCF that you wish to read. For example,

from grail.data import pcf
p = pcf.Pcf("samp10.dat")

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:

elevation : float

The given elevation.

epsilon : float

If the elevation is within epsilon of a bench toe, the corresponding bench crest will be returned.

compositeitem()

Returns the controlling z-item (string).

compositetype()

Returns the composite type (string).

dx()

Returns the block width in the x-direction (float).

dy()

Returns the block width in the y-direction (float).

dz()

Returns the block width in the z-direction (float).

filelist()

Returns the files in the PCF (list of strings).

filelistbytype(type)

Returns the files of a particular type (list of strings)

Arguments:

type : integer

The file type (for example, 11 or 15).

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,

pcf = pcf.Pcf("msop10.dat")
# do stuff...
del pcf

The "del" command will delete any internal memory.

is3dbm()

Returns true is this project is a 3DBM.

isgsm()

Returns true is this project is a GSM.

isimperial()

Returns true is this project is in imperial units.

isitemalpha(file, item)

Returns true if the specified file item is alpha.

Arguments:

file : string

Name of the file containing the item.

item : string

Item name of the item.

isitemfloat(file, item)

Returns true if the specified file item is a float.

Arguments:

file : string

Name of the file containing the item.

item : string

Item name of the item.

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:

file : string

Name of the file containing the item.

item : string

Item name of the item.

isitemint(file, item)

Returns true if the file item has integer precision.

Arguments:

file : string

Name of the file containing the item.

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.

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:

file : string

Name of the file containing the item.

item : string

Item name of the item.

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).

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:

file : string

Name of the file containing the item.

item : string

Item name of the item.

ismetric()

Returns true is this project is in metric units.

isplotimperial()

Returns true is plotter units are in imperial.

isplotmetric()

Returns true is plotter units are in metric units.

isrotated()

Returns true if the project is rotated.

itemflag()

Unused.

itemlist(file)

Returns a list of strings containing a file's items.

Arguments:

file : string

Name of the file containing the item.

itemmax(file, item)

Returns the maximum value (float) of the item as specified when the item was initialized (see itemrealmax).

For full word or alpha items, the max value is pcf.PCFITEM_MAX.

Arguments:

file : string

Name of the file containing the item.

item : string

Item name of the item.

itemmin(file, item)

Returns the minimum value of the item (float).

For full word or alpha items, the min value is pcf.PCFITEM_MIN.

Arguments:

file : string

Name of the file containing the item.

item : string

Item name of the item.

itemprecision(file, item)

Returns the item precision (float).

Arguments:

file : string

Name of the file containing the item.

item : string

Item name of the item.

itemrealmax(file, item)

Returns the maximum storable value for the item (float).

For full word or alpha items, the max storable value is 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:

file : string

Name of the file containing the item.

item : string

Item name of the item.

levelcount()

Returns the number of levels (int) in the project.

levellist()

Returns a list of floats containing either the project's toe elevations for a 3DBM or seam numbers for a GSM

nx()

Returns the number of blocks (int) in the x-direction.

ny()

Returns the number of blocks (int) in the y-direction.

nz()

Returns the number of blocks (int) in the z-direction.

path()

Returns the path of the PCF file (string).

pctitemlist(file)

Returns a list of strings containing a file's percent items.

Arguments:

file : string

Name of the file containing the item.

projid()

Returns the Project ID (string).

projxmax()

Returns max project extent in the x-direction.

projxmin()

Returns min project extent in the x-direction.

projymax()

Returns max project extent in the y-direction.

projymin()

Returns min project extent in the y-direction.

projzmax()

Returns max project extent in the z-direction.

projzmin()

Returns min project extent in the z-direction.

rotationazimuth()

Returns project rotation azimuth (float).

rotationdip()

Returns project rotation dip (float).

rotationisreflected()

Returns true if the project rotation is reflected.

rotationmatrixfrommodel()

Returns 4x4 matrix of rotation from Model to Project coordinates. Prefer to use the helper functions defined in the Functions section.

rotationmatrixtomodel()

Returns 4x4 matrix of rotation from Project to Model coordinates Prefer to use the helper functions defined in the Functions section.

rotationplunge()

Returns project rotation plunge (float).

rotationtype()

Returns project rotation type (int).

Rotation Type	Value	Meaning
pcf.ROT_NONE	0	No rotation
pcf.ROT_HOR	1	Horizontal rotation
pcf.ROT_3D	2	3D rotation

rotationxorigin()

Returns project rotation x-origin (float).

rotationyorigin()

Returns project rotation y-origin (float).

rotationzorigin()

Returns project rotation z-origin (float).

seamlist()

Returns a list of strings containing the project's seam names.

Returns empty list ([]) if the project has no seams (for example, a 3DBM).

seamnumberlist()

Returns a list of floats containing the project's seam numbers.

Returns empty list ([]) if the project has no seams (for example, a 3DBM).

For a GSM project, this function is equivalent to levellist().

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, pcf.determineunitstring() (see Functions).

xmax()

Returns max model limit in the x-direction (float).

xmin()

Returns min model limit in the x-direction (float).

ymax()

Returns max model limit in the y-direction (float).

ymin()

Returns min model limit in the y-direction (float).

zcrest()

Returns the crest elevation at the top of the project (float)

zmax()

Returns max model limit in the z-direction (float).

zmin()

Returns min model limit in the z-direction (float).

Functions

determineunitstring(pcfobj[, imperialstr, metricstr])

Examines the 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 pcfobj. If the pcfobj isimperial() then imperialstr is returned. If the pcfobj ismetric() then the metricstr is returned.

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].

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]]

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]

frommodelvectorlist(pcfobj, vectorlist)

Takes each vector in the 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]]

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].

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]]

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]

tomodelvectorlist(pcfobj, vectorlist)

Takes each vector in the 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 PcfError

Generic exception for all errors generated from this module.

Data

FALSE

TRUE

Defines TRUE (1) and FALSE (0).

MISSING

Defines a missing value.

PCFITEM_MAX

PCFITEM_MIN

Defines a maximum and minimum item.

ROT_3D

ROT_HOR

ROT_NONE

Defines the different types of rotation types.