================================== ``grail.engines.sclip`` Module ================================== .. include:: ..\..\version.h .. contents:: Table of Contents :backlinks: top ----------- Description ----------- A standard interface to the sclip (solid/string clipping) standalone engine executable. -------------------- Standard Definitions -------------------- point_list: A list of points, defined as: [[x0, y0, z0], ..., [xN, yN, zN]]. coded_point_list: A tuple containing two items: the first item is a code (string), the second is the corresponding point_list. This data type is intended to mimic the srv file format. The code should match with an accompanying parameter file (survey code file). For example, ['BENCH', [[x0, y0, z0], ..., [xN, yN, zN]]] face_list: All face lists are described such that the first index indicates how many faces are in the face. For example, [**3**, 1, 2, **3**, 3, 4, 5, 6] States that there are 3 vertexes in the first face, and those vertexes are 1, 2, 3. Then the next face contains 3 vertexes, which are 4, 5, 6. This may seem a bit confusing, but using this structure buys us some definite efficiencies. Note that all faces in MineSightŪ products have 3 vertexes. --------- Functions --------- .. Note:: Be careful with the filepath strings used in these functions. Since the backslash character is used in Python as an escape character, it is best to use forward slashes (or two backslashes) in the filepaths. Most arguments in these functions correspond to an option in the Standalone engine. All arguments in these functions have a default value of `'None'`, which makes the arguments optional. If left unspecified, the option will **not** be included in the call to the engine executable. Calls to these functions must use **`keyword arguments`** (keywords are the formal parameter names). See the examples below for more details. :df:`sclip(solidPointList, solidFaceList, prm, stringsToClip, int, ext, par, intx, union, diff1, diff2, x, dat, n, a, i, v, r, d, opt, delete, debug)` Solid/string clipping Utility. The following sclip options are not currently supported in this function: -drh, -attr, -drill, and -c Arguments: :a:`solidPointList` : point_list (see `Standard Definitions`_). Points of the boundary solid. :a:`solidFaceList` : face_list (see `Standard Definitions`_). Faces of the boundary solid. :a:`prm` : string Parameter file path. If not specified, a default 'survey code file' will be used. :a:`stringsToClip` : list of point_lists (see `Standard Definitions`_). points representing the strings to be clipped. :a:`int` : integer Output strings inside of boundary. Set value to 1 to turn on this option. :a:`ext` : integer Output strings that are outside of boundary or broken at self-intersection points. Set value to 1 to turn on this option. :a:`par` : integer Output strings co-linear to boundary. Set value to 1 to turn on this option. :a:`intx` : integer Output intersection of polygons. Set value to 1 to turn on this option. :a:`union` : integer Output union of polygons. Set value to 1 to turn on this option. :a:`diff1` : integer Output difference: (strings - boundary). Set value to 1 to turn on this option. :a:`diff2` : integer Output difference: (boundary - strings). Set value to 1 to turn on this option. :a:`x` : integer Output intersection points. Set value to 1 to turn on this option. :a:`dat` : string Define a directory for input and output files. :a:`n` : integer Split strings at intersections. Set value to 1 to turn on this option. :a:`a` : integer Add intersection points in to strings. Set value to 1 to turn on this option. :a:`i` : integer Do not intersect strings. Set value to 1 to turn on this option. :a:`v` : integer Validate strings for triangulation. Set value to 1 to turn on this option. :a:`r` : integer Reverse polygons (external oriented clockwise). Set value to 1 to turn on this option. :a:`d` : integer Validate direction for internal and external polygons. Set value to 1 to turn on this option. :a:`opt` : integer Optimize output strings. Set value to 1 to turn on this option. :a:`delete` : integer Delete intersected line segments. Set value to 1 to turn on this option. :a:`debug` : integer Debug option will output the command string used to call the engine executable and will relay any output messages from the engine. Set value to 1 to turn on this option. Returns: A list of point_lists (see `Standard Definitions`_). Example: .. Python:: from grail.engines import sclip cube_points = [[0.0, 0.0, 0.0],[0.0, 1.0, 0.0],[0.0, 0.0, 1.0],[1.0, 0.0, 0.0],[0.0, 1.0, 1.0],[1.0, 1.0, 0.0],[1.0, 0.0, 1.0],[1.0, 1.0, 1.0]] cube_faces = [3,2,6,3,3,2,3,0,3,2,6,7,3,2,7,4,3,6,3,5,3,6,5,7,3,3,0,1,3,3,1,5,3,0,2,4,3,0,4,1,3,4,7,5,3,4,5,1] coded_polyline = ['none', [[-10,0.5,0.5],[10,0.5,0.5]]] polylineList = [coded_polyline] #function expects a list of coded_point_lists #use keyword arguments in function call polylines = sclip.sclip(solidPointList=cube_points, solidFaceList=cube_faces, stringsToClip=polylineList, ext=1) #this particular example will split the line into two segments seg1 = polylines[0] seg2 = polylines[1]