================================= HowTo: Use Embedded Triangulation ================================= .. include:: ..\version.h .. include:: howto-reference.h .. contents:: Table of Contents :backlinks: top ------- Preface ------- This document discusses how to generate triangulated surfaces using MineSightŪ Grail Embedded (MSGe). Triangulation is accomplished by taking MineSightŪ polyline and polygon *elements* and using the grail.ms3d.elementop_ module to generate a set of surface *elements*. We will examine how you can take a set of selected polygon and polylines and generate a new surface. Related Links ------------- - `HowTo: Create an Embedded Script`_ - `HowTo: Work with the Selection Buffer`_ - `grail.ms3d.elementop`_ - `grail.ms3d.element`_ - `grail.ms3d.datamanager`_ - `Example triangulate-selected.py script`__ .. __ : triangulate-selected.py Assumptions ----------- It is assumed that you, - **Are familiar with MineSightŪ 3D**. - **Have an understanding of the basic mechanics behind python scripting**. See `Getting Started`_ for more information on scripting and MineSightŪ. - **Understand how MineSightŪ Grail Embedded scripting works within MineSightŪ 3D**. For more information on MineSightŪ Grail Embedded scripting, see `HowTo: Create an Embedded Script`_. - **Have a working knowledge of operating with the selection buffer**. Although not critical, it is used as part of our example. See `HowTo: Work with the Selection Buffer`_ for more details. - **Have a working knowledge of accessing the datamanager via a Python script**. This is how we store our triangulated surfaces in our example. See grail.ms3d.datamanager_ for more details. Before proceeding it is recommended that you familiarize yourself with the above topics. --------------- Getting Started --------------- Generating triangulated surfaces based on the selection buffer requires the following steps, 1. Retrieve the :c:`Element` objects from the selection buffer. 2. For the group of polyline/polygon :c:`Element` objects selected generate a surface. 3. Store the surface into a new MineSightŪ geometry *object* (:c:`GeometryMob`). We will follow these steps in our sample :file:`triangulate-selected.py` script discussed below. For the purposes of our script will refer to only *polylines*; however, all the discussion with *polylines* is also applicable to MineSightŪ *polygons*. Example of Triangulating Selected Polylines ------------------------------------------- We will start by cloning the :file:`em-boilerplate.py` script found in the :file:`$(medexe)\\scripts\\samples` directory, and renaming the new script :file:`triangulate-selected.py`. The first step will be to add modules that are required to build our script. The following statements should be added alongside the other **import** statements already within our :file:`triangulate-selected.py` script, .. Python:: from grail.ms3d import selectionbuffer from grail.ms3d import element from grail.ms3d import elementop from grail.ms3d import datamanager The grail.ms3d.selectionbuffer_ module is used to query the user's selection. The grail.ms3d.element_ module is used to check the type of :c:`Elements` that the user selected. We only want to generate surfaces for polylines selected by the user. The grail.ms3d.elementop_ module is used to perform the triangulation. Finally, the grail.ms3d.datamanager_ module is used to store our resulting surfaces into a new MineSightŪ object. The next step is to start writing our new script in the :f:`run_code` function of the new :file:`triangulate-area.py` script. We will start by querying the selection buffer for any selected items, and make sure we only have selected polylines. If we fail to have anything useful, we will report an error and exit our :f:`run_code` function. .. Python:: def is_poly(el): return el.get_type() in def run_code(): # (1) Get What the user has selected # (2) Filter so we only have polylines and polygons. selected = selectionbuffer.get_elements( [element.PolylineType, element.PolygonType] ) if not polys: mssys.stderr.write("No polylines selected.") return # exit our script. # (3) Triangulate the polylines. surface = elementop.triangulate(polys) # (4) Store the surface into a geometry object. If the object # already exists remove it. if datamanager.is_object("\\triangulated"): datamanager.remove("\\triangulated") geomObj = datamanager.create_geometry("\\triangulated", "\\materials\\geometry") geomObj.add_elements([surface]) # (5) Update the display. datamanager.refresh("\\") `View the complete triangulate-selected.py script`__. .. __ : triangulate-selected.py As mentioned above, this script will inspect the selection buffer and generate a surface based on the selected polylines. The steps illustrated in the sample code above can be broken down as follows, 1. **Get what the user has selected**. We accomplish this by using the grail.ms3d.selectionbuffer_ module and reading the :c:`Element` objects selected by the user. 2. **Filter so we only have polylines and polygons**. By supplying a list of element types that we are interested in during our selection, we ensure that we only have selected items that we are interested in. 3. **Start Triangulating**. This is where we start triangulating. We simply pass the list of polylines and polygon :c:`Element` objects to the :f:`triangulate` function and we get back a new surface :c:`Element` object. 4. **Store our results**. For the sake of simplicity, we will just store our triangulated surface into a MineSightŪ Object called :file:`\\triangulated`. If one already exists, this script will remove it prior to adding the new surface. 5. **Update the display**. To see our new surface we will tell the datamanager to refresh its display. ------- Summary ------- In order to start triangulating with MineSightŪ Grail Embedded, you need to get a set of polylines/polygon :c:`Element` objects, and put those objects through the grail.ms3d.elementop_ :f:`triangulate` function. --------- Reference --------- .. [#python-lib-builtin] "Built-in Functions". *Python Library Reference*. 21 December 2001. 20 May 2005.