resqpy.surface.TriMeshStencil

class resqpy.surface.TriMeshStencil(pattern, normalize=None, normalize_mode_flat=True)

Bases: object

Class holding a temporary regular hexagonal symmetrical stencil for use with TriMesh objects.

Note

this class does not currently include store and load methods, as the stencil is regarded as a temporary disposable object

Methods:

__init__(pattern[, normalize, ...])	Initialises a TriMeshStencil object from xml, or from arguments.
for_constant_normalized(n[, normalize_mode_flat])	Create a tri mesh stencil with a constant pattern, then normalized to sum to one.
for_constant_unnormalized(n, c)	Create a tri mesh stencil with a constant pattern, without normalization.
for_linear_normalized(n[, normalize_mode_flat])	Create a tri mesh stencil with a linearly decreasing pattern, then normalized to sum to one.
for_linear_unnormalized(n, centre, outer)	Create a tri mesh stencil with a linearly decreasing pattern, without normalization.
for_gaussian_normalized(n[, sigma, ...])	Create a tri mesh stencil with a gaussian pattern, then normalized to sum to one.
for_gaussian_unnormalized(n, centre[, sigma])	Create a tri mesh stencil with a gaussian pattern, without normalization.
apply(tri_mesh[, handle_nan, border_value, ...])	Return a new tri mesh with z values generated by applying the stencil to z values of an existing tri mesh.
log([log_level])	Outputs ascii representation of stencil to loggger.

__init__(pattern, normalize=None, normalize_mode_flat=True)

Initialises a TriMeshStencil object from xml, or from arguments.

Parameters:

• pattern (1D numpy float array) – values for one radial arm of the stencil (first value is centre)

• normalize (non zero float, optional) – if present, stencil values are normalized to sum to this value; if None, no normalization is applied; set to one for smoothing; see also normalize_mode_flat argument

• normalize_mode_flat (bool, default True) – if True (and normalize is not None), then ring values in the stencil preserve relative weights of unnormalized pattern values; if False, weights of ring values (away from centre) are decreased by a factor of the number of elements in the ring; in either case, the final normalization is such that the sum of all stencil elements is the value of the normalize argument

Returns:

the newly created TriMeshStencil object

Note

the area of inflence of the stencil is hexagonal in shape with a half-axis length equal to the t_side length of a target tri mesh multiplied by (n - 1) where n is the length of the pattern

apply(tri_mesh, handle_nan=True, border_value=nan, preserve_nan=False, title=None)

Return a new tri mesh with z values generated by applying the stencil to z values of an existing tri mesh.

Parameters:

• tri_mesh (TriMesh) – an existing tri mesh to apply the stencil to

• handle_nan (bool, default True) – if True, a smoothing style weighted average of non-NaN values is used; if False, a simple convolution is applied and will yield NaN where any input within the stencil area is NaN

• border_value (float, default NaN) – the pre-filled value for an extended bprder around the input tri mesh; set to zero if partial convolution values are wanted at the edge of the tri mesh when handle_nan is False

• preserve_nan (bool, default False) – if True (and handle_nan is True) then where the input tri mesh has a NaN z value, the output will also have NaN; if False, patches of NaNs smaller than the stencil will get ‘smoothed over’, ie. filled in, if handle_nan is True

• title (str, optional) – the title to use for the new tri mesh; if None, title is inherited from input

Returns:

a new TriMesh in the same model as the input tri mesh, with the stencil having been applied to z values

Notes

this method does not write hdf5 nor create xml for the new tri mesh; if handle_nan is False and border_value is NaN, the result will have NaN values around the edge of the tri mesh, to a depth equivalent to the pattern length

classmethod for_constant_normalized(n, normalize_mode_flat=True)

Create a tri mesh stencil with a constant pattern, then normalized to sum to one.

Parameters:

n (int); the length of pattern (ie. half width of hexagon)

Returns:

the newly created TriMeshStencil object

classmethod for_constant_unnormalized(n, c)

Create a tri mesh stencil with a constant pattern, without normalization.

Parameters:

• n (int); the length of pattern (ie. half width of hexagon)

• c (float) – the value to use throughout the stencil

Returns:

the newly created TriMeshStencil object

classmethod for_gaussian_normalized(n, sigma=3.0, normalize_mode_flat=True)

Create a tri mesh stencil with a gaussian pattern, then normalized to sum to one.

Parameters:

• n (int); the length of pattern (ie. half width of hexagon)

• sigma (float, default 3.0) – the number of standard deviations at the outermost ring of the stencil

Returns:

the newly created TriMeshStencil object

classmethod for_gaussian_unnormalized(n, centre, sigma=3.0)

Create a tri mesh stencil with a gaussian pattern, without normalization.

Parameters:

• n (int); the length of pattern (ie. half width of hexagon)

• centre (float) – the value at the centre of the stencil (peak amplitude)

• sigma (float, default 3.0) – the number of standard deviations at the outermost ring of the stencil

Returns:

the newly created TriMeshStencil object

classmethod for_linear_normalized(n, normalize_mode_flat=True)

Create a tri mesh stencil with a linearly decreasing pattern, then normalized to sum to one.

Parameters:

n (int); the length of pattern (ie. half width of hexagon)

Returns:

the newly created TriMeshStencil object

classmethod for_linear_unnormalized(n, centre, outer)

Create a tri mesh stencil with a linearly decreasing pattern, without normalization.

Parameters:

• n (int); the length of pattern (ie. half width of hexagon)

• centre (float) – the value of the pattern at the centre of the stencil

• outer (float) – the value of the pattern in the outer ring of the stencil

Returns:

the newly created TriMeshStencil object

log(log_level=10)

Outputs ascii representation of stencil to loggger.

Parameters:

log_level (int, default DEBUG) – the logging severity level to use