GwySurface: Gwyddion Data Processing Library Reference Manual

## GwySurface GwySurface — General two-dimensional data |

## Functions

#define | gwy_surface_duplicate()
#define | gwy_surface_assign()
#define | gwy_surface_clone()
GwySurface * | gwy_surface_new ()
GwySurface * | gwy_surface_new_sized ()
GwySurface * | gwy_surface_new_from_data ()
GwySurface * | gwy_surface_new_alike ()
GwySurface * | gwy_surface_new_part ()
GwyXYZ * | gwy_surface_get_data ()
const GwyXYZ * | gwy_surface_get_data_const ()
guint | gwy_surface_get_npoints ()
void | gwy_surface_data_changed ()
void | gwy_surface_copy ()
void | gwy_surface_invalidate ()
void | gwy_surface_set_from_data_field ()
void | gwy_surface_set_from_data_field_mask ()
GwySIUnit * | gwy_surface_get_si_unit_xy ()
GwySIUnit * | gwy_surface_get_si_unit_z ()
void | gwy_surface_set_si_unit_xy ()
void | gwy_surface_set_si_unit_z ()
GwySIValueFormat * | gwy_surface_get_value_format_xy ()
GwySIValueFormat * | gwy_surface_get_value_format_z ()
void | gwy_surface_copy_units ()
void | gwy_data_field_copy_units_to_surface ()
void | gwy_surface_copy_units_to_data_field ()
GwyXYZ | gwy_surface_get ()
void | gwy_surface_set ()
void | gwy_surface_get_xrange ()
void | gwy_surface_get_yrange ()
void | gwy_surface_get_min_max ()
void | gwy_surface_multiply ()
void | gwy_surface_add ()
void | gwy_surface_scale_xy ()
const GwyXYZ * | gwy_surface_get_data_full ()
void | gwy_surface_set_data_full ()
gboolean | gwy_surface_xy_is_compatible ()
GwySurface * | gwy_surface_reduce_points ()
void | gwy_surface_resize ()

## Signals

void | data-changed | Run First

## Types and Values

struct | GwySurface
struct | GwySurfaceClass

## Object Hierarchy

        GObject
        ╰── GwySurface

## Implemented Interfaces

GwySurface implements GwySerializable.

## Includes

    #include <libprocess/gwyprocess.h>

## Description

GwySurface represents general, i.e. possibly unevenly spaced, two-dimensional data, also called XYZ data.

Surface points are stored in a flat array GwySurface-struct.data of GwyXYZ values.

Unlike GwyDataField, a surface can also be empty, i.e. contain zero points.

## Functions

### gwy_surface_duplicate()

    #define             gwy_surface_duplicate(surface)

Duplicates a surface.

This is a convenience wrapper of `gwy_serializable_duplicate()`.

#### Parameters

surface | A surface. |

Since: 2.45

### gwy_surface_assign()

    #define             gwy_surface_assign(dest, source)

Convenience macro making one data surface identical to another.

This is just a `gwy_serializable_clone()` wrapper with all the necessary typecasting.

#### Parameters

dest | Target data surface. |
source | Source data surface. |

Since: 2.52

### gwy_surface_clone()

    #define gwy_surface_clone(dest, src) (gwy_serializable_clone(G_OBJECT(dest), G_OBJECT(src)))

`gwy_surface_clone` is deprecated and should not be used in newly-written code.

Copies the value of a surface.

This is a convenience wrapper of `gwy_serializable_clone()`.

Use `gwy_surface_assign()` instead for consistency. Note that the argument order is reversed!

#### Parameters

dest | Destination surface. |
src | Source surface. |

Since: 2.45

### gwy_surface_new ()

    GwySurface *
    gwy_surface_new (void);

Creates a new empty surface.

The surface will not contain any points. This parameterless constructor exists mainly for language bindings, `gwy_surface_new_from_data()` is usually more useful.

#### Returns

A new empty surface.

Since: 2.45

### gwy_surface_new_sized ()

    GwySurface *
    gwy_surface_new_sized (guint n);

Creates a new surface with preallocated size.

The surface will contain the speficied number of points with uninitialised values.

#### Parameters

n | Number of points. |

#### Returns

A new surface.

Since: 2.45

### gwy_surface_new_from_data ()

    GwySurface *
    gwy_surface_new_from_data (const GwyXYZ *points,
                               guint n);

Creates a new surface, filling it with provided points.

#### Parameters

points | Array of `n` points with the surface data. |
n | Number of points. |

#### Returns

A new surface.

Since: 2.45

### gwy_surface_new_alike ()

    GwySurface *
    gwy_surface_new_alike (GwySurface *model);

Creates a new empty surface similar to another surface.

