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

GwyBrick (HEAD)

GwyBrick — Three-dimensional data representation

Functions

#define gwy_brick_duplicate()
#define gwy_brick_assign()
GwyBrick * gwy_brick_new ()
GwyBrick * gwy_brick_new_alike ()
GwyBrick * gwy_brick_new_part ()
void gwy_brick_data_changed ()
void gwy_brick_copy ()
void gwy_brick_resample ()
gint gwy_brick_get_xres ()
gint gwy_brick_get_yres ()
gint gwy_brick_get_zres ()
gdouble gwy_brick_get_xreal ()
gdouble gwy_brick_get_yreal ()
gdouble gwy_brick_get_zreal ()
gdouble gwy_brick_get_xoffset ()
gdouble gwy_brick_get_yoffset ()
gdouble gwy_brick_get_zoffset ()
const gdouble * gwy_brick_get_data_const ()
void gwy_brick_set_xreal ()
void gwy_brick_set_yreal ()
void gwy_brick_set_zreal ()
void gwy_brick_set_xoffset ()
void gwy_brick_set_yoffset ()
void gwy_brick_set_zoffset ()
gdouble gwy_brick_get_dx ()
gdouble gwy_brick_get_dy ()
gdouble gwy_brick_get_dz ()
GwySIUnit * gwy_brick_get_si_unit_x ()
GwySIUnit * gwy_brick_get_si_unit_y ()
GwySIUnit * gwy_brick_get_si_unit_z ()
GwySIUnit * gwy_brick_get_si_unit_w ()
void gwy_brick_set_si_unit_x ()
void gwy_brick_set_si_unit_y ()
void gwy_brick_set_si_unit_z ()
void gwy_brick_set_si_unit_w ()
gdouble gwy_brick_get_min ()
gdouble gwy_brick_get_max ()
void gwy_brick_copy_units ()
GwySIValueFormat * gwy_brick_get_value_format_x ()
GwySIValueFormat * gwy_brick_get_value_format_y ()
GwySIValueFormat * gwy_brick_get_value_format_z ()
GwySIValueFormat * gwy_brick_get_value_format_w ()
gdouble * gwy_brick_get_data ()
gdouble gwy_brick_itor ()
gdouble gwy_brick_rtoi ()
gdouble gwy_brick_jtor ()
gdouble gwy_brick_rtoj ()
gdouble gwy_brick_ktor ()
gdouble gwy_brick_rtok ()
gdouble gwy_brick_ktor_cal ()
gdouble gwy_brick_rtok_cal ()
gdouble gwy_brick_get_val ()
void gwy_brick_set_val ()
gdouble gwy_brick_get_val_real ()
void gwy_brick_set_val_real ()
gdouble gwy_brick_get_dval ()
gdouble gwy_brick_get_dval_real ()
void gwy_brick_clear ()
void gwy_brick_fill ()
void gwy_brick_multiply ()
void gwy_brick_add ()
void gwy_brick_extract_plane ()
void gwy_brick_extract_xy_plane ()
void gwy_brick_sum_plane ()
void gwy_brick_sum_xy_plane ()
void gwy_brick_min_plane ()
void gwy_brick_min_xy_plane ()
void gwy_brick_max_plane ()
void gwy_brick_max_xy_plane ()
void gwy_brick_minpos_plane ()
void gwy_brick_minpos_xy_plane ()
void gwy_brick_maxpos_plane ()
void gwy_brick_maxpos_xy_plane ()
void gwy_brick_mean_plane ()
void gwy_brick_mean_xy_plane ()
void gwy_brick_rms_plane ()
void gwy_brick_rms_xy_plane ()
void gwy_brick_extract_line ()
void gwy_brick_extract_z_line ()
GwyDataLine * gwy_brick_get_zcalibration ()
void gwy_brick_set_zcalibration ()
void gwy_brick_copy_zcalibration ()
void gwy_brick_transpose ()
void gwy_brick_set_plane ()
void gwy_brick_set_xy_plane ()
void gwy_brick_add_to_xy_planes ()
void gwy_brick_add_to_z_lines ()

Signals

void data-changed Run First

Types and Values

  GwyBrickPart
struct GwyBrick
struct GwyBrickClass

Object Hierarchy

    GObject
    ╰── GwyBrick

Implemented Interfaces

GwyBrick implements GwySerializable.

Includes

#include <libprocess/gwyprocess.h>

Description

GwyBrick represents 3D data arrays in Gwyddion. It is typically useful for different volume data obtained from SPMs, like in force volume measurements.

Functions

gwy_brick_duplicate()

#define             gwy_brick_duplicate(brick)

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

Parameters

brick

A data brick to duplicate.

 

Since: 2.31

gwy_brick_assign()

#define             gwy_brick_assign(dest, source)

Convenience macro making one data brick identical to another.

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

Parameters

dest

Target data brick.

 

source

Source data brick.

 

Since: 2.52

gwy_brick_new ()

GwyBrick *
gwy_brick_new (gint xres,
               gint yres,
               gint zres,
               gdouble xreal,
               gdouble yreal,
               gdouble zreal,
               gboolean nullme);

Creates a new data brick.

Parameters

xres

X resolution, i.e., the number of samples in x direction

 

yres

Y resolution, i.e., the number of samples in y direction

 

zres

