GwyCalData: Gwyddion Data Processing Library Reference Manual

## GwyCalData GwyCalData — General calibration data |

## Functions

#define | gwy_caldata_duplicate()
GwyCalData * | gwy_caldata_new ()
void | gwy_caldata_resize ()
void | gwy_caldata_append ()
gint | gwy_caldata_get_ndata ()
gdouble * | gwy_caldata_get_x ()
gdouble * | gwy_caldata_get_y ()
gdouble * | gwy_caldata_get_z ()
gdouble * | gwy_caldata_get_xerr ()
gdouble * | gwy_caldata_get_yerr ()
gdouble * | gwy_caldata_get_zerr ()
gdouble * | gwy_caldata_get_xunc ()
gdouble * | gwy_caldata_get_yunc ()
gdouble * | gwy_caldata_get_zunc ()
void | gwy_caldata_get_range ()
void | gwy_caldata_set_range ()
GwySIUnit * | gwy_caldata_get_si_unit_x ()
GwySIUnit * | gwy_caldata_get_si_unit_y ()
GwySIUnit * | gwy_caldata_get_si_unit_z ()
void | gwy_caldata_set_si_unit_x ()
void | gwy_caldata_set_si_unit_y ()
void | gwy_caldata_set_si_unit_z ()
void | gwy_caldata_setup_interpolation ()
void | gwy_caldata_interpolate ()
void | gwy_caldata_save_data ()
gboolean | gwy_caldata_inside ()

## Types and Values

| GwyCurveCalibrationData
| GwyCalData
| GwyCalDataClass

## Object Hierarchy

        GObject
        ╰── GwyCalData

## Implemented Interfaces

GwyCalData implements GwySerializable.

## Includes

    #include <libprocess/gwyprocess.h>

## Description

GwyCalData is an object representing general calibration data of a SPM system. Any point in the volume that can be reached by SPM scanner can be characterized by two vectors: error and uncertainty. Errors can be used for further data correction, uncertainties for propagation and determination of final uncertainty of results of direct measurements or statistical functions. Using different strategies a different number of these local calibration data can be obtained, starting from single uncertainty applied for whole system up to complex determination of local SPM errors and uncertainties.

## Functions

### gwy_caldata_duplicate()

    #define             gwy_caldata_duplicate(caldata)

### gwy_caldata_new ()

    GwyCalData *
    gwy_caldata_new (gint ndata);

Creates new calibration data.

#### Parameters

ndata | Number of calibration data |

#### Returns

A newly created calibration data.

### gwy_caldata_resize ()

    void
    gwy_caldata_resize (GwyCalData *caldata,
                        gint ndata);

Sets number of calibration data entries, resizing arrays for holding them.

Preserves actual values up to new calibration data size.

#### Parameters

caldata | Calibration data |
ndata | New number of data points |

### gwy_caldata_append ()

    void
    gwy_caldata_append (GwyCalData *caldata,
                        GwyCalData *sec);

Appends calibration data entries, resizing arrays for holding them.

#### Parameters

caldata | Calibration data |
sec | Calibration data to be appended |

Since: 2.23

### gwy_caldata_get_ndata ()

    gint
    gwy_caldata_get_ndata (GwyCalData *caldata);

Gets the number of calibration data entries.

#### Parameters

caldata | Calibration data |

#### Returns

Number of calibration data entries.

Since: 2.23

### gwy_caldata_get_x ()

    gdouble *
    gwy_caldata_get_x (GwyCalData *caldata);

Gets the Y data for calibration data.

#### Parameters

caldata | Calibration data. |

#### Returns

x array pointer for given calibration data.

Since: 2.23

### gwy_caldata_get_y ()

    gdouble *
    gwy_caldata_get_y (GwyCalData *caldata);

Gets the Y data for calibration data.

#### Parameters

caldata | Calibration data. |

#### Returns

y array pointer for given calibration data.

Since: 2.23

### gwy_caldata_get_z ()

    gdouble *
    gwy_caldata_get_z (GwyCalData *caldata);

Gets the Z data for calibration data.

#### Parameters

caldata | Calibration data. |

#### Returns

z array pointer for given calibration data.

Since: 2.23

### gwy_caldata_get_xerr ()

    gdouble *
    gwy_caldata_get_xerr (GwyCalData *caldata);

Gets the X error data for calibration data.

#### Parameters

caldata | Calibration data. |

#### Returns

x error array pointer for given calibration data.

Since: 2.23

### gwy_caldata_get_yerr ()

    gdouble *
    gwy_caldata_get_yerr (GwyCalData *caldata);

Gets the Y error data for calibration data.

#### Parameters

caldata | Calibration data. |

#### Returns

y error array pointer for given calibration data.

Since: 2.23

### gwy_caldata_get_zerr ()

    gdouble *
    gwy_caldata_get_zerr (GwyCalData *caldata);

Gets the Z error data for calibration data.

#### Parameters

caldata | Calibration data. |

#### Returns

z error array pointer for given calibration data.

Since: 2.23

### gwy_caldata_get_xunc ()

    gdouble *
    gwy_caldata_get_xunc (GwyCalData *caldata);

Gets the X uncertainty data for calibration data.

#### Parameters

caldata | Calibration data. |

#### Returns

x uncertainty array pointer for given calibration data.

Since: 2.23

### gwy_caldata_get_yunc ()

    gdouble *
    gwy_caldata_get_yunc (GwyCalData *caldata);

