Surface¶

class surfalize.surface.Surface(height_data, step_x, step_y, metadata=None, image_layers=None)¶

Bases: CachedInstance

Representation a 2D-topography characterised by a 2d array of height data and an associated stepsize in x and y. x hereby denotes the horizontal axis, which corresponds to the second array dimension, while y denotes the vertical axis corresponding to the first array dimension. Generally, the code is written with equal stepsize in both axes in mind. Undexpected behavior may occur if the stepsize is not equal in both axes. This has to be tested in the future.

The class implements methods to calculate roughness parameters defined in ISO 25178 as well as custom parameters for surfaces that exhibit 1D-periodic textures. Moreover, it implements methods for data processing and correction.

Overview over available ISO-25178 roughness parameters:

Height parameters: Sa, Sq, Sz, Sv, Sp, Ssk, Sku
Hybrid parameters: Sdr, Sdq
Functional parameters: Sk, Svk, Spk, Smr1, Smr2, Sxp, Smr(c), Smc(mr)
Functional volume parameters: Vmc, Vmp, Vvc, Vvv
Spatial parameters: Sal, Str

Periodic parameters: - Spatial period: computed from Frourier transform - Structure depth: computed from n profiles - Structure aspect ratio: computed from depth and period - Structure homogeneity: computed using Gini coefficient - Structure orientation: Angle of the dominant texture towards the vertical axis

Overview of data operations: - Zeroing: Setting lowest height value to zero - Centering: Centering height values around the mean - Cropping: Cropping to specified borders - Zooming: Magnification by factor around the center - Rotating: Rotating surface by angle - Aligning: Aligning the surface to the dominant texture direction - Levelling: Leveling by least squares plane - Filtering: Applying lowpass, highpass or bandpass filters - Removing outliers: Remove outliers by mean of median filters - Thresholding: Thresholding based on areal material ratio - Filling non-measured points: Interpolating non-measured points

Plotting: - Surface data - Abbott-Firestone curve - Fourier Transform

Parameters:

height_datandarray: A 2d numpy array containing the height data
step_xfloat: Interval between two datapoints in x-axis (horizontal axis, second array dimension)
step_yfloat: Interval between two datapoints in y-axis (vertical axis, first array dimension)

Attributes:

has_missing_points: Returns true if surface contains non-measured points.
size: Returns the size of the height data array in pixels as a namedtuple of the form (y, x).

Methods