The units of the new surface will be identical to those of `model` but the new surface will not contain any points. Use `gwy_surface_duplicate()` to completely duplicate a surface including data.

#### Parameters

model | A surface to use as the template. |

#### Returns

A new empty surface.

Since: 2.45

### gwy_surface_new_part ()

    GwySurface *
    gwy_surface_new_part (GwySurface *surface,
                          gdouble xfrom,
                          gdouble xto,
                          gdouble yfrom,
                          gdouble yto);

Creates a new surface as a part of another surface.

The new surface consits of data with lateral coordinates within the specified ranges (inclusively). It may be empty.

Data are physically copied, i.e. changing the new surface data does not change `surface` 's data and vice versa.

#### Parameters

surface | A surface. |
xfrom | Minimum x-coordinate value. |
xto | Maximum x-coordinate value. |
yfrom | Minimum y-coordinate value. |
yto | Maximum y-coordinate value. |

#### Returns

A new surface.

Since: 2.45

### gwy_surface_get_data ()

    GwyXYZ *
    gwy_surface_get_data (GwySurface *surface);

Gets the raw XYZ data array of a surface.

The returned buffer is not guaranteed to be valid through whole data surface life time.

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

See `gwy_surface_invalidate()` for some discussion.

#### Parameters

surface | A surface. |

#### Returns

The surface XYZ data as a pointer to an array of `gwy_surface_get_npoints()` items.

Since: 2.45

### gwy_surface_get_data_const ()

    const GwyXYZ *
    gwy_surface_get_data_const (GwySurface *surface);

Gets the raw XYZ data array of a surface, read-only.

The returned buffer is not guaranteed to be valid through whole data field life time.

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

See `gwy_surface_invalidate()` for some discussion.

#### Parameters

surface | A surface. |

#### Returns

The surface XYZ data as a pointer to an array of `gwy_surface_get_npoints()` items.

Since: 2.45

### gwy_surface_get_npoints ()

    guint
    gwy_surface_get_npoints (GwySurface *surface);

Gets the number of points in an XYZ surface.

#### Parameters

surface | A surface. |

#### Returns

The number of points.

Since: 2.45

### gwy_surface_data_changed ()

    void
    gwy_surface_data_changed (GwySurface *surface);

Emits signal GwySurface::data-changed on a surface.

#### Parameters

surface | A surface. |

Since: 2.45

### gwy_surface_copy ()

    void
    gwy_surface_copy (GwySurface *src,
                      GwySurface *dest);

Copies the data of a surface to another surface of the same dimensions.

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

#### Parameters

src | Source surface. |
dest | Destination surface. |

Since: 2.45

### gwy_surface_invalidate ()

    void
    gwy_surface_invalidate (GwySurface *surface);

Invalidates cached surface statistics.

Cached statistics include ranges returned by `gwy_surface_get_xrange()`, `gwy_surface_get_yrange()` and `gwy_surface_get_min_max()`, the fingerprint for `gwy_surface_xy_is_compatible()` and and possibly other characteristics in the future.

See `gwy_data_field_invalidate()` for discussion of invalidation and examples.

#### Parameters

surface | A surface. |

Since: 2.45

### gwy_surface_set_from_data_field ()

    void
    gwy_surface_set_from_data_field (GwySurface *surface,
                                     GwyDataField *data_field);

Fills the data of a surface from a data field.

The number of points in the new surface will be equal to the number of points in the field. Lateral coordinates will be equal to the corresponding `data_field` coordinates; values will be created in regular grid according to `data_field` 's physical size and offset.

Lateral and value units will correspond to `data_field` 's units. This means the field needs to have identical `x` and `y` units.

#### Parameters

surface | A surface. |
data_field | A two-dimensional data field. |

Since: 2.45

### gwy_surface_set_from_data_field_mask ()

    void
    gwy_surface_set_from_data_field_mask (GwySurface *surface,
                                          GwyDataField *data_field,
                                          GwyDataField *mask,
                                          GwyMaskingType masking);

Fills the data of a surface from a data field, possibly using masking.

#### Parameters

surface | A surface. |
data_field | A two-dimensional data field. |
mask | Mask of pixels to include from/exclude, or `NULL` |
masking | Masking mode to use. |

Since: 2.46

### gwy_surface_get_si_unit_xy ()

    GwySIUnit *
    gwy_surface_get_si_unit_xy (GwySurface *surface);

Returns lateral SI unit of a surface.

#### Parameters

surface | A surface. |

#### Returns

SI unit corresponding to the lateral (XY) dimensions of the surface. Its reference count is not incremented.

Since: 2.45

### gwy_surface_get_si_unit_z ()

    GwySIUnit *
    gwy_surface_get_si_unit_z (GwySurface *surface);