Z resolution, i.e., the number of samples in z direction

 

xreal

Real physical dimension in x direction.

 

yreal

Real physical dimension in y direction.

 

zreal

Real physical dimension in z direction.

 

nullme

Whether the data brick should be initialized to zeroes. If FALSE, the data will not be initialized.

 

Returns

A newly created data brick.

Since: 2.31

gwy_brick_new_alike ()

GwyBrick *
gwy_brick_new_alike (GwyBrick *model,
                     gboolean nullme);

Creates a new data brick similar to an existing one.

Use gwy_brick_duplicate() if you want to copy a data brick including data.

Parameters

model

A data brick to take resolutions and units from.

 

nullme

Whether the data brick should be initialized to zeroes. If FALSE, the data will not be initialized.

 

Returns

A newly created data brick.

Since: 2.31

gwy_brick_new_part ()

GwyBrick *
gwy_brick_new_part (const GwyBrick *brick,
                    gint xpos,
                    gint ypos,
                    gint zpos,
                    gint xres,
                    gint yres,
                    gint zres,
                    gboolean keep_offsets);

Creates a new data brick as a part of existing one.

Use gwy_brick_duplicate() if you want to copy a whole data brick.

Parameters

brick

A data brick to take data from

 

xpos

x position where to start from

 

ypos

y position where to start from

 

zpos

z position where to start from

 

xres

x resolution (width) to be extracted

 

yres

y resolution (height) to be extracted

 

zres

z resolution (depth) to be extracted

 

keep_offsets

keep offsets of data during extraction

 

Returns

A newly created data brick.

Since: 2.32

gwy_brick_data_changed ()

void
gwy_brick_data_changed (GwyBrick *brick);

Emits signal "data_changed" on a data brick.

Parameters

brick

A data brick.

 

Since: 2.31

gwy_brick_copy ()

void
gwy_brick_copy (GwyBrick *src,
                GwyBrick *dest,
                gboolean nondata_too);

Copies the contents of an already allocated brick to a brick of the same size.

Parameters

src

Source brick.

 

dest

Destination brick.

 

nondata_too

Whether non-data (units) should be copied too.

 

gwy_brick_resample ()

void
gwy_brick_resample (GwyBrick *brick,
                    gint xres,
                    gint yres,
                    gint zres,
                    GwyInterpolationType interpolation);

Resamples a data brick.

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

Parameters

brick

A data brick.

 

xres

Desired x resolution.

 

yres

Desired y resolution.

 

zres

Desired z resolution.

 

interpolation

Interpolation method to use.

 

Since: 2.31

gwy_brick_get_xres ()

gint
gwy_brick_get_xres (GwyBrick *brick);

Gets the x resolution of a data brick.

Parameters

brick

A data brick.

 

Returns

Resolution (number of data points).

Since: 2.31

gwy_brick_get_yres ()

gint
gwy_brick_get_yres (GwyBrick *brick);

Gets the y resolution of a data brick.

Parameters

brick

A data brick.

 

Returns

Resolution (number of data points).

Since: 2.31

gwy_brick_get_zres ()

gint
gwy_brick_get_zres (GwyBrick *brick);

Gets the z resolution of a data brick.

Parameters

brick

A data line.

 

Returns

Resolution (number of data points).

Since: 2.31

gwy_brick_get_xreal ()

gdouble
gwy_brick_get_xreal (GwyBrick *brick);

Gets the physical size of a data brick in the x direction.

Parameters

brick

A data brick.

 

Returns

Real size of a data brick the x direction.

Since: 2.31

gwy_brick_get_yreal ()

gdouble
gwy_brick_get_yreal (GwyBrick *brick);

Gets the physical size of a data brick in the y direction.

Parameters

brick

A data brick.

 

Returns

Real size of a data brick the y direction.

Since: 2.31

gwy_brick_get_zreal ()

gdouble
gwy_brick_get_zreal (GwyBrick *brick);

Gets the physical size of a data brick in the z direction.

Parameters

brick

A data brick.

 

Returns

Real size of a data brick the z direction.

Since: 2.31

gwy_brick_get_xoffset ()

gdouble
gwy_brick_get_xoffset (GwyBrick *brick);

Gets the offset of data brick origin in x direction.

Parameters

brick

A data brick.

 

Returns

Offset value.

Since: 2.31

gwy_brick_get_yoffset ()

gdouble
gwy_brick_get_yoffset (GwyBrick *brick);

Gets the offset of data brick origin in y direction.

Parameters

brick

A data brick.

 

Returns

Offset value.

Since: 2.31

gwy_brick_get_zoffset ()

gdouble
gwy_brick_get_zoffset (GwyBrick *brick);

Gets the offset of data brick origin in z direction.

Parameters

brick

A data brick.

 

Returns

Offset value.

Since: 2.31

gwy_brick_get_data_const ()

const gdouble *
gwy_brick_get_data_const (GwyBrick *brick);

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

The returned buffer is not guaranteed to be valid through whole data brick life time. Some function may change it, most notably gwy_brick_resample().

Use gwy_brick_get_data() if you want to change the data.

Parameters

brick

A data brick.

 

Returns

The data as an array of doubles of length xres *yres *zres .

Since: 2.31

gwy_brick_set_xreal ()

void
gwy_brick_set_xreal (GwyBrick *brick,
                     gdouble xreal);

