resqpy.grid_surface.find_faces_to_represent_surface_regular¶
- resqpy.grid_surface.find_faces_to_represent_surface_regular(grid, surface, name, title=None, centres=None, agitate=False, random_agitation=False, feature_type='fault', progress_fn=None, consistent_side=False, return_properties=None)¶
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
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
centres (numpy float array of shape (nk, nj, ni, 3), optional) – precomputed cell centre points in local grid space, to avoid possible crs issues; required if grid’s crs includes an origin (offset)?
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’
(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
consistent_side (bool, default False) – if True, the cell pairs will be ordered so that all the first cells in each pair are on one side of the surface, and all the second cells on the other
return_properties (list of str, optional) – if present, a list of property arrays to calculate and return as a dictionary; recognised values in the list are ‘offset’ and ‘normal vector’; offset is a measure of the distance between the centre of the cell face and the intersection point of the inter-cell centre vector with a triangle in the surface; normal vector is a unit vector normal to the surface triangle; each array has an entry for each face in the gcs; the returned dictionary has the passed strings as keys and numpy arrays as values
- Returns
gcs or (gcs, dict) where gcs is a new GridConnectionSet with a single feature, not yet written to hdf5 nor xml created; dict is a dictionary mapping from property name to numpy array; ‘offset’ will map to a numpy float array of shape (gcs.count, ); ‘normal vector’ will map to a numpy float array of shape (gcs.count, 3) holding a unit vector normal to the surface for each of the faces in the gcs; the dict is only returned if a non-empty list has been passed as return_properties
Notes
use find_faces_to_represent_surface_regular_optimised() instead, for faster computation; 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 grid has differing xy & z units, this is accounted for here when generating normal vectors, ie. true normal unit vectors are returned