`grail.data.agdm` Module

Version: 16.2

Warning

Deprecated as of v5.00. Use grail.data.pd module instead.

Table of Contents

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,

Plan

Allows you to define plans within an AGDM. A plan is a collection of geometry segments within the AGDM 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 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 $(MEDEXE)\scripts\samples\grail.data.agdm directory.

Open/Close AGDM

Full Sample Script

$(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).

# 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 db object.

Add Geometry from a Geometry MSR

Full Sample Script

$(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 DSN_STRING. We will be inserting these SHELLS into the plan defined by the PLAN_NAME. In the following example the msrPath is a valid MSR file with SHELLS.

# 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,

Define an AGDM Geometry Dictionary.

Store the AGDM Geometry Dictionary into the AGDM.

The 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 agdmfl_to_fl and 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

$(MEDEXE)\scripts\samples\grail.data.agdm\ex3-define-custom-attributes.py.

The following example will create a new String attribute called "Attr_Str".

# 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 attribdef_exists function, and deleting an attribute definition via the 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 attribdef family of methods on the DB class.

Setting Custom Attributes

Full Sample Script

$(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 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".

# 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 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,

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 geomdict_set_atttrib helper function makes it easy to add attributes to a geometry dictionary.

With an Existing Segment

When you are working with existing segments, then you will set the attributes using the attrib_set function on the existing DB object.

Iterating through All Geometries in a Plan

Full Sample Script

$(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 DB object's geom_listing function. The following example illustrates iterating through all geometry segments within the AGDM.

# 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

$(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).

# 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 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 date_to_tuple function.

One helpful function is the 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 DB(dsnString)

Opens a database connection to the Attributed Geometry Data Model (AGDM) defined by the given dsnString. This will raise an IOError if the dsnString does not exist or if the dsnString points to database that is not an AGDM. It will raise a ValueError if the 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 DSN= defined within it. The database routine is smart enough to extract the dsnName out of the ODBC Connection String.

Once you have a DB object connected you can manipulate the contents of the AGDM through the one of following family of methods,

attrib methods

These are concerned with setting and getting attribute values for a given geometry segment within a given plan.

attribdef methods

These are concerned with manipulating attribute definitions.

geom methods

These are concerned with manipulating geometry segments.

plan methods

These are concerned with manipulating plans within the AGDM.

These categories and a few other extra methods are defined below.

attrib_get(planName, segId, attribName)

Deprecated alias: getattribsid

Returns the attributed value for the given segment ID, segId, within the given planName.

If the attribName does not exist and IndexError is generated. If the AGDM is closed, an IOError is generated.

attrib_set(planName, segId, attribName, value)

Sets an attribute value for the given attribName on the segment defined by the segId within the planName.

If the planName, segId or attribName are invalid or do not exist, then this function will raise an IOError. A ValueError will be generated if the type of the value is not valid for the given attribName.

attribdef_create(name, type, defaultValue)

Deprecated alias: 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,

Specify a string for the name.

Specify a type that is either attribSTR for a string type, attribINT for an integer type, attribFLT for a floating point type, or a attribDATE for a date field.

Specify 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 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 attribDATE field, the default value will be equal to the value DEFAULT_DATE.

If the name already exists within the database a 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 attribdef_exists method to determine if an attribute definition already exists with the given name.

If the defaultValue is not of the same type as the type ( for example, you are using a Integer when trying to create a attribFLT type), then a ValueError will be generated.

If the database is already closed, an IOError will be generated.

If you attempt to create a attribDATE field for a database version that lacks this type, an IOError will be generated. You can use the is_date_field to verify that you database can have attribDATE fields in it. If you supply a blank string for a attribDATE field, it will get a defaultValue defined by DEFAULT_DATE.

The defaultValue for an 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: deleteattribtype.

Deletes the attribute defined by the attribName. If the attribName is not defined for the AGDM, an IndexError is generated. If the AGDM is closed or if there is a problem deleting the attribute an 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.

attribdef_exists(attribName)

Returns true (1) if the given attribName exists as an attribute name within the AGDM.

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_get_default(attribName)

Returns the default value that is specified by the given attribName.

attribdef_listing()

Deprecated alias: getattribtypes.

Returns a list of attribute dictionaries as defined in the Attribute Definition Dictionary section above.

geom_add(planName, geometryDict)

Will take a geometryDict as defined in the Geometry Dictionary section and store it within the given 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".

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 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 attribdef_get_default method. To revisit the above example, consider,

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 geom_set.

geom_set(planName, segId, isExposed, isForce, geomDict)

Deprecated alias: creategeomtrysid()

This is the advanced geometry method.

Prefer to use 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,

planName : string

The name of the plan that will receive the geometry.

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 isForce equal to true (1), then this will override an existing geometry.

Note

You can only either specify an existing segment ID (segId) or a blank segment ID. Where a blank segment ID indicates that one will be assigned to you as a return value.

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 isExposed is merely a suggestion, and will be overridden based on the geometry type supplied.

The recommended value for isExposed should always be 1.

isForce : integer

Set this to 1 (true) if you want to force a creation of a geometry at the given segId. Set this to false to not have it create a geometry at the given segId.

geomDict : dictionary

Defines the geometry via the Geometry Dictionary.

This method will generate an IOError if you attempt to create a geometry at an existing segId and isForce is set to false (0). This method will also generate an IOError if the database is closed.

geom_exists(planName, segementID)

Returns true (1) if there exists a Geometry Dictionary at the given planName and segmentID.

geom_get(planName, segmentId)

Returns a geometry dictionary for the contents defined by the planName and 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 attrib_get.

geom_listing(planName)

Deprecated alias: getplansid

Returns a list of segment IDs for a given planName. If the planName does not exist within the database this will generate an IndexError. If the database is closed, this will generate an IOError.

An empty list is returned if no segment IDs exist within the planName.

get_connection_str()

Deprecated alias: 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;

get_version()

Deprecated alias: 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.

is_date_field()

Returns true (1) if the database is capable of handling a Date Field.

plan_create(planName[,type])

Takes a planName string and an optional type string arguments and creates a new plan within the AGDM.

The type is used to distinguish between different plans such as a IP Scheduling Pln (typeIP_PLAN) or a Haulage Network Plan (typeHAUL_PLAN). If you don't know what these values are, then the default value used here (typeDEFAULT_PLAN) will suffice.

If the database is closed, this function will generate an IOError. If the planName already exists in the AGDM, an IOError will be generated.

plan_delete(planName)

Deprecated alias: deleteplan

Deletes the given planName within the AGDM. If the planName does not exist within the AGDM an IndexError is generated. If the AGDM is closed an IOError is raised.

plan_exists(planName)

Returns true (1) if the given planName exists with the AGDM.

plan_listing()

Deprecated alias: 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 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.

createplan(planDictionary)

Deprecated as of v3.60, prefer to use plan_create.

setattribsid(planName, segId, key, type, value, isForce)

Deprecated as of v3.60, prefer to use attrib_set.

getatttribtypesid(planName, segId):

Deprecated as of v3.60, prefer to use the set of attribdef methods instead.

Functions

Face List Helper Functions

agdmfl_from_fl(faceList): Converts the standard face list, faceList, into an AGDM face list as per the AGDM Data Definitions (AGDM Face List).
agdmfl_as_fl(agdmFaceList): Converts the AGDM face list, agdmFaceList, to a standard face list as per the AGDM Data Definitions (Face Lists).

Date Helper Functions

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, attribDATE. The tupleTime should have the same format as the time tuple used within Python's time module [1].
date_as_tuple(agdmDateStr): Converts the AGDM date string, agdmDateStr, into a time tuple as defined by Python's time module [1]. Use this function to convert results read from AGDM date field, as defined by attribDATE.
date_utc_now(): Returns an AGDM date string for the time NOW in UTC.

Geometry Dictionary Helper Functions

geomdict_create_marker(pointlist[, is_planar])

Returns a Geometry Dictionary configured for markers as defined by the pointlist. The isPlaner value is set to false (0) by default. To add attributes prefer to use the geomdict_set_attrib function described below.

See AGDM Data Definitions for a discussion on how the pointlist.

geomdict_create_polyline(pointlist[, is_planar])

Returns a Geometry Dictionary configured for a polyline as defined by the pointlist. The isPlaner value is set to false (0) by default. To add attributes prefer to use the geomdict_set_attrib function described below.

See AGDM Data Definitions for a discussion on how the pointlist.

geomdict_create_polygon(pointlist[, is_planar])

Returns a Geometry Dictionary configured for a polygon as defined by the pointlist. The isPlaner value is set to false (0) by default. To add attributes prefer to use the geomdict_set_attrib function described below.

See AGDM Data Definitions for a discussion on how the pointlist.

geomdict_create_shell(pointlist, agdmFaceList, [, is_planar])

Returns a Geometry Dictionary configured for a shell as defined by the pointlist and agdmFaceList. The isPlaner value is set to false (0) by default. To add attributes prefer to use the geomdict_set_attrib function described below.

See AGDM Data Definitions for a discussion on how the pointlist and agdmFaceList values should be formatted.

Warning

The agdmFaceList is different from the standard face list format. You should use the agdmf_as_fl and agdmfl_from_fl functions to convert between the standard and the AGDM format.

geomdict_set_attrib(geomdict, type, name, value)

Sets an attribute value into the geomdict specified. This takes care to manage the attribute list in the geomdict. It is the preferred way to set attributes on a Geometry Dictionary.

If an attribute is already set with a name that has been previously set, then this value will replace the name with the new value.

This function does not verify that the 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 name for the attribute. However, you are free to validate via the attribdef_exists method on the DB class (see DB Class).

This function assumes that the geomdict is properly formed. If the geomdict came from geomdict_create_marker, geomdict_create_polyline, &etc, then it will be properly formed.

The following example hopefully illustrates the geomdict_set_attrib usage,

      from grail.data import agdm
      x = 1
      y = 2
      z = 3

      # Notice YZSwap ------------------------------\--\
      marker_dict = agdm.geomdict_create_marker([[x, z, y]])
      agdm.geomdict_set_attrib(
          marker_dict, agdm.attribINT, "MyIntAttrib", 1
          )
      agdm.geomdict_set_attrib(
          marker_dict, agdm.attribSTR, "MyStrAttrib", "Test"
          )
      agdm.geomdict_set_attrib(
          marker_dict, agdm.attribINT, "MyIntAttrib", 10
          )

where the results will be a Geometry Dictionary with the new attributes,

{
'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,

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 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 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:

keyPLAN_NAME

A string indicating the new plan name.

keyPLAN_TYPE

The type is used to distingush between different plans such as a IP Scheduling Plan (typeIP_PLAN) or a Haulage Network Plan (typeHAUL_PLAN). Typically a default (typeDEFAULT_PLAN) value will suffice.

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. Should be the same as the keyPLAN_DATE_CREATE field.

These "key" 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 an attribute, which can be either one of the following, attribSTR, attribINT, attribFLT, or attribDATE.

keyATTRIB_DEFAULT_VALUE

This is the default value used for this attribute.

Finally, these "key" constants are used to access the contents of the Geometry Dictionary,

keyGEOM_TYPE

This defines the type of marker you can have. Valid values are, geomtypeMARKER, geomtypePOLYLLINE, geomtypePOLYGON, or geomtypeSHELL.

keyGEOM_ATTRIBUTED

Set to true (1) if your dictionary is attributed. If you use the geomdict_* functions, this value will be set automatically when you first apply an attribute. See also Geometry Dictionary Helper Functions.

keyGEOM_POINTLIST

This is the point list used for the geometry. See the Point Lists section in AGDM Data Definitions for more details.

keyGEOM_FACELIST

This is list of vertice indices. Typically used for geomtypeSHELL. See AGDM Data Definitions for more details on face lists.

keyGEOM_NUMPOINTS

The number of elements in the keyGEOM_POINTLIST.

keyGEOM_NUMFACES

The number of elements in the keyGEOM_FACELIST.

keyGEOM_NUMATTR

Indicates the number of attributes within the dictionaries keyGEOM_ATTRLIST.

keyGEOM_PLANAR

Set to true (1) if the geometry is planar. Generally you want to leave this as 0 (false).

keyGEOM_ATTRLIST

This is a list of Attribute Definition Dictionary values corresponding to the attributes for the geometry. Prefer to use the dict_set_attrib function instead to make it easier to manipulate. Set the Functions section.

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 typeDEFAULT_PLAN whenever possible,

typeIP_PLAN

Defines an IP Scheduling Plan.

typeHAUL_PLAN

Defines a Haulage Network plan.

typeDEFAULT_PLAN

Value used as a default when no type is defined ("").

The following values are defaults,

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 agdmf_as_fl and 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,

A date format of: DD-MMM-YYYY. Acceptable delimiters between fields can be either: -, /, or \.

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 date_from_tuple and 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 [1]. module.

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

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 agdmf_as_fl and 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?

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.

keyPLAN_NAME

A string indicating the new plan name.

keyPLAN_TYPE

The type is used to distingush between different plans such as a IP Scheduling Plan (typeIP_PLAN) or a Haulage Network Plan (typeHAUL_PLAN). Typically a default (typeDEFAULT_PLAN) value will suffice.

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. Should be the same as the keyPLAN_DATE_CREATE field.

Attribute Definition Dictionary

This dictionary is used to define an attribute type within the AGDM. The key value pairs for this dictionary are,

keyATTRIB_NAME

A string indicating the attribute's name.

keyATTRIB_TYPE

The type of an attribute, which can be either one of the following, attribSTR, attribINT, attribFLT, or attribDATE.

keyATTRIB_DEFAULT_VALUE

This is the default value used for this attribute.

Most of the time you shouldn't have to work with this dictionary directly, and instead should prefer to use the 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 geomdict_ functions described in the Functions section to easy composing a Geometry Dictionary.

The key value pairs for this dictionary are,

keyGEOM_TYPE

This defines the type of marker you can have. Valid values are, geomtypeMARKER, geomtypePOLYLLINE, geomtypePOLYGON, or geomtypeSHELL.

keyGEOM_ATTRIBUTED

Set to true (1) if your dictionary is attributed. If you use the geomdict_* functions, this value will be set automatically when you first apply an attribute. See also Geometry Dictionary Helper Functions.

keyGEOM_POINTLIST

This is the point list used for the geometry. See the Point Lists section in AGDM Data Definitions for more details.

keyGEOM_FACELIST

This is list of vertice indices. Typically used for geomtypeSHELL. See AGDM Data Definitions for more details on face lists.

keyGEOM_NUMPOINTS

The number of elements in the keyGEOM_POINTLIST.

keyGEOM_NUMFACES

The number of elements in the keyGEOM_FACELIST.

keyGEOM_NUMATTR

Indicates the number of attributes within the dictionaries keyGEOM_ATTRLIST.

keyGEOM_PLANAR

Set to true (1) if the geometry is planar. Generally you want to leave this as 0 (false).

keyGEOM_ATTRLIST

This is a list of Attribute Definition Dictionary values corresponding to the attributes for the geometry. Prefer to use the dict_set_attrib function instead to make it easier to manipulate. Set the Functions section.

Reference

[1]	(1, 2, 3) "time -- Time access and conversionss" Python Library Reference. 21 December 2001. 30 January 2007. <http://www.python.org/doc/2.2/lib/module-time.html>

grail.data.agdm Module

`grail.data.agdm` Module