Sets the real x dimension of a brick.

Parameters

brick

A data brick.

 

xreal

New real x dimensions value

 

Since: 2.31

gwy_brick_set_yreal ()

void
gwy_brick_set_yreal (GwyBrick *brick,
                     gdouble yreal);

Sets the real y dimension of a brick.

Parameters

brick

A data brick.

 

yreal

New real y dimensions value

 

Since: 2.31

gwy_brick_set_zreal ()

void
gwy_brick_set_zreal (GwyBrick *brick,
                     gdouble zreal);

Sets the real z dimension of a brick.

Parameters

brick

A data brick.

 

zreal

New real z dimensions value

 

Since: 2.31

gwy_brick_set_xoffset ()

void
gwy_brick_set_xoffset (GwyBrick *brick,
                       gdouble xoffset);

Sets the offset of a data brick origin in the x direction.

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

Parameters

brick

A data brick.

 

xoffset

New offset value.

 

Since: 2.31

gwy_brick_set_yoffset ()

void
gwy_brick_set_yoffset (GwyBrick *brick,
                       gdouble yoffset);

Sets the offset of a data brick origin in the y direction.

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

Parameters

brick

A data brick.

 

yoffset

New offset value.

 

Since: 2.31

gwy_brick_set_zoffset ()

void
gwy_brick_set_zoffset (GwyBrick *brick,
                       gdouble zoffset);

Sets the offset of a data brick origin in the z direction.

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

Parameters

brick

A data brick.

 

zoffset

New offset value.

 

Since: 2.31

gwy_brick_get_dx ()

gdouble
gwy_brick_get_dx (GwyBrick *brick);

Gets the horizontal (X) voxel size of a brick in real units.

The result is the same as gwy_brick_get_xreal(brick)/gwy_brick_get_xres(brick).

Parameters

brick

A data brick.

 

Returns

Horizontal voxel size.

Since: 2.52

gwy_brick_get_dy ()

gdouble
gwy_brick_get_dy (GwyBrick *brick);

Gets the vertical (Y) voxel size of a brick in real units.

The result is the same as gwy_brick_get_yreal(brick)/gwy_brick_get_yres(brick).

Parameters

brick

A data brick.

 

Returns

Vertical voxel size.

Since: 2.52

gwy_brick_get_dz ()

gdouble
gwy_brick_get_dz (GwyBrick *brick);

Gets the level-wise (Z) voxel size of a brick in real units.

The result is the same as gwy_brick_get_zreal(brick)/gwy_brick_get_zres(brick).

Note that it cannot -- and hence does not -- take into account any attached Z calibration.

Parameters

brick

A data brick.

 

Returns

Level-wise voxel size.

Since: 2.52

gwy_brick_get_si_unit_x ()

GwySIUnit *
gwy_brick_get_si_unit_x (GwyBrick *brick);

Returns x direction SI unit of a data brick.

Parameters

brick

A data brick.

 

Returns

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

Since: 2.31

gwy_brick_get_si_unit_y ()

GwySIUnit *
gwy_brick_get_si_unit_y (GwyBrick *brick);

Returns y direction SI unit of a data brick.

Parameters

brick

A data brick.

 

Returns

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

Since: 2.31

gwy_brick_get_si_unit_z ()

GwySIUnit *
gwy_brick_get_si_unit_z (GwyBrick *brick);

Returns z direction SI unit of a data brick.

Parameters

brick

A data brick.

 

Returns

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

Since: 2.31

gwy_brick_get_si_unit_w ()

GwySIUnit *
gwy_brick_get_si_unit_w (GwyBrick *brick);

Returns value SI unit of a data brick.

Parameters

brick

A data brick.

 

Returns

SI unit corresponding to the "value" of the data brick. Its reference count is not incremented.

Since: 2.31

gwy_brick_set_si_unit_x ()

void
gwy_brick_set_si_unit_x (GwyBrick *brick,
                         GwySIUnit *si_unit);

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

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

Parameters

brick

A data brick.

 

si_unit

SI unit to be set.

 

Since: 2.31

gwy_brick_set_si_unit_y ()

void
gwy_brick_set_si_unit_y (GwyBrick *brick,
                         GwySIUnit *si_unit);

Sets the SI unit corresponding to the lateral (Y) dimension of a data brick.

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

Parameters

brick

A data brick.

 

si_unit

SI unit to be set.

 

Since: 2.31

gwy_brick_set_si_unit_z ()

void
gwy_brick_set_si_unit_z (GwyBrick *brick,
                         GwySIUnit *si_unit);

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

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

Parameters

brick

A data brick.

 

si_unit

SI unit to be set.

 

Since: 2.31

gwy_brick_set_si_unit_w ()

void
gwy_brick_set_si_unit_w (GwyBrick *brick,
                         GwySIUnit *si_unit);

Sets the SI unit corresponding to the "value" of a data brick.

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

Parameters

brick

A data brick.

 

si_unit

SI unit to be set.

 

Since: 2.31

gwy_brick_get_min ()

gdouble
gwy_brick_get_min (GwyBrick *brick);

Find the minimum value in a data brick.

Parameters

brick

A data brick.

 

Returns

The minimum value within the brick.

Since: 2.31

gwy_brick_get_max ()

gdouble
gwy_brick_get_max (GwyBrick *brick);

