Table of Contents
This module provides access to the attributed geometry portion of the MineSight Planning Database (MSPD).
The pd library consists of a DB Class and helper Functions that allow you to read and write data to and from a MSPD. The access routines fall into the following broad categories,
Plan
Allows you to define plans within a MSPD. A plan is a collection of geometry segments within the database.
Geometry Segments
A geometry segment is the actual point data representing a geometry such as a polyline, polygon, marker, or surface/volume (SHELL). This module allows you to create and read/write with geometry segments.
Attributes
Allows you to read and write attribute values for a given geometry segment.
Attribute Definitions
Allows to you define, delete and check for the existence of attributes within a given MSPD.
These functions are responsible for creating a DB object. They differ in their connection type. Microsoft Access databases must be accessed with ODBC (Open Database Connectivity). SQL Server databases can be accessed with ODBC or ADO (ActiveX Data Objects). With some queries, the ADO connection can provide faster data retrieval than ODBC.
This class provides the main access point for all database actions.
DB
Use either the open or openADO functions to create a DB object.
- attrib_get(planName, segId, attribName)
- Returns the attributed value for the element defined by the plan and segment ID.
- attrib_set(planName, segId, attribName, value)
- Sets an attribute value for the element defined by the plan and segment ID. If the planName, segId or attribName are invalid or do not exist, then this function will raise an IOError. A TypeError will be generated if the type of the value is not valid for the given attribName.
- attrib_set_force_conversion(planName, segId, attribName, value)
- Sets an attribute value for the element defined by the plan and segment ID. If possible, the function will cast the value to the attribute type. Use caution since data loss may occur due to truncation (e.g. storing a float into an integer attribute).
- attrib_set_all(planName, attribName, value)
- Sets an attribute value for the given attribName for ALL elements in the plan. This function can be used to "reset" an attribute value for all cuts in an IP Plan (i.e. reset include back to 1)
- attribdef_create(name, attrtype, defaultValue)
- Creates an attribute definition in the MSPD that can be set in subsequent calls for other geometry items. A ValueError is generated if the name already exists within the database, or if the defaultValue is not of the correct type.
- attribdef_delete(attribName)
- Delete an attribute (and all corresponding attributed values) from the database.
- attribdef_exists(attribName)
- Returns true (1) if the given attribName exists as an attribute name within the MSPD.
- attribdef_get_default(attribName, planName=None)
- Returns the default value that is specified by the given attribName. If a plan name is specified, then the plan-specific default value will be returned.
- attribdef_get_type(attribName)
- Returns the type specified by the given attribName. The type will be one of the attrib values defined in the Constants section.
- attribdef_listing(planName=None)
- Returns a list of dictionaries with information about each attribute in the database. If a plan name is specified, then information about only the plan attributes will be returned (ie. only the attributes listed on the "Attributes" tab of the MSIP Cut Design Window).
- close()
- Closes the connection to the database.
- geom_add(planName, geomDict)
- Takes a geometry dictionary and stores it in the database with the given plan name. Returns a string with the new segment ID for this geometry.
- geom_exists(planName, segmentID)
- Returns true (1) if the given plan name and segment ID already exist in the database.
- geom_get(planName, segmentID)
- Returns a geometry dictionary for the specified plan and segment ID.
- geom_get_full(planName, segmentID)
- Returns a full geometry dictionary (including attributes) for the specified plan and segment ID.
- geom_listing(planName)
- Returns a list of segment ID's for a given plan.
- geom_set(planName, segmentID, geomDict)
- Updates/overwrites an existing segment with the data in the geometry dictionary. An IOError is generated if the segment ID does not exist in the database.
- get_SID_filter_range(planName, attribName, rangeStart, rangeEnd)
- Returns a list of all segment ID's in the plan that have a value that falls within the specified range (inclusive). This function is intended for use with attributes of type attribINT, attribFLT, and attribDATE. A ValueError is generated if passed an attribute of type attribSTR.
- get_SID_filter_value(planName, attribName, value)
- Returns a list of all segment ID's in the plan that have the specified value of the attribute.
- get_element_type(planName, segmentID)
- Returns the geometry type of the specified element. The type will be one of the geomtype values defined in the Constants section.
- get_plan(planName)
- Returns a dictionary with information about the specified plan.
- get_version()
- Returns version information for the MSPD as a string (e.g. "Geomview:1-8, IPCore:1-3, Haulage:1-1")
- has_date_field()
- Returns true (1) if the database is capable of handling a date field.
- plan_create(planName[, type])
- Takes a plan name string and an optional type string argument and creates a new plan within the MSPD. The type is used to distinguish between different plans (refer to the Constants section). If the planName already exists in the MSPD, an IOError will be generated.
- plan_delete(planName)
- Deletes the given plan within the MSPD. If the plan name does not exist within the MSPD, an IOError is generated.
- plan_exists(planName)
- Returns true (1) if the given plan name exists in the MSPD.
- plan_listing()
- Returns a list of dictionaries with information about each plan in the database.
- plan_set_recompute(planName[, value])
- Sets a flag in given plan that causes the reserves to be recalculated if value is True when the plan is next opened. Used when populating the MSPD from an external source. Generates an IOError if the plan does not exist. Generates a TypeError if the plan is not an IP Plan.
- run_custom_SQL_query(query)
- Executes a custom SQL query against the database. Returns a list of tuples (each inner tuple/list represents one record returned from the query).
- get_current_datetime()
- Returns an MSPD date string for the current local time.
- validate_date_format(dateStr)
- Verifies that a date string is in the correct format for the MSPD. Returns 1 if acceptable, otherwise returns 0.
- tuple_to_date(tupleTime)
- Converts a time tuple (as defined by the Python time module) into a MSPD date string.
- date_to_tuple(dateStr)
- Converts the MSPD date string into a time tuple as defined by the Python time module.
- geomdict_create_marker(pointlist, is_planar=False)
- Returns a Geometry Dictionary configured for markers as defined by the pointlist.
- geomdict_create_polyline(pointlist, is_planar=False)
- Returns a Geometry Dictionary configured for a polyline as defined by the pointlist.
- geomdict_create_polygon(pointlist, is_planar=False)
- Returns a Geometry Dictionary configured for a polygon as defined by the pointlist.
- geomdict_create_shell(pointlist, facelist, is_planar=False)
- Returns a Geometry Dictionary configured for a shell as defined by the pointlist and facelist.
- geomdict_convert(geomDict, YZSwap=False)
- Converts a grail.data.pd geometry dictionary to the format used in grail.ip.geomview.
- geomdict_get_attrib(geomDict, attribName)
- Returns an attribute dictionary from a geometry dictionary given the specified attribute name.
- geomdict_set_attrib(geomDict, attribtype, name, value)
- Either overwrites an existing attribute dictionary in a geometry dictionary, or creates a new one if dictionary does not exist.
- geomdict_set_stnd_attribs(geomDict, cutName, cutMatName, cutPlane, cutMareaName, cutPerID)
- Used to set the five standard MSIP attributes: Cut Name, Material Set, Plane Label, Mining Area, and Period ID. It will either overwrite the existing attribute dictionaries in the geometry dictionary, or else create new dictionaries. The onus is on the script writer to ensure the values make sense for the IP Plan (e.g. Material Set must exist in the IP Plan, or else the cut will be deleted by Interactive Planner).
- get_DSN_Dict()
- Returns a dictionary mapping ODBC data source name to driver type (for all system and user DSN's). An example of the dictionary would be: {'Haulage_Nov': 'SQL Server','MSOPS_Nov': 'Microsoft Access Driver (*.mdb)', 'spreadsheet': 'Microsoft Excel Driver (*.xls)'}
- get_SQLServer_databases(sqlServerInstance="local", username=None, password=None)
- Returns a list of databases available on the SQL Server Instance. An IOError is generated if connection fails.
- getSeams(seam, pcf_seamlist)
- Takes a binary blob value from cutCreation attribute and a pcf seamlist and returns a list of the seams that are occupied by the GSM IP cut. The pcf seamlist can be obtained using the grail.data.pcf module.
- packSeams(seamindices, pcf_seamlist, dontreporttop=0)
- Packs a binary blob for storing in the cutCreation attribute. Requires a full list of seam labels from the PCF (refer to grail.data.pcf module) and a list of seam indices for the cut (eg. [0,1]).
These type constants are used to define the different plan types:
- typeIP_PLAN
- Defines a IP scheduling plan.
- typeHAUL_PLAN
- Defines a haulage network plan.
- typeDEFAULT_PLAN
- Defines a default plan type.
These keyPLAN value pairs for a Plan Dictionary are as follows.
- keyPLAN_NAME
- A string indicating the plan name.
- keyPLAN_TYPE
- The type is used to distinguish between different plans. Valid values include: typeIP_PLAN, typeHAUL_PLAN, or typeDEFAULT_PLAN.
- keyPLAN_DATE_CREATE
- A string that will store the date the plan was created.
- keyPLAN_DATE_MODIFIED
- A string that will store the date the plan was modified.
These geomtype constants are used to define the different geometry types:
- geomtypeMARKER
- Defines a Marker geometry type.
- geomtypePOLYLINE
- Defines a Polyline geometry type.
- geomtypePOLYGON
- Defines a Polygon geometry type.
- geomtypeSHELL
- Defines a Shell geometry type.
These attrib constants are used to define the different attribute types:
- attribSTR
- Defines a String attribute type.
- attribINT
- Defines an Integer attribute type.
- attribFLT
- Defines a Float attribute type.
- attribDATE
- Defines a Date attribute type. Although this value is a string it has a very special format outlined in the MSPD Data Definitions.
- attribBLB
- Defines a Binary blob attribute type. This is used in GSM IP Sets (cutCreation).
These keyGEOM constants are used to access the contents of the Geometry Dictionary:
- keyGEOM_TYPE
- This defines the type of geometry. Valid values include: geomtypeMARKER, geomtypePOLYLINE, geomtypePOLYGON, or geomtypeSHELL.
- keyGEOM_POINTLIST
- This is the point list used for the geometry.
- keyGEOM_FACELIST
- This is list of vertex indices. Typically used for geomtypeSHELL.
- keyGEOM_PLANAR
- Set to true (1) if the geometry is planar. Generally you want to leave this as 0.
- keyGEOM_ATTRLIST
- This is a list of Attribute Definition Dictionary values corresponding to the attributes for the geometry.
These keyATTRIB constants are used to access the contents of the Attribute Definition Dictionary:
- keyATTRIB_NAME
- A string indicating the attribute's name.
- keyATTRIB_TYPE
- The type of the attribute. Valid values include: attribSTR, attribINT, attribFLT, or attribDATE.
- keyATTRIB_VALUE
- The value of the attribute.
Within the MSPD we can handle date fields for our objects. The date fields are passed as strings and must adhere to the following format. It can be one of two formats,
- A date format of: DD-MMM-YYYY. Acceptable delimiters between fields include a hyphen (-), or a forward slash (/).
- With an optional time component of: DD-MMM-YYYY HH:MM:SS.
where the fields and acceptable values are described as,
Field Acceptable Values DD 01-31 MMM Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec YYYY 0000-9999 HH 1-24 MM 0-59 SS 0-59 The tuple_to_date and date_to_tuple functions are provided to allow easy conversion between the MSPD Date Field and the standard time tuple as defined by the Python time module.