`Sa`()	Calcualtes the arithmetic mean height Sa according to ISO 25178-2.
`Sal`([s])	Calculates the autocorrelation length Sal.
`Sdq`()	Calculates the root mean square gradient Sdq according to ISO 25178-2.
`Sdr`()	Calculates the developed interfacial area ratio according to ISO 25178-2.
`Sk`()	Calculates Sk in µm.
`Sku`()	Calcualtes the kurtosis Sku according to ISO 25178-2.
`Smc`(mr)	Calculates the height (c) in µm for a given areal material ratio (mr).
`Smr`(c)	Calculates the ratio of the area of the material at a specified height c (in µm) to the evaluation area.
`Smr1`()	Calculates Smr1 in %.
`Smr2`()	Calculates Smr2 in %.
`Sp`()	Calcualtes the maximum peak height Sp according to ISO 25178-2.
`Spk`()	Calculates Spk in µm.
`Sq`()	Calcualtes the root mean square height Sq according to ISO 25178-2.
`Ssk`()	Calcualtes the skewness Ssk according to ISO 25178-2.
`Std`([angle_step])	Calculates the texture direction parameter, which is the angle at which the angular power spectrum is the largest.
`Str`([s])	Calculates the texture aspect ratio Str.
`Sv`()	Calcualtes the maximum pit height Sv according to ISO 25178-2.
`Svk`()	Calculates Svk in µm.
`Sxp`([p, q])	Calculates the difference in height between the p and q material ratio.
`Sz`()	Calcualtes the skewness Ssk 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.
`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.
`align`([axis, method, inplace])	Computes the dominant orientation of the surface pattern and alignes the orientation with the horizontal or vertical axis.
`aspect_ratio`()	Calculates the aspect ratio of a periodic texture as the ratio of the structure depth and the structure period.
`cavity_volume`([threshold])	Calculates the cavity volume of a flat surface containing an ablation crater with a leveled bottom plane.
`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.
`crop`(box[, in_units, inplace])	Crop the surface to the area specified by the box parameter.
`depth`([nprofiles, sampling_width, plot])	Calculates the peak-to-valley depth of a periodically grooved surface texture.
`detrend_polynomial`([degree, inplace, ...])	Detrend a 2d array of height data using a polynomial surface, handling NaN values
`fill_nonmeasured`([method, inplace])	Fills the non-measured points by interpolation.
`filter`(filter_type, cutoff[, cutoff2, ...])	Filters the surface by applying a Gaussian filter.
`from_raw_surface`(raw_surface)	Classmethod that instantiates a Surface object from a RawSurface object returned by the file readers.
`get_abbott_firestone_curve`()	Instantiates and returns an AbbottFirestoneCurve object.
`get_autocorrelation_function`()	Instantiates and returns an AutocorrelationFunction object.
`get_horizontal_profile`(y[, average, ...])	Extracts a horizontal profile from the surface with optional averaging over parallel profiles.
`get_image_layer_names`()	Returns a list of the names of available image layers.
`get_oblique_profile`(x0, y0, x1, y1)	Extracts an oblique profile from the surface.
`get_vertical_profile`(x[, average, average_step])	Extracts a vertical profile from the surface with optional averaging over parallel profiles.
`height_parameters`()	Calculates the roughness parameters from the height parameter family.
`homogeneity`([parameters, period])	Calculates the homogeneity of a periodic surface through Gini coefficient analysis.
`invert`([inplace])	Inverts the surface topography, creating a negative.
`level`([return_trend, inplace])	Levels the surface by subtraction of a least squares fit plane.
`load`(path_or_buffer[, format, encoding, ...])	Classmethod to load a topography from a file.
`max`()	Computes the maximum value of the surface, ignoring invalid points.
`mean`()	Computes the mean value of the surface, ignoring invalid points.
`median`()	Computes the median value of the surface, ignoring invalid points.
`min`()	Computes the minimum value of the surface, ignoring invalid points.
`orientation`([method])	Computes the orientation angle of the dominant texture to the vertical axis in degree.
`period`()	Calculates the 1d spatial period based on the Fourier transform.
`period_x_y`()	Calculates the spatial period along the x and y axes based on the Fourier transform.
`plot_2d`([cmap, maskcolor, layer, ax, vmin, ...])	Creates a 2D-plot of the surface using matplotlib.
`plot_3d`([vertical_angle, horizontal_angle, ...])	Renders a surface object in 3d using pyvista.
`plot_abbott_curve`([nbars, save_to])	Plots the Abbott-Firestone curve.
`plot_autocorrelation`([ax, cmap, show_cbar, ...])	Plots the Autocorrelation function.
`plot_fourier_transform`([ax, log, hanning, ...])	Plots the 2d Fourier transform of the surface.
`plot_functional_parameter_study`([save_to])	Plots the Abbott-Firestone curve.
`projected_area`()	Calculates the projected surface area.
`remove_outliers`([n, method, inplace])	Removes outliers based on the n-sigma criterion.
`rotate`(angle[, inplace])	Rotates the surface counterclockwise by the specified angle and crops it to largest possible rectangle with the same aspect ratio as the original surface that does not contain any invalid points.
`roughness_parameters`(parameters)	Computes multiple roughness parameters at once and returns them in a dictionary.
`save`(path_or_buffer[, format, encoding])	Saves the surface to a supported file format.
`show`([cmap, maskcolor, layer, ax])	Shows a 2D-plot of the surface using matplotlib.
`std`()	Computes the standard deviation the surface, ignoring invalid points.
`stepheight`()	Calculates the stepheight of two-level ablation experiment.
`stepheight_level`([inplace])	Levels the surface only based on the datapoints from the upper level surface in a rectangular ablation cavity.
`surface_area`()	Calculates the surface area of the surface according to the method proposed by ISO 25178 and used by MountainsMap, whereby two triangles are spanned between four corner points.
`threshold`([threshold, inplace])	Removes data outside of threshold percentage of the material ratio curve.
`zero`([inplace])	Sets the minimum height of the surface to zero.
`zoom`(factor[, inplace])	Magnifies the surface by the specified factor.

plot_angular_power_spectrum

Examples

Constructing a surface from a 2d array.