Find the maximum value in a data brick.

Parameters

brick

A data brick.

 

Returns

The maximum value within the brick.

Since: 2.31

gwy_brick_copy_units ()

void
gwy_brick_copy_units (const GwyBrick *brick,
                      GwyBrick *target);

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

Parameters

brick

A data brick.

 

target

Target data brick.

 

Since: 2.49

gwy_brick_get_value_format_x ()

GwySIValueFormat *
gwy_brick_get_value_format_x (GwyBrick *brick,
                              GwySIUnitFormatStyle style,
                              GwySIValueFormat *format);

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

Parameters

brick

A data brick.

 

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

gwy_brick_get_value_format_y ()

GwySIValueFormat *
gwy_brick_get_value_format_y (GwyBrick *brick,
                              GwySIUnitFormatStyle style,
                              GwySIValueFormat *format);

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

Parameters

brick

A data brick.

 

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

gwy_brick_get_value_format_z ()

GwySIValueFormat *
gwy_brick_get_value_format_z (GwyBrick *brick,
                              GwySIUnitFormatStyle style,
                              GwySIValueFormat *format);

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

Parameters

brick

A data brick.

 

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

gwy_brick_get_value_format_w ()

GwySIValueFormat *
gwy_brick_get_value_format_w (GwyBrick *brick,
                              GwySIUnitFormatStyle style,
                              GwySIValueFormat *format);

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

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

Parameters

brick

A data brick.

 

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

gwy_brick_get_data ()

gdouble *
gwy_brick_get_data (GwyBrick *brick);

Gets the raw data buffer of a data brick.

The returned buffer is not guaranteed to be valid through whole data brick life time. Some function may change it, most notably gwy_brick_resample().

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

Parameters

brick

A data brick.

 

Returns

The data as an array of doubles of length xres *yres *zres .

Since: 2.31

gwy_brick_itor ()

gdouble
gwy_brick_itor (GwyBrick *brick,
                gdouble pixpos);

Transforms pixel coordinate to real (physical) coordinate in x direction.

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

Parameters

brick

A data brick.

 

pixpos

Pixel coordinate.

 

Returns

pixpos in real coordinates.

Since: 2.31

gwy_brick_rtoi ()

gdouble
gwy_brick_rtoi (GwyBrick *brick,
                gdouble realpos);

Transforms real (physical) coordinate to pixel coordinate in x axis.

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

Parameters

brick

A data brick.

 

realpos

Real coordinate.

 

Returns

realpos in pixel coordinates.

Since: 2.31

gwy_brick_jtor ()

gdouble
gwy_brick_jtor (GwyBrick *brick,
                gdouble pixpos);

Transforms pixel coordinate to real (physical) coordinate in y direction.

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

Parameters

brick

A data brick.

 

pixpos

Pixel coordinate.

 

Returns

pixpos in real coordinates.

Since: 2.31

gwy_brick_rtoj ()

gdouble
gwy_brick_rtoj (GwyBrick *brick,
                gdouble realpos);

Transforms real (physical) coordinate to pixel coordinate in y axis.

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

Parameters

brick

A data brick.

 

realpos

Real coordinate.

 

Returns

realpos in pixel coordinates.

Since: 2.31

gwy_brick_ktor ()

gdouble
gwy_brick_ktor (GwyBrick *brick,
                gdouble pixpos);

Transforms pixel coordinate to real (physical) coordinate in z direction.

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

Parameters

brick

A data brick.

 

pixpos

Pixel coordinate.

 

Returns

pixpos in real coordinates.

Since: 2.31

gwy_brick_rtok ()

gdouble
gwy_brick_rtok (GwyBrick *brick,
                gdouble realpos);

Transforms real (physical) coordinate to pixel coordinate in z axis.

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

Parameters

brick

A data brick.

 

realpos

Real coordinate.

 

Returns

realpos in pixel coordinates.

Since: 2.31

gwy_brick_ktor_cal ()

gdouble
gwy_brick_ktor_cal (GwyBrick *brick,
                    gdouble pixpos);

Transforms pixel coordinate to real (physical) coordinate in z direction, taking into account calibration.

Unlike gwy_brick_ktor(), this function takes into account the z calibration and, if calibration is not present, the z axis offset. Since the calibration is available only for discrete pixel coordinates, the values are interpolated between and clamped if outside the range.

The values in the calibration are assumed to correspond to pixel centres. This convention is also kept when no calibration is present.

Parameters

brick

A data brick.

 

pixpos

Pixel coordinate.

 

Returns

pixpos in real coordinates.

Since: 2.42

gwy_brick_rtok_cal ()

gdouble
gwy_brick_rtok_cal (GwyBrick *brick,
                    gdouble realpos);

Transforms real (physical) coordinate to pixel coordinate in z axis, taking into account calibration.

Unlike gwy_brick_rtok(), this function takes into account the z calibration and, if calibration is not present, the z axis offset. Since the calibration is available only for discrete pixel coordinates, the values are interpolated between and clamped if outside the range.

The values in the calibration are assumed to correspond to pixel centres. This convention is also kept when no calibration is present.

Parameters

brick

A data brick.

 

realpos

Real coordinate.

 

Returns

realpos in pixel coordinates.

Since: 2.42

gwy_brick_get_val ()

