Surface¶

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

Bases: BaseTopography

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
Feature parameters: Spd, Svd, Spc, Svc, S5p, S5v, S10z

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:

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

Methods

`S10z`([pruning, exclude_edge])	Calculates the ten-point height S10z according to ISO 25178-2 (in µm), the sum of the five-point peak height S5p and the five-point pit depth S5v.
`S5p`([pruning, exclude_edge])	Calculates the five-point peak height S5p according to ISO 25178-2 (in µm), the mean of the heights of the five highest significant peaks referenced to the mean plane.
`S5v`([pruning, exclude_edge])	Calculates the five-point pit depth S5v according to ISO 25178-2 (in µm), the mean of the depths of the five deepest significant pits referenced to the mean plane.
`Sa`()	Calcualtes the arithmetic mean height Sa according to ISO 25178-2.
`Sak1`()	Calculates the area of the hills Sak1 in %·µm according to ISO 25178-2, the area of the triangle obtained during the reduction process of the protruding hills.
`Sak2`()	Calculates the area of the dales Sak2 in %·µm according to ISO 25178-2, the area of the triangle obtained during the reduction process of the protruding dales.
`Sal`([s])	Calculates the autocorrelation length Sal.
`Sdc`([p, q])	Calculates the material ratio height difference Sdc according to ISO 25178-2, the difference in height between the p and q material ratio with p < q.
`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 %.
`Smrk1`()	Calculates Smrk1 in %, the material ratio of the hills according to ISO 25178-2:2021.
`Smrk2`()	Calculates Smrk2 in %, the material ratio of the dales according to ISO 25178-2:2021.
`Sp`()	Calcualtes the maximum peak height Sp according to ISO 25178-2.
`Spc`([pruning, exclude_edge])	Calculates the arithmetic mean peak curvature Spc according to ISO 25178-2 (in 1/µm), the mean of the local mean curvature at the peaks of the significant hills.
`Spd`([pruning, exclude_edge])	Calculates the density of peaks Spd according to ISO 25178-2, the number of significant hills per unit area (in 1/µm²).
`Spk`()	Calculates Spk in µm.
`Spkx`()	Calculates the maximum peak height Spkx in µm according to ISO 25178-2, i.e. the height of the highest point above the core surface before the reduction process.
`Sq`()	Calcualtes the root mean square height Sq according to ISO 25178-2.
`Ssk`()	Calcualtes the skewness Ssk according to ISO 25178-2.
`Ssw`()	Calculates the dominant spatial wavelength Ssw according to ISO 25178-2, the wavelength which corresponds to the largest absolute value of the Fourier transform of the ordinate values.
`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.
`Svc`([pruning, exclude_edge])	Calculates the arithmetic mean pit curvature Svc according to ISO 25178-2 (in 1/µm), the mean of the local mean curvature at the pits of the significant dales.
`Svd`([pruning, exclude_edge])	Calculates the density of pits Svd according to ISO 25178-2, the number of significant dales per unit area (in 1/µm²).
`Svk`()	Calculates Svk in µm.
`Svkx`()	Calculates the maximum pit depth Svkx in µm according to ISO 25178-2, i.e. the depth of the deepest point below the core surface before the reduction process.
`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.
`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.
`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.
`copy`()	Returns a deep copy of the surface.
`create_cache_entry`(method, entry, args, kwargs)	Manually creates a cache entry for the specified method.
`crop`([box, border, in_units, inplace])	Crop the surface to the area specified by the box or border 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 topography 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_feature_parameters`()	Instantiates and returns a FeatureParameters object, which performs the watershed segmentation and Wolf pruning underlying the ISO 25178-2 feature parameters.
`get_fourier_transform`()	Instantiates and returns a FourierTransform 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, ...])	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 topography, creating a negative.
`level`([return_trend, inplace])	Levels the surface by subtraction of a least squares fit plane.
`level_points`(points, radius[, in_units, ...])	Levels the surface by subtracting a least squares plane fitted only to the areas around a set of user-specified points.
`load`(path_or_buffer[, format, encoding, ...])	Classmethod to load a topography from a file.
`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.
`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_feature_segmentation`([kind, pruning, ...])	Plots the watershed segmentation of the surface into significant motifs (hills or dales) used by the feature parameters, together with the motif boundaries (ridge/course lines) and critical points (pits/peaks).
`plot_fourier_transform`([ax, log, hanning, ...])	Plots the 2d Fourier transform of the surface.
`plot_functional_parameter_study`([save_to])	Plots a visual study of the functional parameters derived from the Abbott-Firestone curve.
`projected_area`()	Calculates the projected surface area.
`remove_cylinder`([radius, axis, inplace, ...])	Removes a cylindrical form from the surface.
`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 of the height values, 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 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', 'Ssw', 'Sk', 'Spk', 'Svk', 'Spkx', 'Svkx', 'Sak1', 'Sak2', 'Smr1', 'Smr2', 'Sxp', 'Sdc', 'Vmp', 'Vmc', 'Vvv', 'Vvc', 'Spd', 'Svd', 'Spc', 'Svc', 'S5p', 'S5v', 'S10z', 'period', 'depth', 'aspect_ratio', 'homogeneity', 'stepheight', 'cavity_volume')¶