Gets the Y uncertainty data for calibration data.

#### Parameters

caldata | Calibration data. |

#### Returns

y uncertainty array pointer for given calibration data.

Since: 2.23

### gwy_caldata_get_zunc ()

    gdouble *
    gwy_caldata_get_zunc (GwyCalData *caldata);

Gets the Z uncertainty data for calibration data.

#### Parameters

caldata | Calibration data. |

#### Returns

z uncertainty array pointer for given calibration data.

Since: 2.23

### gwy_caldata_get_range ()

    void
    gwy_caldata_get_range (GwyCalData *caldata,
                           gdouble *xfrom,
                           gdouble *xto,
                           gdouble *yfrom,
                           gdouble *yto,
                           gdouble *zfrom,
                           gdouble *zto);

Obtains boundaries of calibration data validity.

#### Parameters

caldata | Calibration data. |
xfrom | x minimum |
xto | x maximum |
yfrom | y minimum |
yto | y maximum |
zfrom | z minimum |
zto | z maximum |

Since: 2.23

### gwy_caldata_set_range ()

    void
    gwy_caldata_set_range (GwyCalData *caldata,
                           gdouble xfrom,
                           gdouble xto,
                           gdouble yfrom,
                           gdouble yto,
                           gdouble zfrom,
                           gdouble zto);

Sets boundaries of calibration data validity.

#### Parameters

caldata | Calibration data. |
xfrom | x minimum |
xto | x maximum |
yfrom | y minimum |
yto | y maximum |
zfrom | z minimum |
zto | z maximum |

Since: 2.23

### gwy_caldata_get_si_unit_x ()

    GwySIUnit *
    gwy_caldata_get_si_unit_x (GwyCalData *caldata);

Returns lateral SI unit of calibration data.

#### Parameters

caldata | Calibration data |

#### Returns

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

Since: 2.23

### gwy_caldata_get_si_unit_y ()

    GwySIUnit *
    gwy_caldata_get_si_unit_y (GwyCalData *caldata);

Returns lateral SI unit of calibration data

#### Parameters

caldata | Calibration data. |

#### Returns

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

Since: 2.23

### gwy_caldata_get_si_unit_z ()

    GwySIUnit *
    gwy_caldata_get_si_unit_z (GwyCalData *caldata);

Returns value SI unit of calibration data

#### Parameters

caldata | Calibration data. |

#### Returns

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

Since: 2.23

### gwy_caldata_set_si_unit_x ()

    void
    gwy_caldata_set_si_unit_x (GwyCalData *caldata,
                               GwySIUnit *si_unit);

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

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

#### Parameters

caldata | Calibration data. |
si_unit | SI unit to be set. |

Since: 2.23

### gwy_caldata_set_si_unit_y ()

    void
    gwy_caldata_set_si_unit_y (GwyCalData *caldata,
                               GwySIUnit *si_unit);

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

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

#### Parameters

caldata | Calibration data. |
si_unit | SI unit to be set. |

Since: 2.23

### gwy_caldata_set_si_unit_z ()

    void
    gwy_caldata_set_si_unit_z (GwyCalData *caldata,
                               GwySIUnit *si_unit);

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

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

#### Parameters

caldata | Calibration data. |
si_unit | SI unit to be set. |

Since: 2.23

### gwy_caldata_setup_interpolation ()

    void
    gwy_caldata_setup_interpolation (GwyCalData *caldata);

Prepares data for interpolating the calibration data (building Delaunay triangulation, etc.).

#### Parameters

caldata | Calibration data. |

Since: 2.23

### gwy_caldata_interpolate ()

    void
    gwy_caldata_interpolate (GwyCalData *caldata,
                             gdouble x,
                             gdouble y,
                             gdouble z,
                             gdouble *xerr,
                             gdouble *yerr,
                             gdouble *zerr,
                             gdouble *xunc,
                             gdouble *yunc,
                             gdouble *zunc);

Determines (interpolates) caldata parameters for given position.

#### Parameters

caldata | Calibration data. |
x | x coordinate of requested position |
y | y coordinate of requested position |
z | z coordinate of requested position |
xerr | x error at given position |
yerr | y error at given position |
zerr | z error at given position |
xunc | x uncertainty at given position |
yunc | y uncertainty at given position |
zunc | z uncertainty at given position |

Since: 2.23

### gwy_caldata_save_data ()

    void
    gwy_caldata_save_data (GwyCalData *caldata,
                           gchar *filename);

Saves calibration data to Gwyddion's caldata resource directory.

#### Parameters

caldata | Calibration data. |
filename | Name of file to save the data to. |

Since: 2.23

### gwy_caldata_inside ()

    gboolean
    gwy_caldata_inside (GwyCalData *caldata,
                        gdouble x,
                        gdouble y,
                        gdouble z);

Tests whether a point is inside calibration data range.

#### Parameters

caldata | Calibration data. |
x | x position |
y | y position |
z | z position |

#### Returns

`TRUE` if xyz position is inside calibration data range.

Since: 2.23

## Types and Values

### GwyCurveCalibrationData

    typedef struct {
        gdouble *xerr;
        gdouble *yerr;
        gdouble *zerr;
        gdouble *xunc;
        gdouble *yunc;
        gdouble *zunc;
        gint n;
    } GwyCurveCalibrationData;

### GwyCalData

    typedef struct _GwyCalData GwyCalData;

### GwyCalDataClass

    typedef struct _GwyCalDataClass GwyCalDataClass;