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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Outputs ascii representation of stencil to loggger.

Parameters

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