Class DataLine

Creates a new data line.

Parameters:

• res - Resolution, i.e., the number of samples. (int)
• real - Real physical dimension. (float)
• nullme - Whether the data line should be initialized to zeroes. If False, the data will not be initialized. (bool)

Returns:

A newly created data line. (DataLine)

Checks whether two data lines are compatible.

Parameters:

• data_line2 - Another data line. (DataLine)
• check - The compatibility tests to perform. Expected values: DATA_COMPATIBILITY_RES, DATA_COMPATIBILITY_REAL, DATA_COMPATIBILITY_MEASURE, DATA_COMPATIBILITY_LATERAL, DATA_COMPATIBILITY_VALUE, DATA_COMPATIBILITY_AXISCAL, DATA_COMPATIBILITY_NCURVES, DATA_COMPATIBILITY_CURVELEN, DATA_COMPATIBILITY_ALL. (DataCompatibilityFlags)

Returns:

Zero if all tested properties are compatible. Flags corresponding to failed tests if data lines are not compatible. (DataCompatibilityFlags)

Checks whether a data line is compatible with brick Z-profiles.

If check includes DATA_COMPATIBILITY_REAL or DATA_COMPATIBILITY_LATERAL but not DATA_COMPATIBILITY_AXISCAL, data_line is simply compared to brick in the Z direction.

If you include DATA_COMPATIBILITY_AXISCAL and brick has a Z-calibration data line, then the value range and units of this data line are compared to data_line. This may not be very useful.

Parameters:

• brick - A three-dimensional data brick. (Brick)
• check - The compatibility tests to perform. Expected values: DATA_COMPATIBILITY_RES, DATA_COMPATIBILITY_REAL, DATA_COMPATIBILITY_MEASURE, DATA_COMPATIBILITY_LATERAL, DATA_COMPATIBILITY_VALUE, DATA_COMPATIBILITY_AXISCAL, DATA_COMPATIBILITY_NCURVES, DATA_COMPATIBILITY_CURVELEN, DATA_COMPATIBILITY_ALL. (DataCompatibilityFlags)

Returns:

Zero if all tested properties are compatible. Flags corresponding to failed tests if the data objects are not compatible. (DataCompatibilityFlags)

Fills missing values in a data line using Laplace data correction.

Both data lines must have the same number of values.

For one-dimensional data the missing data interpolation is explicit. Interior missing segments are filled with linear dependence between the edge points. Missing segments with one end open are filled with the edge value.

Parameters:

• mask_line - Mask of places to be corrected. (DataLine)

Returns:

True if the line contained any data at all. If there are no data the False is returned and data_line is filled with zeros. (bool)

Sets lateral and value units of a data field to match a data line.

Parameters:

• data_field - A data field to set units of. (DataField)

Creates a new data line similar to an existing one.

Use DataLine.duplicate() if you want to copy a data line including data.

Parameters:

• nullme - Whether the data line should be initialized to zeroes. If False, the data will not be initialized. (bool)

Returns:

A newly created data line. (DataLine)

Creates a new data line by resampling an existing one.

This method is equivalent to DataLine.duplicate() followed by DataLine.resample(), but it is more efficient.

Parameters:

• res - Desired resolution. (int)
• interpolation - Interpolation method to use. Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)

Returns:

A newly created data line. (DataLine)

Resamples a data line.

In other words changes the size of one dimensional field related with data line. The original values are used for resampling using a requested interpolation alorithm.

Parameters:

• res - Desired resolution. (int)
• interpolation - Interpolation method to use. Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)

Resizes (crops) a data line.

Extracts a part of data line in range from..(to-1), recomputing real sizes.

Parameters:

• from_ - (int)
• to - Where to finish + 1. (int)

Extracts a part of a data line to a new data line.

Parameters:

• from_ - (int)
• len - Length of extracted segment. (int)

Returns:

The extracted area as a newly created data line. (DataLine)

Copies the contents of a data line to another already allocated data line of the same size.

Parameters:

• target - Destination data line. (DataLine)

Gets the number of data points in a data line.

Returns:

Resolution (number of data points). (int)

Gets the physical size of a data line.

Returns:

Real size of data line. (float)

Sets the real data line size.

Parameters:

• real - value to be set (float)

