=============================== ``grail.ms3d.elementop`` Module =============================== .. include:: ../../version.h .. include:: ref.h .. contents:: Table of Contents :backlinks: top -------- Overview -------- This module focus on function/operations that work on the MineSightŪ Grail Embedded :c:`Element` class (see grail.ms3d.element_). --------- Functions --------- :df:`calc_area(element)` Calculates the area for a given :c:`Element`. If your data is already in :c:`Element` format this is a much more efficient call compared to the appropriate grail.ag_ area calculation function. If the item does have an area a :e:`TypeError` [#python-lib]_ will be generated .. Warning:: It is your responsibility to determine if the :c:`Element` can have an area. For example, markers and polylines do no have an area. Arguments: :a:`element` : Element An :c:`Element` that can have an area (i.e. polygons and surfaces). Returns: The area of an :c:`Element`. :df:`contour(surface, begin, end, step[, iscoincident]):` Generates a list of :c:`Element` objects corresponding to the requested contours around the surface :c:`Element`. Your contour will be in the range [begin, end). This function will throw an :e:`ArithmeticError` [#python-lib]_ if it is unable to compute a contoured surface. There are some important items to note when using the contour function, * Your surface is plane-planar. In other words we are generating contours in the z (up) direction. * Generating exact contours. When contours are generated for the given surface, and a contour falls on an edge exposed in the surface, the general algorithm will bump the contour up a very, very, very small amount to find a location that does not correspond to an edge. However, in some cases you may wish to perform an exact contour of your data. For exact contours ensure the :a:`iscoincident` keyword is set as 1. When you contour with :a:`iscoincident` you are saying it is OK to contour along edges. The :a:`iscoincident` keyword is equivalent to using the check box on the Contour dialog. This option may be necessary for triangulations that have been imported from other systems, or if you have created a triangulation, without the new 'Minimize Flat Area' option in the triangulation dialog. * This is a single precision operation. All calculations will be done in single precision. * Smoothing contours. To smooth contours use the :f:`smooth_spline` function (mentioned below) on the resulting contours. For example, .. Python:: contours = elementop.contour(surface, 0, 2000, 500) smoothed = [] for contour in contours: smooth = elementop.smooth_spline(contour, 5) smoothed.append(smooth) At this point you will have a list of smoothed contours. Arguments: :a:`surface` : Element Surface element you wish to contour. :a:`begin`: float Elevation for the first contour. :a:`end` : float The last elevation *not* to contour, contouring ends when the requested elevation is greater than this value. :a:`step` : float The value to increment by until we reach the ending value. :a:`iscoincident` : integer Specifics if you would like exact contours (see above for a more detailed explanation). Returns: A list of :c:`Element` objects, where each element is a :d:`PolygonType` or a :d:`PolylineType`. Each :c:`Element` is a valid contour for the range specified.s :df:`smooth_average(element, averagecount)` Creates a new smoothed :c:`Element` by computing an average polyline/polygon for all nodes within the :a:`element`. The :a:`averagecount` indicates how many nodes to average across. This function only applies to :d:`element.PolygonType` and :d:`element.PolylineType` :c:`Element` objects. For this function to work correctly you will require at least three points to perform an average across. to work. If you have less than three points this function will generate a :e:`ValueError` [#python-lib]_. Returns: A new smoothed :c:`Element` object. :df:`smooth_bezier(element, addnodes, smoothfactor)` Creates a new smoothed :c:`Element` by applying the Bezier algorithm to the polyline/polygon for all nodes within the :a:`element`. The Bezier smoothing algorithm will intersect nodes while it smooths the curve. The :a:`addnodes` specifies how many nodes to add during the smoothing process, and the :a:`smoothfactor` indicates how smooth to make the curve. The larger the :a:`smoothfactor` the greater the curve will deviate from the original. This function only applies to :d:`element.PolygonType` and :d:`element.PolylineType` :c:`Element` objects. Any element that only contains two points (a line) will be cloned and returned back. Returns: A new smoothed :c:`Element` object. :df:`smooth_spline(element, addnodes)` Creates a new smoothed :c:`Element` by applying the Spline smoothing algorithm to the polyline/polygon for all nodes within the :a:`element`. The Spline smoothing algorithm *does not* respect nodes while it smooths the curve. The :a:`addnodes` specifies how many nodes to add during the smoothing process. This function only applies to :d:`element.PolygonType` and :d:`element.PolylineType` :c:`Element` objects. Any element that only contains two points (a line) will be cloned and returned back. Returns: A new smoothed :c:`Element` object. :df:`triangulate(elements)` Takes a list of :c:`Element` objects and generates a simple triangulated surface :c:`Element`. This function will throw an :e:`ArithmeticError` [#python-lib]_ if it is unable to compute a triangulated surface. ---- .. [#python-lib] "Built-in Exceptions" *Python Library Reference*. 19 December 2001. 1 May 2005.