ISO_PARAMETERS = ('Sa', 'Sq', 'Sp', 'Sv', 'Sz', 'Ssk', 'Sku', 'Sdr', 'Sdq', 'Sal', 'Str', 'Ssw', 'Sk', 'Spk', 'Svk', 'Spkx', 'Svkx', 'Sak1', 'Sak2', 'Smr1', 'Smr2', 'Sxp', 'Sdc', 'Vmp', 'Vmc', 'Vvv', 'Vvc', 'Spd', 'Svd', 'Spc', 'Svc', 'S5p', 'S5v', 'S10z')¶

NON_ISO_PARAMETERS = ('period', 'depth', 'aspect_ratio', 'homogeneity', 'stepheight', 'cavity_volume')¶

S10z(pruning=5, exclude_edge=True)¶

Calculates the ten-point height S10z according to ISO 25178-2 (in µm), the sum of the five-point peak height S5p and the five-point pit depth S5v.

Parameters:

pruningfloat, default 5: Wolf pruning threshold as a percentage of Sz. The default value of 5 % follows ISO 25178-3.
exclude_edgebool, default True: If True, features whose region touches the border of the evaluation area are excluded from the feature set.

Returns:

S10zfloat

Note

This method is available in the Batch class.

S5p(pruning=5, exclude_edge=True)¶

Calculates the five-point peak height S5p according to ISO 25178-2 (in µm), the mean of the heights of the five highest significant peaks referenced to the mean plane. If fewer than five significant peaks are found, the mean is taken over those available.

Parameters:

pruningfloat, default 5: Wolf pruning threshold as a percentage of Sz. The default value of 5 % follows ISO 25178-3.
exclude_edgebool, default True: If True, hills whose region touches the border of the evaluation area are excluded from the feature set.

Returns:

S5pfloat

Note

This method is available in the Batch class.

S5v(pruning=5, exclude_edge=True)¶

Calculates the five-point pit depth S5v according to ISO 25178-2 (in µm), the mean of the depths of the five deepest significant pits referenced to the mean plane. If fewer than five significant pits are found, the mean is taken over those available.

Parameters:

pruningfloat, default 5: Wolf pruning threshold as a percentage of Sz. The default value of 5 % follows ISO 25178-3.
exclude_edgebool, default True: If True, dales whose region touches the border of the evaluation area are excluded from the feature set.

Returns:

S5vfloat

Note

This method is available in the Batch class.

Sa()¶

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

Returns:

Safloat

Note

This method is available in the Batch class.

Sak1()¶

Calculates the area of the hills Sak1 in %·µm according to ISO 25178-2, the area of the triangle obtained during the reduction process of the protruding hills.

Returns:

Sak1float

Note

This method is available in the Batch class.

Sak2()¶

Calculates the area of the dales Sak2 in %·µm according to ISO 25178-2, the area of the triangle obtained during the reduction process of the protruding dales.

Returns:

Sak2float

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.

Sdc(p=2.5, q=50)¶

Calculates the material ratio height difference Sdc according to ISO 25178-2, the difference in height between the p and q material ratio with p < q. This generalizes Sxp; the default values of p and q match Sxp.

Parameters:

pfloat, default 2.5: material ratio p in %.
qfloat, default 50: material ratio q in %.

Returns:

Height differencefloat

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.

Smrk1()¶

Calculates Smrk1 in %, the material ratio of the hills according to ISO 25178-2:2021. This is the parameter formerly named Smr1.

Returns:

Smrk1float

Note

This method is available in the Batch class.

Smrk2()¶

Calculates Smrk2 in %, the material ratio of the dales according to ISO 25178-2:2021. This is the parameter formerly named Smr2.

Returns:

Smrk2float

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.

Spc(pruning=5, exclude_edge=True)¶

Calculates the arithmetic mean peak curvature Spc according to ISO 25178-2 (in 1/µm), the mean of the local mean curvature at the peaks of the significant hills.

Parameters:

pruningfloat, default 5: Wolf pruning threshold as a percentage of Sz. The default value of 5 % follows ISO 25178-3.
exclude_edgebool, default True: If True, hills whose region touches the border of the evaluation area are excluded from the feature set.