>>> step_x = step_y = 0.1 # mm
>>> size_x = 200
>>> size_y = 100
>>> period = 5
>>> y, x = np.mgrid[0:size_y:step_y, 0:size_x:step_x]
>>> height_data = np.sin(x / period * 2 * np.pi)
>>> surface = Surface(height_data, step_x, step_y)

Use the load class method to load a topography from a file.

>>> filepath = r'path\to\surface.plu'
>>> surface = Surface.load(filepath)

AVAILABLE_PARAMETERS = ('Sa', 'Sq', 'Sp', 'Sv', 'Sz', 'Ssk', 'Sku', 'Sdr', 'Sdq', 'Sal', 'Str', 'Sk', 'Spk', 'Svk', 'Smr1', 'Smr2', 'Sxp', 'Vmp', 'Vmc', 'Vvv', 'Vvc', 'period', 'depth', 'aspect_ratio', 'homogeneity', 'stepheight', 'cavity_volume')¶

ISO_PARAMETERS = ('Sa', 'Sq', 'Sp', 'Sv', 'Sz', 'Ssk', 'Sku', 'Sdr', 'Sdq', 'Sal', 'Str', 'Sk', 'Spk', 'Svk', 'Smr1', 'Smr2', 'Sxp', 'Vmp', 'Vmc', 'Vvv', 'Vvc')¶

Sa()¶

Calcualtes the arithmetic mean height Sa according to ISO 25178-2.

Returns:

Safloat

Note

This method is available in the Batch class.

Sal(s=0.2)¶

Calculates the autocorrelation length Sal. Sal represents the horizontal distance of the f_ACF(tx,ty) which has the fastest decay to a specified value s, with 0 < s < 1. s represents the fraction of the maximum value of the autocorrelation function. The default value for s is 0.2 according to ISO 25178-3.

Parameters:

sfloat: threshold value below which the data is considered to be uncorrelated. The point of fastest and slowest decay are calculated respective to the threshold value, to which the autocorrelation function decays. The threshold s is a fraction of the maximum value of the autocorrelation function.

Returns:

Salfloat: autocorrelation length.

Note

This method is available in the Batch class.

Sdq()¶

Calculates the root mean square gradient Sdq according to ISO 25178-2.

Returns:

Sdqfloat

Note

This method is available in the Batch class.

Sdr()¶

Calculates the developed interfacial area ratio according to ISO 25178-2.

Returns:

areafloat

Note

This method is available in the Batch class.

Sk()¶

Calculates Sk in µm.

Returns:

Skfloat

Note

This method is available in the Batch class.

Sku()¶

Calcualtes the kurtosis Sku according to ISO 25178-2. It is the quotient of the mean quartic value of the ordinate values and the fourth power of Sq within a definition area.

Returns:

Skufloat

Note

This method is available in the Batch class.

Smc(mr)¶

Calculates the height (c) in µm for a given areal material ratio (mr).

Parameters:

mrfloat: areal material ratio in %.

Returns:

heightfloat

Note

This method is available in the Batch class.

Smr(c)¶

Calculates the ratio of the area of the material at a specified height c (in µm) to the evaluation area.

Parameters:

cfloat: height in µm.

Returns:

areal material ratiofloat

Note

This method is available in the Batch class.

Smr1()¶

Calculates Smr1 in %.

Returns:

Smr1float

Note

This method is available in the Batch class.

Smr2()¶

Calculates Smr2 in %.

Returns:

Smr2float

Note

This method is available in the Batch class.

Sp()¶

Calcualtes the maximum peak height Sp according to ISO 25178-2.

Returns:

Spfloat

Note

This method is available in the Batch class.

Spk()¶

Calculates Spk in µm.

Returns:

Spkfloat

Note

This method is available in the Batch class.

Sq()¶

Calcualtes the root mean square height Sq according to ISO 25178-2.

Returns:

Sqfloat

Note

This method is available in the Batch class.

Ssk()¶

Calcualtes the skewness Ssk according to ISO 25178-2. It is the quotient of the mean cube value of the ordinate values and the cube of Sq within a definition area.

Returns:

Sskfloat

Note

This method is available in the Batch class.

Std(angle_step=0.5)¶

Calculates the texture direction parameter, which is the angle at which the angular power spectrum is the largest. It represents the lay of the surface texture.

Parameters:

angle_stepfloat: Angular resolution of the power spectrum in degree. Defaults to 0.5

