GwyLine: Gwyddion Library Reference Manual

## GwyLine GwyLine — One-dimensional floating point data |

## Functions

GwyLine * | gwy_line_new ()
GwyLine * | gwy_line_new_alike ()
GwyLine * | gwy_line_copy ()
void | gwy_line_assign ()
void | gwy_line_data_changed ()
GwyLine * | gwy_line_new_resampled ()
void | gwy_line_resample ()
void | gwy_line_make_alike ()
void | gwy_line_resize ()
void | gwy_line_crop ()
GwyLine * | gwy_line_part_extract ()
void | gwy_line_copy_data ()
void | gwy_line_part_copy ()
gdouble * | gwy_line_get_data ()
const gdouble * | gwy_line_get_data_const ()
gdouble * | gwy_line_get_data_with_size ()
void | gwy_line_set_data_with_size ()
void | gwy_line_invalidate ()
gint | gwy_line_get_res ()
gdouble | gwy_line_get_real ()
void | gwy_line_set_real ()
gdouble | gwy_line_get_offset ()
void | gwy_line_set_offset ()
gdouble | gwy_line_get_dx ()
GwyUnit * | gwy_line_get_unit_x ()
GwyUnit * | gwy_line_get_unit_y ()
GwyValueFormat * | gwy_line_get_value_format_x ()
GwyValueFormat * | gwy_line_get_value_format_y ()
void | gwy_line_copy_units ()
gdouble | gwy_line_itor ()
gdouble | gwy_line_rtoi ()
gdouble | gwy_line_get_val ()
void | gwy_line_set_val ()
gdouble | gwy_line_get_dval ()
gdouble | gwy_line_get_dval_real ()
void | gwy_line_flip ()
void | gwy_line_invert_value ()
void | gwy_line_clear ()
void | gwy_line_fill ()
void | gwy_line_multiply ()
void | gwy_line_add ()
void | gwy_line_part_clear ()
void | gwy_line_part_fill ()
void | gwy_line_part_multiply ()
void | gwy_line_part_add ()
gint | gwy_line_threshold ()
gint | gwy_line_part_threshold ()
gdouble | gwy_line_der ()
void | gwy_line_cumulate ()
void | gwy_line_filter_slope ()
void | gwy_line_sqrt ()

## Signals

void | data-changed | Run First

## Types and Values

struct | GwyLine
struct | GwyLineClass

## Object Hierarchy

        GObject
        ╰── GwyLine

## Implemented Interfaces

GwyLine implements GwySerializable.

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

GwyLine is a one-dimensional floating point data array. It is used for most of the data processing functions connected with 1D data, graphs, etc.

## Functions

### gwy_line_new()

    GwyLine *
    gwy_line_new (gint res,
                  gdouble real,
                  gboolean nullme);

Creates a new data line.

[constructor]

#### Parameters

res | Resolution, i.e., the number of samples. |
real | Real physical dimension. |
nullme | Whether the data line should be initialized to zeroes. If `FALSE`, the data will not be initialized. |

#### Returns

A newly created data line.

[transfer full]

### gwy_line_new_alike()

    GwyLine *
    gwy_line_new_alike (GwyLine *model,
                        gboolean nullme);

Creates a new data line similar to an existing one.

Use `gwy_line_duplicate()` if you want to copy a data line including data.

#### Parameters

model | A data line to take resolutions and units from. |
nullme | Whether the data line should be initialized to zeroes. If `FALSE`, the data will not be initialized. |

#### Returns

A newly created data line.

[transfer full]

### gwy_line_copy()

    GwyLine *
    gwy_line_copy (GwyLine *line);

Create a new data line as a copy of an existing one.

This function is a convenience `gwy_serializable_copy()` wrapper.

#### Parameters

line | A data line to duplicate. |

#### Returns

A copy of the data line.

[transfer full]

### gwy_line_assign()

    void
    gwy_line_assign (GwyLine *destination,
                     GwyLine *source);

