`grail.mstype` Module

Version: 16.2

Table of Contents

Overview
Details
Functions
Known Issue
- Using type() on a mstype will not return a ListType

Overview

The grail.mstype module was designed to improve the handling of large point and face data throughout the MSGRAIL system. In general, the mstype module should just work without you having to do much to make it work.

In general, the mstypes will work in all cases, except for a single Known Issue. It is recommended that all new scripts enable mstypes. To allow for backward compatibility concerns, the mstypes are disabled by default.

To enable mstypes you must insert the following line into your script,

import grail.mstype_enable

this convenience module will automatically rewire the underlying mechanics with point and face data within MSGRAIL and MineSight(r) to use mstypes.

This module also provides a set of Functions that allow you to transform your data from the new mstypes to the older format, and vicea versa.

Details

Prior to v4.00 of MSGRAIL all point data (and face data) were transformed from their efficient underlying binary structure to a less efficient Python structure. This lead to unnecessary performance penalities if you were passing point data from one MSGRAIL function to another. For example, the following call will result in too many unneccessary conversion,

points = el.get_pointlist() # (1) Binary -> Python
itIs = ag.ispointlistaline(points) # (2) Python -> Binary

In line 1, we would convert binary data to a python point list, followed by a reconversion back to the original binary data in line 2.

The purpose of mstypes is to remove the reconversion process. If mstypes are enabled, you will end up passing a reference to the underlying binary data, and the binary data will only be convert at the moment you need a python list. Even then, the conversion will only occur if you decide to do something with the mstype that doesn't make sense (for example, attempting to insert a string into a point list).

In essesence we are delaying the conversion from binary data to a python list to the very last moment.

For convenience, we provide a module that you can import to automatically enable mstypes in your script. If you do the following,

import grail.mstype_enable

you will automatically enable mstypes. The above call effectively does the following,

import grail.mstype

grail.mstype.Enable()

Functions

Controlling Mstypes

Note

If you are using the convenience import grail.mstype_enable idiom, mixing the following calls in your script should be done carefully.

Disable(): Call this function to disable mstypes in the MineSight(r) system.
Enable(): Call this function to enable mstypes in the MineSight(r) system.
Is_Enabled(): Call this function to determine if mstypes are enabled within the MineSight(r) system.
Set_Enabled_State(is_on): Will set the state of the mstypes based on the value of the is_on argument.

Conversion

As_Py(obj): This function will convert obj to a pure python representation, and remove any notion of mstypes. It can be considered the universal escape hatch.

Point Lists

PointList_Check(obj)

Returns true if obj is a point list. The obj can either be a pure python list or a mstype.

PointList(obj)

Converts the obj to a mstype pointlist.

PointList_YZSwap(obj)

This will perform a YZSwap on the points in obj. It will return a new copy of obj with all its coordinates swapped. If you do not want to duplicate memory you should perfer to use the nPointList_YZSwap described below.

An example of using this routine is,

>>> from grail import mstype

>>> pointList = [[1, 2, 3], [10, 20, 30], [100, 200, 300]]

>>> swapped = mstype.PointList_YZSwap(pointList)

>>> print pointList

[[1, 2, 3], [10, 20, 30], [100, 200, 300]]

>>> print swapped

[[1, 3, 2], [10, 30, 20], [100, 300, 200]]

as you can see, the original point is not modified.

nPointList_YZSwap(obj)

Occasionally you will stumble across a routine that needs to swap coordinates from XYZ (cartesian coordinate space) to XZY (graphical coordinate space), this routine will efficiently swap the Y and Z coordinates.

The change will modify the contents of obj. For example,

>>> from grail import mstype

>>> pointList = [[1, 2, 3], [10, 20, 30], [100, 200, 300]]

>>> mstype.nPointList_YZSwap(pointList)

>>> print pointList

[[1, 3, 2], [10, 30, 20], [100, 300, 200]]

and if we re-run the routine we will get back our original point list.

>>> mstype.nPointList_YZSwap(pointList)

>>> print pointList

[[1, 2, 3], [10, 20, 30], [100, 200, 300]]

If the obj is not a valid pointlist a TypeError exception will be generated.

Point

Point_Check(obj)

Returns true if obj is a point. The obj can either be a pure python list or a mstype.

Point(obj)

Converts the obj to a mstype point.

Point_YZSwap(obj)

Performs a YZSwap of obj, but returns a new point without modifiying the original. If you want to efficiently modify the contents in place use nPoint_YZSwap.

An example of using this routine is,

>>> from grail import mstype

>>> point = [1, 2, 3]

>>> swapped = mstype.Point_YZSwap(point)

>>> print point

[1, 2, 3]

>>> print swapped

[1, 3, 2]

nPoint_YZSwap(obj)

The change will modify the contents of obj. For example,

>>> from grail import mstype

>>> point = [1, 2, 3]

>>> mstype.nPoint_YZSwap(point)

>>> print point

[1, 3, 2]

If the obj is not a valid point a TypeError exception will be generated.

Face List

FaceList_Check(obj): Returns true if obj is a face list. The obj can either be a pure python list or a mstype.
FaceList(obj): Converts the obj to a mstype face list.

Known Issue

Using type() on a mstype will not return a ListType

If you do the following when mstypes are enabled,

type(aPointList)

it will not be equal to a python types.ListType. Some old scripts used the following test,

type(aPointList) == types.ListType

to ensure that they are getting valid data.

It is recommended that you replace the above test with,

import mstype

mstype.PointList_Check(aPointList)

which will confirm that aPointList is in fact a pointlist, even if it is a mstype.

The same issues apply to a point and facelist, where it is recommended that you use the Point_Check and FaceList_Check respectively.

grail.mstype Module

`grail.mstype` Module