Returns:

float

Str(s=0.2)¶

Calculates the texture aspect ratio Str. Str represents the ratio of the horizontal distance of the f_ACF(tx,ty) which has the fastest decay to a specified value s to the horizontal distance of the fACF(tx,ty) which has the slowest decay to s, with 0 < s < 1. s represents the fraction of the maximum value of the autocorrelation function. The default value for s is 0.2 according to ISO 25178-3.

Parameters:

sfloat: threshold value below which the data is considered to be uncorrelated. The point of fastest and slowest decay are calculated respective to the threshold value, to which the autocorrelation function decays. The threshold s is a fraction of the maximum value of the autocorrelation function.

Returns:

Strfloat: texture aspect ratio.

Note

This method is available in the Batch class.

Sv()¶

Calcualtes the maximum pit height Sv according to ISO 25178-2.

Returns:

Svfloat

Note

This method is available in the Batch class.

Svk()¶

Calculates Svk in µm.

Returns:

Svkfloat

Note

This method is available in the Batch class.

Sxp(p=2.5, q=50)¶

Calculates the difference in height between the p and q material ratio. For Sxp, p and q are defined by the standard ISO 25178-3 to be 2.5% and 50%, respectively.

Parameters:

pfloat: material ratio p in % as defined by the standard ISO 25178-3
qfloat: material ratio q in % as defined by the standard ISO 25178-3

Returns:

Height difference: float

Note

This method is available in the Batch class.

Sz()¶

Calcualtes the skewness Ssk according to ISO 25178-2.

Returns:

Sskfloat

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.: areal material ratio in %.
qfloat, default 80.: areal 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.: areal material ratio in %.

Returns:

Vmpfloat

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.: areal material ratio in %.
qfloat, default 80.: areal 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.: areal material ratio in %.

Returns:

Vvvfloat

Note

This method is available in the Batch class.

align(axis='y', method='fft_refined', inplace=False)¶

Computes the dominant orientation of the surface pattern and alignes the orientation with the horizontal or vertical axis.

Parameters:

axis{‘x’, ‘y’}, default ‘y’: The axis with which to align the texture with.
method{‘fft_refined’, ‘fft’}: Method by which to calculate the orientation. Default is ‘fft_refined’. See Surface.orientation for more details.
inplacebool, default False: If False, create and return new Surface object with processed data. If True, changes data inplace and return self

Returns:

surfacesurfalize.Surface: Surface object.

Note

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

aspect_ratio() → float¶

Calculates the aspect ratio of a periodic texture as the ratio of the structure depth and the structure period.

Returns:

aspect_ratiofloat

Note

This method is available in the Batch class.

cavity_volume(threshold=0.5)¶

Calculates the cavity volume of a flat surface containing an ablation crater with a leveled bottom plane.

Parameters:

thresholdfloat, default 0.5: Percentage threshold value for the cutoff between the upper and lower levels used to determine the area inside which the volume is calculated.

Returns:

volumefloat

Note

This method is available in the Batch class.

center(inplace=False)¶

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

Parameters:

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

Returns:

surfacesurfalize.Surface: Surface object.

Note

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

crop(box, in_units=True, inplace=False)¶

Crop the surface to the area specified by the box parameter.

Parameters:

boxtuple[float, float, float, float]: The crop rectangle, as a (x0, x1, y0, y1) tuple.
in_unitsbool, default True: If true, the box is interpreted as physical units (µm). If false, the box is interpreted in pixel values.

Returns:

surfacesurfalize.Surface: Surface object.

Note

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

depth(nprofiles: int = 30, sampling_width: float = 0.2, plot: int = None) → tuple[float, float]¶

Calculates the peak-to-valley depth of a periodically grooved surface texture. It samples a specified number of equally spaced apart profiles from the surface and fits them with a sinusoid. It then evaluates the actual profile data in a specified interval around the minima and maxima of the sinusoid and computes their median value to reduce the influence of outliers. It then computes the depth by taking the absoulte distance between two adjacent maxima and minima. The overall depth is then calculated as the mean of all peak-to-valley depths over all sampled profiles.

Parameters:

nprofilesint, default 30: Number of profiles to sample from the surface.
sampling_widthfloat, default 0.2: Sampling width around the extrema of the sinusoid as a fraction of the spatial period.
plotNone | list-like[int], default None: List of number of profiles to plot.