Makes one data line equal to another.

This function is a convenience `gwy_serializable_assign()` wrapper.

#### Parameters

destination | Target data line. |
source | Source data line. |

### gwy_line_data_changed()

    void
    gwy_line_data_changed (GwyLine *line);

Emits signal "data_changed" on a data line.

#### Parameters

line | A data line. |

### gwy_line_new_resampled()

    GwyLine *
    gwy_line_new_resampled (GwyLine *line,
                            gint res,
                            GwyInterpolationType interpolation);

Creates a new data line by resampling an existing one.

This method is equivalent to `gwy_line_duplicate()` followed by `gwy_line_resample()`, but it is more efficient.

#### Parameters

line | A data line. |
res | Desired resolution. |
interpolation | Interpolation method to use. |

#### Returns

A newly created data line.

[transfer full]

### gwy_line_resample()

    void
    gwy_line_resample (GwyLine *line,
                       gint res,
                       GwyInterpolationType interpolation);

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

line | A data line. |
res | Desired resolution. |
interpolation | Interpolation method to use. |

### gwy_line_make_alike()

    void
    gwy_line_make_alike (GwyLine *line,
                         GwyLine *model);

Resizes a data field and updates its properties to match another data field.

Physical dimensions, offsets and units are all updated to match `model` . Since the function can resize `field` , its contents must be considered undefined. See `gwy_field_resize()` for just pixel resize and `gwy_field_assign()` for making one field completely identical to another.

#### Parameters

line | A data line. |
model | A data line to take resolutions and units from. |

### gwy_line_resize()

    void
    gwy_line_resize (GwyLine *line,
                     gint res);

Resizes a data line to different size, discarding data.

The real size and offset are kept unchanged. The line contents becomes undefined. The function just makes sure `line` has the correct pixel dimension.

#### Parameters

line | A data line. |
res | Desired resolution. |

### gwy_line_crop()

    void
    gwy_line_crop (GwyLine *line,
                   gint pos,
                   gint len);

Crops a data line to a smaller length.

The real size is updated and the offset is reset to zero.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of extracted segment. |

### gwy_line_part_extract()

    GwyLine *
    gwy_line_part_extract (GwyLine *line,
                           gint pos,
                           gint len);

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

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of extracted segment. |

#### Returns

The extracted area as a newly created data line.

[transfer full]

### gwy_line_copy_data()

    void
    gwy_line_copy_data (GwyLine *src,
                        GwyLine *dest);

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

Only the data points are copied. To make a data line completely identical to another, including units and change of dimensions, you can use `gwy_line_assign()`.

#### Parameters

src | Source data line. |
dest | Destination data line. |

### gwy_line_part_copy()

    void
    gwy_line_part_copy (GwyLine *src,
                        GwyLine *dest,
                        gint pos,
                        gint len,
                        gint destpos);

Copies a segment from one data line to another.

The part starts at `pos` in `src` and its dimension is `len` . It is copied to `dest` starting from `destpos` .

The source part has to be completely contained in `src` . No assumptions are made about destination position, however. Parts of the source part sticking out the destination data field `dest` are cut off.

If `src` is the same data line as `dest` , the parts may not overlap.

#### Parameters

src | Source data line. |
dest | Destination data line. |
pos | Index where to start in `src` . |
len | Length of copied segment. You can also pass -1 for full `src` size. |
destpos | Destination position in `dest` . |

### gwy_line_get_data()

    gdouble *
    gwy_line_get_data (GwyLine *line);

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 `gwy_line_resize()` and `gwy_line_resample()`.

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

#### Parameters

line | A data line. |

#### Returns

The data as an array of doubles of length `gwy_line_get_res()`.

[type gpointer]

### gwy_line_get_data_const()

    const gdouble *
    gwy_line_get_data_const (GwyLine *line);

Gets the raw data buffer of a data line, read-only.

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