Returns:

Spcfloat

Note

This method is available in the Batch class.

Spd(pruning=5, exclude_edge=True)¶

Calculates the density of peaks Spd according to ISO 25178-2, the number of significant hills per unit area (in 1/µm²). Significant hills are obtained by watershed segmentation followed by Wolf pruning.

Parameters:

pruningfloat, default 5: Wolf pruning threshold as a percentage of Sz. The default value of 5 % follows ISO 25178-3.
exclude_edgebool, default True: If True, hills whose region touches the border of the evaluation area are excluded, since such features are incomplete. This matches the default behaviour of commercial software such as MountainsMap.

Returns:

Spdfloat

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.

Spkx()¶

Calculates the maximum peak height Spkx in µm according to ISO 25178-2, i.e. the height of the highest point above the core surface before the reduction process.

Returns:

Spkxfloat

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.

Ssw() → float¶

Calculates the dominant spatial wavelength Ssw according to ISO 25178-2, the wavelength which corresponds to the largest absolute value of the Fourier transform of the ordinate values.

Returns:

Sswfloat

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.

Svc(pruning=5, exclude_edge=True)¶

Calculates the arithmetic mean pit curvature Svc according to ISO 25178-2 (in 1/µm), the mean of the local mean curvature at the pits of the significant dales. Pits are concave, so Svc is negative.

Parameters:

pruningfloat, default 5: Wolf pruning threshold as a percentage of Sz. The default value of 5 % follows ISO 25178-3.
exclude_edgebool, default True: If True, dales whose region touches the border of the evaluation area are excluded from the feature set.

Returns:

Svcfloat

Note

This method is available in the Batch class.

Svd(pruning=5, exclude_edge=True)¶

Calculates the density of pits Svd according to ISO 25178-2, the number of significant dales per unit area (in 1/µm²). Significant dales are obtained by watershed segmentation followed by Wolf pruning.

Parameters:

pruningfloat, default 5: Wolf pruning threshold as a percentage of Sz. The default value of 5 % follows ISO 25178-3.
exclude_edgebool, default True: If True, dales whose region touches the border of the evaluation area are excluded, since such features are incomplete. This matches the default behaviour of commercial software such as MountainsMap.

Returns:

Svdfloat

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.

Svkx()¶

Calculates the maximum pit depth Svkx in µm according to ISO 25178-2, i.e. the depth of the deepest point below the core surface before the reduction process.

Returns:

Svkxfloat

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.

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.

copy()¶

Returns a deep copy of the surface. The height data and the mask are copied, while metadata and image layers are shallow-copied.

Returns:

surfacesurfalize.Surface

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

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

Exactly one of box or border must be given.

Parameters:

boxtuple[float, float, float, float], optional: The crop rectangle, as a (x0, x1, y0, y1) tuple.
borderfloat | tuple[float, float, float, float], optional: Alternative to box: the distance from each edge inwards to the crop rectangle, in the same units and axis order as box. A scalar keeps the same distance to all four edges, so surface.crop(border=100) is equivalent to surface.crop((100, surface.width_um - 100, 100, surface.height_um - 100)). A (x0, x1, y0, y1) tuple sets the distance to each edge individually.
in_unitsbool, default True: If true, box/border are interpreted as physical units (µm). If false, they are 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.

property data¶: The 2d height data array. The returned array is a read-only view: mutating it in place (e.g. surface.data[i, j] = x) is disallowed because it would not invalidate the cached roughness parameters. To edit values in place use surface[i, j] = x, which clears the cache. Assigning a new array (surface.data = new_array) recomputes width_um/height_um and clears the cache.

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.

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_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_feature_parameters()¶

Instantiates and returns a FeatureParameters object, which performs the watershed segmentation and Wolf pruning underlying the ISO 25178-2 feature parameters. The cache returns the same object on every call, so that the segmentation is shared between all feature parameters that use the same pruning value.

Returns:

FeatureParameters

Note

This method is available in the Batch class.

get_fourier_transform()¶

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

Returns:

FourierTransform

Note

This method is available in the Batch class.