Gets the offset of data line origin.

Returns:

Offset value. (float)

Sets the offset of a data line origin.

Note offsets don't affect any calculation, nor functions like DataLine.rtoi().

Parameters:

• offset - New offset value. (float)

Gets the sample distance (pixel size) of a data line in real units.

The result is the same as DataLine.get_real(data_line)/DataLine.get_res(data_line).

Returns:

Sampling step size. (float)

Returns lateral SI unit of a data line.

Returns:

SI unit corresponding to the lateral (X) dimension of the data line. Its reference count is not incremented. (SIUnit)

Returns value SI unit of a data line.

Returns:

SI unit corresponding to the "height" (Z) dimension of the data line. Its reference count is not incremented. (SIUnit)

Sets the SI unit corresponding to the lateral (X) dimension of a data line.

It does not assume a reference on si_unit, instead it adds its own reference.

Parameters:

• si_unit - SI unit to be set. (SIUnit)

Sets the SI unit corresponding to the "height" (Y) dimension of a data line.

It does not assume a reference on si_unit, instead it adds its own reference.

Parameters:

• si_unit - SI unit to be set. (SIUnit)

Finds value format good for displaying coordinates of a data line.

Parameters:

• style - Unit format style. Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX, SI_UNIT_FORMAT_VFTEX, SI_UNIT_FORMAT_UNICODE, SI_UNIT_FORMAT_VFUNICODE. (SIUnitFormatStyle)

Returns:

Tuple consisting of 2 values (value, format). ((SIValueFormat), (SkipArg))

Finds value format good for displaying values of a data line.

Note this functions searches for minimum and maximum value in data_line, therefore it's relatively slow.

Parameters:

• style - Unit format style. Expected values: SI_UNIT_FORMAT_NONE, SI_UNIT_FORMAT_PLAIN, SI_UNIT_FORMAT_MARKUP, SI_UNIT_FORMAT_VFMARKUP, SI_UNIT_FORMAT_TEX, SI_UNIT_FORMAT_VFTEX, SI_UNIT_FORMAT_UNICODE, SI_UNIT_FORMAT_VFUNICODE. (SIUnitFormatStyle)

Returns:

Tuple consisting of 2 values (value, format). ((SIValueFormat), (SkipArg))

Sets lateral and value units of a data line to match another data line.

Parameters:

• target - Destination data line. (DataLine)

Transforms pixel coordinate to real (physical) coordinate.

That is it maps range [0..resolution] to range [0..real-size]. It is not suitable for conversion of matrix indices to physical coordinates, you have to use DataLine.itor(data_line, pixpos + 0.5) for that.

Parameters:

• pixpos - Pixel coordinate. (float)

Returns:

pixpos in real coordinates. (float)

Transforms real (physical) coordinate to pixel coordinate.

That is it maps range [0..real-size] to range [0..resolution].

Parameters:

• realpos - Real coordinate. (float)

Returns:

realpos in pixel coordinates. (float)

Gets value at given position in a data line.

Do not access data with this function inside inner loops, it's slow. Get raw data buffer with DataLine.get_data_const() and access it directly instead.

Parameters:

• i - Position in the line (index). (int)

Returns:

Value at given index. (float)

Sets the value at given position in a data line.

Do not set data with this function inside inner loops, it's slow. Get raw data buffer with DataLine.get_data() and write to it directly instead.

Parameters:

• i - Position in the line (index). (int)
• value - Value to set. (float)

Gets interpolated value at arbitrary data line point indexed by pixel coordinates.

Note pixel values are centered in intervals [j, j+1], so to get the same value as DataLine.get_val(data_line, j) returns, it's necessary to add 0.5: DataLine.get_dval(data_line, j+0.5, interpolation).

See also DataLine.get_dval_real() that does the same, but takes real coordinates.

Parameters:

• x - Position in data line in range [0, resolution]. If the value is outside this range, the nearest border value is returned. (float)
• interpolation - Interpolation method to use. (int)

Returns:

Value interpolated in the data line. (float)

Gets interpolated value at arbitrary data line point indexed by real coordinates.

See also DataLine.get_dval() for interpolation explanation.

Parameters:

• x - real coordinates position (float)
• interpolation - interpolation method used (int)