Use `gwy_line_get_data()` if you want to change the data.

#### Parameters

line | A data line. |

#### Returns

The data as an array of doubles of length `gwy_line_get_res()`.

### gwy_line_get_data_with_size()

    gdouble *
    gwy_line_get_data_with_size (GwyLine *line,
                                 gsize *out_count);

Gets the raw data buffer of a data line. Used for gobject-introspection bindings.

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

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

#### Parameters

line | A data line. |
out_count | Number of items in the returned buffer. | [out]

#### Returns

The data as an array of doubles of length `gwy_line_get_res()`.

[transfer none][array length=out_count]

### gwy_line_set_data_with_size()

    void
    gwy_line_set_data_with_size (GwyLine *line,
                                 gdouble *data,
                                 gsize data_count);

Sets new values to the raw data buffer of a data line. Used for gobject-introspection bindings.

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

#### Parameters

line | A data line. |
data | The data to be set as a pointer to an array of `data_count` gdoubles. | [array length=data_count]
data_count | Number of items in `data` . It has to be equal to `gwy_line_get_res()`, else the function does nothing. |

### gwy_line_invalidate()

    void
    gwy_line_invalidate (GwyLine *line);

Invalidates cached data line stats.

User code should rarely need this macro, as all GwyLine methods do proper invalidation when they change data, as well as `gwy_line_get_data()` does.

However, if you get raw data with `gwy_line_get_data()` and then mix direct changes to it with calls to methods like `gwy_line_get_max()`, you may need to explicitely invalidate cached values to let `gwy_line_get_max()` know it has to recompute the maximum.

#### Parameters

line | A data line. |

### gwy_line_get_res()

    gint
    gwy_line_get_res (GwyLine *line);

Gets the number of data points in a data line.

#### Parameters

line | A data line. |

#### Returns

Resolution (number of data points).

### gwy_line_get_real()

    gdouble
    gwy_line_get_real (GwyLine *line);

Gets the physical size of a data line.

#### Parameters

line | A data line. |

#### Returns

Real size of data line.

### gwy_line_set_real()

    void
    gwy_line_set_real (GwyLine *line,
                       gdouble real);

Sets the real data line size.

#### Parameters

line | A data line. |
real | value to be set |

### gwy_line_get_offset()

    gdouble
    gwy_line_get_offset (GwyLine *line);

Gets the offset of data line origin.

#### Parameters

line | A data line. |

#### Returns

Offset value.

### gwy_line_set_offset()

    void
    gwy_line_set_offset (GwyLine *line,
                         gdouble offset);

Sets the offset of a data line origin.

Note offsets don't affect any calculation, nor functions like `gwy_line_rtoi()`.

#### Parameters

line | A data line. |
offset | New offset value. |

### gwy_line_get_dx()

    gdouble
    gwy_line_get_dx (GwyLine *line);

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

The result is the same as gwy_line_get_real(line)/gwy_line_get_res(line).

#### Parameters

line | A data line. |

#### Returns

Sampling step size.

### gwy_line_get_unit_x()

    GwyUnit *
    gwy_line_get_unit_x (GwyLine *line);

Returns lateral SI unit of a data line.

The returned object can be modified to change the line x units.

#### Parameters

line | A data line. |

#### Returns

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

[transfer none]

### gwy_line_get_unit_y()

    GwyUnit *
    gwy_line_get_unit_y (GwyLine *line);

Returns value SI unit of a data line.

The returned object can be modified to change the line value units.

#### Parameters

line | A data line. |

#### Returns

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

[transfer none]

### gwy_line_get_value_format_x()

    GwyValueFormat *
    gwy_line_get_value_format_x (GwyLine *line,
                                 GwyUnitFormatStyle style,
                                 GwyValueFormat *format);

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

#### Parameters

line | A data line. |
style | Unit format style. |
format | A SI value format to modify, or `NULL` to allocate a new one. | [nullable]

