Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

GwySurface (HEAD)

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

Warning

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

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