Returns:

Value interpolated in the data line. (float)

Reflects and/or inverts a data line.

In the case of value reflection, it's inverted about mean value.

Parameters:

• x - Whether to invert data point order. (bool)
• z - Whether to invert in Z direction (i.e., invert values). (bool)

Fills a data line with specified value.

Parameters:

• value - Value to fill data line with. (float)

Multiplies all values in a data line with a specified value.

Parameters:

• value - Value to multiply data line with. (float)

Adds a specified value to all values in a data line.

Parameters:

• value - Value to be added. (float)

Fills a data line part with zeroes.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Fills specified part of data line with specified number

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)
• value - Value to fill data line part with. (float)

Multiplies all values in a part of data line by specified value.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)
• value - Value multiply data line part with. (float)

Adds specified value to all values in a part of a data line.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)
• value - Value to be added (float)

Sums two data lines.

Parameters:

• operand1 - First data line operand. (DataLine)
• operand2 - Second data line operand. (DataLine)

Subtracts two data lines.

Parameters:

• operand1 - First data line operand. (DataLine)
• operand2 - Second data line operand. (DataLine)

Multiplies two data lines.

Parameters:

• operand1 - First data line operand. (DataLine)
• operand2 - Second data line operand. (DataLine)

Computes point-wise general linear combination of two data lines.

Parameters:

• coeff1 - Factor to multiply the first operand with. (float)
• operand1 - First data line operand. (DataLine)
• coeff2 - Factor to multiply the second operand with. (float)
• operand2 - Second data line operand. (DataLine)
• constant - Constant term to add to the result. (float)

Sets all the values to bottom or top value depending on whether the original values are below or above threshold value

Parameters:

• threshval - Threshold value. (float)
• bottom - Lower replacement value. (float)
• top - Upper replacement value. (float)

Returns:

total number of values above threshold (int)

Sets all the values within interval to bottom or top value depending on whether the original values are below or above threshold value.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)
• threshval - Threshold value. (float)
• bottom - Lower replacement value. (float)
• top - Upper replacement value. (float)

Returns:

total number of values above threshold within interval (int)

Finds line leveling coefficients.

The coefficients can be used for line leveling using relation data[i] := data[i] - (av + bv*i);

Returns:

Tuple consisting of 2 values (av, bv). ((float), (float))

Performs line leveling.

See DataLine.get_line_coeffs() for deails.

Parameters:

• av - Height coefficient. (float)
• bv - Slope coefficient. (float)

Performs line rotation.

This is operation similar to leveling, but it does not change the angles between line segments (on the other hand it introduces other deformations due to discretization).

Parameters:

• angle - Angle of rotation (in radians), counterclockwise. (float)
• interpolation - Interpolation method to use (can be only of two-point type). Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)

Performs line rotation.

Use DataLine.rotate() instead.

Parameters:

• angle - Angle of rotation (in radians), counterclockwise. (float)
• interpolation - Interpolation method to use (can be only of two-point type). (int)

Computes central derivaltion at given index in a data line.

Parameters:

• i - Pixel coordinate. (int)

Returns:

Derivation at given position. (float)

Transforms a distribution in a data line to cummulative distribution.

Each element becomes sum of all previous elements in the line, including self.

Performs steps of the wavelet decomposition.

The smallest low pass coefficients block is equal to minsize. Run with minsize = dline->res/2 to perform one step of decomposition or minsize = 4 to perform full decomposition (or anything between).

Parameters:

• wt_coefs - Data line where the wavelet transform coefficients are stored. (DataLine)
• direction - Transform direction. Expected values: TRANSFORM_DIRECTION_BACKWARD, TRANSFORM_DIRECTION_FORWARD. (TransformDirection)
• minsize - size of minimal transform result block (int)

Calculates Fast Fourier Transform of a data line.

A windowing or data leveling can be applied if requested.

Parameters:

