5.11. Roughness
Summary: |
Algorithms for roughness evaluation |
Type: |
Algorithm |
License: |
LPGL licensed |
Platforms: |
Windows, Linux |
Author: |
M. Gronle, ITO, University Stuttgart |
5.11.1. Overview
This plugin contains algorithms for the 1D roughness evaluation.
The contained algorithms are:
calcRoughnessProfile: divide the given profile row-by-row into roughness and waviness
evalRoughnessProfile: evaluate either the roughness or waviness based on various 1D roughness parameters (e.g. Rz, Ra…)
roughnessProfile: combination of the two algorithms above as well as a possible initial subtraction of a regression line
calcAbbottCurve: determination of the abbott curve based on the roughness or waviness
Some algorithms the plugin ‘fittingFilters’ for a valid execution.
These filters are defined in the plugin:
5.11.2. Filters
Detailed overview about all defined filters:
- itom.algorithms.calcAbbottCurve(roughness, abbott[, nr_of_endeffect_pixels, histogram])
This filter calculates the Abbott firestone curve (as well as an optional histogram) of a roughness or waviness profile, e.g. obtained from the filter ‘calcRoughnessProfile’.
The evaluation is done based on DIN EN ISO 4287:2010.
- Parameters
roughness (itom.dataObject) – real input object (1D or 2D, no unsigned data types) - must be either the output argument ‘roughness’ or ‘waviness’ from filter ‘calcRoughnessProfile’. The roughness is determined row-by-row. The axis units must be set to ‘mm’, ‘µm’ or ‘nm’.
abbott (itom.dataObject) – abbott firestone curve with a horizontal step width of 1% (float64, size: Mx100 for M rows in the input object.
nr_of_endeffect_pixels (int, optional) –
nr of pixels at both sides of the profile that contain wrong values to the final length of the convolution filter kernel. Skip these pixels in any evaluation (see DIN EN ISO 16610-21, 4.3; DIN EN ISO 16610-28 will show more information when it is released in a final version)
Value range: [0, inf], Default: 0histogram (itom.dataObject, optional) – optional histogram with 100 buckets (int32, 1x100). Only the first line is evaluated.
- itom.algorithms.calcRoughnessProfile(input, roughness, waviness, Lc, Ls[, mode, periodicity, cutoff_factor])
calculate the roughness and waviness profile based in a given real input data object.
The roughness and waviness profile is determined row-by-row from the given input object that is filtered using one or two gaussian convolution operations. The gaussian filters are choosen such that a transmission of 50% is obtained at the given cut-off wavelength levels.
The waviness is a lowpass of the input data cut at the cut-off wavelength Lc. The roughness is the obtained by the difference between input and waviness. Additionally a lowpass is applied at the cut-off wavelength Ls (if Ls > 0.0).
You need to define if your profile is an open, non-periodic profiel or a closed, periodic profile. In the latter case the evaluation is only implemented by a convolution based algorithm, in the first case one can choose between the fast dft-implementation or the convolution-based implementation. If ‘mode’ is set to ‘auto’, lowpass filter operations with big wavelengths are evaluated using the dft-approach (Lc) while the high-frequency cut-off Ls is done using the convolution operation.
In order to guarantee an efficient algorithm, the gaussian filter kernel will be cut after a certain length. This length can be controlled using the parameter ‘cutoff_factor’.
This filter is implemented based on DIN EN ISO 16610-21:2013.
- Parameters
input (itom.dataObject) – real input object (1D or 2D). The roughness is determined row-by-row. The axis units must be set to ‘mm’, ‘µm’ or ‘nm’.
roughness (itom.dataObject) – roughness output object of the same size than the input object. Type is float64.
waviness (itom.dataObject) – waviness output object of the same size than the input object. Type is float64.
Lc (float) –
cut-off wavelength in µm for the separation between the waviness and roughness
Value range: [10, 100000], Default: 80Ls (float) –
short cut-off wavelength in µm for the separation between roughness and further high-frequency components (set 0.0 to omit this filtering)
Value range: [0, 25], Default: 2.5mode (str, optional) –
mode of determination: convolution, dft or auto (auto-selection of both methods)
Match: [“auto”, “dft”, “convolution”], Default: “auto”periodicity (int, optional) –
0: non periodic profile (default), 1: periodic profile (not implemented yet)
Value range: [0, 1], Default: 0cutoff_factor (float, optional) –
quality factor for the convolution based calculation. The convolution kernel is set to zero for indices > cutoff-wavelength * cutoff_factor. See ISO 16610-21:2013 A.5: 0.5 for general purpose, high precision: 0.6, reference software: 1.0
Value range: [0.5, 1], Default: 0.6
- Returns
nr_of_endeffect_pixels - nr of pixels at both sides of the profile that contain wrong values to the final length of the convolution filter kernel. Skip these pixels in any evaluation (see DIN EN ISO 16610-21, 4.3; DIN EN ISO 16610-28 will show more information when it is released in a final version)
- Return type
- itom.algorithms.evalRoughnessProfile(roughness, param, Lc[, nr_of_endeffect_pixels, sampling_length_mode, result_detailed, mr_range])
Evaluates given roughness or waviness profiles for a specific roughness profile parameter.
The given roughness data is evaluated line by line. If only one line is evaluated, ‘result’ contains:
(mean-value-over-all-samples, min-value-over-all-samples, max-value-over-all-samples)
The result values are always in µm. In case of Rt (or Wt), the evaluation is not separated to various samples, therefore mean, min and max contain the same values.
If multiple lines are evaluated, the result contains the
(mean-value-over-all-lines, min-value, max-value, std-dev), where min-value, max-value and std-dev are calculated over the mean-values of all lines.
The evaluation is done based on DIN EN ISO 4287:2010, the separation of different sample lengths is based on DIN EN ISO 4288:1997.
Possible roughness parameters are Rp, Rv, Rz, Rt, Ra, Rq, Rsk, Rku, Rdq, Rda, Rdc. If you pass the waviness profile instead of the roughness profile the parameters are then Wp, Wv, Wz, Wt, Wa, Wq, Wsk, Wku, Wdq, Wda, Wdc.
- Parameters
roughness (itom.dataObject) – real input object (1D or 2D, no unsigned data types) - must be either the output argument ‘roughness’ or ‘waviness’ from filter ‘calcRoughnessProfile’. The roughness is determined row-by-row. The axis units must be set to ‘mm’, ‘µm’ or ‘nm’.
param (str) –
roughness or waviness parameter to determine
Match: [“Rp”, “Rv”, “Rz”, “Rt”, “Ra”, “Rq”, “Rsk”, “Rku”, “Rdq”, “Rda”, “Rdc”, “Wp”, “Wv”, “Wz”, “Wt”, “Wa”, “Wq”, “Wsk”, “Wku”, “Wdq”, “Wda”, “Wdc”, “Pp”, “Pv”, “Pz”, “Pt”, “Pa”, “Pq”, “Psk”, “Pku”, “Pdq”, “Pda”, “Pdc”], Default: “Ra”Lc (float) –
cut-off wavelength in µm used for the separation between the waviness and roughness
Value range: [10, 100000], Default: 80nr_of_endeffect_pixels (int, optional) –
nr of pixels at both sides of the profile that contain wrong values to the final length of the convolution filter kernel. Skip these pixels in any evaluation (see DIN EN ISO 16610-21, 4.3; DIN EN ISO 16610-28 will show more information when it is released in a final version)
Value range: [0, inf], Default: 0sampling_length_mode (int, optional) –
mode how to split the measurement length (ml) into different sampling lengths (sl): 0: split ml into five samples (warn if the sl does not correspond to Lc), 1: split ml into n samples whose length is Lc, 2: same as 1 but only use the first 5 sampling lengths.
Value range: [0, 2], Default: 0result_detailed (itom.dataObject, optional) – returns a Nx3 float64 data object will the mean,min and max roughness value for each evaluated line (only interesting if input contains more than one line)
mr_range (Tuple[int,int] (range [v1,v2)), optional) –
[min,max] range in percent for the parameter Rdc or Wdc (height difference between two levels of the Abbott-Firstone-Curve
, Value range: [0, 100], Default: [20, 80]
- Returns
result - resulting values. See docstring of filter.
- Return type
Sequence[float]
- Returns
nr_of_samples - Number of evaluated samples per line (5 is the desired value with respect to DIN EN ISO 4288), Rt is evaluated over the whole measurement range, therefore nr_of_samples is 1.
- Return type
- itom.algorithms.getGaussianFilterKernel(kernel, cutoff_wavelength, spacing[, cutoff_factor])
returns the gaussian filter kernel as used by calcRoughnessProfile, based on EN ISO 11562
- Parameters
kernel (itom.dataObject) – kernel data object that contains the kernel after the call.
cutoff_wavelength (float) –
cut-off wavelength in µm
Value range: [0.0001, 100000], Default: 80spacing (float) –
spacing in µm between two adjacent pixels
Value range: [0, inf], Default: 1cutoff_factor (float, optional) –
quality factor for the length of the filter kernel. The kernel is set to zero for indices > cutoff-wavelength * cutoff_factor. See ISO 16610-21:2013 A.5: 0.5 for general purpose, high precision: 0.6, reference software: 1.0
Value range: [0.5, 1], Default: 0.6
- itom.algorithms.roughnessProfile(input, param, Lc, Ls[, remove_form, periodicity, cutoff_factor, sampling_length_mode, mr_range])
Calculate a profile roughness parameter for each line in the given input object.
The evaluation is done based on DIN EN ISO 4287:2010, the separation of different sample lengths is based on DIN EN ISO 4288:1997.
This filter is a thre-step filter, based on the single filters ‘subtract1DRegression’ from the plugin ‘FittingFilters’ and ‘calcRoughnessProfile’ as well as ‘evalRoughnessProfile’. The first is an optional filter to remove the form of the raw signal. The second filter splits the raw signal into the waviness and roughness signal (given by the cut-off wavelengths Lc and Ls). The last filter evaluates the given roughness parameter and returns the result. For more information see the description of the single filters.
- Parameters
input (itom.dataObject) – real input object (1D or 2D). The roughness is determined row-by-row. The axis units must be set to ‘mm’, ‘µm’ or ‘nm’.
param (str) –
roughness parameter to determine
Match: [“Rp”, “Rv”, “Rz”, “Rt”, “Ra”, “Rq”, “Rsk”, “Rku”, “Rdq”, “Rda”, “Rdc”, “Wv”, “Wz”, “Wt”, “Wa”, “Wq”, “Wsk”, “Wku”, “Wdq”, “Wda”, “Wdc”], Default: “Ra”Lc (float) –
cut-off wavelength in µm for the separation between the waviness and roughness
Value range: [10, 100000], Default: 80Ls (float) –
short cut-off wavelength in µm for the separation between roughness and further high-frequency components (set 0.0 to omit this filtering)
Value range: [0, 25], Default: 2.5remove_form (int, optional) –
0: no form is subtracted from input as first step, else: a polynomial form of given order (1: line) is fitted and removed as first step (requires filter plugin ‘FittingFilters’)
Value range: [0, 5], Default: 1periodicity (int, optional) –
0: non periodic profile (default), 1: periodic profile (not implemented yet)
Value range: [0, 1], Default: 0cutoff_factor (float, optional) –
quality factor for the convolution based calculation. The convolution kernel is set to zero for indices > cutoff-wavelength * cutoff_factor. See ISO 16610-21:2013 A.5: 0.5 for general purpose, high precision: 0.6, reference software: 1.0
Value range: [0.5, 1], Default: 0.6sampling_length_mode (int, optional) –
mode how to split the measurement length (ml) into different sampling lengths (sl): 0: split ml into five samples (warn if the sl does not correspond to Lc), 1: split ml into n samples whose length is Lc, 2: same as 1 but only use the first 5 sampling lengths.
Value range: [0, 1], Default: 0mr_range (Tuple[int,int] (range [v1,v2)), optional) –
[min,max] range in percent for the parameter Rdc or Wdc (height difference between two levels of the Abbott-Firstone-Curve
, Value range: [0, 100], Default: [20, 80]
- Returns
result - resulting values. See docstring of filter.
- Return type
Sequence[float]
- Returns
nr_of_samples - Number of evaluated samples per line (5 is the desired value with respect to DIN EN ISO 4288), Rt is evaluated over the whole measurement range, therefore nr_of_samples is 1.
- Return type