============================== ``grail.data.torq`` Module ============================== .. include:: ../../version.h .. contents:: Table of Contents :backlinks: top -------- Overview -------- This module provides access to drillholes (i.e. sample sites) in a MineSight Torque database. .. warning:: This module can only be used with embedded scripts (scripts designed to be run from within MineSight 3-D). -------- Examples -------- The following snippet illustrates how to connect to a Torque database, load a drillhole set, retrieve a drillhole, and set the value of a Sample Attribute for all intervals. .. Python:: sqlserver = "MYCOMP\\SQLEXPRESS" database = "GRADE_CNTRL" conn = torq.connect(sqlserver, database) dhset = torq.openDHSet(conn) dh = dhset.getDrillholeByName('1200-001-333') numIntervals = dh.getIntervalCount() for idx in range(numIntervals): dh.setIntervalDataAt("GC", idx, "TOTALCOPPER", 0.14) dh.save() #save changes to the individual drillhole dhset.saveChanges() #commit all changes to database dhset.close() torq.disconnect(conn) The following snippet illustrates how to connect to a Torque database and load a filtered drillhole set. .. Python:: sqlserver = "MYCOMP\\SQLEXPRESS" database = "GRADE_CNTRL" conn = torq.connect(sqlserver, database) #create a compound filter for Names that begin with "2010" and ShotNumber exceeding 40 nameFilter = (torq.filterCategory_STANDARD, "Name", comparisonOp_EQ, "2010*", torq.logicalOp_AND) customFilter = (torq.filterCategory_CUSTOM, "ShotNumber", torq.comparisonOp_GT, 40, torq.logicalOp_AND) filterList=[nameFilter, customFilter] coverageName = "Assays" dhset = torq.openDHSetFiltered(conn, coverageName, filterList, torq.typeBLASTHOLE) #do something here dhset.close() torq.disconnect(conn) The following snippet illustrates how to connect to a Torque database and create/save a new Drillhole. .. Python:: sqlserver = "MYCOMP\\SQLEXPRESS" database = "GRADE_CNTRL" conn = torq.connect(sqlserver, database) dhset = torq.openDHSet(conn, loaddata=False) #declare parameters for new drillhole type = torq.typeBLASTHOLE coverage = "Assays" sampprogram = "Original" unit = "Foot" bhname = "DH1" legacyname = 1 azimuth = 348.0 dip = -90.0 depth = 39.0 easting = 12548.0 northing = 689556.0 elev = 2950.0 dh = dhset.createDrillhole(type, coverage, sampprogram, unit, bhname, legacyname, azimuth, dip, depth, True) dh.setCollar([easting,northing,elev]) dh.save() #save the new drillhole dhset.saveChanges() #commit all changes to database dhset.close() torq.disconnect(conn) --------------------- Functions --------------------- :df:`connect(sqlserver, database, username=None, password=None)` This function connects to the Torque database and returns a `Connection` object. Keep a reference to this object as it will be needed to disconnect. The function raises an IOError if a valid license cannot be located, or if there is a connection error. :df:`disconnect(conn)` This function disconnects from the Torque database. :df:`openDHSet(conn, loaddata=True)` This function creates and returns a `DHSet` object. By default, all drillholes in the project will be loaded. If the `loaddata` parameter is set to False, then no drillholes will be loaded. The function raises an IOError if the specified database is not a valid Torque database. :df:`openDHSetFiltered(conn, coverageName, filterset, filterType=typeBLASTHOLE)` This function is used to load a filtered subset of drillholes. It creates and returns a `DHSet` object. The parameter `filterset` is a list of one or more tuples containing the following five elements: `filterCategory`: the filter category. See `Constants`_ section. `fieldName`: the field or attribute name (String) `comparisonOp`: comparison operator. See `Constants`_ section. `value`: the field/attribute value to compare to. `logicalOp`: logical operator used to connect two or more filter sets. See `Constants`_ section. ------------ DHSet Class ------------ This class provides the main access point for a Torque project. :c:`DHSet` Use :df:`openDHSet` or :df:`openDHSetFiltered` to create a :c:`DHSet` object. :df:`close()` Closes the DHSet and removes it from memory. :df:`compareVersion(major, minor)` Compares the project version to the version specified by the arguments. Returns 1 if project is greater than the specified version; 0 if project is the same as the specified version; or -1 if the project is less than the specified version. :df:`createDrillhole(type, coverageName, sampleProgramName, unitName, name, legacyName, azimuth, dip, length, overwrite=True)` Creates a new Drillhole with a single interval and returns the `Drillhole` object. Raises a `ValueError` if Legacy Name already exists in set. You must call `Drillhole::save()` followed by `DHSet::saveChanges()` in order to permanently store this drillhole in the project. :df:`getAreaEnumValues()` Returns a list containing the enumeration values (Strings) for Area. :df:`getBlastholeTypeEnumValues()` Returns a list containing the enumeration values (Strings) for Blasthole Type. :df:`getCoverages()` Returns a list containing all coverage names in the project. :df:`getCustomFieldNames()` Returns a list containing all Custom Field names in the project. This includes SampleSite custom fields (shared) and custom fields specific to both Drillholes and Blastholes. :df:`getCustomFieldType(customFieldName)` Returns the Custom Field datatype. See `Constants`_ section. :df:`getDrillholeAt(index)` Creates and returns a `Drillhole` object for the drillhole at the specified index. :df:`getDrillholeByName(name)` Creates and returns a `Drillhole` object for the drillhole with the specified name. :df:`getDrillholeCount()` Returns the number of loaded drillholes in the set. :df:`getDrillholeNames()` Returns a list of names for the drillholes loaded in the set. :df:`getDrillholesInPointList2d(pointlist, endpoints=False)` Returns a list of drillhole names with collars (or toes) inside the 2-dimensional geometry of the pointlist. .. warning:: This function is for Sample Sites of type `Blasthole` only. .. warning:: This function considers X and Y coordinates only. To include elevation, test the `Bench Toe` value (or Collar Z value) of the drillholes returned. :df:`getExistingNames()` Returns a list containing all drillhole names in the project (regardless of the DHSet filters). :df:`getExistingLegacyNames()` Returns a list containing all drillhole legacy names in the project (regardless of the DHSet filters). :df:`getIntervalTypeEnumValues()` Returns a list containing the enumeration values (Strings) for Interval Type. :df:`getSampleAttribNames()` Returns a list containing all Sample Attribute names in the project. :df:`getSampleAttribEnumValues(sampleAttribName)` Returns a list containing the enumeration values (Strings) for the specified Sample Attribute. This function raises a `TypeError` if the Sample Attribute is not an enumerated type. :df:`getSampleAttribType(sampleAttribName)` Returns the data type of the specified Sample Attribute. See `Constants`_ section. :df:`getSamplePrograms()` Returns a list of sample programs. :df:`getVersion()` Returns a tuple containing the major and minor version numbers of the project. :df:`saveChanges()` Deprecated alias: `storeAll()`. Writes all changes made to drillholes back to the database. Returns the number of holes saved. ---------------- Drillhole Class ---------------- This class provides the main access point for a single drillhole (i.e. sample site). :c:`Drillhole` Use :df:`createDrillhole` or :df:`getDrillholeAt` or :df:`getDrillholeByName` to create a :c:`Drillhole` object. :df:`delete()` Removes the Drillhole from the project. Note that you must subsequently call `DHSet::saveChanges()` to commit the change. :df:`getArea()` Returns the value of the standard field "Area". :df:`getBenchToe()` Returns the value of the standard field "Bench Toe". Raises a `TypeError` if drillhole is not of type Blasthole. :df:`getBlastholeType()` Returns the value of the standard field "Blasthole Type". Raises a `TypeError` if drillhole is not of type Blasthole. :df:`getCollar()` Returns the collar location as a list of co-ordinates: [x, y, z]. :df:`getComment()` Returns the value of the comment field. :df:`getCoordinateSystem()` Returns the drillhole coordinate system. :df:`getCoverages()` Returns a list containing all coverage names for this drillhole. :df:`getCustomField(customFieldName)` Returns the value of the specified Custom Field. :df:`getCustomFieldNames()` Returns a list containing all Custom Field names for this drillhole. :df:`getCustomFieldType(customFieldName)` Returns the Custom Field datatype. See `Constants`_ section. :df:`getDate()` Returns the value of the date field as a string. The format of the date returned depends on the machine's region settings (short date format). :df:`getGeometryType()` Returns the geometry type. See `Constants`_ section. :df:`getIntervalCount()` Returns the number of intervals in the drillhole. :df:`getIntervalDataAt(coverageName, interval_idx, sampleAttribName)` Returns the value of the Sample Attribute for the specified interval. :df:`getIntervalFromTo(coverageName, interval_idx)` Returns a (from,to) tuple representing the downhole depth of the start and end of the interval. :df:`getIntervalType()` Returns the Interval Type of the drillhole. :df:`getLegacyName()` Returns the legacy name of the drillhole. :df:`getLength()` Returns the drillhole length. :df:`getMineType()` Returns the value of the standard field "Mine Type". Raises a `TypeError` if drillhole is not of type Blasthole. :df:`getName()` Returns the drillhole name. :df:`getShotLabel()` Returns the value of the standard field "Shot Label". Raises a `TypeError` if drillhole is not of type Blasthole. :df:`getSurveyAzimuth(surveyPointIdx)` Returns the azimuth for the survey point index. :df:`getSurveyPointCount()` Returns the number of survey points in the drillhole. :df:`getSurveyDepth(surveyPointIdx)` Returns the depth for the survey point index. :df:`getSurveyDip(surveyPointIdx)` Returns the dip for the survey point index. :df:`getType()` Returns the drillhole type. See `Constants`_ section. :df:`getUnit()` Returns the drillhole unit. :df:`save()` Deprecated alias: `store()`. Saves the new/modified Drillhole to the DHSet. Note that you must subsequently call `DHSet::saveChanges()` to commit the change. :df:`setArea(value)` Sets the value of the standard field "Area". Raises a `ValueError` if the value is not an existing Area enumeration. :df:`setBenchToe(value)` Sets the value of the standard field "Bench Toe". Raises a `TypeError` if drillhole is not of type Blasthole. :df:`setBlastholeType(value)` Sets the Blasthole Type. Raises a `ValueError` if the value is not an existing Blasthole Type enumeration. Raises a `TypeError` if drillhole is not of type Blasthole. :df:`setCollar(point)` Sets the value of the drillhole collar. :df:`setComment(value)` Sets the value of the comment field. :df:`setCoordinateSystem(value)` Sets the drillhole coordinate system. Raises a `ValueError` if the argument is not a valid coordinate system. :df:`setCustomField(customFieldName, value)` Sets the value of the specified Custom Field. If setting a field of datatypeDATE, the date string must follow format "MM/DD/YYYY". :df:`setDate(value)` Sets the Date field. Raises a `ValueError` if the date string does not follow format "MM/DD/YYYY". :df:`setIntervalDataAt(coverageName, interval_idx, sampleAttribName, value)` Sets the value of the Sample Attribute for the specified interval. If setting a field of datatypeDATE, the date string must follow format "MM/DD/YYYY". :df:`setIntervalType(value)` Sets the Interval Type. Raises a `ValueError` if the value is not an existing Interval Type enumeration. :df:`setLegacyName(value)` Sets the drillhole legacy name. :df:`setLength(value)` Sets the drillhole length. :df:`setMineType(value)` Sets the value of the standard field "Mine Type". Raises a `TypeError` if drillhole is not of type Blasthole. :df:`setName(value)` Sets the drillhole name. :df:`setShotLabel(value)` Sets the value of the standard field "Shot Label". Raises a `TypeError` if drillhole is not of type Blasthole. :df:`setUnit(value)` Sets the drillhole unit. Raises a `ValueError` if the argument is not a valid unit. :df:`setIntervalFloatDataAt_direct(coverageName, interval_idx, sampleAttribName, value)` Writes the Float value directly to the Sample Attribute. This function can be used to set `datatypeSMALLREAL` and `datatypeLARGEREAL`. A call to function `saveChanges()` is NOT required to apply the change. :df:`setIntervalIntegerDataAt_direct(coverageName, interval_idx, sampleAttribName, value)` Writes the Integer value directly to the Sample Attribute. This function can be used to set `datatypeSMALLINTEGER`, `datatypeSTANDARDINTEGER`, and `datatypeBOOLEAN`. A call to function `saveChanges()` is NOT required to apply the change. --------- Constants --------- Constant for missing data :d:`MISSING` These `type` constants are used to define the different drillhole types: :d:`typeDRILLHOLE` :d:`typeBLASTHOLE` :d:`typeOTHER` :d:`typeUNDEFINED` These `datatype` constants are used to define the different data types: :d:`datatypeSTRING` :d:`datatypeDATE` :d:`datatypeENUM` :d:`datatypeSTANDARDINTEGER` :d:`datatypeSMALLINTEGER` :d:`datatypeLARGEREAL` :d:`datatypeSMALLREAL` :d:`datatypeBOOLEAN` :d:`datatypeUNDEFINED` These `geomtype` constants are used to define the different drillhole geometry types: :d:`geomtypeBYPOLYLINE` :d:`geomtypeBYSURVEYS` :d:`geomtypeBYPOINT` :d:`geomtypeUNDEFINED` These `filterCategory` constants are used to define the different filter types: :d:`filterCategory_STANDARD` (filter drillholes by standard MSTorque fields) :d:`filterCategory_CUSTOM` (filter drillholes by custom field values) :d:`filterCategory_SAMPLE` (filter drillholes by sample attribute values) These `comparisonOp` constants are used to define the comparison operators used in filter expressions: :d:`comparisonOp_LT` (less than) :d:`comparisonOp_LTE` (less than or equal to) :d:`comparisonOp_EQ` (equal to) :d:`comparisonOp_NEQ` (not equal to) :d:`comparisonOp_GTE` (greater than or equal to) :d:`comparisonOp_GT` (greater than) :d:`comparisonOp_IN` :d:`comparisonOp_NOTIN` :d:`comparisonOp_ISNULL` :d:`comparisonOp_ISNOTNULL` These `logicalOp` constants are used to define the logical operators used in filter expressions: :d:`logicalOp_AND` :d:`logicalOp_OR`