Returns value SI unit of a surface.

#### Parameters

surface | A surface. |

#### Returns

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

Since: 2.45

### gwy_surface_set_si_unit_xy ()

    void
    gwy_surface_set_si_unit_xy (GwySurface *surface,
                                GwySIUnit *si_unit);

Sets the SI unit corresponding to the lateral (XY) dimensions of a surface.

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

#### Parameters

surface | A surface. |
si_unit | SI unit to be set. |

Since: 2.45

### gwy_surface_set_si_unit_z ()

    void
    gwy_surface_set_si_unit_z (GwySurface *surface,
                               GwySIUnit *si_unit);

Sets the SI unit corresponding to the "height" (Z) dimension of a surface.

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

#### Parameters

surface | A surface. |
si_unit | SI unit to be set. |

Since: 2.45

### gwy_surface_get_value_format_xy ()

    GwySIValueFormat *
    gwy_surface_get_value_format_xy (GwySurface *surface,
                                     GwySIUnitFormatStyle style,
                                     GwySIValueFormat *format);

Finds value format good for displaying coordinates of a surface.

#### Parameters

surface | A surface. |
style | Unit format style. |
format | A SI value format to modify, or `NULL` to allocate a new one. |

#### Returns

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

Since: 2.45

### gwy_surface_get_value_format_z ()

    GwySIValueFormat *
    gwy_surface_get_value_format_z (GwySurface *surface,
                                    GwySIUnitFormatStyle style,
                                    GwySIValueFormat *format);

Finds value format good for displaying values of a surface.

#### Parameters

surface | A surface. |
style | Unit format style. |
format | A SI value format to modify, or `NULL` to allocate a new one. |

#### Returns

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

Since: 2.45

### gwy_surface_copy_units ()

    void
    gwy_surface_copy_units (GwySurface *surface,
                            GwySurface *target);

Sets lateral and value units of a surface to match another surface.

#### Parameters

surface | A surface. |
target | Target surface. |

Since: 2.49

### gwy_data_field_copy_units_to_surface ()

    void
    gwy_data_field_copy_units_to_surface (GwyDataField *data_field,
                                          GwySurface *surface);

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

#### Parameters

data_field | A two-dimensional data field. |
surface | A surface. |

Since: 2.46

### gwy_surface_copy_units_to_data_field ()

    void
    gwy_surface_copy_units_to_data_field (GwySurface *surface,
                                          GwyDataField *data_field);

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

#### Parameters

surface | A surface. |
data_field | A two-dimensional data field. |

Since: 2.46

### gwy_surface_get ()

    GwyXYZ
    gwy_surface_get (GwySurface *surface,
                     guint pos);

Obtains a single XYZ surface point.

This function exists only for language bindings as it is very slow compared to simply accessing `data` in GwySurface directly in C.

#### Parameters

surface | A surface. |
pos | Position in `surface` . |

#### Returns

The point at `pos` .

Since: 2.45

### gwy_surface_set ()

    void
    gwy_surface_set (GwySurface *surface,
                     guint pos,
                     GwyXYZ point);

Sets a single XYZ surface value.

This function exists only for language bindings as it is very slow compared to simply accessing `data` in GwySurface directly in C.

#### Parameters

surface | A surface. |
pos | Position in `surface` . |
point | Point to store at given position. |

Since: 2.45

### gwy_surface_get_xrange ()

    void
    gwy_surface_get_xrange (GwySurface *surface,
                            gdouble *min,
                            gdouble *max);

Gets the range of X coordinates of an XYZ surface.

This information is cached.

#### Parameters

surface | A surface. |
min | Location where to store the minimum value. |
max | Location where to store the maximum value. |

Since: 2.45

### gwy_surface_get_yrange ()

    void
    gwy_surface_get_yrange (GwySurface *surface,
                            gdouble *min,
                            gdouble *max);

Gets the range of Y coordinates of an XYZ surface.

This information is cached.

#### Parameters

surface | A surface. |
min | Location where to store the minimum value. |
max | Location where to store the maximum value. |

Since: 2.45

### gwy_surface_get_min_max ()

    void
    gwy_surface_get_min_max (GwySurface *surface,
                             gdouble *min,
                             gdouble *max);

Gets the range of Z values of an XYZ surface.

This information is cached.

#### Parameters

surface | A surface. |
min | Location where to store the minimum value. |
max | Location where to store the maximum value. |

Since: 2.45

### gwy_surface_multiply ()

    void
    gwy_surface_multiply (GwySurface *surface,
                          gdouble value);

Multiplies all values in an XYZ surface by given constant.

#### Parameters

surface | A surface. |
value | The value to multiply all data with. |

Since: 2.64