gdouble
gwy_brick_get_val (GwyBrick *brick,
                   gint col,
                   gint row,
                   gint lev);

Gets value at given position in a data brick.

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

Parameters

brick

A data brick.

 

col

Position in the brick (column index).

 

row

Position in the brick (row index).

 

lev

Position in the brick (level index).

 

Returns

Value at given index.

Since: 2.31

gwy_brick_set_val ()

void
gwy_brick_set_val (GwyBrick *brick,
                   gint col,
                   gint row,
                   gint lev,
                   gdouble value);

Sets value at given position in a data brick.

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

Parameters

brick

A data brick.

 

col

Position in the brick (column index).

 

row

Position in the brick (row index).

 

lev

Position in the brick (level index).

 

value

Value to be set.

 

Since: 2.31

gwy_brick_get_val_real ()

gdouble
gwy_brick_get_val_real (GwyBrick *brick,
                        gdouble x,
                        gdouble y,
                        gdouble z);

Gets value at given position in a data brick, in real coordinates.

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

Parameters

brick

A data brick.

 

x

Position in the brick (x direction).

 

y

Position in the brick (y direction).

 

z

Position in the brick (z direction).

 

Returns

Value at given index.

Since: 2.31

gwy_brick_set_val_real ()

void
gwy_brick_set_val_real (GwyBrick *brick,
                        gdouble x,
                        gdouble y,
                        gdouble z,
                        gdouble value);

Sets value at given position in a data brick.

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

Parameters

brick

A data brick.

 

x

Position in the brick (x direction).

 

y

Position in the brick (y direction).

 

z

Position in the brick (z direction).

 

value

Value to be set.

 

Since: 2.31

gwy_brick_get_dval ()

gdouble
gwy_brick_get_dval (GwyBrick *brick,
                    gdouble x,
                    gdouble y,
                    gdouble z,
                    gint interpolation);

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

Note pixel values are centered in intervals [i , i +1]. See also gwy_brick_get_dval_real() that does the same, but takes real coordinates.

Parameters

brick

A data brick.

 

x

Position in data brick in range [0, x resolution]. If the value is outside this range, the nearest border value is returned.

 

y

Position in data brick in range [0, y resolution]. If the value is outside this range, the nearest border value is returned.

 

z