• isrc - Imaginary input data line. (DataLine)
• rdest - Real output data line. It will be resized to the size of the input data line. (DataLine)
• idest - Imaginary output data line. It will be resized to the size of the input data line. (DataLine)
• windowing - Windowing type to use. Expected values: WINDOWING_NONE, WINDOWING_HANN, WINDOWING_HAMMING, WINDOWING_BLACKMANN, WINDOWING_LANCZOS, WINDOWING_WELCH, WINDOWING_RECT, WINDOWING_NUTTALL, WINDOWING_FLAT_TOP, WINDOWING_KAISER25. (WindowingType)
• direction - FFT direction. Expected values: TRANSFORM_DIRECTION_BACKWARD, TRANSFORM_DIRECTION_FORWARD. (TransformDirection)
• interpolation - Interpolation type. Ignored since 2.8 as no resampling is performed. Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)
• preserverms - True to preserve RMS value while windowing. (bool)
• level - 0 to perform no leveling, 1 to subtract mean value, 2 to subtract line (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available). (int)

Calculates Fast Fourier Transform of a part of a data line.

A windowing or data leveling can be applied if requested.

Parameters:

• isrc - Imaginary input data line. Since 2.7 it can be None for real-to-complex transforms. (DataLine)
• rdest - Real output data line, it will be resized to len. (DataLine)
• idest - Imaginary output data line, it will be resized to len. (DataLine)
• from_ - (int)
• len - Lenght of data line part, it must be at least 2. (int)
• windowing - Windowing type to use. Expected values: WINDOWING_NONE, WINDOWING_HANN, WINDOWING_HAMMING, WINDOWING_BLACKMANN, WINDOWING_LANCZOS, WINDOWING_WELCH, WINDOWING_RECT, WINDOWING_NUTTALL, WINDOWING_FLAT_TOP, WINDOWING_KAISER25. (WindowingType)
• direction - FFT direction. Expected values: TRANSFORM_DIRECTION_BACKWARD, TRANSFORM_DIRECTION_FORWARD. (TransformDirection)
• interpolation - Interpolation type. Ignored since 2.8 as no resampling is performed. Expected values: INTERPOLATION_NONE, INTERPOLATION_ROUND, INTERPOLATION_LINEAR, INTERPOLATION_BILINEAR, INTERPOLATION_KEY, INTERPOLATION_BSPLINE, INTERPOLATION_OMOMS, INTERPOLATION_NNA, INTERPOLATION_SCHAUM. (InterpolationType)
• preserverms - True to preserve RMS value while windowing. (bool)
• level - 0 to perform no leveling, 1 to subtract mean value, 2 to subtract line (the number can be interpreted as the first polynomial degree to keep, but only the enumerated three values are available). (int)

Calculates Fast Fourier Transform of a data line.

No leveling, windowing nor scaling is performed.

The normalisation of FFT is symmetrical, so transformations in both directions are unitary.

Since 2.8 the dimensions need not to be from the set of sizes returned by gwy_fft_find_nice_size().

Parameters:

• isrc - Imaginary input data line. Since 2.7 it can be None for real-to-complex transform. (DataLine)
• rdest - Real output data line. It will be resized to the size of the input data line. (DataLine)
• idest - Imaginary output data line. It will be resized to the size of the input data line. (DataLine)
• direction - FFT direction. Expected values: TRANSFORM_DIRECTION_BACKWARD, TRANSFORM_DIRECTION_FORWARD. (TransformDirection)

Computes Zoom FFT of a data line.

The output is DFTs, but computed for an arbitrary linear sequence of frequencies. The frequencies do not have to be in any relation to the data sampling step.

The first item of output corresponds exactly to f0 and the last exactly to f1. So the frequency sampling step will be (f1 − f0)/(m − 1), instead of the more usual division by m. To follow the usual Gwyddion conventions, the output data line real size will be (f1 − f0)/(m − 1)*m. If it seems confusing, just take the output as indexed by integers and work with that.

Frequency step of one corresponds to the normal DFT frequency step. Therefore, passing f0=0, f1=n-1 (where rsrc has n points) and m=n reproduces the usual DFT, except more slowly. The result is normalised as raw FFT and the units of the output data lines are unchanged.

The transform direction is always forward. Windowing or other preprocessing need to be done separately beforehand. They would be usually once, but followed by any number of (Zoom) FFTs.

Parameters:

• isrc - Imaginary input data line. It can be None for real-to-complex transform. (DataLine)
• rdest - Real output data line. It will be resized to m samples. (DataLine)
• idest - Imaginary output data line. It will be resized to m samples. (DataLine)
• m - The number of frequencies to compute. It must be at least 2. (int)
• f0 - The first spatial frequency, measured in DFT frequency steps. (float)
• f1 - The last spatial frequency, measured in DFT frequency steps. (float)

Performs windowing of a data line in preparation for FFT.

Parameters:

• windowing - Windowing type to use. Expected values: WINDOWING_NONE, WINDOWING_HANN, WINDOWING_HAMMING, WINDOWING_BLACKMANN, WINDOWING_LANCZOS, WINDOWING_WELCH, WINDOWING_RECT, WINDOWING_NUTTALL, WINDOWING_FLAT_TOP, WINDOWING_KAISER25. (WindowingType)

Finds the maximum value of a data line.

Returns:

The maximum value. (float)

Finds the minimum value of a data line.

Returns:

The minimum value. (float)

Finds the minimum and maximum values of a data line.

Since 2.42

Returns:

Tuple consisting of 2 values (min, max). ((float), (float))

Finds the minimum pixel position of a data line.

For historical reasons the value is returned as double, but it is always an integer.

Returns:

The minimum pixel position.

Since 2.48 (float)

Finds the maximum pixel position of a data line.

For historical reasons the value is returned as double, but it is always an integer.

Returns:

The maximum pixel position.

Since 2.48 (float)

Finds the real minimum position in a data line.

Returns:

Real position for the minimum.

Since 2.48 (float)

Finds the real maximum position in a data line.

Returns:

Real position for the maximum.

Since 2.48 (float)

Computes average value of a data line.

Returns:

Average value (float)

Computes root mean square value of a data line.

Returns:

Root mean square deviation of values. (float)

Computes root mean square slope in a data line.

Returns:

Root mean square slope within a given interval. (float)

Computes the total variation of a data line.

See DataLine.part_get_variation() for definition and discussion.

Returns:

The total variation. (float)

Computes sum of all values in a data line.

Returns:

sum of all the values. (float)

Computes the mean absolute deviation of a data line.

Returns:

The mean absolute deviation of height values. (float)

Computes the skew of a data line.

Returns:

The skew of height values. (float)

Computes the kurtosis of a data line.

Returns:

The kurtosis of height values.

Note the kurtosis returned by this function returns is the excess kurtosis which is zero for the Gaussian distribution (not 3). (float)

Finds the maximum value of a part of a data line.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Maximum within given interval. (float)

Finds the minimum value of a part of a data line.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Minimum within given interval. (float)

Finds the minimum and maximum values of a part of a data line.

Since 2.42

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Tuple consisting of 2 values (min, max). ((float), (float))

Computes mean value of all values in a part of a data line.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Average value within given interval. (float)

Computes root mean square value of a part of a data line.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Root mean square deviation of heights within a given interval (float)

Computes root mean square slope in a part of a data line.

This is the root mean square of value derivatives, it is also proportional to the second derivative of both HHCF and ACF at zero.

This roughness quantity is also known as Dq.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Root mean square slope within a given interval. (float)

Computes the total variation of a part of a data line.

The total variation is estimated as the integral of the absolute value of local gradient. For one dimensional data, the variation reduces to the integral of absolute value of the derivative. Its units are thus the same as the value units of the line. See also DataField.area_get_variation() for some more discussion.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

The total variation within a given interval. (float)

Computes sum of all values in a part of a data line.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Sum of all values within the interval. (float)

Computes mean absolute deviation value of a part of a data line.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Mean absolute deviation of heights within a given interval. (float)

Computes skew value of a part of a data line.

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Skew of heights within a given interval. (float)

Computes kurtosis value of a part of a data line.

Note the kurtosis returned by this function returns is the excess kurtosis which is zero for the Gaussian distribution (not 3).

Parameters:

• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

Kurtosis of heights within a given interval. (float)

Finds approximate modus of a data line.

See DataLine.part_get_modus() for details and caveats.

Parameters:

• histogram_steps - Number of histogram steps used for modus searching, pass a nonpositive number to autosize. (int)

Returns:

The modus. (float)

Finds approximate modus of a data line part.

As each number in the data line is usually unique, this function does not return modus of the data itself, but modus of a histogram.

Parameters:

