Class DataLine

Creates a new data line.

Parameters:

• 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.

Checks whether two data lines are compatible.

Parameters:

• data_line2 - Another data line. (DataLine)
• check - The compatibility tests to perform. (DataCompatibilityFlags)

Returns:

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

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.

Emits signal "data_changed" on a data line.

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.

Since: 2.1

Parameters:

• res - Desired resolution. (int)
• interpolation - Interpolation method to use. (InterpolationType)

Returns:

A newly created data line.

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. (InterpolationType)

Resizes (crops) a data line.

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

Parameters:

• _from - Where to start. (int)
• to - Where to finish + 1. (int)

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

Parameters:

• _from - Where to start. (int)
• len - Length of extracted segment. (int)

Returns:

The extracted area as a newly created data line.

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

<warning>Semantic of method differs from DataField.copy(), it copies only data. It will be probably changed.</warning>

Parameters:

• b - Destination data line. (DataLine)

Gets the raw data buffer of a data line.

The returned buffer is not guaranteed to be valid through whole data line life time. Some function may change it, most notably DataLine.resize() and DataLine.resample().

This function invalidates any cached information, use DataLine.get_data_const() if you are not going to change the data.

Returns:

The data as an array of doubles of length DataLine.get_res().

Gets the number of data points in a data line.

Returns:

Resolution (number of data points).

Gets the physical size of a data line.

Returns:

Real size of data line.

Sets the real data line size.

Parameters:

• real - value to be set (float)

Gets the offset of data line origin.

Returns:

Offset value.

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)

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.

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.

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" (Z) 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. (SIUnitFormatStyle)
• format - A SI value format to modify, or NULL to allocate a new one. (SIValueFormat*)

Returns:

The value format. If format is NULL, a newly allocated format is returned, otherwise (modified) format itself is returned.

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. (SIUnitFormatStyle)
• format - A SI value format to modify, or NULL to allocate a new one. (SIValueFormat*)

Returns:

The value format. If format is NULL, a newly allocated format is returned, otherwise (modified) format itself is returned.

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.

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.

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.

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.

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.

Reflects amd/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 zeroes.

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 - Index the line part starts at. (int)
• to - Index the line part ends at + 1. (int)

Fills specified part of data line with specified number

Parameters:

• _from - Index the line part starts at. (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 - Index the line part starts at. (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 - Index the line part starts at. (int)
• to - Index the line part ends at + 1. (int)
• value - Value to be added (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

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 - Index the line part starts at. (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

Finds line leveling coefficients.

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

Parameters:

• av - Height coefficient. (gdouble*)
• bv - Slope coeficient. (gdouble*)

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).

Since: 2.7

Parameters:

• angle - Angle of rotation (in radians), counterclockwise. (float)
• interpolation - Interpolation method to use (can be only of two-point type). (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.

Fits a polynomial through a part of a data line.

Please see DataLine.fit_polynom() for more details.

Parameters:

• n - Polynom degree. (int)
• coeffs - An array of size n+1 to store the coefficients to, or NULL (a fresh array is allocated then). (gdouble*)
• _from - Index the line part starts at. (int)
• to - Index the line part ends at + 1. (int)

Returns:

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

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.line_coeffs() because they are faster.

Parameters:

• n - Polynom degree. (int)
• coeffs - An array of size n+1 to store the coefficients to, or NULL (a fresh array is allocated then). (gdouble*)

Returns:

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

Subtracts a polynomial from a part of a data line.

Parameters:

• n - Polynom degree. (int)
• coeffs - An array of size n+1 with polynomial coefficients to. (const-gdouble*)
• _from - Index the line part starts at. (int)
• to - Index the line part ends at + 1. (int)

Subtracts a polynomial from a data line.

Parameters:

• n - Polynom degree. (int)
• coeffs - An array of size n+1 with polynomial coefficients to. (const-gdouble*)

Transforms a distribution in a data line to cummulative distribution.

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

Applies sqrt() to each element in a data line.

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. (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 mode. (WindowingType)
• direction - FFT direction. (TransformDirection)
• interpolation - Interpolation type. Ignored since 2.8 as no resampling is performed. (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 NULL 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 - The index in input lines to start from (inclusive). (int)
• len - Lenght of data line part, it must be at least 2. (int)
• windowing - Windowing mode. (WindowingType)
• direction - FFT direction. (TransformDirection)
• interpolation - Interpolation type. Ignored since 2.8 as no resampling is performed. (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.

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

Since: 2.1

Parameters:

• isrc - Imaginary input data line. Since 2.7 it can be NULL 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. (TransformDirection)

Finds the maximum value of a data line.

Returns:

The maximum value.

Finds the minimum value of a data line.

Returns:

The minimum value.

Computes average value of a data line.

Returns:

Average value

Computes root mean square value of a data line.

Returns:

Root mean square deviation of values.

Computes root mean square slope in a data line.

Since: 2.2

Returns:

Root mean square slope within a given interval.

Computes sum of all values in a data line.

Returns:

sum of all the values.

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

Parameters:

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

Returns:

Maximum within given interval.

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

Parameters:

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

Returns:

Minimum within given interval.

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

Parameters:

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

Returns:

Average value within given interval.

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

Parameters:

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

Returns:

Root mean square deviation of heights within a given interval

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.

Since: 2.2

Parameters:

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

Returns:

Root mean square slope within a given interval.

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

Parameters:

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

Returns:

Sum of all values within the interval.

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.

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 - The index in data_line to start from (inclusive). (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.

Finds median of a data line.

Since: 2.1

Returns:

The median.

Finds median of a data line part.

Since: 2.1

Parameters:

• _from - The index in data_line to start from (inclusive). (int)
• to - The index in data_line to stop (noninclusive). (int)

Returns:

The median.

Calculates physical length of a data line.

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

Returns:

The line length.

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.

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].

Since: 2.8

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

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.

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.7 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 reampling is performed. (int)