#### Returns

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

### gwy_line_get_value_format_y()

    GwyValueFormat *
    gwy_line_get_value_format_y (GwyLine *line,
                                 GwyUnitFormatStyle style,
                                 GwyValueFormat *format);

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

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

#### Parameters

line | A data line. |
style | Unit format style. |
format | A SI value format to modify, or `NULL` to allocate a new one. | [nullable]

#### Returns

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

### gwy_line_copy_units()

    void
    gwy_line_copy_units (GwyLine *line,
                         GwyLine *target);

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

#### Parameters

line | A data line. |
target | Destination data line. |

### gwy_line_itor()

    gdouble
    gwy_line_itor (GwyLine *line,
                   gdouble pixpos);

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 gwy_line_itor(`line` , `pixpos` + 0.5) for that.

#### Parameters

line | A data line. |
pixpos | Pixel coordinate. |

#### Returns

`pixpos` in real coordinates.

### gwy_line_rtoi()

    gdouble
    gwy_line_rtoi (GwyLine *line,
                   gdouble realpos);

Transforms real (physical) coordinate to pixel coordinate.

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

#### Parameters

line | A data line. |
realpos | Real coordinate. |

#### Returns

`realpos` in pixel coordinates.

### gwy_line_get_val()

    gdouble
    gwy_line_get_val (GwyLine *line,
                      gint i);

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 `gwy_line_get_data_const()` and access it directly instead.

#### Parameters

line | A data line. |
i | Position in the line (index). |

#### Returns

Value at given index.

### gwy_line_set_val()

    void
    gwy_line_set_val (GwyLine *line,
                      gint i,
                      gdouble value);

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 `gwy_line_get_data()` and write to it directly instead.

#### Parameters

line | A data line. |
i | Position in the line (index). |
value | Value to set. |

### gwy_line_get_dval()

    gdouble
    gwy_line_get_dval (GwyLine *line,
                       gdouble x,
                       GwyInterpolationType interpolation);

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 gwy_line_get_val(`line` , `j` ) returns, it's necessary to add 0.5: gwy_line_get_dval(`line` , * `j` +0.5, `interpolation` ).

See also `gwy_line_get_dval_real()` that does the same, but takes real coordinates.

#### Parameters

line | A data line. |
x | Position in data line in range [0, resolution]. If the value is outside this range, the nearest border value is returned. |
interpolation | Interpolation method to use. |

#### Returns

Value interpolated in the data line.

### gwy_line_get_dval_real()

    gdouble
    gwy_line_get_dval_real (GwyLine *line,
                            gdouble x,
                            GwyInterpolationType interpolation);

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

See also `gwy_line_get_dval()` for interpolation explanation.

#### Parameters

line | A data line. |
x | Position in real coordinates. |
interpolation | Interpolation method to use. |

#### Returns

Value interpolated in the data line.

### gwy_line_flip()

    void
    gwy_line_flip (GwyLine *line);

Reflects a data line in place.

#### Parameters

line | A data line. |

### gwy_line_invert_value()

    void
    gwy_line_invert_value (GwyLine *line);

Inverts a data line data in place.

Values are inverted about the mean value. Use `gwy_line_multiply()` to change the signs of all values.

#### Parameters

line | A data line. |

### gwy_line_clear()

    void
    gwy_line_clear (GwyLine *line);

Fills a data line with zeroes.

#### Parameters

line | A data line. |

### gwy_line_fill()

    void
    gwy_line_fill (GwyLine *line,
                   gdouble value);

Fills a data line with specified value.

#### Parameters

line | A data line. |
value | Value to fill data line with. |

### gwy_line_multiply()

    void
    gwy_line_multiply (GwyLine *line,
                       gdouble value);

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

#### Parameters

line | A data line. |
value | Value to multiply data line with. |

### gwy_line_add()

    void
    gwy_line_add (GwyLine *line,
                  gdouble value);

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

