================================== ``grail.engines.sit`` Module ================================== .. include:: ..\version.h .. contents:: Table of Contents :backlinks: top ----------- Description ----------- A standard interface to the Intersect Surfaces tool. The Intersect Surfaces tool has a comprehensive set of options for generating new surfaces from the intersection of two existing surfaces. --------- Examples --------- Example #1: .. Python:: from grail.engines import sit def callback(): print '.', return False #Do not terminate #read surfaces in from shl files prim_shl = shlfile.open(prim_shl_path) prim_pts, prim_fcs = prim_shl.read_shell() prim_shl.close() sec_shl = shlfile.open(sec_shl_path) sec_pts, sec_fcs = sec_shl.read_shell() sec_shl.close() #set-up attributes prim_attr = {"name":"primary", "tons":2345.6} sec_attr = {"name":"secondary", "tons":888.8} sitop = sit.SITOp() sitop.opt_op(sit.opMERGE_CUT_DIFF) sitop.opt_merge_primary(sit.mergeNONE) sitop.opt_merge_secondary(sit.mergeNONE) sitop.opt_is_merge_result(True) sitop.opt_area(10.0) sitop.opt_progress(callback) sitop.add_primary(prim_pts, prim_fcs, prim_attr) sitop.add_secondary(sec_pts, sec_fcs, sec_attr) sitop.add_limit(boundingPoly) sitop.opt_limit_primary(True) sitop.opt_limit_secondary(True) sitop.opt_limit_options(1) shells = sitop.process() #returns a list of tuples for i in range(len(shells)): pts, faces, attribs = shells[i] --------- Constants --------- The following constants are used to define an intersect operation type. Operations are listed in the same order as they appear on the dialog. Refer to MineSightŪ 3-D Helpdoc (Intersect Surfaces) for more information on each of these operations. :df:`opMERGE_FILL_DIFF` The Fill Surface (diff) option patches the portion of the Secondary surface which is above the Primary surface into the Primary surface, deleting that portion of the Primary surface which is below the Secondary surface. :df:`opMERGE_FILL_UNION` The Fill Surface (union) option returns the topmost combined surface, or the maximum of both the Primary and Secondary surfaces. :df:`opMERGE_FILL_INT` The Fill Surface (int) option returns the topmost combined surface, in the area where the Primary and Secondary surfaces overlap. :df:`opMERGE_CUT_DIFF` The Cut Surface (diff) option patches the portion of the Secondary surface which is below the Primary surface into the Primary surface, deleting that portion of the Primary surface which is above the Secondary surface. :df:`opMERGE_CUT_UNION` The Cut Surface (union) option returns the bottom most combined surface, or the minimum of both the Primary and Secondary surfaces. :df:`opMERGE_CUT_INT` The Cut Surface (int) option returns the bottom most combined surface, in the area where the Primary and Secondary surfaces overlap. :df:`opMERGE_PATCH_DIFF` The Patch Surface (diff) option patches the Secondary surface into the Primary surface, deleting that portion of the Primary surface which is overlapped by the Secondary surface. :df:`opMERGE_PATCH_UNION` The Patch Surface (union) option patches the portion of the Secondary surface which is internal to the Primary surface (viewed in plan) into the Primary surface, deleting that portion of the Primary surface which is overlapped by the Secondary surface. :df:`opPRI_ABOVE_SEC` Primary surface option: primary above secondary. :df:`opPRI_BELOW_SEC` Primary surface option: primary below secondary. :df:`opPRI_INTERNAL` Primary surface option: primary internal. :df:`opPRI_EXTERNAL` Primary surface option: primary external. :df:`opPRI_EXCEPT_SEC_ABOVE` Primary surface option: primary except where secondary is above. :df:`opPRI_EXCEPT_SEC_BELOW` Primary surface option: primary except where secondary is below. :df:`opSEC_ABOVE_PRI` Secondary surface option: secondary above primary. :df:`opSEC_BELOW_PRI` Secondary surface option: secondary below primary. :df:`opSEC_INTERNAL` Secondary surface option: secondary internal. :df:`opSEC_EXTERNAL` Secondary surface option: secondary external. :df:`opSEC_EXCEPT_PRI_ABOVE` Secondary surface option: secondary except where primary is above. :df:`opSEC_EXCEPT_PRI_BELOW` Secondary surface option: secondary except where primary is below. :df:`opFILL_SOLID` Generate fill solid from the intersection of the two surfaces. :df:`opCUT_SOLID` Generate cut solid from the intersection of the two surfaces. .. note:: This module does not implement the `Line Of Intersection` operation. This operation can be performed using the `Union`_ engine. The following constants are used to define merge options: :df:`mergeNONE` No merging of overlaps within group. :df:`mergeCUT` Merge overlaps within group. :df:`mergeFILL` Merge overlaps within group. The following constants are used to define limit options: :df:`limitINTERNAL` limit the surface(s) to the area enclosed by the limiting polygon. :df:`limitEXTERNAL` limit the surfaces(S) to the area outside the region defined by the polygon. ------------ SITOp Class ------------ class :c:`SITOp()` A SITOp object is used to specify intersect options and begin the intersect operation. Constructor takes no arguments. **Methods** :df:`opt_op(op)` Sets the operation type to be performed. See `Constants`_. :df:`opt_merge_primary(op)` Option to merge primary surfaces before operation. See `Constants`_. :df:`opt_merge_secondary(op)` Option to merge secondary surfaces before operation. See `Constants`_. :df:`opt_is_merge_result(True)` Option to merge all surfaces in the result into one shell. Argument can be True (1) or False (0). :df:`opt_area(minArea)` Option to specify the minimum size of the surface element to use. Surfaces with the area that is smaller than specified value will be ignored and left unmodified. :df:`opt_norm(x, y, z)` Set orientation in which intersection happens (horizontal plane is used by default). :df:`opt_progress(callback)` Option to show progress during execution. The callback function will be run during the execution of the surface intersector. The callback function will terminate the execution if True (1) is returned. :df:`add_primary(prim_pts, prim_fcs, attrs=None)` Set primary surface. Primary attributes can be specified if needed. Attributes can be stored in any data structure (list, dictionary, etc.). By default, attributes are set to None. :df:`add_secondary(sec_pts, sec_fcs, attrs=None)` Set secondary surface. Secondary attributes can be specified if needed. Attributes can be stored in any data structure (list, dictionary, etc.). By default, attributes are set to None. :df:`add_limit(point_list)` Set limiting polygon. Either the Primary or Secondary surfaces can be limited to the area enclosed by the limiting polygon. :df:`opt_limit_primary(op)` Option to limit primary surface by limiting polygon. See `Constants`_. :df:`opt_limit_secondary(op)` Option to limit secondary surface by limiting polygon. See `Constants`_. :df:`opt_limit_options(op)` Set the limit options. See `Constants`_. :df:`opt_verify_surfaces(True)` Option to verify that input surfaces are not solids and are not self-overlapping. If a problem is found, an EngineError exception is raised. :df:`process()` The main function to perform the operation on the surfaces. Returns a list of tuples containing: (point_list, face_list, attributes). Note that attributes of the primary group have higher priority than those of the secondary group. --------- Functions --------- The following "high-level" functions will process the two shells with the most commonly-used options. These functions save you the time of setting-up the SITOp structure. :df:`intersectSurfaces(prim_pts, prim_fcs, sec_pts, sec_fcs, operation)` Run surface intersector on two surfaces. Arguments: :a:`prim_pts` : point_list (see `Standard Definitions`_). point_list for primary surface. :a:`prim_fcs` : face_list (see `Standard Definitions`_). face_list for primary surface. :a:`sec_pts` : point_list (see `Standard Definitions`_). point_list for secondary surface. :a:`sec_fcs` : face_list (see `Standard Definitions`_). face_list for secondary surface. :a:`operation` : integer (constant specifying the operation type. See `Constants`_.) intersect operation Returns: A tuple containing: point_list, face_list (see `Standard Definitions`_). An EngineError is raised if no result is found. :df:`intersectSurfacesFromFile(primary_MSR_path, secondary_MSR_path, result_MSR_path, operation)` Run surface intersector on MineSight Resource files containing surfaces. Arguments: :a:`primary_MSR_path` : string file path of the MSR file containing the primary surface(s). An IOError is raised if file does not exist. :a:`secondary_MSR_path` : string file path of the MSR file containing the secondary surface(s). An IOError is raised if file does not exist. :a:`result_MSR_path` : string file path of an MSR file where the resulting surface(s) will be stored. If the file does not exist, it will be created. :a:`operation` : integer (constant specifying the operation type. See `Constants`_.) intersect operation :df:`intersectSurfacesLimit(prim_pts, prim_fcs, sec_pts, sec_fcs, operation, limitPointList)` Run surface intersector on two surfaces. Limit the surfaces (and result) to the area enclosed by the limitPointList. Arguments: :a:`prim_pts` : point_list (see `Standard Definitions`_). point_list for primary surface. :a:`prim_fcs` : face_list (see `Standard Definitions`_). face_list for primary surface. :a:`sec_pts` : point_list (see `Standard Definitions`_). point_list for secondary surface. :a:`sec_fcs` : face_list (see `Standard Definitions`_). face_list for secondary surface. :a:`operation` : integer (constant specifying the operation type. See `Constants`_.) intersect operation :a:`limitPointList` : point_list (see `Standard Definitions`_). point_list of the limiting polygon Returns: A tuple containing: point_list, face_list (see `Standard Definitions`_). An EngineError is raised if no result is found. .. _Standard Definitions: ../lib-grail-ag.html#standard-definitions .. _Union: ../lib-grail-engines-union.html#