================================= ``grail.ip.geomview`` Module ================================= .. include:: ../../version.h .. include:: ref.h .. contents:: Table of Contents :backlinks: top -------- Overview -------- This module was designed to allow script writers to accomplish three main goals, 1. to set and get database attributes. This allows you to set and get database values for attributes that exist within your database via the :f:`xGetAttr` and :f:`vSetAttr` functions. 2. To generate transient data that would not be stored permanently within the database. This provides you with the ability to highlight data and provide immediate feedback to the users when they execute your script. 3. to add raw data straight into the database. A generic, all purpose, add to database functionality provided by the :f:`vAddGeometry`. In general, most script writers will only concern themselves with Item 1 and modifying their attributes via the `Attribute Functions`_. The remaining items are fairly complex and are not expected to be within the realm of every script writer. --------- Functions --------- The functions can be divided into three main groups, 1. `Attribute Functions`_ 2. `Transient Data Functions`_ 3. `Raw Database Interaction`_ Attribute Functions ------------------- Provides access to the attributes within the database directly. :df:`sGetAttrType(cutgeomkey, attrname)` Returns the attribute type for the given attribute name for a given geometry cut key. This will return a string that can be one of the following geomview constants, * :d:`INTEGER_ATTR` * :d:`DOUBLE_ATTR` * :d:`STRING_ATTR` If the attribute type is not found or not one of the above types, then the Python :a:`None` will be returned. :df:`xGetAttr(cutgeomkey, attrname)` Retrieves the value for the given geometry. If the attribute name is not valid for the particular cut, then the Python :a:`None` will be returned. :df:`vSetAttr(cutgeomkey, attrname, value)` Sets the value for a given attribute. If the attribute name does not exist within the geometry view of the database, then this function does nothing. If the type for the value is not the same as the type for the attribute then this function will generate a :e:`TypeError` exception. One way to to help ensure that you are always inputting the correct attribute, is to wrap your input value with either one of the python built-in functions :f:`str`, :f:`int`, or :f:`float` functions [#python-lib-builtin-func]_. For example, consider that you want to set a "length" attribute that is of type :d:`DOUBLE_ATTR`, .. Python:: val = "1.2" geomview.vSetAttr(cut['geomkey'], "length", float(val)) notice that the :a:`val` is a string, but by wrapping it with the :f:`float` built-in function, we can call on Python to attempt to make sure the input value is of the right type. If a custom attribute exists, but is not part of the given IP Plan, then a :e:`ValueError` is generated indicating what custom attribute can not be accessed correctly. Ensure your IP Plan has the custom attribute added to its list of attributes and attempt to call this function again. .. Note:: That setting the the attribute within the database *does not* update the *Reserves Dictionary*. The reserves dictionary is initialized once per script execution only, and then acts as a read-only entity during the lifetime of the script. :df:`vRefreshStyling()` Refreshes the cut styling of the geometry view. Use this after modifying the values of the cutoff styling attribute to update the styling for all cuts. This is the equivilent of clicking Edit->Refresh Styling in the Cut Design dialog. Transient Data Functions ------------------------ :df:`vAddTransMarker(geomview, x, y, z)` Adds a transient marker to the position specificed by :a:`x`, :a:`y` and :a:`z`. :df:`vAddTransLine(geomview, x0, y0, z0, x1, y1, z1)` Adds a transient line to the geometry view. The start points are specified by :a:`x0`, :a:`y0`, :a:`z0`, and the end points are specified by :a:`x1`, :a:`y1`, :a:`z1`. :df:`vAddTransText(geomview, x, y, z, text)` Adds the transient :a:`text` to the geometry view at :a:`x`, :a:`y`, :a:`z`. :df:`vFlushTrans(geomview)` Flushes the transient contents of the geometry view out to the viewer. Raw Database Interaction ------------------------ .. Warning:: The usage of this of this function is highly dependent on the internal knowledge of the MineSightŪ-3D and MineSightŪ Interactive Planner systems. It is not expected that script writer's know or understand all the details described below. :df:`vAddGeometry(objectid, segmentid, exposed, force, geom)` This performs a raw, direct dump of data into the database. You will not see any results in the viewer. The behavior of this function is fundamentally different from the other modules. The :a:`objectid` is the name of the Plan that you wish to add the geometry to. The :a:`segementid` correpsonds to the name of the new geometry you wish to insert at the given :a:`objectid`. If the :a:`segmentid` is blank, then a new on will be generated. The :a:`exposed` is a suggestion on wheter to expose the points (1) or to store the points as a blob. As of v3.60, this is a merely a suggestion, and may or may not be heeded. If the :a:`force` flag is set to true (1), and there is already a geometry with the given :a:`segementid` and :a:`objectid` defined, then the new geometry will replace the existing one. :a:`geom` is a dictionary that should have the following key, value pair layout. :a:`Type` Can be either one of the following strings: "Polyline", "Polygon" "Marker", and "Shell". String value is case sensitive. :a:`Attributed` 1 if it is attribute 0 otherwise. :a:`PointList` A list of point triplets of the form:: [[x0, y0, z0], ..., [xN, yN, zN]] :a:`FaceList` A list of vertex indice triples. In the form:: [[v0_0, v0_1, v0_2], ..., [vN_M, ...]] where each triplet corresponds to a face. You can use the :f:`agdm.agdmfl_from_fl` and :f:`agdm.agdmfl_as_fl` routines found in grail.agdm_ to help convert between the facelist used in grail.ag_ and the one used here. See the `Face List Helper Functions`_ section in the grail.agdm_ documentation. .. _grail.agdm: ../grail.data/lib-grail-data-agdm.html .. _Face List Helper Functions: ../grail.data/lib-grail-data-agdm.html#face-list-helper-functions .. _grail.ag: ../lib-grail-ag.html :a:`NumFaces` The length of the list supplied to :a:`FaceList`. :a:`NumPoints` The length of the list supplied to :a:`PointList`. :a:`Planar` Set to 1 if the geometry is planar, otherwise set to 0. :a:`NumAttr` Number of attributes in the :a:`AttrList`. :a:`AttrList` A list of attribute dictionaries. Each attribute dictionary should have the following key, value pairs, :a:`Name` Name of the attribute :a:`Type` Type of the attribute. This can be one of the following strings: "String", "Real", "Integer". Type values are case sensitive. :a:`Value` Value for the attribute. The *type* of value should match the type specified for :a:`Type`. You may find that the `Geometry Dictionary Helper Functions`_ and helper functions found in grail.agdm_ .. _Geometry Dictionary Helper Functions: ../grail.data/lib-grail-data-agdm.html#geometry-dictionary-helper-functions --------- Constants --------- :dd:`INTEGER_ATTR` Indicates that a given attribute is an Integer Type. :dd:`DOUBLE_ATTR` Indicates that a given attribute is a Double Type. :dd:`STRING_ATTR` Indicates that a given attribute is a String Type. ---- .. [#python-lib-builtin-func] "Built-in Functions". *Python Library Reference*. 30 May 2003. 23 June 2004.