================================= ``grail.data.agdm`` Module ================================= .. include:: ../../version.h .. warning:: Deprecated as of v5.00. Use `grail.data.pd`_ module instead. .. _grail.data.pd: lib-grail-data-pd.html .. contents:: Table of Contents :backlinks: top -------- Overview -------- Provides access to the Attributed Geometry Data Model (AGDM) stored within a database. The AGDM library consists of a `DB Class`_ and helper `Functions`_ that allow you to read and write data to and from a AGDM Database. The access routines fall into the following broad categories, 1. **Plan** Allows you to define plans within an AGDM. A plan is a collection of geometry segments within the AGDM database. 2. **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. 3. **Attributes** Allows you to read and write attribute values for a given geometry segment. 4. **Attribute Definitions** Allows to you define, delete and check for the existence of attributes within a given AGDM. -------- Examples -------- The follow code snippets illustrate different ways of using the grail.data.agdm module. Each of these snippets come from full example scripts that can be found in the :file:`$(MEDEXE)\\scripts\\samples\\grail.data.agdm` directory. Open/Close AGDM --------------- **Full Sample Script** :file:`$(MEDEXE)\\scripts\\samples\\grail.data.agdm\\ex1-open-close.py`. To open an AGDM DB connection you will require a valid Date Source Name (DSN). .. Python:: # Open the DB db = agdm.DB(DSN_STRING) # Close the DB db.close() While the database is open you can read/write data to and from the database via the :c:`db` object. Add Geometry from a Geometry MSR -------------------------------- **Full Sample Script** :file:`$(MEDEXE)\\scripts\\samples\\grail.data.agdm\\ex2-add-shells.py`. In this example we will add 3D surfaces (SHELLS) from a MineSightŪ Resource (MSR) File into a database defined the :d:`DSN_STRING`. We will be inserting these SHELLS into the plan defined by the :d:`PLAN_NAME`. In the following example the :d:`msrPath` is a valid MSR file with SHELLS. .. Python:: # Open the MSR file msr = geometry.Geometry(msrPath) # Open the DB db = agdm.DB(DSN_STRING) # If our PLAN_NAME is not defined, create it. if not db.plan_exists(PLAN_NAME): db.plan_create(PLAN_NAME) # Read from the MSR and add to the AGDM. numShells = msr.getshellcount() for shellIndex in range(numShells): points = msr.getshellpointsat(shellIndex) faces = msr.getshellfacesat(shellIndex) # AGDM stores face lists differently, use a helper function to convert # it to the proper format. agdmFaces = agdm.agdmfl_from_fl(faces) # Build a AGDM Geometry Dictionary definition. This dictionary is what # will be stored within the AGDM. # # NOTE: That points in the AGDM are stored in "Graphical Coordinates" # (XZY) instead of Cartesian Coordinates (XYZ). So we need to perform # a YZ swap. points = map(lambda (x, y, z): [x, z, y], points) geomdict = agdm.geomdict_create_shell(points, agdmFaces) # Store it within the AGDM. segmentId = db.geom_add(PLAN_NAME, geomdict) # The segmentID is the unique ID used to identify our geometry segment # at a later time. print "Shell #%d added with Segment ID '%s'. " %\ (shellIndex+1, segmentId) # Close the MSR. msr.free() # Close the DB db.close() The basic steps shown above are, 1. Define an AGDM Geometry Dictionary. 2. Store the AGDM Geometry Dictionary into the AGDM. The :f:`agdm.geomdict_xxx` functions have been provided to help make it easier to construct a geometry dictionary based on your data. .. Note:: That the face list structure for the AGDM is different from face list structure found elsewhere in the MSGRAIL library. Use the :f:`agdmfl_to_fl` and :f:`agdmfl_from_fl` functions to help translate between the two different formats. In addition, the points in the AGDM are stored in X, **Z**, Y format, but in the MSR they are stored in X, **Y**, Z format. We have to swap the Y and Z coordinates when adding values into the AGDM. Defining Custom Attributes -------------------------- **Full Sample Script** :file:`$(MEDEXE)\\scripts\\samples\\grail.data.agdm\\ex3-define-custom-attributes.py`. The following example will create a new String attribute called "Attr_Str". .. Python:: # Open the DB db = agdm.DB(DSN_STRING) # To let this example be run multiple times, we will delete any previous # reference to this attribute before we create a new one. if db.attribdef_exists("Attr_Str"): db.attribdef_delete("Attr_Str") # Define a custom STRING attribute with a default blank string "". db.attribdef_create("Attr_Str", agdm.attribSTR, "") # Close the DB db.close() This example also illustrates how you can test for the existence of an attribute via the :f:`attribdef_exists` function, and deleting an attribute definition via the :f:`attribdef_delete` functions. Once you create an attribute all additional segments will have this attribute defined. The segments will also get the default value assigned to them when you read a segment. In this case the default value is a blank string (""). Attribute definitions are done via the :f:`attribdef` family of methods on the :c:`DB` class. Setting Custom Attributes ------------------------- **Full Sample Script** :file:`$(MEDEXE)\\scripts\\samples\\grail.data.agdm\\ex4-setting-custom-attributes.py` Continuing from our `Add Geometry from a Geometry MSR`_ example we will read from a geometry MSR file and add shells with a custom attribute "Attr_Str". In the following example, we will use the :f:`geomdict_set_attrib` helper function to add an attribute to the geometry dictionary. This geometry dictionary will be stored within the AGDM. This example assumes you have already defined an attribute called "Attr_Str". .. Python:: # Read from the MSR and add to the AGDM. numShells = msr.getshellcount() for shellIndex in range(numShells): points = msr.getshellpointsat(shellIndex) faces = msr.getshellfacesat(shellIndex) # AGDM stores face lists differently, use a helper function to convert # it to the proper format. agdmFaces = agdm.agdmfl_from_fl(faces) # Build a AGDM Geometry Dictionary definition. This dictionary is what # will be stored within the AGDM. # # NOTE: That points in the AGDM are stored in "Graphical Coordinates" # (XZY) instead of Cartesian Coordinates (XYZ). So we need to perform # a YZ swap. points = map(lambda (x, y, z): [x, z, y], points) geomdict = agdm.geomdict_create_shell(points, agdmFaces) # Set an Attribute by adding the definition to the geometry dictionary. agdm.geomdict_set_attrib( geomdict, agdm.attribSTR, "Attr_Str", "MyExample" ) # Store it within the AGDM. segmentId = db.geom_add(PLAN_NAME, geomdict) # Setting an attribute on an existing segment db.attrib_set(PLAN_NAME, segmentId, "Attr_Str", "SettingANewValue") At the end of this script we use the :f:`attrib_set` function to illustrate setting attributes on an existing geometry. To summarize, there are two ways to set an custom attribute on a geometry segment within the AGDM, 1. **With a New Segment** When you have a new geometry segment, adding the attribute to the geometry dictionary definition is by far the most efficient way to set attributes. The :d:`geomdict_set_atttrib` helper function makes it easy to add attributes to a geometry dictionary. 2. **With an Existing Segment** When you are working with existing segments, then you will set the attributes using the :f:`attrib_set` function on the existing :c:`DB` object. Iterating through All Geometries in a Plan ------------------------------------------ **Full Sample Script** :file:`$(MEDEXE)\\scripts\\samples\\grail.data.agdm\\ex5-iterate-through-geometries-in-a-plan.py` To iterate you need to get a listing of segment IDs for a given plan. The segment IDs can be retrieved via the :c:`DB` object's :f:`geom_listing` function. The following example illustrates iterating through all geometry segments within the AGDM. .. Python:: # Iterating through all the geometries in our plan. segmentIdListing = db.geom_listing(PLAN_NAME) for segmentId in segmentIdListing: geomDict = db.geom_get(PLAN_NAME, segmentId) attr = db.attrib_get(PLAN_NAME, segmentId, "Attr_Str") Working with the Date Field --------------------------- **Full Sample Script** :file:`$(MEDEXE)\\scripts\\samples\\grail.data.agdm\\ex6-date-fields.py` .. Note:: In order to work with Date Fields you will require an attribute database version 1.7 or greater. This database was released with v3.60 of MineSightŪ. Date fields within the geometry are described in detail in the `Data Definitions`_ `Date`_ section. The following example illustrates how to assign the current date to a Date Field within the AGDM while inserting geometry objects from a MSR (continuing from our `Add Geometry from a Geometry MSR`_ example). .. Python:: # Setting a CURRENT DATE attribute. First we need to get the current # time, then we need to convert it to a DateStr formatted for the # AGDM. now = time.gmtime() dateStr = agdm.date_from_tuple(now) # Set an Attribute by adding the definition to the geometry dictionary. agdm.geomdict_set_attrib( geomdict, agdm.attribDATE, "Attr_Date", dateStr ) Use the :f:`date_from_tuple` function to convert the tuple date representation returned by `time.gmtime`. In order to convert a AGDM Date string back to a tuple you can use the :f:`date_to_tuple` function. One helpful function is the :f:`date_utc_now` function which returns an AGDM Date string based on the current time in Universal Time Coordinates (UTC). -------- DB Class -------- This class provides the main access point for all database actions. class :dc:`DB(dsnString)` Opens a database connection to the Attributed Geometry Data Model (AGDM) defined by the given :a:`dsnString`. This will raise an :e:`IOError` if the :a:`dsnString` does not exist or if the :a:`dsnString` points to database that is not an AGDM. It will raise a :e:`ValueError` if the :a:`dsnString` supplied is not a valid string for a DSN. .. Note:: That you can supply and ODBC Connection String as long as that ODBC connection string has a :d:`DSN=` defined within it. The database routine is smart enough to extract the :a:`dsnName` out of the ODBC Connection String. Once you have a :c:`DB` object connected you can manipulate the contents of the AGDM through the one of following family of methods, 1. **attrib** methods These are concerned with setting and getting attribute values for a given geometry segment within a given plan. 2. **attribdef** methods These are concerned with manipulating attribute definitions. 3. **geom** methods These are concerned with manipulating geometry segments. 4. **plan** methods These are concerned with manipulating plans within the AGDM. These categories and a few other extra methods are defined below. :df:`attrib_get(planName, segId, attribName)` Deprecated alias: :f:`getattribsid` Returns the attributed value for the given segment ID, :a:`segId`, within the given :a:`planName`. If the :a:`attribName` does not exist and :e:`IndexError` is generated. If the AGDM is closed, an :e:`IOError` is generated. :df:`attrib_set(planName, segId, attribName, value)` Sets an attribute :a:`value` for the given :a:`attribName` on the segment defined by the :a:`segId` within the :a:`planName`. If the :a:`planName`, :a:`segId` or :a:`attribName` are invalid or do not exist, then this function will raise an :e:`IOError`. A :e:`ValueError` will be generated if the **type** of the `value` is not valid for the given :a:`attribName`. :df:`attribdef_create(name, type, defaultValue)` Deprecated alias: :df:`createattribtype(name, type, defaultValue)` Creates an attribute definition in the AGDM that can be set in subsequent calls for other geometry items. To create an attribute definition you will need to, 1. Specify a string for the :a:`name`. 2. Specify a :a:`type` that is either :d:`attribSTR` for a string type, :d:`attribINT` for an integer type, :d:`attribFLT` for a floating point type, or a :d:`attribDATE` for a date field. 3. Specify a :a:`defaultValue`. This is the value that the attribute should have when no value is specified. This value will **not** be added automatically when you add a geometry segment. Think of this as a convenient storage location that you can query via the :f:`attribdef_get_default` function if you need to find a value, and explicitly set on your geometry segment. If you specify a blank string, (""), for an :d:`attribDATE` field, the default value will be equal to the value :d:`DEFAULT_DATE`. If the :a:`name` already exists within the database a :e:`ValueError` will be generated. Try removing the attribute definition and re-adding it again if you want a new format for your attribute definition. Use the :f:`attribdef_exists` method to determine if an attribute definition already exists with the given :a:`name`. If the :a:`defaultValue` is not of the same type as the :a:`type` ( for example, you are using a Integer when trying to create a :d:`attribFLT` :a:`type`), then a :e:`ValueError` will be generated. If the database is already closed, an :e:`IOError` will be generated. If you attempt to create a :d:`attribDATE` field for a database version that lacks this type, an :e:`IOError` will be generated. You can use the :f:`is_date_field` to verify that you database can have :d:`attribDATE` fields in it. If you supply a blank string for a :d:`attribDATE` field, it will get a :a:`defaultValue` defined by :d:`DEFAULT_DATE`. The :a:`defaultValue` for an :d:`attribDATE` field will not be validated as something feasible. In other words, you will need to ensure that your default date field is a workable field. See the `Data Definitions`_ `Date`_ section for more details. In other words, you will need to ensure that your default date field is a workable field. See the `Data Definitions`_ `Date`_ section for more details. `df:`attribdef_delete(attribName)` Deprecated alias: :f:`deleteattribtype`. Deletes the attribute defined by the :a:`attribName`. If the :a:`attribName` is not defined for the AGDM, an :e:`IndexError` is generated. If the AGDM is closed or if there is a problem deleting the attribute an :e:`IOError` is generated. .. Warning:: Deleting an Attribute Definition will remove any reference to the attribute in every geometry segment within every plan. Be careful if you decide to use this. :df:`attribdef_exists(attribName)` Returns true (1) if the given :a:`attribName` exists as an attribute name within the AGDM. :df:`attribdef_get_type(attribName)` Returns the type specified by the given :a:`attribName`. The type will be one of the "attrib" values defined in the `Constants`_ section. :df:`attribdef_get_default(attribName)` Returns the default value that is specified by the given :a:`attribName`. :df:`attribdef_listing()` Deprecated alias: :df:`getattribtypes`. Returns a list of attribute dictionaries as defined in the `Attribute Definition Dictionary`_ section above. :df:`geom_add(planName, geometryDict)` Will take a :a:`geometryDict` as defined in the `Geometry Dictionary`_ section and store it within the given :a:`planName`. It will return a string with the new segment ID for this geometry. You can then use this segment ID to modify attributes associated with the geometry object. As an example, consider this following code snippet that creates a marker dictionary, sets an attribute and creates it within the dictionary. The following example assumes that you have a plan called "MyPlanName" and an attribute called "MyIntAttrib". .. Python:: db = agdm.DB(mydsnString) x = 1 y = 2 z = 3 pointList = [[x, z, y]] # Notice the YZ Swap. markerDict = geomdict_create_marker(pointList) geomdict_set_attrib(markerDict, attribINT, "MyIntAttrib", 1) segmentId = db.geom_add("MyPlanName", markerDict) In this case there will now exist a marker with the properties defined in the :a:`markerDict` in the "MyPlanName" plan. It is important to note that if you do not specify an attribute for your `Geometry Dictionary`_, the default value for your new geometry segment will not be applied. The best method for ensuring default values are applied is to use the :f:`attribdef_get_default` method. To revisit the above example, consider, .. Python:: db = agdm.DB(mydsnString) x = 1 y = 2 z = 3 pointList = [[x, z, y]] # Notice the YZ Swap. markerDict = geomdict_create_marker(pointList) # Query the DB to find out the default value for the "MyIntAttrib" # attribute. geomdict_set_attrib( markerDict, attribINT, "MyIntAttrib", db.attribdef_get_default("MyIntAttrib") ) segmentId = db.geom_add("MyPlanName", markerDict) This method is a simplified version of :f:`geom_set`. :df:`geom_set(planName, segId, isExposed, isForce, geomDict)` Deprecated alias: :df:`creategeomtrysid()` This is the advanced geometry method. Prefer to use :f:`geom_add` over this method if all you want to do is add a new geometry item. If you want to overwrite an existing item, then you will need to use this method. It will set a geometry and return a segment ID as a string. The arguments are as follows, :a:`planName` : string The name of the plan that will receive the geometry. :a:`segId` : string Allows you to specify the segment ID that you want to use for the geometry. If you leave this value as a blank string ("") one will be assigned to you. If you specify :a:`isForce` equal to true (1), then this will override an existing geometry. .. Note:: You can only either specify an existing segment ID (:a:`segId`) or a blank segment ID. Where a blank segment ID indicates that one will be assigned to you as a return value. :a:`isExposed`: integer Set this to 1 (true) if you want the point data to be stored in an accessible format. Setting this to 0 (false) will imply that you want to store the point data as one big binary chunk. It is important to note that as of v3.60 :a:`isExposed` is merely a suggestion, and will be overridden based on the geometry type supplied. The recommended value for :a:`isExposed` should always be 1. :a:`isForce` : integer Set this to 1 (true) if you want to force a creation of a geometry at the given :a:`segId`. Set this to false to not have it create a geometry at the given :a:`segId`. :a:`geomDict` : dictionary Defines the geometry via the `Geometry Dictionary`_. This method will generate an :e:`IOError` if you attempt to create a geometry at an existing :a:`segId` and :a:`isForce` is set to false (0). This method will also generate an :e:`IOError` if the database is closed. :df:`geom_exists(planName, segementID)` Returns true (1) if there exists a `Geometry Dictionary`_ at the given :a:`planName` and :a:`segmentID`. :df:`geom_get(planName, segmentId)` Returns a geometry dictionary for the contents defined by the :a:`planName` and :a:`segmentId`. For efficiency reasons this will only return the geometry data (for example, point list, face list, and type). In order to query for an attribute use the :f:`attrib_get`. :df:`geom_listing(planName)` Deprecated alias: :f:`getplansid` Returns a list of segment IDs for a given `planName`. If the `planName` does not exist within the database this will generate an :e:`IndexError`. If the database is closed, this will generate an :e:`IOError`. An empty list is returned if no segment IDs exist within the `planName`. :df:`get_connection_str()` Deprecated alias: :df:`getconnstr()` Returns the string that was used to connect to the AGDM. For example, if our supplied DSN was for an access database, we would have a connection string that appeared similar to the following, :: ODBC;DSN=TESTDB;DBQ=c:/mydb/TESTDB.mdb;DriverId=25;FIL=MS Access;MaxBufferSize=2048;PageTimeout=5; :df:`get_version()` Deprecated alias: :f:`getdbversion()` Returns some underlying version information for the AGDM as a string. For example, :: Geomview:1-7, IPCore:1-3 The *Geomview* version refers to the version of the AGDM schematics, whereas, the *IPCore* refers to the version of the MSIP data schematics. :df:`is_date_field()` Returns true (1) if the database is capable of handling a Date Field. :df:`plan_create(planName[,type])` Takes a :a:`planName` string and an optional :a:`type` string arguments and creates a new plan within the AGDM. The :a:`type` is used to distinguish between different plans such as a IP Scheduling Pln (:d:`typeIP_PLAN`) or a Haulage Network Plan (:d:`typeHAUL_PLAN`). If you don't know what these values are, then the default value used here (:d:`typeDEFAULT_PLAN`) will suffice. If the database is closed, this function will generate an :e:`IOError`. If the :a:`planName` already exists in the AGDM, an :e:`IOError` will be generated. :df:`plan_delete(planName)` Deprecated alias: :f:`deleteplan` Deletes the given :a:`planName` within the AGDM. If the :a:`planName` does not exist within the AGDM an :e:`IndexError` is generated. If the AGDM is closed an :e:`IOError` is raised. :df:`plan_exists(planName)` Returns true (1) if the given :a:`planName` exists with the AGDM. :df:`plan_listing()` Deprecated alias: :df:`getplans()`. Returns a list of Plan Dictionaries that can be iterated across. See the `Plan Dictionary`_ section for a description of the dictionaries key-value pairs. If the database is closed, this function will generate an :e:`IOError`. The following methods are deprecated, prefer to use the alternate values. These methods have different signatures so they couldn't be "aliased" to the new definitions. :df:`createplan(planDictionary)` Deprecated as of v3.60, prefer to use :f:`plan_create`. :df:`setattribsid(planName, segId, key, type, value, isForce)` Deprecated as of v3.60, prefer to use :f:`attrib_set`. :df:`getatttribtypesid(planName, segId)`: Deprecated as of v3.60, prefer to use the set of :f:`attribdef` methods instead. --------- Functions --------- Face List Helper Functions -------------------------- :f:`agdmfl_from_fl(faceList)` Converts the standard face list, :a:`faceList`, into an AGDM face list as per the `AGDM Data Definitions`_ (`AGDM Face List`_). :f:`agdmfl_as_fl(agdmFaceList)` Converts the AGDM face list, :a:`agdmFaceList`, to a standard face list as per the `AGDM Data Definitions`_ (`Face Lists`_). Date Helper Functions --------------------- :f:`date_from_tuple(tupleTime)` Returns an AGDM Date string defined in the `AGDM Data Definitions`_ that can be stored in the AGDM under the date field, :d:`attribDATE`. The :a:`tupleTime` should have the same format as the time tuple used within Python's ``time`` module [#python-lib-time]_. :f:`date_as_tuple(agdmDateStr)` Converts the AGDM date string, :a:`agdmDateStr`, into a time tuple as defined by Python's ``time`` module [#python-lib-time]_. Use this function to convert results read from AGDM date field, as defined by :d:`attribDATE`. :f:`date_utc_now()` Returns an AGDM date string for the time NOW in UTC. Geometry Dictionary Helper Functions ------------------------------------ :f:`geomdict_create_marker(pointlist[, is_planar])` Returns a `Geometry Dictionary`_ configured for markers as defined by the :a:`pointlist`. The :a:`isPlaner` value is set to false (0) by default. To add attributes prefer to use the :d:`geomdict_set_attrib` function described below. See `AGDM Data Definitions`_ for a discussion on how the :a:`pointlist`. :f:`geomdict_create_polyline(pointlist[, is_planar])` Returns a `Geometry Dictionary`_ configured for a polyline as defined by the :a:`pointlist`. The :a:`isPlaner` value is set to false (0) by default. To add attributes prefer to use the :d:`geomdict_set_attrib` function described below. See `AGDM Data Definitions`_ for a discussion on how the :a:`pointlist`. :f:`geomdict_create_polygon(pointlist[, is_planar])` Returns a `Geometry Dictionary`_ configured for a polygon as defined by the :a:`pointlist`. The :a:`isPlaner` value is set to false (0) by default. To add attributes prefer to use the :d:`geomdict_set_attrib` function described below. See `AGDM Data Definitions`_ for a discussion on how the :a:`pointlist`. :f:`geomdict_create_shell(pointlist, agdmFaceList, [, is_planar])` Returns a `Geometry Dictionary`_ configured for a shell as defined by the :a:`pointlist` and :a:`agdmFaceList`. The :a:`isPlaner` value is set to false (0) by default. To add attributes prefer to use the :d:`geomdict_set_attrib` function described below. See `AGDM Data Definitions`_ for a discussion on how the :a:`pointlist` and :a:`agdmFaceList` values should be formatted. .. Warning:: The :a:`agdmFaceList` is different from the standard face list format. You should use the :f:`agdmf_as_fl` and :f:`agdmfl_from_fl` functions to convert between the standard and the AGDM format. :f:`geomdict_set_attrib(geomdict, type, name, value)` Sets an attribute value into the :a:`geomdict` specified. This takes care to manage the attribute list in the :a:`geomdict`. It is the *preferred way to set attributes* on a `Geometry Dictionary`_. If an attribute is already set with a :a:`name` that has been previously set, then this value will replace the :a:`name` with the new :a:`value`. This function *does not verify* that the :a:`name` is a valid attribute name for the given AGDM. Since, at this point, there is no relationship between this dictionary and the AGDM, there is no way to ensure a valid :a:`name` for the attribute. However, you are free to validate via the :f:`attribdef_exists` method on the :c:`DB` class (see `DB Class`_). This function assumes that the :a:`geomdict` is properly formed. If the :a:`geomdict` came from :f:`geomdict_create_marker`, :f:`geomdict_create_polyline`, &etc, then it will be properly formed. The following example hopefully illustrates the :f:`geomdict_set_attrib` usage, .. code-block-incl:: Python :file: ..\..\..\grail\test\agdmtest.py :start: Start_SetAttrib_Ex :end: End_SetAttrib_Ex where the results will be a `Geometry Dictionary`_ with the new attributes, .. Python:: { 'AttrList': [{'Type': 'Integer', 'Name': 'MyIntAttrib', 'Value': 10}, {'Type': 'String', 'Name': 'MyStrAttrib', 'Value': 'Test'}], 'Attributed': 1, 'FaceList': [], 'NumAttr': 2, 'NumFaces': 0, 'NumPoints': 1, 'Planar': 0, 'PointList': [[1, 2, 3]], 'Type': 'Marker' } Notice that the *MyIntAttrib* value was replaced, not added into the existing attribute list within the `Geometry Dictionary`_. --------- Constants --------- These "attrib" constants are used to define the different "type" of attributes that you can define, :d:`attribSTR` Defines a String attribute type. :d:`attribINT` Defines an Integer attribute type. :d:`attribFLT` Defines a Float attribute type. :d:`attribDATE` Defines a Date attribute type. Although this value is a string it has a very special format outlined in the `AGDM Data Definitions`_. This is only available in the v1.3/1.7 or greater AGDM databases. The v1.3/1.7 AGDM database was released alongside v3.60 of MineSightŪ. You can use the :f:`is_date_field` method on the `DB Class`_ to determine if a database is capable of handling date fields. The following "key" constants are typically used in defining the keys for the `Plan Dictionary`_: .. include:: agdm-plan-dict.h These "key" constants are used to access the contents of the `Attribute Definition Dictionary`_, .. include:: agdm-attrib-dict.h Finally, these "key" constants are used to access the contents of the `Geometry Dictionary`_, .. include:: agdm-geom-dict.h The "type" constants are used to define the two popular types of plans. In general you should not have to worry about these, and prefer to use the :d:`typeDEFAULT_PLAN` whenever possible, :d:`typeIP_PLAN` Defines an IP Scheduling Plan. :d:`typeHAUL_PLAN` Defines a Haulage Network plan. :d:`typeDEFAULT_PLAN` Value used as a default when no type is defined (""). The following values are defaults, :d:`DEFAULT_DATE` Value used when a date field default value is not defined. --------------------- AGDM Data Definitions --------------------- * `Data Definitions`_ * `AGDM Face List`_ * `Date`_ * `Face Lists`_ * `Points`_ * `Point Lists`_ * `Dictionary Definitions`_ * `Plan Dictionary`_ * `Attribute Definition Dictionary`_ * `Geometry Dictionary`_ Data Definitions ---------------- Data within the AGDM can be broken down into the following types. AGDM Face List .............. These are a slight variation on the `Face Lists`_. Instead of a single list, this will be a list of lists, where each sub-list contains three elements. So for example, the standard face list shown above, [**3**, 1, 2, 3, **3**, 4, 5, 6] would become, [ [1, 2, 3], [4, 5, 6] ] The :f:`agdmf_as_fl` and :f:`agdmfl_from_fl` functions to help convert between the standard format and the AGDM format for face lists. Date .... Within the AGDM 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, 1. A date format of: **DD-MMM-YYYY**. Acceptable delimiters between fields can be either: -, /, or \\. 2. 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 1-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 :f:`date_from_tuple` and :f:`date_as_tuple` functions are provided to allow easy conversion between the AGDM Date Field and the standard time tuple as defined by the Python ``time`` [#python-lib-time]_. module. Face Lists .......... All face lists are described such that the first index indicates how many faces are in the face. For example, [**3**, 1, 2, 4, **3**, 3, 4, 5, 6] States that there are 3 vertexes in the first face, and those vertexes are 1, 2, 3. Then the next face contains 3 vertexes, which are 4, 5, 6. This may seem a bit confusing, but using this structure buys us some definite efficiencies. .. Note:: In the AGDM module the standard format for face lists are specified by the term **AGDM Face Lists** (see above). This module provides the :f:`agdmf_as_fl` and :f:`agdmfl_from_fl` helper functions to make conversion between the two easier. Points ...... A list of co-ordinates, defined as: [x, **z**, **y**]. That points are stored "as is" within the AGDM. When MS3D reads data from the AGDM, it reads it assuming a "graphical" coordinate system. This is a graphical format that allows us to quickly render data to the MS3D viewer. In a "graphical" coordinate system a cartesian system would appear as [x, **z**, y]. So prior to inserting data you should perform what is known as a "YZSwap". See also the FAQ_ for `How can I quickly swap y,z coordinates within a point list?`_ .. _How can I quickly swap y,z coordinates within a point list?: ../../05_Faq.html#q-how-can-i-quickly-swap-y-z-coordinates-within-a-point-list Point Lists ........... A list of points, defined as: [[x0, **z0**, **y0**], ..., [xN, **zN**, **yN**]]. That points are stored "as is" within the AGDM. When MS3D reads data from the AGDM, it reads it assuming a "graphical" coordinate system. This is a graphical format that allows us to quickly render data to the MS3D viewer. In a "graphical" coordinate system a cartesian system would appear as [x, **z**, y]. So prior to inserting data you should perform what is known as a "YZSwap". See also the FAQ_ for `How can I quickly swap y,z coordinates within a point list?`_ Dictionary Definitions ---------------------- Throughout this module you will need to construct or work with python dictionary for passing information back and forth. This module has constants prefixed with *key* for the dictionary keys, and helper functions for creating those dictionaries. The following sections describe the main dictionaries that you will need to work with. In general you should not have to work with a dictionary directly. You should prefer to use the helper functions defined in the AGDM module. Plan Dictionary ............... The key value pairs for a Plan Dictionary are as follows. .. include:: agdm-plan-dict.h Attribute Definition Dictionary ............................... This dictionary is used to define an attribute type within the AGDM. The key value pairs for this dictionary are, .. include:: agdm-attrib-dict.h Most of the time you shouldn't have to work with this dictionary directly, and instead should prefer to use the :f:`geomdict_` functions defined in the Functions_ section. Geometry Dictionary ................... This dictionary is used to define a geometry object to store within the AGDM. You should prefer to use the :f:`geomdict_` functions described in the `Functions`_ section to easy composing a Geometry Dictionary. The key value pairs for this dictionary are, .. include:: agdm-geom-dict.h --------- Reference --------- .. [#python-lib-time] "time -- Time access and conversionss" *Python Library Reference*. 21 December 2001. 30 January 2007. .. ----- .. LINKS .. ----- .. _FAQ: ../../05_Faq.html .. _How can I quickly swap y,z coordinates within a point list: ../../05_Faq.html#q-how-can-i-quickly-swap-y-z-coordinates-within-a-point-list