get_horizontal_profile(y, average=1, average_step=None, start=None, end=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, measured from the bottom of the surface to match the convention of Surface.plot_2d and Surface.crop. The value is rounded to the closest data point.
startfloat, default None: lateral (width) value in µm at which the profile starts. Defaults to the left edge (0) if None.
endfloat, default None: lateral (width) value in µm at which the profile ends. Defaults to the right edge (width) if None.
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, start=None, end=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.
startfloat, default None: vertical (height) value in µm at which the profile starts. Defaults to the bottom edge (0) if None.
endfloat, default None: vertical (height) value in µm at which the profile ends. Defaults to the top edge (height) if None.
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_masked_points¶

Returns true if the surface contains masked points.

Returns:

bool

height_parameters()¶

Calculates the roughness parameters from the height parameter family. Returns a dictionary of the height parameters. Masked points are excluded from the calculation.

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.

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.

level_points(points, radius, in_units=True, inplace=False, return_trend=False)¶

Levels the surface by subtracting a least squares plane fitted only to the areas around a set of user-specified points.

A circular region of the given radius is placed around each point, and the leveling plane is fitted to the valid (measured, unmasked) data inside the union of these regions. This is useful when the reference (datum) areas are known but a global plane fit would be biased by features that should be ignored, e.g. laser-ablated cavities or other deep structures. Selecting a few points on the undisturbed reference surface avoids the extensive masking that would otherwise be required to exclude those features from the fit.

Parameters:

pointssequence of (x, y): At least three coordinate pairs marking the reference areas. If in_units is True, the coordinates are in µm with the y-axis measured from the bottom of the surface, matching the convention of Surface.crop and the mask region methods. Otherwise they are pixel indices (column, row) from the top-left. The points must not be collinear.
radiusfloat: Radius of the circular region around each point, in µm (in_units=True) or pixels (in_units=False).
in_unitsbool, default True: If True, interpret points and radius in physical units (µm). If False, in pixels.
inplacebool, default False: If False, create and return a new Surface object with processed data. If True, change data inplace and return self.
return_trendbool, default False: Return the fitted plane as a Surface object alongside the leveled 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.

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

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, masked_color='red', masked_alpha=0.5)¶

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 non-measured points.
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.
masked_colorstr, default ‘red’: Color of the translucent overlay drawn over masked points on the topography layer.
masked_alphafloat, default 0.5: Opacity of the masked-point overlay, between 0 (invisible) and 1 (opaque).

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_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_feature_segmentation(kind='dale', pruning=5, exclude_edge=True, ax=None, cmap='jet', save_to=None)¶

Plots the watershed segmentation of the surface into significant motifs (hills or dales) used by the feature parameters, together with the motif boundaries (ridge/course lines) and critical points (pits/peaks).

Parameters:

kind{‘dale’, ‘hill’}, default ‘dale’: Whether to plot the dale (pit) or hill (peak) segmentation.
pruningfloat, default 5: Wolf pruning threshold as a percentage of Sz.
exclude_edgebool, default True: If True, motifs touching the border of the evaluation area are not marked as significant features.
axmatplotlib axis, default None: If specified, the plot is drawn on the given axis.
cmapstr | mpl.cmap, default ‘jet’: Colormap applied to the height 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

projected_area()¶

Calculates the projected surface area.

Returns:

projected areafloat

Note

This method is available in the Batch class.

remove_cylinder(radius=None, axis='auto', inplace=False, return_trend=False)¶

Removes a cylindrical form from the surface. This is intended for surfaces measured on a cylindrical part, where the dominant form is the curvature of the cylinder. A cylinder is fitted to the height data in 3d space by treating the position and orientation of the rotation axis (and optionally the radius) as free parameters, and the cylinder form is subtracted from the height data.

The cylinder is fitted by minimizing the squared radial deviations of the measured points from the cylinder surface. The form is then removed by subtracting, at each lateral position, the z-height of the fitted cylinder directly below or above the measured point, so that the returned surface retains the original lateral grid and positive features remain positive.

If the radius of the cylinder is known (e.g. from the part diameter), it should be passed via the radius argument. In that case only the position and orientation of the axis are optimized, which is more robust. If no radius is provided, it is estimated from the data and optimized alongside the axis.

Parameters:

radiusfloat | None, default None: Known radius of the cylinder in the same lateral units as the surface (typically µm). If provided, the radius is held fixed during the fit. If None, the radius is estimated and optimized.
axis{‘auto’, ‘x’, ‘y’}, default ‘auto’: Approximate orientation of the cylinder’s rotation axis in the lateral plane, used as the starting point for the fit. With ‘auto’, the axis orientation is inferred from the direction of lowest curvature. The fit refines the orientation from this starting point, so small tilts of the axis relative to the chosen direction are accounted for.
inplacebool, default False: If False, create and return new Surface object with processed data. If True, changes data inplace and return self.
return_trendbool, default False: Return the trend (the fitted cylinder form) 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.

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.

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, masked_color='red', masked_alpha=0.5)¶

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 non-measured points.
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.
masked_colorstr, default ‘red’: Color of the translucent overlay drawn over masked points on the topography layer.
masked_alphafloat, default 0.5: Opacity of the masked-point overlay, between 0 (invisible) and 1 (opaque).

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

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.

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.size¶: alias of Size