`grail.ms3d.datamanager` Module

Version: 16.2

Table of Contents

Overview
Paths in the Datamanager
Constants
Functions
MineSight® Objects (MOBS)
- Geometry MineSight® Object
- Model View MineSight® Object

Overview

Manipulate the datamanager via MineSight® objects.

This module gives you the ability to manipulate the folders and objects located in the datamanager.

Currently the datamanager module is limited to working with Geometry objects. Furthermore, you are unable to modify the materials.

Note

The MineSight® Object is often referred to as a MOB. This comes from having fun with the term '[M]ineSight [O][b]ject'.

Paths in the Datamanager

With all the datamanager functions, the path refers to the path within the datamanager. Where the datamanager.ROOT refers to the base directory within the datamanager. You can compose paths easily by taking advantage of the Python's os.path.join function. For example, if you wish to construct a path called \phase2\pit1 for a pit1 geometry MSR file, you would do the following,

pit1path = os.path.join(datamanager.ROOT, "phase2", "pit1")

Constants

ROOT: Root path for the datamanager. This represents the base directory used to construct paths within the datamanager. This does not represent the physical root directory on the system. See Paths in the Datamanager.

FILTER_GEOMETRY FILTER_MODELVIEW FILTER_ALL

Filter flags, for use with the get_selected function. FILTER_ALL is equivalent to using all the flags. This means,

FILTER_ALL is equal to FILTER_GEOMOBJ | FILTER_MODELVIEW

DEFAULT_GEOMETRY_MATERIAL

The name of the material in the DEFAULT_GEOMETRY_MATERIAL_PATH.

DEFAULT_GEOMETRY_MATERIAL_PATH

The default path for the materials assigned to geometry objects. It should be \materials\geometry.

Functions

create_geometry(path[, material_path])

Creates a new GeometryMob at the given path with the given material. An example of creating a standard geometry file called mygeometry in the MineSight® Resource directory would be,

mob = datamanager.create_geometry(

              "\\mygeometry",

              material_path="\\materials\\geometry"

              )

which will use the Geometry material for your new geometry object. See also Paths in the Datamanager.

The material_path will default to the DEFAULT_GEOMETRY_MATERIAL_PATH.

create_or_open_geometry(path[, material_path])

If the path already exists, then an open geometry object is returned, if the path does not exist, one is created using the material_path. The same concepts apply here as they do in the create_geometry and open_geometry functions.

The material_path will default to the DEFAULT_GEOMETRY_MATERIAL_PATH.

create_unique_geometry(in_dir[, material_path])

Works the same as create_geometry, except will automatically generate a unique geomtery name (i.e. Geometry1, Geometry2, and so on) within the specified in_dir.

create_modelview(path, pcfpath, modelname)

Creates a new ModelViewMob at the given path (see Paths in the Datamanager). The pcfpath is the path to the project control file on the user's file system. The modelname refers to the name of the model file to view. For example,

mvmob = datamanager.create_modelview("\\mymodelview",

                                     "c:\\msop\\msop10.dat",

                                     "msop15.dat")

will create a "mymodelview" within the root directory of the datamanager that uses the msop10.dat found at c:\msop\msop10.dat to create a view of msop15.dat.

get_path(mob)

Returns the datamanager path for the given MineSight® Object. This is the path that is relative to the datamanager root. Use get_physical_path if you want to get the path of the MineSight® Object on the disk.

get_physical_path(mob)

Returns the physical path for MineSight® Object. This is real path on the hard drive. For example, if your project is in c:\myproject and your MineSight® Object is located at \sample\mygeometry within the datamanager, then the physical path would be c:\myproject\_msresources\sample\mygeometry.

get_selected([filter, isrecursive])

Returns a list of paths in the datamanager that are highlighted by the user.

An example of only getting a GeometryMob and a ModelViewMob that were selected by the user,

filter = datamanager.FILTER_GEOMETRY |\

         datamanager.FILTER_MODELVIEW

mobs = datamanager.get_selected(filter=filter)

This will only consider those items selected in the contents portion of the datamanager.

filter : a filter flag: Flags used to filter what values you want to extract. This defaults to return all the available MineSight® Objects to the user. See Constants.
isrecursive : integer: Indicates if you want to recurse into sub-folders.

is_folder(path)

Indicates if a path points to a folder.

is_object(path)

Indicates if a path points to a MineSight® object.

hide(path)

Will cause the object in the datamanager to close and a no longer display in the viewer.