Returns:

Mean depth and standard deviationtuple[float, float].

Note

This method is available in the Batch class.

detrend_polynomial(degree=1, inplace=False, return_trend=False)¶

Detrend a 2d array of height data using a polynomial surface, handling NaN values

Parameters:

degreeint, default 1: Polynomial degree.
inplacebool, default False: If False, create and return new Surface object with processed data. If True, changes data inplace and return self.
return_trend: bool, default False: return the trend as a Surface object alongside the detrended surface if True.

Returns:

Surface or tuple of Surfaces

Note

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

fill_nonmeasured(method='nearest', inplace=False)¶

Fills the non-measured points by interpolation.

Parameters:

method{‘linear’, ‘nearest’, ‘cubic’}, default ‘nearest’: Method by which to perform the interpolation. See scipy.interpolate.griddata for details.
inplacebool, default False: If False, create and return new Surface object with processed data. If True, changes data inplace and return self.

Returns:

surfacesurfalize.Surface: Surface object.

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 surface 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 surfaces
‘bandpass’: computes frequencies below the specified cutoff value and above the value specified for cutoff2

The surface 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 Surface object with processed data. If True, changes data inplace and return self. Inplace operation is not compatible with mode=’both’ argument, since two surfalize.Surface 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:

surfacesurfalize.Surface: Surface object.

Note

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

classmethod from_raw_surface(raw_surface)¶

Classmethod that instantiates a Surface object from a RawSurface object returned by the file readers.

Parameters:

raw_surface: surfalize.file.common.RawSurface: Raw surface object.

Returns:

surfalize.Surface

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.

get_autocorrelation_function()¶

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

Returns:

AutocorrelationFunction

Note

This method is available in the Batch class.

get_horizontal_profile(y, average=1, average_step=None)¶

Extracts a horizontal profile from the surface with optional averaging over parallel profiles. Profiles on the edge might be averaged over fewer profiles.

Parameters:

yfloat: vertical (height) value in µm from where the profile is extracted. The value is rounded to the closest data point.
averageint: number of profiles over which to average. Defaults to 1. Profiles will be extracted above and below the position designated by y.
average_stepfloat, default None: distance in µm between parallel profiles used for averaging. The value is rounded to the closest integer multiple of the pixel resolution. If the value is None, a distance of 1 px will be assumed.

Returns:

profilesurfalize.Profile

get_image_layer_names()¶

Returns a list of the names of available image layers.

Returns:

List[str]

get_oblique_profile(x0, y0, x1, y1)¶

Extracts an oblique profile from the surface.

Parameters:

x0float: starting point of the profile in x.
y0float: starting point of the profile in y.
x1float: end point of the profile in x.
y1float: end point of the profile in y.

Returns:

profilesurfalize.Profile

Raises:

ValueError: If the points lie outside the definition area.

get_vertical_profile(x, average=1, average_step=None)¶

Extracts a vertical profile from the surface with optional averaging over parallel profiles. Profiles on the edge might be averaged over fewer profiles.

Parameters:

xfloat: laterial (width) value in µm from where the profile is extracted. The value is rounded to the closest data point.
averageint: number of profiles over which to average. Defaults to 1. Profiles will be extracted above and below the position designated by x.
average_stepfloat, default None: distance in µm between parallel profiles used for averaging. The value is rounded to the closest integer multiple of the pixel resolution. If the value is None, a distance of 1 px will be assumed.

Returns:

profilesurfalize.Profile

property has_missing_points¶

Returns true if surface contains non-measured points.

Returns:

bool

height_parameters()¶

Calculates the roughness parameters from the height parameter family. Returns a dictionary of the height parameters.

Returns:

dict[str: float]

homogeneity(parameters: tuple[str] = ('Sa', 'Sku', 'Sdr'), period: float = None) → float¶

Calculates the homogeneity of a periodic surface through Gini coefficient analysis. It returns 1 - Gini, which is distributed on in the range between 0 and 1, where 0 represents minimum and 1 represents maximum homogeneity. The homogeneity factor is calculated for each roughness parameter specified in ‘parameters’ and the mean value is returned. The surface is divided into square unit cells with a side length equivalent to the period, for which each parameter is evaluated.

Parameters:

parameterstuple[str], optional: Roughness parameters that are evaluated for their homogeneity distribution. Defaults to [‘Sa’, ‘Sku’, Sdr’].
periodNone | float, optional: The period which is used to devide the surface into unit cells. If None, the period is automatically computed from the fourier transform.

Returns:

Homogeneityfloat: Value between 0 and 1.

Notes

The algoritm used by this function was proposed by Lechthaler et al. [1] and parctically applied by Soldera et al. [2]. Note that only surface rougness parameters which do not yield negative number qualify for the Gini analysis (e.g. the skewness ‘Ssk’ is not a valid input).

References

[1]

Lechthaler, B., Pauly, C. & Mücklich, F. Objective homogeneity quantification of a periodic surface using the Gini coefficient. Sci Rep 10, 14516 (2020). https://doi.org/10.1038/s41598-020-70758-9

[2]

Soldera, S., Reichel, C., Kuisat, F., Lasagni, A. F. Topography Analysis and Homogeneity Quantification of Laser-Patterned Periodic Surface Structures. JLMN 17, 81 (2022). https://doi.org/0.2961/jlmn.2022.02.2002

Note

This method is available in the Batch class.

invert(inplace=False)¶

Inverts the surface topography, creating a negative.

Parameters:

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

Returns:

surfacesurfalize.Surface: Surface object.

Note

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

level(return_trend=False, inplace=False)¶

Levels the surface by subtraction of a least squares fit plane.

Parameters:

return_trend: bool, default False: return the trend as a Surface object alongside the detrended surface if True.
inplacebool, default False: If False, create and return new Surface object with processed data. If True, changes data inplace and return self.

Returns:

Surface

Note

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

classmethod load(path_or_buffer, format=None, encoding='auto', read_image_layers=False)¶

Classmethod to load a topography from a file.

Parameters:

path_or_bufferstr | pathlib.Path | buffer: Filepath pointing to the topography file or buffer.
formatstr | None: File format in which file should be read. If the file is provided as a path and does not contain a suffix, the format must be specified here. If both a suffix and format are given, the format overrides the suffix. If the surface is read from a buffer, the format value must be specified.
encodingstr, Default auto: Encoding of characters in the file. If set to ‘auto’, the encoding is inferred automatically. For file formats with fixed encoding (such as ASCII formats), this parameter has no effect. The default value is ‘auto’.
read_image_layersbool, Default False: If true, reads all available image layers in the file and saves them in Surface.image_layers dict

Returns:

surfacesurfalize.Surface

max()¶

Computes the maximum value of the surface, ignoring invalid points.

Returns:

float

mean()¶

Computes the mean value of the surface, ignoring invalid points.

Returns:

float

median()¶

Computes the median value of the surface, ignoring invalid points.

Returns:

float

min()¶

Computes the minimum value of the surface, ignoring invalid points.

Returns:

float

orientation(method: str = 'fft_refined') → float¶

Computes the orientation angle of the dominant texture to the vertical axis in degree. The fft method estimates the angle from the peak positions in the 2d Fourier transform. However, the angular resolution for low frequencies is quite poor and therefore deviations of up to multiple degree should be expected depending on the angle. The fft_refined method refines the estimate from the Fourier transform by sampling profiles along the texture, fitting the profiles with a sinusoid and computing the drift of the position of the first peak. From this drift, the angle can be obtained with much better precision. The tradeoff is longer computing time.

Parameters:

method{‘fft_refined’, ‘fft’}: Method by which to calculate the orientation. Default is ‘fft_refined’.

Returns:

orientationfloat: Angle of dominant texture to vertical axis in degree.

Note

This method is available in the Batch class.

period() → float¶

Calculates the 1d spatial period based on the Fourier transform. This can yield unexcepted results if the surface contains peaks at lower spatial frequencies than the frequency of the periodic structure to be evaluated. It is advised to perform appropriate filtering and leveling to remove waviness before invoking this method.

Returns:

periodfloat

Note

This method is available in the Batch class.

period_x_y() → tuple[float, float]¶

Calculates the spatial period along the x and y axes based on the Fourier transform.

Returns:

(periodx, periody)tuple[float, float]

plot_2d(cmap='jet', maskcolor='black', layer='Topography', ax=None, vmin=None, vmax=None, show_cbar=None, save_to=None)¶

Creates a 2D-plot of the surface using matplotlib.

Parameters:

cmapstr | mpl.cmap, default ‘jet’: Colormap to apply on the topography layer. Argument has no effect if an image layer is selected.
maskcolorstr, default ‘Black’: Color for masked values.
layerstr, default Topography: Indicate the layer to plot, by default the topography layer is shown. Alternatively, the label of an image layer can be indicated.
axmatplotlib axis, default None: If specified, the plot will be drawn the specified axis.
vminfloat, default None: Minimum value of the colormap, passed to imshow.
vmaxfloat, default None: Maximum value of the colormap, passed to imshow.
show_cbarbool | None, default None: Determines whether to show a colorbar. If the value is None, the colorbar is shown only for topographies and omitted for image data.
save_tostr | pathlib.Path | None: Path to where the plot should be saved.

Returns:

plt.Figure, plt.Axes

plot_3d(vertical_angle=50, horizontal_angle=0, zoom=1, cmap='jet', colorbar=True, show_grid=True, light=0.3, light_position=None, crop_white=True, cbar_pad=50, cbar_height=0.5, scale=1, level_of_detail=100, save_to=None, interactive=False, window_title='surfalize', perspective_projection=True)¶

Renders a surface object in 3d using pyvista.

Parameters:

vertical_anglefloat: Angle of the camera in the vertical plane in degree. Defaults to 50.
horizontal_anglefloat: Angle of the camera in the horizontal plane in degree. Defaults to 0.
zoomfloat: Zoom factor of the surface render. Defaults to 1. Decreasing the value will zoom out the render.
cmapstr: Matplotlib colormap name. Defaults to jet.
colorbarbool: Whether to show a colorbar. Defaults to True.
show_gridbool: Whether to show a grid. Defaults to True.
lightfloat: Intensity of the light from 0 to 1. Defaults to 1.
light_positiontuple[float, float, float]: Position of the light source. Defaults to the position of the camera.
crop_whitebool: Whether to crop out white image borders in the horizontal axis. Defaults to True.
cbar_padint: Additional padding of the colorbar from the 3d render in pixels. Defaults to 50.
cbar_heightfloat: Height of the colorbar as a fraction of the image height.
scalefloat: Vertical scaling factor of the topography. Defaults to 1. Currently, there are issues with the grid rendering for scale values other than 1 due to the current pyvista implementation.
level_of_detailfloat: Level of detail in % by which the topography is downsampled for the 3d plot. A value of 50 will downsample the number of points in each axis by a factor of 2. Defaults to 100.
save_tostr | pathlib.Path | None: Path to where the plot should be saved.
interactivebool: Specifies whether the plot should be shown in an interactive window. Does not currently work for jupyter. Defaults to False.
window_titlestr: The window title to show in interactive mode. Defaults to ‘surfalize’.
perspective_projectionbool: Whether to use perspective or parallel projection. Default is True.

Returns:

PIL.Image