Position in data brick in range [0, z 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 brick.

Since: 2.31

gwy_brick_get_dval_real ()

gdouble
gwy_brick_get_dval_real (GwyBrick *brick,
                         gdouble x,
                         gdouble y,
                         gdouble z,
                         gint interpolation);

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

Note pixel values are centered in intervals [j , j +1]. See also gwy_brick_get_dval() that does the same, but takes pixel coordinates.

Parameters

brick

A data brick.

 

x

Position in data brick in range [0, x resolution]. If the value is outside this range, the nearest border value is returned.

 

y

Position in data brick in range [0, y resolution]. If the value is outside this range, the nearest border value is returned.

 

z

Position in data brick in range [0, z 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 brick.

Since: 2.31

gwy_brick_clear ()

void
gwy_brick_clear (GwyBrick *brick);

Fills a data brick with zeroes.

Parameters

brick

A data brick.

 

Since: 2.31

gwy_brick_fill ()

void
gwy_brick_fill (GwyBrick *brick,
                gdouble value);

Fills a data brick with specified value.

Parameters

brick

A data brick.

 

value

Value to fill data brick with.

 

Since: 2.31

gwy_brick_multiply ()

void
gwy_brick_multiply (GwyBrick *brick,
                    gdouble value);

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

Parameters

brick

A data brick.

 

value

Value to multiply data brick with.

 

Since: 2.31

gwy_brick_add ()

void
gwy_brick_add (GwyBrick *brick,
               gdouble value);

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

Parameters

brick

A data brick.

 

value

Value to be added.

 

Since: 2.31

gwy_brick_extract_plane ()

void
gwy_brick_extract_plane (const GwyBrick *brick,
                         GwyDataField *target,
                         gint istart,
                         gint jstart,
                         gint kstart,
                         gint width,
                         gint height,
                         gint depth,
                         gboolean keep_offsets);

Extracts a plane from a data brick.

One value of set (width , height , depth ) needs to be -1, determining the plane orientation.

Use gwy_brick_extract_xy_plane() to simply extract one entire XY plane.

Parameters

brick

A data brick.

 

target

Datafield to be filled by extracted plane. It will be resized if necessary.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

width

Pixel width of extracted plane. If width is -1, the yz plane will be extracted.

 

height

Pixel height of extracted plane. If height is -1, the xz plane will be extracted

 

depth

Pixel depth of extracted plane. If depth is -1, the xy plane will be extracted

 

keep_offsets

Keep the physical offsets in extracted field.

 

Since: 2.31

gwy_brick_extract_xy_plane ()

void
gwy_brick_extract_xy_plane (const GwyBrick *brick,
                            GwyDataField *target,
                            gint lev);

Extracts one full XY plane of a data brick to a data field.

Parameters

brick

A data brick.

 

target

Datafield to be filled by extracted plane. It will be resized if necessary.

 

lev

Position in the brick (level index).

 

Since: 2.52

gwy_brick_sum_plane ()

void
gwy_brick_sum_plane (const GwyBrick *brick,
                     GwyDataField *target,
                     gint istart,
                     gint jstart,
                     gint kstart,
                     gint width,
                     gint height,
                     gint depth,
                     gboolean keep_offsets);

Sums planes in certain direction

One value of set (width , height , depth ) needs to be -1, determining the plane orientation. In contrast to gwy_brick_extract_plane, the appropriate start coordinate (e.g. istart if width = -1) is not used for single plane extraction, but the planes are accumulated in whole range (0..xres for given example).

Parameters

brick

A data brick.

 

target

Datafield to be filled by summed plane. It will be resized if necessary.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

width

Pixel width of summed plane. If width is -1, the yz planes will be summed.

 

height

Pixel height of summed plane. If height is -1, the xz planes will be summed

 

depth

Pixel depth of summed plane. If depth is -1, the xy planes will be summed

 

keep_offsets

Keep the physical offsets in extracted field.

 

Since: 2.31

gwy_brick_sum_xy_plane ()

void
gwy_brick_sum_xy_plane (const GwyBrick *brick,
                        GwyDataField *target);

Sums all z-profiles of a data brick to a data field.

The result is an xy plane and can be alternatively imagined as the sum of all xy planes.

Parameters

brick

A data brick.

 

target

Datafield to be filled by the summary data. It will be resized if necessary.

 

Since: 2.52

gwy_brick_min_plane ()

void
gwy_brick_min_plane (const GwyBrick *brick,
                     GwyDataField *target,
                     gint istart,
                     gint jstart,
                     gint kstart,
                     gint width,
                     gint height,
                     gint depth,
                     gboolean keep_offsets);

Finds minima of profiles in certain direction.

One value of set (width , height , depth ) needs to be -1, determining the plane orientation. In contrast to gwy_brick_extract_plane, the appropriate start coordinate (e.g. istart if width = -1) is not used for single plane extraction, but the planes are accumulated in whole range (0..xres for given example).

Parameters

brick

A data brick.

 

target

Datafield to be filled by the minima plane. It will be resized if necessary.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

width

Pixel width of summarized plane. If width is -1, the yz planes will be summarized.

 

height

Pixel height of summarized plane. If height is -1, the xz planes will be summarized.

 

depth

Pixel depth of summarized plane. If depth is -1, the xy planes will be summarized

 

keep_offsets

Keep the physical offsets in extracted field.

 

Since: 2.32

gwy_brick_min_xy_plane ()

void
gwy_brick_min_xy_plane (const GwyBrick *brick,
                        GwyDataField *target);

Computes the minima along z-axis of a data brick to a data field.

The result is an xy plane.

Parameters

brick

A data brick.

 

target

Datafield to be filled by the summary data. It will be resized if necessary.

 

Since: 2.52

gwy_brick_max_plane ()

void
gwy_brick_max_plane (const GwyBrick *brick,
                     GwyDataField *target,
                     gint istart,
                     gint jstart,
                     gint kstart,
                     gint width,
                     gint height,
                     gint depth,
                     gboolean keep_offsets);

Finds minima of profiles in certain direction.

One value of set (width , height , depth ) needs to be -1, determining the plane orientation. In contrast to gwy_brick_extract_plane, the appropriate start coordinate (e.g. istart if width = -1) is not used for single plane extraction, but the planes are accumulated in whole range (0..xres for given example).

Parameters

brick

A data brick.

 

target

Datafield to be filled by the maxima plane. It will be resized if necessary.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

width

Pixel width of summarized plane. If width is -1, the yz planes will be summarized.

 

height

Pixel height of summarized plane. If height is -1, the xz planes will be summarized.

 

depth

Pixel depth of extracted plane. If depth is -1, the xy planes will be summarized

 

keep_offsets

Keep the physical offsets in extracted field.

 

Since: 2.32

gwy_brick_max_xy_plane ()

void
gwy_brick_max_xy_plane (const GwyBrick *brick,
                        GwyDataField *target);

Computes the maxima along z-axis of a data brick to a data field.

The result is an xy plane.

Parameters

brick

A data brick.

 

target

Datafield to be filled by the summary data. It will be resized if necessary.

 

Since: 2.52

gwy_brick_minpos_plane ()

void
gwy_brick_minpos_plane (const GwyBrick *brick,
                        GwyDataField *target,
                        gint istart,
                        gint jstart,
                        gint kstart,
                        gint width,
                        gint height,
                        gint depth,
                        gboolean keep_offsets);

Finds minima coordinates in profiles in certain direction.

One value of set (width , height , depth ) needs to be -1, determining the plane orientation. In contrast to gwy_brick_extract_plane, the appropriate start coordinate (e.g. istart if width = -1) is not used for single plane extraction, but the planes are accumulated in whole range (0..xres for given example)

Parameters

brick

A data brick.

 

target

Datafield to be filled by the minima positions plane. It will be resized if necessary.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

width

Pixel width of summarized plane. If width is -1, the yz planes will be summarized.

 

height

Pixel height of summarized plane. If height is -1, the xz planes will be summarized.

 

depth

Pixel depth of summarized plane. If depth is -1, the xy planes will be summarized

 

keep_offsets

Keep the physical offsets in summarized field.

 

Since: 2.32

gwy_brick_minpos_xy_plane ()

void
gwy_brick_minpos_xy_plane (const GwyBrick *brick,
                           GwyDataField *target);

Computes the location of minima along z-axis of a data brick to a data field.

The result is an xy plane.

Parameters

brick

A data brick.

 

target

Datafield to be filled by the summary data. It will be resized if necessary.

 

Since: 2.52

gwy_brick_maxpos_plane ()

void
gwy_brick_maxpos_plane (const GwyBrick *brick,
                        GwyDataField *target,
                        gint istart,
                        gint jstart,
                        gint kstart,
                        gint width,
                        gint height,
                        gint depth,
                        gboolean keep_offsets);

Finds maxima coordinates of profiles in certain direction.

One value of set (width , height , depth ) needs to be -1, determining the plane orientation. In contrast to gwy_brick_extract_plane, the appropriate start coordinate (e.g. istart if width = -1) is not used for single plane extraction, but the planes are accumulated in whole range (0..xres for given example).

Parameters

brick

A data brick.

 

target

Datafield to be filled by the maxima positions plane. It will be resized if necessary.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

width

Pixel width of summarized plane. If width is -1, the yz planes will be summarized.

 

height

Pixel height of summarized plane. If height is -1, the xz planes will be summarized

 

depth

Pixel depth of summarized plane. If depth is -1, the xy planes will be summarized

 

keep_offsets

Keep the physical offsets in summarized field. Not implemented.

 

Since: 2.32

gwy_brick_maxpos_xy_plane ()

void
gwy_brick_maxpos_xy_plane (const GwyBrick *brick,
                           GwyDataField *target);

Computes the location of maxima along z-axis of a data brick to a data field.

The result is an xy plane.

Parameters

brick

A data brick.

 

target

Datafield to be filled by the summary data. It will be resized if necessary.

 

Since: 2.52

gwy_brick_mean_plane ()

void
gwy_brick_mean_plane (const GwyBrick *brick,
                      GwyDataField *target,
                      gint istart,
                      gint jstart,
                      gint kstart,
                      gint width,
                      gint height,
                      gint depth,
                      gboolean keep_offsets);

Finds mean of planes in certain direction.

One value of set (width , height , depth ) needs to be -1, determining the plane orientation. In contrast to gwy_brick_extract_plane, the appropriate start coordinate (e.g. istart if width = -1) is not used for single plane extraction, but the planes are accumulated in whole range (0..xres for given example).

Parameters

brick

A data brick.

 

target

Datafield to be filled by the mean plane. It will be resized if necessary.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

width

Pixel width of summarized plane. If width is -1, the yz planes will be summarized.

 

height

Pixel height of summarized plane. If height is -1, the xz planes will be summarized.

 

depth

Pixel depth of summarized plane. If depth is -1, the xy planes will be summarized.

 

keep_offsets

Keep the physical offsets in summarized field.

 

Since: 2.32

gwy_brick_mean_xy_plane ()

void
gwy_brick_mean_xy_plane (const GwyBrick *brick,
                         GwyDataField *target);

Calculates mean values of all z-profiles of a data brick to a data field.

The result is an xy plane and can be alternatively imagined as the average of all xy planes.

Parameters

brick

A data brick.

 

target

Datafield to be filled by the summary data. It will be resized if necessary.

 

Since: 2.52

gwy_brick_rms_plane ()

void
gwy_brick_rms_plane (const GwyBrick *brick,
                     GwyDataField *target,
                     gint istart,
                     gint jstart,
                     gint kstart,
                     gint width,
                     gint height,
                     gint depth,
                     gboolean keep_offsets);

Finds rms of planes in certain direction and extract the result (GwyDataField). One value of set (width , height , depth ) needs to be -1, determining the plane orientation. In contrast to gwy_brick_extract_plane, the appropriate start coordinate (e.g. istart if width = -1) is not used for single plane extraction, but the planes are accumulated in whole range (0..xres for given example)

Parameters

brick

A data brick.

 

target

Datafield to be filled by the rms plane. It will be resized if necessary.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

width

Pixel width of summarized plane. If width is -1, the yz planes will be summarized.

 

height

Pixel height of summarized plane. If height is -1, the xz planes will be summarized.

 

depth

Pixel depth of summarized plane. If depth is -1, the xy planes will be summarized.

 

keep_offsets

Keep the physical offsets in extracted field.

 

Since: 2.32

gwy_brick_rms_xy_plane ()

void
gwy_brick_rms_xy_plane (const GwyBrick *brick,
                        GwyDataField *target);

Calculates rms values of all z-profiles of a data brick to a data field.

The result is an xy plane and can be alternatively imagined as the variation among xy planes.

Parameters

brick

A data brick.

 

target

Datafield to be filled by the summary data. It will be resized if necessary.

 

Since: 2.52

gwy_brick_extract_line ()

void
gwy_brick_extract_line (const GwyBrick *brick,
                        GwyDataLine *target,
                        gint istart,
                        gint jstart,
                        gint kstart,
                        gint iend,
                        gint jend,
                        gint kend,
                        gboolean keep_offsets);

Extracts a line (GwyDataLine) from the brick.

Only line orientations parallel to coordinate axes are supported now, i.e. two of the start coordinates need to be same as end ones.

Parameters

brick

A data brick.

 

target

Dataline to be filled by extracted line. It will be resized if necessary.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

iend

Column where to end, exclusive (pixel coordinates).

 

jend

Row where to end, exclusive (pixel coordinates).

 

kend

Level where to end, exclusive (pixel coordinates).

 

keep_offsets

Keep physical offsets in extracted line.

 

Since: 2.31

gwy_brick_extract_z_line ()

void
gwy_brick_extract_z_line (const GwyBrick *brick,
                          GwyDataLine *target,
                          gint i,
                          gint j);

Extracts one full Z profile of a data brick to a data line.

Parameters

brick

A data brick.

 

target

Dataline to be filled by extracted line. It will be resized if necessary.

 

i

Column index.

 

j

Row index.

 

Since: 2.52

gwy_brick_get_zcalibration ()

GwyDataLine *
gwy_brick_get_zcalibration (const GwyBrick *brick);

Gets the z-axis non-linear calibration of a data brick.

Parameters

brick

A data brick.

 

Returns

Z Calibration (non-linear Z-axis values as ordinates).

Since: 2.32

gwy_brick_set_zcalibration ()

void
gwy_brick_set_zcalibration (GwyBrick *brick,
                            GwyDataLine *calibration);

Sets the z-axis non-linear calibration of a data brick.

Parameters

brick

A data brick.

 

calibration

GwyDataLine pointer with z-axis non-linear calibration of a data brick (values are stored as ordinates). It can also be NULL to unset the calibration.

 

Since: 2.32

gwy_brick_copy_zcalibration ()

void
gwy_brick_copy_zcalibration (const GwyBrick *brick,
                             GwyBrick *target);

Copies non-linear z-axis calibration between two data bricks.

Both bricks must have the same Z resolution. For a meaningful usage, they should also have the same Z real sizes and units (uncalibrated).

If brick has no z-axis calibration, existing targets ' calibration is deleted.

Parameters

brick

A data brick.

 

target

Target data brick.

 

Since: 2.52

gwy_brick_transpose ()

void
gwy_brick_transpose (GwyBrick *brick,
                     GwyBrick *target,
                     GwyBrickTransposeType type,
                     gboolean xflipped,
                     gboolean yflipped,
                     gboolean zflipped);

Transposes a data brick, exchanging and/or flipping axes.

Real dimensions and units are updated. Since real sizes cannot go backward, flipping an axis results in the corresponding offset being reset (the real dimension stays positive). If the Z axis is preserved its calibration is copied to the target; otherwise the target will have no Z axis calibration.

Parameters

brick

A data brick.

 

target

Destination data brick. It will be resized as needed.

 

type

Basic transposition type (which axes are swapped).

 

xflipped

New X axis will be inverted.

 

yflipped

New Y axis will be inverted.

 

zflipped

New Z axis will be inverted.

 

Since: 2.51

gwy_brick_set_plane ()

void
gwy_brick_set_plane (GwyBrick *brick,
                     GwyDataField *plane,
                     gint istart,
                     gint jstart,
                     gint kstart,
                     gint width,
                     gint height,
                     gint depth);

Fill a single plane in the brick by a two-dimensional data (GwyDataField).

One value of set (width , height , depth ) needs to be -1, determining the plane orientation.

Parameters

brick

A data brick.

 

plane

Datafield to be inserted into brick. It must have the appropriate size.

 

istart

Column where to start (pixel coordinates).

 

jstart

Row where to start (pixel coordinates).

 

kstart

Level where to start (pixel coordinates).

 

width

Pixel width of the inserted plane. If width is -1, the yz plane will be filled.

 

height

Pixel height of insered plane. If height is -1, the xz plane will be filled.

 

depth

Pixel depth of inserted plane. If depth is -1, the xy plane will be filled.

 

Since: 2.51

gwy_brick_set_xy_plane ()

void
gwy_brick_set_xy_plane (GwyBrick *brick,
                        GwyDataField *plane,
                        gint lev);

Sets one full single XY plane in a data brick from data field values.

Parameters

brick

A data brick.

 

plane

Datafield to be inserted into brick. It must have dimensions xres by yres .

 

lev

Position in the brick (level index).

 

Since: 2.52

gwy_brick_add_to_xy_planes ()

void
gwy_brick_add_to_xy_planes (GwyBrick *brick,
                            GwyDataField *plane);

Adds a data field to all brick XY planes.

Parameters

brick

A data brick.

 

plane

Datafield to be added to all brick XY planes. It must have dimensions xres by yres .

 

Since: 2.55

gwy_brick_add_to_z_lines ()

void
gwy_brick_add_to_z_lines (GwyBrick *brick,
                          GwyDataLine *line);

Adds a data line to all brick Z lines.

Parameters

brick

A data brick.

 

line

Data line to add to each Z lines. It must have dimension zres .

 

Since: 2.55

Types and Values

GwyBrickPart

typedef struct {
    guint col;
    guint row;
    guint level;
    guint width;
    guint height;
    guint depth;
} GwyBrickPart;

struct GwyBrick

struct GwyBrick;

The GwyBrick struct contains private data only and should be accessed using the functions below.

Since: 2.31

struct GwyBrickClass

struct GwyBrickClass {
    GObjectClass parent_class;

    void (*data_changed)(GwyBrick *brick);
};

Signal Details

The “data-changed” signal

void
user_function (GwyBrick *gwydataline,
               gpointer  user_data)

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

Parameters

gwydataline

The GwyBrick which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS