Overview

Create and manipulate MineSight® elements via this module. Elements are the standard means of communicating data within the MineSight®-3D environment.

Definitions

Standard definitions for this module:

Points:

A list of co-ordinates, defined as: [x, y, z].

Point Lists:

A list of points, defined as: [[x0, y0, z0], ..., [xN, yN, zN]].

Planes:

A tuple of floats, defined as: (A, B, C, D) where A, B, C & D are the co-efficients of a plane equation

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

All faces in MineSight® products have 3 vertexes.

Matrix:

This is a list of lists. Each list will contain 4 elements of the form,

[ [e00, e01, e02, e03], [e10, e11, e12, e13], [e20, e21, e22, e23], [e30, e31, e32, e33] ]

A modeling matrix, which indicates the transformation applied to a label starting at point P. The transformation matrix typically has rotation and translation data stored in it. Consult a Graphics Programming book for more information on transformation matrices.

All matrices are right-multiplied. The standard is shown in the book Computer Graphics by Foley [1].

Vectors:

A list of x, y, and z components, defined as [x, y, z].

Orientation Vector:

Used to specify the position and orientation of a text element (for example with semi/non-transform labels). The Orientation Vector is comprised of three points: the origin, an up vector, and a right vector. As in,

[[Xo, Yo, Zo], [Xu, Yu, Zu], [Xr, Yr, Zr]]

where "o" implies origin, "u" implies up vector, and "r" implies right vector.

The up and right vectors are specified as unit vectors that generate a triangle. The following diagram helps to explain,

Picture of an orientation vector.

In most cases if you only supply a single point, as in,

[Xo, Yo, Zo]

a default up and right vector will be provide for you.

Element Class

class Element

An Element object defines one of the possible geometry types that can be found within MS-3D.

Whenever you create shell (surface/solid), polyline, polygon or marker, you will get Element as a return value.

Typically Geometry MSR files consist of a collection of Elements.

get_pointlist()

Returns a list of points that define the element (see Point List in Definitions). The values within the point list are with respect to the project's coordinates. If you wish to get the raw point values you will need to subtract the projects x, y and z minimum values (see get_xmin, get_ymin and get_zmin in grail.ms3d.project).

If the Element is a element.NonTransformLabelType (upright label) or element.SemiTransformLabelType (forward label), then this will return the list of points corresponding to the label's location, up vector and right vector.

get_facelist()

Returns a facelist that defines the element (see Face Lists in Definitions).

This is only applicable for element.ShellType elements. All other elements will return an empty list ([]).

get_label_alignment_block()

Returns the label text block alignment around the insertion point.

Call is_label_alignment_block_set() first to see if there is a block alignment set on the label. The return value if not set is meaningless.

This will return one of the following values.

Element.LABEL_ALIGNMENT_BLOCK_TOP_LEFT,
Element.LABEL_ALIGNMENT_BLOCK_TOP_CENTER,
Element.LABEL_ALIGNMENT_BLOCK_TOP_RIGHT,
Element.LABEL_ALIGNMENT_BLOCK_MID_LEFT,
Element.LABEL_ALIGNMENT_BLOCK_MID_CENTER,
Element.LABEL_ALIGNMENT_BLOCK_MID_RIGHT,
Element.LABEL_ALIGNMENT_BLOCK_BOT_LEFT,
Element.LABEL_ALIGNMENT_BLOCK_BOT_CENTER,
Element.LABEL_ALIGNMENT_BLOCK_BOT_RIGHT

get_label_alignment_line()

Returns the label line alignment. The longest line in a label defines the label block width. All other, shorter lines will adjust left, center, or right based on this longest line.

This will return one of the following values.

Element.LABEL_ALIGNMENT_LINE_LEFT,
Element.LABEL_ALIGNMENT_LINE_CENTER,
Element.LABEL_ALIGNMENT_LINE_RIGHT

get_label_color_[r|g|b]()

Returns the label color.

Call is_label_color_set() first to see if there is a color set on the label. The return value if not set is meaningless.

Values are between 0.0 and 1.0.

get_label_font()

Returns the label font.

Call is_label_font_set() first to see if there is a font definition set on the label. The return value if not set is meaningless.

get_label_size()

Returns the font size of the label.

Call is_label_size_set() to see if there is a size set on the label. The return value if not set is meaningless.

Call is_label_size_relative() to determine if the value returned is a percent value from 0.0 to 100.0 or a project unit value.

get_label_spacing()

Returns the character spacing of the label.

This will return one of the following values.

Element.LABEL_SPACING_PROPORTIONAL,
Element.LABEL_SPACING_MONOSPACE,
Element.LABEL_SPACING_MONOSPACE_NUMBER

get_label_text()

Returns the text of the label as a single string. Multi-line text labels will have embedded new line characters inside the string.

get_label_type()

Returns the type of label.

This will return one of the following values.

Element.LABEL_TYPE_FIXED, Element.LABEL_TYPE_FORWARD, Element.LABEL_TYPE_UPRIGHT

get_material()

Returns the name of the material associated with this Element as a string. A blank string, "", indicates that no material is associated with this element.

get_name()

Returns the name of the element as a string.

get_parent_name()

Returns the name of the MineSight® Resource (MSR) file that this element belongs too.

For example, if you loaded a shell from a datamanager object found at \myfolder\myshellobject, then this function will return,

myshellobject

If this element has not been "rooted" into a MSR file yet, this method will return a blank string ("").

get_parent_path()

Returns the path relative to the datamanager for the MSR file. The path will lack the MSR extension.

For example, if you loaded a shell from a datamanager object found at \myfolder\myshellobject, then this function will return,

\\myfolder\\myshellobject

If this element has not been "rooted" into a MSR file yet, this method will return a blank string ("").

get_parent_physical_path()

Returns the physical path to the MineSight® Resource (MSR) file on the disk.

For example, if you Resource directory was at c:\myproject\_msresource, and you loaded a shell from a datamanager object found at \myfolder\myshellobject, then this function will return,

c:\\myproject\\_msresource\\myfolder\\myshellobject.msr

get_plane()

Returns the plane of an element. If this element is non planar, or has no plane will return None.

get_text()

Returns the text. Each line is delimited with a "\n". If this Element is not an type of label, then this will return a blank string.

get_type()

Returns the type of the element.

All types are defined in the Data section and are typically named as element.<type>Type. For example a polygon would be a element.PolygonType.

is_label_alignment_block_set()

Returns True if the block alignment is set per label. False otherwise.

is_label_color_set()

Returns True if the coloer is set per label. False otherwise.

is_label_fixed_and_locked()

Returns True only if the label is of fixed type and is locked. Locked means that the label will not flip if viewed from behind or upside down. False is returned otherwise.

is_label_font_bold()

Returns True if the font is bold. False otherwise.

Call is_label_font_set() to see if there is a font set on the label. The return value if not set is meaningless.

is_label_font_italic()

Returns True if the font is italic. False otherwise.

Call is_label_font_set() to see if there is a font set on the label. The return value if not set is meaningless.

is_label_font_set()

Returns True if the font is set per label. False otherwise.

is_label_size_relative()

Returns True if the font size is a 5 size of the screen. False if the size in project units.

Call is_label_size_set() to see if there is a size set on the label. The return value if not set is meaningless.

is_label_size_set()

Returns True if the size is set per label. False otherwise.

is_parent()

Returns True if this element belongs to a MineSight® Resource (MSR) file. In otherwords, the element was not created, it was rooted in an original file.

set_label_alignment_block(set [, alignment])

Set a per label block alignment.

Block alignment is where the origin point for the label is positioned with respect to the text block of the label.

set should be True to set the size. False to remove the setting.

alignment is one of the following.

Element.LABEL_ALIGNMENT_BLOCK_TOP_LEFT,
Element.LABEL_ALIGNMENT_BLOCK_TOP_CENTER,
Element.LABEL_ALIGNMENT_BLOCK_TOP_RIGHT,
Element.LABEL_ALIGNMENT_BLOCK_MID_LEFT,
Element.LABEL_ALIGNMENT_BLOCK_MID_CENTER,
Element.LABEL_ALIGNMENT_BLOCK_MID_RIGHT,
Element.LABEL_ALIGNMENT_BLOCK_BOT_LEFT,
Element.LABEL_ALIGNMENT_BLOCK_BOT_CENTER,
Element.LABEL_ALIGNMENT_BLOCK_BOT_RIGHT

Returns True on success. False otherwise.

set_label_alignment_line(alignment)

Set a label line alignment.

Line alignment is how each line in the label is position with respect to the longest line in the label text block.

alignment is one of the following.

Element.LABEL_ALIGNMENT_LINE_LEFT,
Element.LABEL_ALIGNMENT_LINE_CENTER,
Element.LABEL_ALIGNMENT_LINE_RIGHT

Returns True on success. False otherwise.

set_label_color(set [, r, g, b]):

Set a per label color. r, g, and b must be numbers between 0.0 and 1.0 (inclusive).

set should be True to set the size. False to remove the setting.

Returns True on success. False otherwise.

set_label_font(set [, fontName, isBold, isItalic])

Set a per label font.

set should be True to set the size. False to remove the setting.

fontName is the name of the font you will find in the font picker in MineSight. If it is misspelt or can not be found then this operation will return False and do nothing.

isBold and isItalic will indicate how the font should be rendered. Note, not all fonts have a bold representation.

Returns True on success. False otherwise.

set_label_size(set [, size, isRelative])

Set a per label size.

set should be True to set the size. False to remove the setting.

size should be larger than 0.0.

isRelative will indication that the provided size is a percent value.

Returns True on success. False otherwise.

set_label_spacing(spacing)

Set the label character spacing.

spacing is one of the following.

Element.LABEL_SPACING_PROPORTIONAL,
Element.LABEL_SPACING_MONOSPACE,
Element.LABEL_SPACING_MONOSPACE_NUMBER

Monospace will space the letters such that the widest letter also fits in the space provided.

Monospace Number will space the letters based on the widest number character. If you asked to print a 'W' using this option, the W may overlap neighboring characters as there may not be enough space.

Returns True on success. False otherwise.

set_label_type(type)

Set the label type.

type is one of the following.

Element.LABEL_TYPE_FIXED,
Element.LABEL_TYPE_FORWARD,
Element.LABEL_TYPE_UPRIGHT

Returns True on success. False otherwise.

set_label_type_locked(value)

Set a FIXED label to be also locked. This means the label will not flip the rendering of the text when viewed upside down or from behind.

This function will fail if the label type is not set to FIXED.

Returns True on success. False otherwise.

set_material(materialName [,create_if_not_exist]):

Sets a materialName for the Element, where the materialName is a material defined within the project's materials folder.

If the material does not exist in the project's material folder this function will generate an IOError by default. If you set the create_if_not_exist to 1, then this function will create a new material object within the project.

For example, to set a material on an object, and have that material be created if it does not already exist you can do the following,

el.set_material("SampleMaterial", create_if_not_exist=1)

Now your Element will have a "SampleMaterial" associated with it, as well as, the project will have a new "SampleMaterial" added to it.

Warning

If your element does not have a name, the set_material function will generate a IOError. Any Element object that lacks a name can not have a material. In order to avoid the potential error, you can use the set_name_and_material to set a name and material in one step.

set_name(name)

Sets a new name on the element.

set_name_and_material(name, material [,create_if_not_exist])

Sets the name and material on an object in one step. With an Element object you need to specify a name in order to set a material, this convience function lets you do it in one step.

If the material does not exist in the project's material folder this function will generate an IOError by default. If you set the create_if_not_exist to 1, then this function will create a new material object within the project.

In cases where you want to just use the existing name and continue to take advantage of this method, you can do the following,

el.set_name_and_material(el.get_name(), "SampleMaterial")

See also set_material.

set_plane(plane)

Takes a single arguement plane, if plane is True will calculate and set the plane of the element (if no plane can be calculated element will remain 3D). If plane is False will set the element to 3D. Only works with polylines and polygons.

Functions

generate_shape(shapetype, height, width, depth, rotation, position)

Generates a shape based on the shapetype and specified dimensions. All Shapes are defined in this module and are prefixed with SHAPE_. For example, the dump truck shape is defined as, element.SHAPE_DUMP_TRUCK.

Arguments:

shapetype : constant (see Data)

Type of shape, one of the element.SHAPE_<xxx> constants.

height : float

Height for your shape. This corresponds to the Z direction, and is equivalent to the project's elevation.

width : float

Width for your shape. This corresponds to the X direction, and is equivalent to the project's easting.

depth : float

Depth for your shape. This corresponds to the Y direction, and is equivalent to the project's northing.

rotation : float

Rotation of the returned object in degrees.

position : list

Starting position for your shape defined by a point (see Definitions).

Returns:

A new Element object with the defined shape (see Element class).

create_marker(point [,name])

Generates a new marker element of type element.MarkerType.

Argument:

point : list

A location for the new marker (see Definitions).

name : string

An element name.

Returns:

A new Element object with the defined shape (see Element class).

create_label(orientationVector, text [, name])

Creates a label at the given position.

Arguments:

orientationVector : list of points

Position of the label defined by a point (see Orientation Vectors in Definitions).

text : list or string

This is either a list of strings where each element in the list corresponds to a line on the non-transform label, or a string with a "\n" delimiter to represent a line.

name : string

An element name.

create_nontransform_label(orientationVector, text [, name])

Creates a non-transform label at the given position.

Arguments:

orientationVector : list of points

Position of the label defined by a point (see Orientation Vectors in Definitions).

In earlier versions of this function you could just supply a single point and a default up and right vector would be supplied for you. This behaviour is still available.

text : list or string

This is either a list of strings where each element in the list corresponds to a line on the non-transform label, or a string with a "\n" delimiter to represent a line.

name : string

An element name.

Warning

DEPRECATED (as of MineSight® v8.00) Use create_label() instead. This funtion will still work so old scripts will continue to run.

create_polygon(pointlist [,name, is_planar])

Create a polygon element.

If the last point on the polygon is not the same as the first, it will be duplicated upon creation. The difference between a polygon and a polyline is that a polygon is a closed segment.

Argument:

pointlist : list

A list of points (see Definitions).

name : string

An element name.

is_planar : int

Anything other than 0 will make the element planar, defaults to 0

Returns:

A new Element object with the defined shape (see Element class).

create_polyline(pointlist [,name, is_planar])

Creates a polyline element.

Arguments:

pointlist : list

A list of points (see Definitions).

name : string

An element name.

is_planar : int

Anything other than 0 will make the element planar, defaults to 0

Returns:

A new Element object with the defined shape (see Element class).

create_semitransform_label(orientationVector, text [, name])

Creates a semi-transform label at the given position.

Arguments:

orientationVector : list of points

Position of the label defined by a point (see Orientation Vectors in Definitions).

text : list or string

This is either a list of strings where each element in the list corresponds to a line on the semitransform label, or a string with a "\n" delimiter to represent a line.

name : string

An element name.

Warning

DEPRECATED (as of MineSight® v8.00) Use create_label() instead. This funtion will still work so old scripts will continue to run.

create_transform_label(position, matrix, text[, name])

Creates a transform label at the given at the position.

Arguments:

position : list

A Point as defined in the Definitions section.

matrix : list of lists

A Matrix as defined in the Definitions section.

text : string

This is a string representing the text you wish to display. For multi-line text use the n within the string. For example,

multiLine = "Line1\nLine2"

name : string

(Optional) name of the element.

Warning

DEPRECATED (as of MineSight® v8.00) Use create_label() instead. This funtion will still work so old scripts will continue to run.

create_shell(pointlist, facelist[,name])

Creates a shell (surface or solid) defined by the point list and face list. Point list and face list is as defined in grail.ag.

Arguments:

pointlist : list

A list of points (see Definitions).

facelist : list

A list of faces using the 'hoops' convention (see Definitions).

name : string

An element name.

Returns:

A new Element object with the defined shape (see Element class).

is_element(object)

Returns True if the supplied object is an Element class.

Data

DEFAULT_NAME

Default name for all elements.

SHAPE_CUBOID

Signals you want a cuboid shape.

SHAPE_CONE

Signals you want a cone shape.

SHAPE_SPHERE

Signals you want a sphere shape.

SHAPE_CONIFEROUS_TREE

Signals you want a coniferous tree shape.

SHAPE_DECIDUOUS_TREE

Signals you want a deciduous tree shape.

SHAPE_HEAD_FRAME

Signals you want a head frame shape.

SHAPE_DRILL_RIG

Signals you want a drill rig shape.

SHAPE_DUMP_TRUCK

Signals you want a dump-truck shape.

SHAPE_FULL_DUMP_TRUCK

Signals you want a full dump-truck shape.

SHAPE_SCOOP

Signals you want a scooper shape.

SHAPE_SHOVEL

Signals you want a shovel shape.

SHAPE_EXCAVATOR

Signals you want an excavator shape.

SHAPE_DIGGER

Signals you want a digger shape.

SHAPE_DRAGLINE

Signals you want drag line shape.

SHAPE_BUCKET_WHEEL

Signals you want a bucket wheel shape.

SHAPE_DRILL

Signals you want a drill shape.

SHAPE_ROCK_BOLTER

Signals you want a rock bolter shape.

SHAPE_MINER

Signals you want a miner shape.

NoType

Elements that have no type defined for them.

MarkerType

Elements that are markers.

PolylineType

Elements that are polylines.

PolygonType

Elements that are polygons.

ShellType

Elements that are shells. This defines all surfaces and solids within MineSight® 3D.

MeshType

Elements that are meshes.

GridType

Elements that are grids.

TextType

Elements that are text.

Warning

DEPRECATED (as of MineSight® v3.50-04). Prefer to use the exact 'Label' type instead (i.e. SemiTransformLabelType, also known as a Forward Label).

SemiTransformLabelType

Elements that are semi-transform labels. These are also known as "Forward Labels".

NonTransformLabelType

Elements that are non-transform labels. These are also known as "Upright Labels".

SpecialElementType

Special elements (very rare).

TransformLabelType

Elements that are transform labels. These are known as "Fixed Labels".

Reference