============================== HowTo: Use Embedded Contouring ============================== .. include:: ..\version.h .. include:: howto-reference.h .. contents:: Table of Contents :backlinks: top .. The steps for creating a howto are, .. .. 1. Copy the howto-boilerplate to the desired filename (X). .. 2. Update the index-howto.txt file to have a reference to X. .. 3. Update the howto-reference.h file with the appropriate .. reference. ------- Preface ------- This document discusses how to generate contours using the MineSightŪ Grail Embedded (MSGe) contouring engine. Contouring is accomplished by taking MineSightŪ surface *elements* and using the grail.ms3d.elementop_ module to generate a set of polyline and polygon *elements* for a given elevation start, end and step. We will examine how you can take a set of surfaces selected by the user and generate contours at with a start of 0 units and an end of 2000 units, and steps of 10 units and 50 units. Related Links ------------- - `HowTo: Create an Embedded Script`_ - `HowTo: Work with the Selection Buffer`_ - `grail.ms3d.elementop`_ - `grail.ms3d.element`_ - `grail.ms3d.datamanager`_ - `Example contour-selected.py script`__ .. __ : contour-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 contours 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 contours based on the selection buffer requires the following steps, 1. Retrieve the surface :c:`Element` objects from the selection buffer. 2. For each surface :c:`Element` object, generate contours. 3. Store the contours into a new MineSightŪ geometry *object* (:c:`GeometryMob`). We will follow these steps in our sample :file:`contour-selected.py` script discussed below. For the purposes of our script will refer to only *surfaces*; however, all the discussion with *surfaces* is also applicable to MineSightŪ *solids*. Example of Contouring Selected Surfaces --------------------------------------- We will start by cloning the :file:`em-boilerplate.py` script found in the :file:`$(medexe)\\scripts` directory, and renaming the new script :file:`contour-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:`contour-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 contours for surfaces selected by the user. The grail.ms3d.elementop_ module is used to perform the contouring. Finally, the grail.ms3d.datamanager_ module is used to store our resulting contours 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:`contour-area.py` script. We will start by querying the selection buffer for any selected items, and make sure we only have selected surfaces. If we fail to have anything useful, we will report an error and exit our :f:`run_code` function. .. Python:: def run_code(): """Sample 'function' in embedded script. This function will write some text out the message window, but you can have it do anything you like. """ # (1) Get what the user has selected. # (2) Filter so we only have surfaces. selected = selectionbuffer.get_elements([element.ShellType]) if not surfaces: return # exit our script # (3) For each surface, start contouring. start = 0 end = 2000 minor_elevation = 10 major_elevation = 50 print "contouring...", for surface in surfaces: print ".", minor = elementop.contour(surface, start, end, minor_elevation) major = elementop.contour(surface, start, end, major_elevation) # (4) Store them into a MineSight(r) Object; if one already exists, # then remove it prior to adding new contours. if datamanager.is_object("\\contours"): datamanager.remove("\\contours") g = datamanager.create_geometry("\\contours", "\\materials\\geometry") g.add_elements(minor) g.add_elements(major) print "OK." `View the complete contour-selected.py script`__. .. __ : contour-selected.py As mentioned above, this script will inspect the selection buffer and generate contours for each selected surface. The contours will be generated from 0 to 2000 units, with minor contours at 10 units and major contours at 50 units. 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 surfaces**. By supplying a list of element types that we are interested in we can ensure that only surfaces will be selected. 3. **Start contouring**. This is where we start contouring. For the sake of simplicity, we will just attempt to contour between 0 and 2000 units, with major contours every 50 units, and minor contours every 10 units. The for loop operates on each surface selected by the user, and runs the :f:`elementop.contour` function on the surface. The :f:`elementop.contour` function requires the :a:`start`, :a:`end` and :a:`step` for the resulting contours. The results are stored back into the :d:`minor` or :d:`major` Python variables, which are a list of polyline/polygon :c:`Element` objects. These objects can now be either stored back to a :c:`GeometryMob`, or operated on further. It is important to remember that contours are not always exactly one single line per step. You can imagine a surface with two mountains on it that will result in two contours having the same elevation. 4. **Store our results**. For the sake of simplicity, we will just store our contours into a MineSightŪ Object called :file:`\\contours`. If one already exists, this script will remove it prior to adding the new contours. ------- Summary ------- In order to start contouring with MineSightŪ Grail Embedded, you need to get a set of surface/solid :c:`Element` objects, and put those objects through the grail.ms3d.elementop_ :f:`contour` function. The :f:`contour` function requires a surface, start elevation, end elevation and a elevation step for your contours, and the contour operation will begin. After you have all your contours you can store them or do further operations on them such as running the :f:`smooth_bezier` function in grail.ms3d.elementop_ in order to smooth your results.