Base¶

class surfalize.base.BaseTopography¶

Bases: CachedInstance

Common base class of Surface and Profile that implements all operations and roughness parameters which are agnostic to the dimensionality of the underlying height data. Methods defined here operate solely on the height data array and therefore apply identically to profiles (1d) and surfaces (2d).

Subclasses must implement the methods ‘_set_data’, which overwrites the data inplace and invalidates the cache, and ‘_with_data’, which constructs a new instance of the subclass with new height data but otherwise identical attributes.

Attributes:

has_masked_points: Returns true if the topography contains masked points.
has_missing_points: Returns true if the topography contains non-measured points.

Methods

`Vm`(p)	Calculates the material volume per unit area at a given material ratio p (Vm(p)) according to ISO 25178-2.
`Vmc`([p, q])	Calculates the difference in material volume between the p and q material ratio.
`Vmp`([p])	Calculates the peak material volume at p.
`Vv`(p)	Calculates the void volume per unit area at a given material ratio p (Vv(p)) according to ISO 25178-2.
`Vvc`([p, q])	Calculates the difference in void volume between p and q material ratio.
`Vvv`([q])	Calculates the dale volume at p material ratio.
`center`([inplace])	Centers the data around its mean value.
`clear_cache`()	Clears the cache for the entire instance.
`create_cache_entry`(method, entry, args, kwargs)	Manually creates a cache entry for the specified method.
`filter`(filter_type, cutoff[, cutoff2, ...])	Filters the topography by applying a Gaussian filter.
`get_abbott_firestone_curve`()	Instantiates and returns an AbbottFirestoneCurve object.
`invert`([inplace])	Inverts the topography, creating a negative.
`max`()	Computes the maximum height value, ignoring invalid points.
`mean`()	Computes the mean height value, ignoring invalid points.
`median`()	Computes the median height value, ignoring invalid points.
`min`()	Computes the minimum height value, ignoring invalid points.
`plot_abbott_curve`([nbars, save_to])	Plots the Abbott-Firestone curve.
`plot_functional_parameter_study`([save_to])	Plots a visual study of the functional parameters derived from the Abbott-Firestone curve.
`remove_outliers`([n, method, inplace])	Removes outliers based on the n-sigma criterion.
`roughness_parameters`([parameters])	Computes multiple roughness parameters at once and returns them in a dictionary.
`std`()	Computes the standard deviation of the height values, ignoring invalid points.
`threshold`([threshold, inplace])	Removes data outside of threshold percentage of the material ratio curve.
`zero`([inplace])	Sets the minimum height to zero.

Vm(p)¶

Calculates the material volume per unit area at a given material ratio p (Vm(p)) according to ISO 25178-2. Vmp and Vmc are special cases of this general parameter.

Parameters:

pfloat: material ratio in %.

Returns:

Vmfloat

Note

This method is available in the Batch class.

Vmc(p=10, q=80)¶

Calculates the difference in material volume between the p and q material ratio. The default value of p and q are is 10% and 80%, respectively, according to ISO-25178-3.

Parameters:

pfloat, default 10.: material ratio in %.
qfloat, default 80.: material ratio in %.

Returns:

Vmcfloat

Note

This method is available in the Batch class.

Vmp(p=10)¶

Calculates the peak material volume at p. The default value of p is 10% according to ISO-25178-3.

Parameters:

pfloat, default 10.: material ratio in %.

Returns:

Vmpfloat

Note

This method is available in the Batch class.

Vv(p)¶

Calculates the void volume per unit area at a given material ratio p (Vv(p)) according to ISO 25178-2. Vvv and Vvc are special cases of this general parameter.

Parameters:

pfloat: material ratio in %.

Returns:

Vvfloat

Note

This method is available in the Batch class.

Vvc(p=10, q=80)¶

Calculates the difference in void volume between p and q material ratio. The default value of p and q are is 10% and 80%, respectively, according to ISO-25178-3.

Parameters:

pfloat, default 10.: material ratio in %.
qfloat, default 80.: material ratio in %.

Returns:

Vvcfloat

Note

This method is available in the Batch class.

Vvv(q=80)¶

Calculates the dale volume at p material ratio. The default value of p is 80% according to ISO-25178-3.

Parameters:

pfloat, default 80.: material ratio in %.

Returns:

Vvvfloat

Note

This method is available in the Batch class.

center(inplace=False)¶

Centers the data around its mean value. The height will be distributed equally around 0.

Parameters:

inplacebool, default False: If False, create and return new object with processed data. If True, changes data inplace and return self.

Returns:

Surface | Profile

Note

This method is available in the Batch class. The following parameters are removed in the batch version: inplace.

filter(filter_type, cutoff, cutoff2=None, inplace=False, endeffect_mode='reflect')¶

Filters the topography by applying a Gaussian filter.

There a several types of filtering:

‘highpass’: computes spatial frequencies above the specified cutoff value
‘lowpass’: computes spatial frequencies below the specified cutoff value
‘both’: computes and returns both the highpass and lowpass filtered topographies
‘bandpass’: computes frequencies below the specified cutoff value and above the value specified for cutoff2

The object’s data can be changed inplace by specifying ‘inplace=True’ for ‘highpass’, ‘lowpass’ and ‘bandpass’ mode. For mode=’both’, inplace=True will raise a ValueError.

Parameters:

filter_typestr: Mode of filtering. Possible values: ‘highpass’, ‘lowpass’, ‘both’, ‘bandpass’.
cutofffloat: Cutoff wavelength in µm at which the high and low spatial frequencies are separated. Actual cutoff will be rounded to the nearest pixel unit (1/px) equivalent.
cutoff2float | None, default None: Used only in mode=’bandpass’. Specifies the larger cutoff wavelength of the bandpass filter. Must be greater than cutoff.
inplacebool, default False: If False, create and return new object with processed data. If True, changes data inplace and return self. Inplace operation is not compatible with mode=’both’ argument, since two objects will be returned.
endeffect_mode{reflect, constant, nearest, mirror, wrap}, default reflect: The parameter determines how the endeffects of the filter at the boundaries of the data are managed. For details, see the documentation of scipy.ndimage.gaussian_filter. https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.gaussian_filter.html

Returns:

Surface | Profile

Note

This method is available in the Batch class. The following parameters are removed in the batch version: inplace.

get_abbott_firestone_curve()¶

Instantiates and returns an AbbottFirestoneCurve object. LRU cache is used to return the same object with every function call.

Returns:

AbbottFirestoneCurve

Note

This method is available in the Batch class.

property has_masked_points¶

Returns true if the topography contains masked points. The base implementation always returns False; subclasses that support masking (such as Surface) override this.

Returns:

bool

property has_missing_points¶

Returns true if the topography contains non-measured points.

Returns:

bool

invert(inplace=False)¶

Inverts the topography, creating a negative.

Parameters:

inplacebool, default False: If False, create and return new object with processed data. If True, changes data inplace and return self.

Returns:

Surface | Profile

Note

This method is available in the Batch class. The following parameters are removed in the batch version: inplace.

max()¶

Computes the maximum height value, ignoring invalid points.

Returns:

float

mean()¶

Computes the mean height value, ignoring invalid points.

Returns:

float

median()¶

Computes the median height value, ignoring invalid points.

Returns:

float

min()¶

Computes the minimum height value, ignoring invalid points.

Returns:

float

plot_abbott_curve(nbars=20, save_to=None)¶

Plots the Abbott-Firestone curve.

Parameters:

nbarsint: Number of bars to display for the material density
save_tostr | pathlib.Path | None: Path to where the plot should be saved.

Returns:

plt.Figure, tuple[plt.Axes]

plot_functional_parameter_study(save_to=None)¶

Plots a visual study of the functional parameters derived from the Abbott-Firestone curve.

Parameters:

save_tostr | pathlib.Path | None: Path to where the plot should be saved.

Returns:

plt.Figure, plt.Axes

remove_outliers(n=3, method='mean', inplace=False)¶

Removes outliers based on the n-sigma criterion. All values that fall outside n-standard deviations of the mean are replaced by nan values. The default is three standard deviations. This method supports operation on data which contains non-measured points.

Parameters:

nfloat, default 3: Number of standard deviations outside of which values are considered outliers if method is ‘mean’. If the method is ‘median’, n represents the number of medians distances of the data to its median value.
method{‘mean’, ‘median’}, default ‘mean’: Method by which to perform the outlier detection. The default method is mean, which removes outliers outside an interval of n standard deviations from the mean. The method ‘median’ removes outliers outside n median distances of the data to its median.
inplacebool, default False: If False, create and return new object with processed data. If True, changes data inplace and return self.

Returns:

Surface | Profile

Note

This method is available in the Batch class. The following parameters are removed in the batch version: inplace.

roughness_parameters(parameters=None)¶

Computes multiple roughness parameters at once and returns them in a dictionary.

Parameters:

parameterslist-like[str], default None: List-like object of parameters to evaluate. If None, all available parameters are evaluated.

Returns:

parametersdict[str: float]

Examples

>>> surface.roughness_parameters(['Sa', 'Sq', 'Sz'])
{'Sa': 1.23, 'Sq': 1.87, 'Sz': 2.51}

std()¶

Computes the standard deviation of the height values, ignoring invalid points.

Returns:

float

threshold(threshold=0.5, inplace=False)¶

Removes data outside of threshold percentage of the material ratio curve. The topmost percentage (given by threshold) of hight values and the lowest percentage of height values are replaced with non-measured points. This method supports operation on data which contains non-measured points.

Parameters:

thresholdfloat or tuple[float, float], default 0.5: Percentage threshold value of the material ratio. If threshold is a tuple, the first value represents the upper threshold and the second value represents the lower threshold. For example, threshold=0.5 removes the uppermost and lowermost 0.5% from the material ratio curve. The achieve the same result when specifiying the upper and lower threshold explicitly, the tuple passed ton threshold must be (0.5, 0.5)
inplacebool, default False: If False, create and return new object with processed data. If True, changes data inplace and return self.

Returns:

Surface | Profile

Note

This method is available in the Batch class. The following parameters are removed in the batch version: inplace.

zero(inplace=False)¶

Sets the minimum height to zero.

Parameters:

inplacebool, default False: If False, create and return new object with processed data. If True, changes data inplace and return self.

Returns:

Surface | Profile

Note

This method is available in the Batch class. The following parameters are removed in the batch version: inplace.

surfalize.base.batch_method(type_, return_labels=None, batch_doc=None, fixed={'inplace': True})¶

Decorator to mark Surface methods for batch processing.

Parameters:

type_str: Type of batch method (‘operation’ or ‘parameter’)
return_labelstuple, optional: Labels for multiple return values (only used for parameters)
batch_docstr, optional: Additional batch-specific documentation.
fixeddict[str: Any]: Keyword arguments that must have a specific value when calling the method from the Batch class. By default, the inplace argument is set to True for the Batch method, since returning a copy of the surface object does not make sense. Parameters with fixed values are removed from the function signature and docstring of the Batch method.

Returns:

Wrapped function

surfalize.base.no_nonmeasured_points(function)¶

Decorator that raises an Exception if the method is called on a surface or profile object that contains non-measured points. This decorator should be used for any method that does not compute correctly if nan values are present in the array.

Parameters:

functionfunction: Function to be decorated.

Returns:

Wrapped function