================================= ``grail.ms3d.datamanager`` Module ================================= .. include:: ../../version.h .. include:: ref.h .. contents:: Table of Contents :backlinks: top -------- 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 :a:`path` refers to the path within the datamanager. Where the :d:`datamanager.ROOT` refers to the base directory within the datamanager. You can compose paths easily by taking advantage of the Python's :f:`os.path.join` function. For example, if you wish to construct a path called :file:`\\phase2\\pit1` for a :file:`pit1` geometry MSR file, you would do the following, .. Python:: pit1path = os.path.join(datamanager.ROOT, "phase2", "pit1") --------- Constants --------- :dd:`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`_. :dd:`FILTER_GEOMETRY` :dd:`FILTER_MODELVIEW` :dd:`FILTER_ALL` Filter flags, for use with the :f:`get_selected` function. :d:`FILTER_ALL` is equivalent to using all the flags. This means, FILTER_ALL is equal to FILTER_GEOMOBJ | FILTER_MODELVIEW :dd:`DEFAULT_GEOMETRY_MATERIAL` The name of the material in the :d:`DEFAULT_GEOMETRY_MATERIAL_PATH`. :dd:`DEFAULT_GEOMETRY_MATERIAL_PATH` The default path for the materials assigned to geometry objects. It should be :file:`\\materials\\geometry`. --------- Functions --------- :df:`create_geometry(path[, material_path])` Creates a new :c:`GeometryMob` at the given :a:`path` with the given material. An example of creating a standard geometry file called :file:`mygeometry` in the MineSight® Resource directory would be, .. Python:: 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 :a:`material_path` will default to the :d:`DEFAULT_GEOMETRY_MATERIAL_PATH`. :df:`create_or_open_geometry(path[, material_path])` If the :a:`path` already exists, then an open geometry object is returned, if the :a:`path` does not exist, one is created using the :a:`material_path`. The same concepts apply here as they do in the :f:`create_geometry` and :f:`open_geometry` functions. The :a:`material_path` will default to the :d:`DEFAULT_GEOMETRY_MATERIAL_PATH`. :df:`create_unique_geometry(in_dir[, material_path])` Works the same as :f:`create_geometry`, except will automatically generate a unique geomtery name (i.e. Geometry1, Geometry2, and so on) within the specified :a:`in_dir`. :df:`create_modelview(path, pcfpath, modelname)` Creates a new :c:`ModelViewMob` at the given :a:`path` (see `Paths in the Datamanager`_). The :a:`pcfpath` is the path to the project control file on the user's file system. The :a:`modelname` refers to the name of the model file to view. For example, .. Python:: 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 :file:`msop10.dat` found at :file:`c:\\msop\\msop10.dat` to create a view of :file:`msop15.dat`. :df:`get_path(mob)` Returns the datamanager path for the given MineSight® Object. This is the path that is *relative to the datamanager root*. Use :f:`get_physical_path` if you want to get the path of the MineSight® Object on the disk. :df:`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 :file:`c:\\myproject` and your MineSight® Object is located at :file:`\\sample\\mygeometry` within the datamanager, then the physical path would be :file:`c:\\myproject\\_msresources\\sample\\mygeometry`. :df:`get_selected([filter, isrecursive])` Returns a list of paths in the datamanager that are highlighted by the user. An example of only getting a :c:`GeometryMob` and a :c:`ModelViewMob` that were selected by the user, .. Python:: 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. :a:`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_. :a:`isrecursive` : integer Indicates if you want to recurse into sub-folders. :df:`is_folder(path)` Indicates if a path points to a folder. :df:`is_object(path)` Indicates if a path points to a MineSight® object. :df:`hide(path)` Will cause the object in the datamanager to close and a no longer display in the viewer. *New in version 10.0.* :df:`list_filtered(folder[, filter, isrecursive])` Scans the contents of the given :a:`folder` and returns a list of all datamanager paths for that folder. You can use a :a:`filter` to control what object type paths to return in the same way the :f:`get_selected` function uses the filter. The default is to return ALL available objects. If :a:`isrecursive` is True (1), then the search is done recursively through the given :a:`folder`. The default is not to recurse through the folder. The following example will return all geometry objects within the entire project. .. Python:: dmPaths = datamanager.list_filtered( datamanager.ROOT, datamanager.FILTER_GEOMETRY isRecursive ) See the :file:`$(medexe)\\scripts\\samples\\grail.ms3d.datamanager\\em-list-filtered.py` script for an example of using the :f:`list_filtered` function. :df:`list_folder(path)` Returns the contents of a folder. :df:`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, .. Python:: 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, .. Python:: datamanager.make_folder("my_folder") The :f:`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, .. Python:: 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 :e:`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, .. Python:: try: datamanager.create_folder("\\phase1") except IOError: pass # folder already exists :df:`make_unique_folder(in_dir[,prefix])` Will generate a new folder within :a:`in_dir`. If :a:`in_dir` does not exist it will be created (including sub-directories). The optional :a:`prefix` will be inserted before the unique name. By default :a:`prefix` will be "_". :df:`open_geometry(path)` Opens a :c:`GeometryMob` object. :df:`open_modelview(path)` Opens a :c:`ModelViewMob` object. :df:`refresh(path)` Updates the display of the object pointed to by the :a:`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, .. Python:: mob = datamanager.open_geometry("\\mygeometry") mob.close() datamanager.refresh("\\mygeometry") An invalid refresh with a MineSight® Object that is still open, .. Python:: mob = datamanager.open_geometry("\\mygeometry") datamanager.refresh("\\mygeometry) :df:`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 :e:`IOError` [#python-exception]_. :df:`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. :df:`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 :dc:`GeometryMob` Defines a MineSight® Geometry Object. This object is returned by the :f:`datamanager.create_geometry` or :f:`datamanager.open_geometry` functions. :df:`add_elements(elements)` Adds a list of :c:`Element` objects to a Geometry object. :df:`close()` Explicitly closes a reference to a Geometry object. :df:`get_elements()` Returns a list of :c:`Element` objects stored within the Geometry object. :df:`get_material()` Returns the material name for the :c:`GeometryMob`. :df:`set_material(material[, create_if_not_exist])` Sets a new :a:`material` on the :c:`GeometryMob` object. The :a:`material` should be specified as a name that exists within the :file:`materials` folder. If the :a:`material` does not exist, and the :a:`create_if_not_exist` is set to 0, then an :e:`IOError` will be generated. If you set :a:`create_if_not_exist` to 1, then a new material will be created in the project's :file:`material` directory. Model View MineSight® Object ---------------------------- class :dc:`ModelViewMob` Defines a MineSight® Modelview Object. This object is returned by the :f:`datamanager.create_modelview` or :f:`datamanager.open_modelview` functions. :df:`close()` Explicitly closes a reference to a Modelview object. :df:`get_pcf_path()` Returns the full path to the PCF file used to define the Modelview Object. :df:`get_modelname()` Returns the name of the model file used to define the Modelview Object. ----- .. [#python-exception] "Built-in Exceptions" *Python Library Reference*. 19 December 2001. 31 May 2004.