plot_abbott_curve(nbars: int = 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_angular_power_spectrum(ax=None, angle_step=1)¶

plot_autocorrelation(ax=None, cmap='jet', show_cbar=True, save_to=None)¶

Plots the Autocorrelation function.

Parameters:

axmatplotlib axis, default None: If specified, the plot will be drawn the specified axis.
cmapstr | mpl.cmap, default ‘jet’: Colormap to apply on the topography layer. Argument has no effect if an image layer is selected.
show_cbarbool | None, default None: Determines whether to show a colorbar. If the value is None, the colorbar is shown only for topographies and omitted for image data.
save_tostr | pathlib.Path | None: Path to where the plot should be saved.

Returns:

plt.Figure, plt.Axes

plot_fourier_transform(ax=None, log=True, hanning=False, subtract_mean=True, fxmax=None, fymax=None, cmap='inferno', adjust_colormap=True, save_to=None)¶

Plots the 2d Fourier transform of the surface. Optionally, a Hanning window can be applied to reduce to spectral leakage effects that occur when analyzing a signal of finite sample length.

Parameters:

axmatplotlib axis, default None: If specified, the plot will be drawn the specified axis.
logbool, Default True: Shows the logarithm of the Fourier Transform to increase peak visibility.
hanningbool, Default False: Applys a Hanning window to the data before the transform.
subtract_meanbool, Default False: Subtracts the mean of the data before the transform to avoid the zero peak.
fxmaxfloat, Default None: Maximum frequency displayed in x. The plot will be cropped to -fxmax : fxmax.
fymaxfloat, Default None: Maximum frequency displayed in y. The plot will be cropped to -fymax : fymax.
cmapstr, Default ‘inferno’: Matplotlib colormap with which to map the data.
adjust_colormapbool, Default True: If True, the colormap starts at the mean and ends at 0.7 time the maximum of the data to increase peak visibility.
save_tostr | pathlib.Path | None: Path to where the plot should be saved.

Returns:

plt.Figure, plt.Axes

plot_functional_parameter_study(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, plt.Axes

projected_area()¶

Calculates the projected surface area.

Returns:

projected areafloat

Note

This method is available in the Batch class.

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 Surface object with processed data. If True, changes data inplace and return self.

Returns:

surfacesurfalize.Surface: Surface object.

Note

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

rotate(angle, inplace=False)¶

Rotates the surface counterclockwise by the specified angle and crops it to largest possible rectangle with the same aspect ratio as the original surface that does not contain any invalid points.

Parameters:

anglefloat: Angle in degrees.
inplacebool, default False: If False, create and return new Surface object with processed data. If True, changes data inplace and return self.

Returns:

surfacesurfalize.Surface: Surface object.

Note

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

roughness_parameters(parameters: list[str] = None) → dict[slice(<class 'str'>, <class 'float'>, 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}

save(path_or_buffer, format=None, encoding='utf-8', **kwargs)¶

Saves the surface to a supported file format. The kwargs are specific to individual file formats.

Parameters:

path_or_bufferstr | pathlib.Path | buffer: Filepath pointing to the topography file or buffer.
formatstr | None: File format in which file should be saved. If the file is provided as a path and does not contain a suffix, the format must be specified here. If both a suffix and format are given, the format overrides the suffix. If the surface is saved to a buffer, the format value must be specified.
encodingstr, Default utf-8: Encoding of characters in the file. Defaults to utf-8.

Returns:

None

show(cmap='jet', maskcolor='black', layer='Topography', ax=None)¶

Shows a 2D-plot of the surface using matplotlib.

Parameters:

cmapstr | mpl.cmap, default ‘jet’: Colormap to apply on the topography layer. Argument has no effect if an image layer is selected.
maskcolorstr, default ‘Black’: Color for masked values.
layerstr, default Topography: Indicate the layer to plot, by default the topography layer is shown. Alternatively, the label of an image layer can be indicated.
axmatplotlib axis, default None: If specified, the plot will be drawn the specified axis.

Returns:

None.

property size¶

Returns the size of the height data array in pixels as a namedtuple of the form (y, x). The elements can be accessed either through indexing or dot notation.

Returns:

sizenamedtuple(y, x)

Examples

>>> surface.size
(y=768, x=1024)

>>> surface.size[0]
768

>>> surface.size.y
768

std()¶

Computes the standard deviation the surface, ignoring invalid points.

Returns:

float

stepheight()¶

Calculates the stepheight of two-level ablation experiment.

Returns:

stepheightfloat

Note

This method is available in the Batch class.

stepheight_level(inplace=False)¶

Levels the surface only based on the datapoints from the upper level surface in a rectangular ablation cavity. This function is intended to be used when the measurement contains two approximately flat surfaces on two different levels.

Parameters:

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

Returns:

surfacesurfalize.Surface: Surface object.

Note

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

surface_area()¶

Calculates the surface area of the surface according to the method proposed by ISO 25178 and used by MountainsMap, whereby two triangles are spanned between four corner points.

Returns:

areafloat

Note

This method is available in the Batch class.

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 areal 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 Surface object with processed data. If True, changes data inplace and return self.

Returns:

surfacesurfalize.Surface: Surface object.

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 of the surface to zero.

Parameters:

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

Returns:

surfacesurfalize.Surface: Surface object.

Note

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

zoom(factor, inplace=False)¶

Magnifies the surface by the specified factor.

Parameters:

factorfloat: Factor by which the surface is magnified
inplacebool, default False: If False, create and return new Surface object with processed data. If True, changes data inplace and return self

Returns:

surfacesurfalize.Surface: Surface object.

Note

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

surfalize.surface.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.surface.no_nonmeasured_points(function)¶

Decorator that raises an Exception if the method is called on a surface 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

surfalize.surface.size¶: alias of Size