New in version 10.0.

list_filtered(folder[, filter, isrecursive])

Scans the contents of the given folder and returns a list of all datamanager paths for that folder.

You can use a filter to control what object type paths to return in the same way the get_selected function uses the filter. The default is to return ALL available objects.

If isrecursive is True (1), then the search is done recursively through the given folder. The default is not to recurse through the folder.

The following example will return all geometry objects within the entire project.

dmPaths = datamanager.list_filtered(

    datamanager.ROOT,

    datamanager.FILTER_GEOMETRY

    isRecursive

    )

See the $(medexe)\scripts\samples\grail.ms3d.datamanager\em-list-filtered.py script for an example of using the list_filtered function.

list_folder(path)

Returns the contents of a folder.

make_folder(path)

Creates a new folder if and only if the parent folder already exists. In order to use this function correctly you must specify a parent folder within the path. For example, the following will create a folder off the root directory for the datamanager,

path = os.path.join(datamanager.ROOT, "my_folder")
# path is "\\my_folder"
datamanager.make_folder(path)

In this case, the root directory, "\", is the parent folder. Simply doing the following will not result in a folder being created,

datamanager.make_folder("my_folder")

The make_folder routine is capable of creating folders recursively. In other words, if a portion of the required path does not exist it will be created. For example, if you lack a folder called "phase1", the following will work,

path = os.path.join(datamanager.ROOT, "phase1", "my_folder")
datamanager.make_folder(path)

and result in a "\phase1\my_folder" folder within the datamanager. In the above example the missing folder, "phase1" was created for you.

If the requested path already exists, this will generate a IOError. One trick to create folders if they do not already exist, and to just pass if it already exists is to do the following,

try:
datamanager.create_folder("\\phase1")
except IOError:
pass # folder already exists

make_unique_folder(in_dir[,prefix])

Will generate a new folder within in_dir. If in_dir does not exist it will be created (including sub-directories). The optional prefix will be inserted before the unique name. By default prefix will be "_".

open_geometry(path)

Opens a GeometryMob object.

open_modelview(path)

Opens a ModelViewMob object.

refresh(path)

Updates the display of the object pointed to by the path. The object can not have any open references. The following code snippets illustrate a valid and invalid method for refreshing your MineSight® Object.

A valid refresh with a MineSight® Object that has been closed,

mob = datamanager.open_geometry("\\mygeometry")

mob.close()

datamanager.refresh("\\mygeometry")

An invalid refresh with a MineSight® Object that is still open,

mob = datamanager.open_geometry("\\mygeometry")

datamanager.refresh("\\mygeometry)

remove(path)

Removes a MineSight® object from the project.

If there exists any MineSight® Objects that are still open (including ones that may have been open prior to script execution), then this function will generate an IOError [1].

remove_folder(path)

Removes a folder from the project (assuming no open children). This will remove all sub-directories as well. Only MineSight related files will be removed from the folder.

show(path)

Will cause the object in the datamanager to open and display in the viewer.

New in version 10.0.

MineSight® Objects (MOBS)

The following sections discuss the various types of MineSight® Objects you can load up via this module.

Geometry MineSight® Object

class GeometryMob

Defines a MineSight® Geometry Object.

This object is returned by the datamanager.create_geometry or datamanager.open_geometry functions.

add_elements(elements)

Adds a list of Element objects to a Geometry object.

close()

Explicitly closes a reference to a Geometry object.

get_elements()

Returns a list of Element objects stored within the Geometry object.

get_material()

Returns the material name for the GeometryMob.

set_material(material[, create_if_not_exist])

Sets a new material on the GeometryMob object. The material should be specified as a name that exists within the materials folder.

If the material does not exist, and the create_if_not_exist is set to 0, then an IOError will be generated. If you set create_if_not_exist to 1, then a new material will be created in the project's material directory.

Model View MineSight® Object

class ModelViewMob

Defines a MineSight® Modelview Object.

This object is returned by the datamanager.create_modelview or datamanager.open_modelview functions.

close(): Explicitly closes a reference to a Modelview object.
get_pcf_path(): Returns the full path to the PCF file used to define the Modelview Object.
get_modelname(): Returns the name of the model file used to define the Modelview Object.

[1]	"Built-in Exceptions" Python Library Reference. 19 December 2001. 31 May 2004. <http://www.python.org/doc/2.2/lib/module-exceptions.html>

grail.ms3d.datamanager Module