================================= ``grail.ip.reserves`` Module ================================= .. include:: ../../version.h .. contents:: Table of Contents :backlinks: top -------- Overview -------- The reserves module provides access to the MineSightŪ Interactive Planner (MSIP) reserve information for an MSIP session. The main purpose of this module is to provide access to two important dictionaries, 1. The reserves dictionary. 2. The equipment dictionary. Rarely should these dictionaries by access directly by the script writer. Instead the script writer should use the grail.ip.reslib_ library for working with the reserves dictionary, and the grail.ip.equtils_ for working with the equipment dictionary. .. _grail.ip.reslib: lib-grail-ip-reslib.html ---------------------------------------------- Example of MineSightŪ IP Script Initialization ---------------------------------------------- In order to use this module effectively you will need to perform the following two steps, 1. You must get a handle to the current reserves reference. 2. You must use that handle to get the reserves dictionary. In Python code this would look like, .. Python:: hres = reserves.hGetCurResRef() dres = reserves.dGetRes(hres) --------- Functions --------- :df:`hGetCurResRef()` Returns the a current handle that can be used to get the reserves dictionary. See `Example of MineSightŪ IP Script Initialization`_. :df:`dGetRes(hres)` Given the handle, :a:`hres`, return a reserves dictionary (see `Reserves Dictionary`_). This function works with the :f:`hGetCurResRef()` function.k :df:`vRefreshPlan()` Triggers a plan refresh from the database. This call is reentrant, meaning you can call and get the new modified dRes after making the refresh call to get the newly loaded data. Any existing dRes structures obtained from before the refresh call will NOT reflect the reloaded data. As an example consider the following, .. Python:: # Initially, get our handle on the reserves dictionary. hRes = reserves.hGetCurResRef() dRes = reserves.dGetRes(hRes) # ... later ... reserves.vRefreshPlan() hRes_r = reserves.hGetCurResRef() dRes_r = reserves.dGetRes(hRes) in the above example, as soon as you execute :f:`vRefreshPlan`, the value of :d:`hRes` and :d:`dRes` become invalid. The :d:`hRes_r` and :d:`dRes_r` now have the *new* plan information stored within them. To simplify the above example, you could have simply done the following, .. Python:: # Refresh our handle on the reserves dictionary. reserves.vRefreshPlan() hRes = reserves.hGetCurResRef() dRes = reserves.dGetRes(hRes) and now the :d:`hRes` and :d:`dRes` will reference the correct reserves dictionary. :df:`vDeleteCut(gkey)` Deletes cut which corresponds to the :a:`gkey` provided. :df:`vCreatePartialsFile(cut_index, filename)` Given a cut's :a:`cut_index` from the dRes dictionary and a :a:`filename`, this function will create a corresponding partials file. :df:`dGetGeometry(hres, cutindex)` Returns the geometry dictionary for the indexed cut. The data dictionary contains the following keys, Dictionary Keys: :a:`Planar` Either 0 or 1. :a:`Type` Can be either "Polyline", "Polygon", "Shell" :a:`NumPoints` Indicates the number of points in the point list. :a:`PointList` A list of points as triplet lists, in the form, [[x0, y0, z0], ..., [xN, yN, zN]] :a:`NumFaces` The number of faces in the face list. :a:`FaceList` A list of vertex indice triples. In the form, [[v0_0, v0_1, v0_2], ..., [vN_M, ...]] where the first each triplet corresponds to a face. .. Note:: That the face list definition used above is *not* the same as the one used in the grail.ag_ module. .. _grail.ag: ../lib-grail-ag.html :df:`dGetCacheGeometry()` Returns cached geometry for the current cut in the same format as :f:`dGetGeometry` above. :df:`dGetGeomLimits(hRes, index)` Returns a dictionary that describes the limits (bounding box) for the cut at the given :a:`index`. Dictionary keys used are, * :a:`Easting.min` * :a:`Easting.max` * :a:`Northing.min` * :a:`Northing.max` * :a:`Elevation.min` * :a:`Elevation.max` These values report 3-D box that inscribes the cut. :df:`dGetEquipInfo(geometrycutkey, materialname, number)` Returns the a dictionary containing the equipment information for a given material within the given geometry cut key. An example of using this would be, .. Python:: cut = dres['cuts'][0] # first cut for material in reslib.getmaterialsbycut(dres, cut): for num in range(len(material['cutoffs'])): equipdict = reserves.dGetEquipInfo(cut['geomkey'], material['name'], num) See the grail.ip.equtils_ module for information about working with the equipment dictionary. .. _grail.ip.equtils: lib-grail-ip-equtils.html :df:`iSetEquipInfo(geometrycutkey, cutkey, cutoffindex, equipdict)` Sets the equipment dictionary for a given geometry cut. :df:`iReplaceValid()` xxx -- needs documentation. :df:`vClearTransBuff()` xxx -- needs documentation. ------------------- Reserves Dictionary ------------------- In the following listing, each indentation either represents another Python dictionary or Python listing. .. Note:: It is not recommended that you work with the reserves dictionary directly unless you really have to. The grail.ip.reslib_ module provides methods to make working with the dictionary much easier. If you choose to work with the dictionary directly the internal organization is not always guaranteed to work from MineSightŪ Grail version to version. The reserves dictionary is listed as follows, :a:`planname` : string The plan name. :a:`volredpct` : integer True if volume reduction / mined out is represented by a percent. :a:`imperial` : integer Imperial flag. :a:`curcut` : integer Current cut index; -1 if there is no current cut. :a:`numcuts` : integer Number of cuts. :a:`numareas` : integer Number of areas. :a:`curarea` : integer The current area. :a:`curminearea` : string The current mining area. :a:`curperiod` : string The current period. :a:`attribnames` : list List of attribute names. :a:`cuts` : list List of cut dictionaries (use numerical index). :a:`geomkey`: integer Key to geometry segment. :a:`planelabel` : string Plane label. :a:`name` : string The cut's name. :a:`area` : string The cut's area. :a:`matset` : string Material set name. :a:`miningarea` : string The cut's mining area. :a:`period` : string The cut's period. :a:`geomcreation` : string The cut's Geom Info. Typically this refers to the seams in a GSM. :a:`cutSurfaceSet`: string The cut's Surface Set. :a:`numres` : integer Number of cut reserves. :a:`numcustom` : integer Number of the cut's custom attributes. :a:`attributes` : list List of customs attribute dictionaries. :a:`name` : string Attribute name. :a:`type` : string Attribute type. It can be one of 'integer', 'double' or 'string'. :a:`value` : any Value of attribute. The type of attribute is dependent on the the value in the type field. :a:`reserves` : list A listing of reserve dictionaries with the following keys, :a:`material` : string Material name. :a:`zoneidx` : Zone index number. :a:`numgrades` : integer Number of grades. :a:`cutoff` : float Cutoff index. :a:`tons` : float Tons of this reserve item. :a:`volume` : float Volume of this reserve item. :a:`numblocks` : float Number of blocks used to calculate these values. :a:`nullflag` : list List of null flags. If the grade value in :a:`gradevalues` is actually a null and not a zero this flag is set to true. :a:`gradenames` : list Listing of grade names. Each grade name is a string. :a:`gradevalues` : list List of grade values. Each grade value is a float. :a:`areas` : list of dictionaries A list of area dictionaries where the keys are defined as follows, :a:`name` : string Area name. :a:`thicknessitem` : string Thickness item name. :a:`volreditem` : string Volume reduction item name. :a:`partialsitem` : string Partials item name. :a:`model` : integer Model handle. :a:`partialsmodel` : integer Partials model handle. :a:`flags` : integer .. Warning:: Do not use. :a:`volreduction` : integer Volume reduction flag. This flag is 1 if volume reduction item was used. :a:`items` : list List of ore and waste items only 1 in simple case. :a:`pctitem` : string Percent item name. :a:`zoneitem` : string Zone item name. :a:`orepctitem` : string Ore percent item (only used in single ore percent case). :a:`densityitem` : string Density item. :a:`sgflag` : integer This is 1 if using specific gravity (SG). :a:`waste` : integer This is 1 if waste in the multi-percent case. :a:`priority` : integer Numeric priority, values can be repeated. :a:`numgrades` : integer Num grades. :a:`grades` : list List of grades dictionaries, where the keys are defined as follows, :a:`name` : string Grade name. :a:`accum` : integer Flag accumulated versus averaged. :a:`thick` : integer This is flag for thickness grade so average with :a:`numblocks`. :a:`materialsets` : list of dictionaries List of material set dictionaries where the keys are defined as follows, :a:`name` : string Material set name. :a:`materials` : list of dictionaries The material dictionary keys are defined as follows, :a:`name` : string Material name. :a:`index` : integer Materials index. :a:`waste` : integer Set to 1 if waste. :a:`default` : integer Set to 1 if this is the default material. :a:`numcutoffs` : integer Number of cutoffs. :a:`density` : float Default density for this material. :a:`cutoffs` : list A listing of cutoff values (each element is a float).