### gwy_surface_add ()

    void
    gwy_surface_add (GwySurface *surface,
                     gdouble value);

Adds a constant to all data in an XYZ surface.

#### Parameters

surface | A surface. |
value | The value to add to all data. |

Since: 2.64

### gwy_surface_scale_xy ()

    void
    gwy_surface_scale_xy (GwySurface *surface,
                          gdouble xfactor,
                          gdouble yfactor,
                          gdouble xoffset,
                          gdouble yoffset);

Rescales and/or shifts all X and Y coordinates of an XYZ surface.

The multiplicative factors are applied before the offsets.

#### Parameters

surface | A surface. |
xfactor | Factor to multiply all X coordinates with. |
yfactor | Factor to multiply all Y coordinates with. |
xoffset | Offset to add to all X coordinates. |
yoffset | Offset to add to all Y coordinates. |

Since: 2.64

### gwy_surface_get_data_full ()

    const GwyXYZ *
    gwy_surface_get_data_full (GwySurface *surface,
                               guint *n);

Provides the values of an entire surface as a flat array.

This function, paired with `gwy_surface_set_data_full()` can be namely useful in language bindings.

Note that this function returns a pointer directly to `surface` 's data.

#### Parameters

surface | A surface. |
n | Location to store the count of extracted data points. |

#### Returns

The array containing the surface points.

Since: 2.45

### gwy_surface_set_data_full ()

    void
    gwy_surface_set_data_full (GwySurface *surface,
                               const GwyXYZ *points,
                               guint n);

Puts back values from a flat array to an entire data surface.

If you do not have an array of GwyXYZ and want to fill the data sequentially, use `gwy_surface_resize()` and `gwy_surface_get_data()`.

See `gwy_surface_get_data_full()` for a discussion.

#### Parameters

surface | A surface. |
points | Data points to copy to the surface. They replace whatever points are in `surface` now. |
n | The number of points in `data` . |

Since: 2.45

### gwy_surface_xy_is_compatible ()

    gboolean
    gwy_surface_xy_is_compatible (GwySurface *surface,
                                  GwySurface *othersurface);

Checks whether the XY positions of two surfaces are compatible.

Compatible XY positions mean the XY units are the same and the points are the same. Two surfaces that have the same set of XY points but in different orders are not considered compatible. This is because the points at the same index in `data` are different and thus calculations involving data from the two surfaces are impossible. It is necessary to match the points order in the two surfaces to make this possible.

This information is cached.

#### Parameters

surface | A surface. |
othersurface | Another surface. |

#### Returns

`TRUE` if the surfaces are XY-position compatible, `FALSE` if they are not.

Since: 2.45

### gwy_surface_reduce_points ()

    GwySurface *
    gwy_surface_reduce_points (GwySurface *surface,
                               guint npoints);

Creates a similar surface with smaller number of points.

The functions attempts to choose points from the original surface to cover its full area, even though points from dense regions are still more likely to be found in the result than points from sparse regions. As the main purpose to enable quick rough operations that may take long time with the full surface, the focus is on speed not fidelity.

The function may employ random selection and thus be be non-deterministic.

#### Parameters

surface | A surface. |
npoints | Requested number of points in the reduced surface. If it is not smaller than the number of points in `surface` then the function behaves like `gwy_surface_duplicate()`. |

#### Returns

A newly created GwySurface with reduced number of points.

Since: 2.48

### gwy_surface_resize ()

    void
    gwy_surface_resize (GwySurface *surface,
                        guint npoints);

Changes the number of points in a surface.

If the number of points decreases then the first `npoints` points will be kept. If the number of points increases the new points will be uninitialised. Although usually you would overwrite all the points after using this function.

Use `gwy_surface_set_data_full()` if you already have an array of GwyXYZ to fill the surface data with.

#### Parameters

surface | A surface. |
npoints | New number of points in the surface. |

Since: 2.61

## Types and Values

### struct GwySurface

    struct GwySurface {
        guint n;
        GwyXYZ *data;
    };

Object representing surface data.

The GwySurface struct contains some public fields that can be directly accessed for reading. To set them, you must use the GwySurface methods.

#### Members

guint `n`; | Number of points. |
GwyXYZ *`data`; | Surface data. See the introductory section for details. |

Since: 2.45

### struct GwySurfaceClass

    struct GwySurfaceClass {
        GObjectClass g_object_class;

        void (*data_changed)(GwySurface *surface);
    };

Class of surfaces.

Since: 2.45

## Signal Details

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

    void
    user_function (GwySurface *gwysurface,
                   gpointer    user_data)

The ::data-changed signal is never emitted by surface itself. It is intended as a means to notify others data field users they should update themselves.

#### Parameters

gwysurface | The GwySurface which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First