slippy.surface.roughness

slippy.surface.roughness(profile_in: {<class 'numpy.ndarray'>, <class 'slippy.core.abcs._SurfaceABC'>}, parameter_name: {typing.Sequence[str], <class 'str'>}, grid_spacing: typing.Optional[float] = None, mask: typing.Optional[typing.Union[numpy.ndarray, float]] = None, curved_surface: bool = False, no_flattening: bool = False, filter_cut_off: typing.Optional[float] = None, four_nearest: bool = False) → {<class 'list'>, <class 'float'>}[source]

Find 3d surface roughness parameters

Calculates and returns common surface roughness parameters also known as birmingham parameters

Parameters

  • profile_in (array like or Surface) – The surface profile or surface object to be used

  • parameter_name (str or Sequence[str]) – The name of the surface roughness parameter to be returned see notes for descriptions of each

  • grid_spacing (float optional (None)) – The distance between adjacent grid points in the surface only required for some parameters, see notes

  • mask (array-like same shape as profile or float (None)) – If an array, the array is used as a mask for the profile, it must be the same shape as the profile, if a float or list of floats is given, those values are excluded from the calculation. If None, no mask is used. Limited applicability, see notes

  • curved_surface (bool optional (False)) – True if the measurement surface was curved, in this case a 2nd order polynomial is subtracted other wise a 1st order polynomial is subtracted before the measurement

  • no_flattening (bool optional (False)) – If true, flattening will be skipped, no polynomial will be subtracted before calculation of parameters, used for periodic surfaces or to save time

  • filter_cut_off (float, optional (None)) – The cut off frequency of the low pass filter applied to the surface before finding summits, only used for parameters which need summits, if not set no low pass filter is applied

  • four_nearest (bool, optional (False)) – If true any point that is higher than it’s 4 nearest neighbours will be counted as a summit, otherwise a point must be higher than it’s 8 nearest neighbours to be a summit. Only used if summit descriptions are required, passed to find_summits.

Returns

out – The requested parameters

Return type

float or list[float]

See also

Surface

a helper class with useful surface analysis functionality

subtract_polynomial, find_summits, get_mat_vr, get_summit_curvatures

Notes

Before calculation the least squares plane is subtracted if a periodic surface is used this can be prevented by setting the no_flattening key word to true. If a curved surface is used a bi quadratic polynomial is fitted and removed before analysis as described in the above text.

If a list of valid parameter names is given this method will return a list of parameter values.

If a parameter based on summit descriptions is needed the following key words can be set to refine what counts as a summit, see find_summits for more information. This is only used to find summits, calculations of curvature are run on the unfiltered profile:

  • filter_cut_off (default None)

  • and

  • four_nearest (default False)

Descriptions of each of the surface roughness parameters are given below:

Amplitude parameters:

  • Sq - RMS deviation of surface height *

  • Sz - Ten point height (based on definition of summits) *-

  • Ssk - Skew of the surface (3rd moment) *

  • Sku - Kurtosis of the surface (4th moment) *

  • Sv - Lowest valley in the sample *

Spatial parameters:

  • Sds - Summit density*-, see note above on definition of summit

  • Str - Texture aspect ratio defined using the aacf

  • Std - Texture direction

  • Sal - Fastest decay auto correlation length +

hybrid parameters:

  • Sdelq- RMS slope +

  • Ssc - Mean summit curvature, see note above on definition of summit *+

  • Sdr - Developed interfacial area ratio +

functional parameters:

  • Sbi - Bearing index *

  • Sci - Core fluid retention index *

  • Svi - Valley fluid retention index *

non ‘core’ parameters (implemented):

  • Sa - Mean amplitude of surface *

  • Stp - Surface bearing ratio *

  • Smr - Material volume ratio of the surface *

  • Svr - Void volume ratio of the surface, as for previous *

non ‘core’ parameters (not implemented):

  • Sk - Core roughness depth

  • Spk - Reduced summit height

  • Svk - Reduced valley depth

  • Sr1 - Upper bearing area

  • Sr2 - Lower bearing area

* masking supported

+ requires grid_spacing

- requires grid spacing only if filtering is used for summit definition

Summit parameters only support masking if low pass filtering is not required

Parameter names are not case sensitive

Examples

References

Stout, K., Sullivan, P., Dong, W., Mainsah, E., Luo, N., Mathia, T., & Zahouani, H. (1993). The development of methods for the characterisation of roughness in three dimensions. EUR(Luxembourg), 358. Retrieved from http://cat.inist.fr/?aModele=afficheN&cpsidt=49475 chapter 12