resqpy.grid_surface.find_faces_to_represent_surface_regular_optimised

resqpy.grid_surface.find_faces_to_represent_surface_regular_optimised(grid, surface, name, title=None, agitate=False, random_agitation=False, feature_type='fault', is_curtain=False, progress_fn=None, return_properties=None, raw_bisector=False, n_batches=20, packed_bisectors=False, patch_indices=None, direction='IJK')

Returns a grid connection set containing those cell faces which are deemed to represent the surface.

Parameters:

  • grid (RegularGrid) – the grid for which to create a grid connection set representation of the surface; must be aligned, ie. I with +x, J with +y, K with +z and local origin of (0.0, 0.0, 0.0)

  • surface (Surface) – the surface to be intersected with the grid

  • name (str) – the feature name to use in the grid connection set

  • title (str, optional) – the citation title to use for the grid connection set; defaults to name

  • agitate (bool, default False) – if True, the points of the surface are perturbed by a small offset, which can help if the surface has been built from a regular mesh with a periodic resonance with the grid

  • random_agitation (bool, default False) – if True, the agitation is by a small random distance; if False, a constant positive shift of 5.0e-6 is applied to x, y & z values; ignored if agitate is False

  • feature_type (str, default 'fault') – ‘fault’, ‘horizon’ or ‘geobody boundary’

  • is_curtain (bool, default False) – if True, only the top layer of the grid is processed and the bisector property, if requested, is generated with indexable element columns

  • (f(x (progress_fn) – float), optional): a callback function to be called at intervals by this function; the argument will progress from 0.0 to 1.0 in unspecified and uneven increments

  • return_properties (List[str]) – if present, a list of property arrays to calculate and return as a dictionary; recognised values in the list are ‘triangle’, ‘depth’, ‘offset’, ‘flange bool’, ‘grid bisector’, or ‘grid shadow’; triangle is an index into the surface triangles of the triangle detected for the gcs face; depth is the z value of the intersection point of the inter-cell centre vector with a triangle in the surface; offset is a measure of the distance between the centre of the cell face and the intersection point; grid bisector is a grid cell boolean property holding True for the set of cells on one side of the surface, deemed to be shallower; grid shadow is a grid cell int8 property holding 0: cell neither above nor below a K face of the gridded surface, 1 cell is above K face(s), 2 cell is below K face(s), 3 cell is between K faces; the returned dictionary has the passed strings as keys and numpy arrays as values

  • raw_bisector (bool, default False) – if True and grid bisector is requested then it is left in a raw form without assessing which side is shallower (True values indicate same side as origin cell)

  • n_batches (int, default 20) – the number of batches of triangles to use at the low level (numba multi threading allows some parallelism between the batches)

  • packed_bisectors (bool, default False) – if True and return properties include ‘grid bisector’ then non curtain bisectors are returned in packed form

  • patch_indices (numpy int array, optional) – if present, an array over grid cells indicating which patch of surface is applicable in terms of a bisector, for each cell

  • direction (str, default 'IJK') – indicates which face directions to include; one of ‘I’, ‘J’, ‘K’, ‘IJ’, IK’, ‘JK’, ‘IJK”

Returns:

gcs or (gcs, gcs_props) where gcs is a new GridConnectionSet with a single feature, not yet written to hdf5 nor xml created; gcs_props is a dictionary mapping from requested return_properties string to numpy array (or tuple

of numpy array and curtain bool in the case of grid bisector)

Notes

this function is designed for aligned regular grids only; this function can handle the surface and grid being in different coordinate reference systems, as long as the implicit parent crs is shared; no trimming of the surface is carried out here: for computational efficiency, it is recommended to trim first; organisational objects for the feature are created if needed; if the offset return property is requested, the implicit units will be the z units of the grid’s crs; if patch_indices is present and grid bisectors are being returned, a composite bisector array is returned with elements set from individual bisectors for each patch of surface; if generating a grid bisector property then direction will typically need to be ‘IJK’