• from_ - (int)
• to - The index in data_line to stop (noninclusive). (int)
• histogram_steps - Number of histogram steps used for modus searching, pass a nonpositive number to autosize. (int)

Returns:

The modus. (float)

Finds median of a data line.

Returns:

The median. (float)

Finds median of a data line part.

Parameters:

• from_ - (int)
• to - The index in data_line to stop (noninclusive). (int)

Returns:

The median. (float)

Calculates physical length of a data line.

The length is calculated from approximation by straight segments between values.

Returns:

The line length. (float)

Calculates a peak roughness quantity for a data line.

Depending on m and k, the function can calculate Average Maximum Profile Peak Height Rpm or Maximum Profile Peak Height Rp, Pp, Wp.

Parameters:

• m - Number of sampling lengths. (int)
• k - Number of peaks to consider. (int)

Returns:

The peak roughness quantity defined by m and k. (float)

Calculates a valley roughness quantity for a data line.

Depending on m and k, the function can calculate Average Maximum Profile Valley Depth Rvm or Maximum Profile Peak Depth Rv, Pv, Wv.

Parameters:

• m - Number of sampling lengths. (int)
• k - Number of valleys to consider. (int)

Returns:

The valley roughness quantity defined by m and k. (float)

Calculates a total roughness quantity for a data line.

The total quantity is just the sum of the corresponding quantities obtained by DataLine.get_xpm() and DataLine.get_xvm().

Parameters:

• m - Number of sampling lengths. (int)
• k - Number of peaks and valleys to consider. (int)

Returns:

The total roughness quantity defined by m and k. (float)

Counts peaks or valleys defined by thresholds in a data line.

Peak is defined as a part of the profile that extends above the peak threshold and is separarted by valleys that extend below the valley threshold. For non-zero thresholds there may be parts between that are neither peaks not valleys because the local maxima in them are insignificant.

In either case, values of pthreshold and vthreshold must be non-negative. Usually one passes the same value for both.

Parameters:

• peaks - True for peaks, False for valleys. If you pass False, swap the meanings of peaks and valleys in the description. Valley depths are positive. (bool)
• pthreshold - Peak height threshold. Peaks must stick above this threshold. (float)
• vthreshold - Valley depth threshold. Valleys must fall below this threshold. (float)

Returns:

The number of peaks found. (int)

Calculates the distribution of data line values.

This function is quite similar to DataLine.dh(), the differences are: output normalization (chosen to make the integral unity), output units (again set to make the integral unity), automated binning.

Note the i-th bin is [i*dx+off,(i+1)*dx+off] so the central value you probably want to use for plotting is (i+0.5)*dx+off (where dx is the distribution data line pixel size, off is its offset).

If all values are equal and ymin, ymax are not explictly specified, the range is chosen as [v-|v|/2,v+|v/2] where v is the unique value, except when v=0, in which case the range is set to [-1,1].

Parameters:

• distribution - Data line to put the distribution of data_line values to. It will be resampled to nstats samples (or the automatically chosen number of bins). (DataLine)
• ymin - Start of value range, pass ymin = ymax = 0.0 for the full range. (float)
• ymax - End of value range. (float)
• normalize_to_unity - True to normalize the integral to unity (including setting y-units of output to the inverse of x-units), False to keep plain counts in the output (and set y-units to none). (bool)
• nstats - The requested number of histogram bins, pass a non-positive number to automatically choose a suitable number of bins. (int)

Computes distribution of heights in interval [ymin, ymax).

If the interval is (0, 0) it computes the distribution from real data minimum and maximum value.

Parameters:

• target_line - Data line to store height distribution function to. It will be resized to nsteps. (DataLine)
• ymin - Height distribution minimum value. (float)
• ymax - Height distribution maximum value. (float)
• nsteps - Number of histogram steps. (int)

Computes cumulative distribution of heighs in interval [ymin, ymax).

If the interval is (0, 0) it computes the distribution from real data minimum and maximum value.

Parameters:

• target_line - Data line to store height distribution function to. It will be resized to nsteps. (DataLine)
• ymin - Height distribution minimum value. (float)
• ymax - Height distribution maximum value. (float)
• nsteps - Number of histogram steps. (int)

Computes distribution of angles in interval [ymin, ymax).

If the interval is (0, 0) it computes the distribution from real data minimum and maximum angle value.

Parameters:

• target_line - Data line to store angle distribution function to. (DataLine)
• ymin - Angle distribution minimum value. (float)
• ymax - Angle distribution maximum value. (float)
• nsteps - Mumber of angular histogram steps. (int)

Computes cumulative distribution of angles in interval [ymin, ymax).

If the interval is (0, 0) it computes the distribution from real data minimum and maximum angle value.

Parameters:

• target_line - Data line to store angle distribution function to. It will be resized to nsteps. (DataLine)
• ymin - Angle distribution minimum value. (float)
• ymax - Angle distribution maximum value. (float)
• nsteps - Number of angular histogram steps. (int)

Coputes autocorrelation function and stores the values in target_line

Up to version 2.53 it did not set the output units properly.

Parameters:

• target_line - Data line to store autocorrelation function to. It will be resized to data_line size. (DataLine)

Computes height-height correlation function and stores results in target_line.

Up to version 2.53 it did not set the output units properly.

Parameters:

• target_line - Data line to store height-height function to. It will be resized to data_line size. (DataLine)

Calculates the power spectral density function of a data line.

Up to version 2.45 it destroyed the input data and did not set the output units properly.

Parameters:

• target_line - Data line to store power spectral density function to. It will be resized to data_line size. (DataLine)
• windowing - Windowing method to use. (int)
• interpolation - Interpolation type. Ignored since 2.8 as no resampling is performed. (int)

Extract the data of a data line.

The returned list contains a copy of the data. Changing its contents does not change the data line's data.

Returns:

List containing extracted data line data. (list)

Sets the entire contents of a data line.

The length of data must be equal to the number of elements of the data line.

Parameters:

• data - Sequence of floating point values. (list)

Fits a polynomial through a part of a data line.

Please see DataLine.fit_polynom() for more details.

Parameters:

• n - Polynom degree. (int)
• from_ - (int)
• to - Index the line part ends at + 1. (int)

Returns:

The coefficients of the polynomial (coeffs when it was not None, otherwise a newly allocated array). (list)

Fits a polynomial through a data line.

Note n is polynomial degree, so the size of coeffs is n+1. X-values are indices in the data line.

For polynomials of degree 0 and 1 it's better to use DataLine.get_avg() and DataLine.get_line_coeffs() because they are faster.

Parameters:

• n - Polynom degree. (int)

Returns:

The coefficients of the polynomial (coeffs when it was not None, otherwise a newly allocated array). (list)

Subtracts a polynomial from a part of a data line.

Parameters:

• coeffs - An array of size n+1 with polynomial coefficients to. (list)
• from_ - (int)
• to - Index the line part ends at + 1. (int)

Subtracts a polynomial from a data line.

Parameters:

• coeffs - An array of size n+1 with polynomial coefficients to. (list)

Calculate k-th largers peaks or valleys in a data line split into given number of sampling lengths.

This is a general function that can be used as the base for various standard roughness quantities such as Rp, Rpm, Rv, Rvm or R3z. It is assumed the line is already levelled, the form removed, etc.

See DataLine.count_peaks() for the description what is considered a peak.

For larger thresholds and/or short lines some sampling lengths may not contain the requested number of peaks. If there are any peaks at all, the smallest peak height (even though it is not rank-th) is used. If there are no peaks, a large negative value is stored in the corresponding peakvalues item.

Parameters:

• m - Number of sampling lengths the line is split into. (int)
• rank - Rank of the peak to find. One means the highest peak, three the third highers, etc. (int)
• peaks - True for peaks, False for valleys. If you pass False, swap the meanings of peaks and valleys in the description. Valley depths are positive. (bool)
• average - Calculate the average of the first rank peaks instead of the height of rank-th peak. (bool)
• pthreshold - Peak height threshold. Peaks must stick above this threshold. (float)
• vthreshold - Valley depth threshold. Valleys must fall below this threshold. The depth is a positive value. (float)

Returns:

List with m items containing the peak heights. (list)

Convenience macro doing gwy_serializable_duplicate() with all the necessary typecasting.

Returns:

(DataLine)

Gets pointer to data which the data line contains.

Returns:

integer pointing to the raw data of the data field (long)