#### Parameters

line | A data line. |
value | Value to be added. |

### gwy_line_part_clear()

    void
    gwy_line_part_clear (GwyLine *line,
                         gint pos,
                         gint len);

Fills a data line part with zeroes.

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |

### gwy_line_part_fill()

    void
    gwy_line_part_fill (GwyLine *line,
                        gint pos,
                        gint len,
                        gdouble value);

Fills specified part of data line with specified number

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |
value | Value to fill data line part with. |

### gwy_line_part_multiply()

    void
    gwy_line_part_multiply (GwyLine *line,
                            gint pos,
                            gint len,
                            gdouble value);

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

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |
value | Value multiply data line part with. |

### gwy_line_part_add()

    void
    gwy_line_part_add (GwyLine *line,
                       gint pos,
                       gint len,
                       gdouble value);

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

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |
value | Value to be added |

### gwy_line_threshold()

    gint
    gwy_line_threshold (GwyLine *line,
                        gdouble threshval,
                        gdouble bottom,
                        gdouble top);

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

#### Parameters

line | A data line. |
threshval | Threshold value. |
bottom | Lower replacement value. |
top | Upper replacement value. |

#### Returns

total number of values above threshold

### gwy_line_part_threshold()

    gint
    gwy_line_part_threshold (GwyLine *line,
                             gint pos,
                             gint len,
                             gdouble threshval,
                             gdouble bottom,
                             gdouble top);

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

#### Parameters

line | A data line. |
pos | Index where to start. |
len | Length of the segment. |
threshval | Threshold value. |
bottom | Lower replacement value. |
top | Upper replacement value. |

#### Returns

total number of values above threshold within interval

### gwy_line_der()

    gdouble
    gwy_line_der (GwyLine *line,
                  gint i);

Computes central derivaltion at given index in a data line.

#### Parameters

line | A data line. |
i | Pixel coordinate. |

#### Returns

Derivation at given position.

### gwy_line_cumulate()

    void
    gwy_line_cumulate (GwyLine *line,
                       gboolean transform_to_cdist);

Transforms a distribution in a data line to cummulative distribution.

Each element becomes sum of all previous elements in the line, including self. If `transform_to_cdist` is `FALSE`, this is the only change.

If it is `TRUE`, the values are also multiplied by `gwy_line_dx()` and the y-unit is multiplied by the x-unit, corresponding to integration. In addition, the tail is forced to not exceed 1 and the last value is forced to be exactly 1 (working around possible rounding errors). This is useful when `line` is normalised as a probability distribution function and it should be fully transformed to a cummulative distribution function.

See also `gwy_accumulate_counts()`.

#### Parameters

line | A data line. |
transform_to_cdist | `TRUE` to fully transform, including units; `FALSE` to just do the cummulative summation. |

### gwy_line_filter_slope()

    void
    gwy_line_filter_slope (GwyLine *line,
                           GwyLine *der);

Calculates the derivative for an entire data line.

The derivatives are in physical units (not pixel-wise) and calculated from simple symmetrical differences, except at the edges where the differences are one-sided.

#### Parameters

line | A data line. |
der | Data line where the derivative is to be stored. It will be resized to match `line` . |

### gwy_line_sqrt()

    void
    gwy_line_sqrt (GwyLine *line);

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

#### Parameters

line | A data line. |

## Types and Values

### struct GwyLine

    struct GwyLine;

### struct GwyLineClass

    struct GwyLineClass {
        GObjectClass parent_class;

        void (*data_changed)(GwyLine *line);
    };

## Signal Details

### The `“data-changed”` signal

    void
    user_function (GwyLine *gwyline,
                   gpointer user_data)

The ::data-changed signal is never emitted by the object itself. It is intended as a means to notify object users they should update themselves, usually when a computation modifying the data is finished.

#### Parameters

gwyline | The GwyLine which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First