Arithmetic: Gwyddion Library Reference Manual

## Arithmetic Arithmetic — Arithmetic operations with data |

## Functions

void | gwy_line_sum_lines ()
void | gwy_line_subtract_lines ()
void | gwy_line_multiply_lines ()
void | gwy_line_linear_combination ()
void | gwy_field_sum_fields ()
void | gwy_field_subtract_fields ()
void | gwy_field_divide_fields ()
void | gwy_field_multiply_fields ()
void | gwy_field_min_of_fields ()
void | gwy_field_max_of_fields ()
void | gwy_field_hypot_of_fields ()
void | gwy_field_linear_combination ()
GwyDataMismatchFlags | gwy_line_is_incompatible ()
GwyDataMismatchFlags | gwy_field_is_incompatible ()
GwyDataMismatchFlags | gwy_nield_is_incompatible ()
GwyDataMismatchFlags | gwy_brick_is_incompatible ()
GwyDataMismatchFlags | gwy_scatter_is_incompatible ()
GwyDataMismatchFlags | gwy_lawn_is_incompatible ()
GwyDataMismatchFlags | gwy_field_is_incompatible_with_brick_xy ()
GwyDataMismatchFlags | gwy_line_is_incompatible_with_brick_z ()
GwyDataMismatchFlags | gwy_field_is_incompatible_with_lawn ()
GwyDataMismatchFlags | gwy_nield_is_incompatible_with_field ()
GwyDataMismatchFlags | gwy_nield_is_incompatible_with_brick_xy ()
GwyDataMismatchFlags | gwy_nield_is_incompatible_with_lawn ()

## Types and Values

enum | GwyDataMismatchFlags

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

Data arithmetic functions perform simple operations combining several data fields. Their sizes have to be size-compatible, i.e. gwy_field_is_incompatible(operand1, operand2, GWY_DATA_MISMATCH_RES) must pass and the same must hold for the data field to store the result to.

Functions `gwy_field_is_incompatible()`, `gwy_line_check_compatibility()` and `gwy_brick_is_incompatible()` simplify testing compatibility of data fields, lines and bricks, respectively.

## Functions

### gwy_line_sum_lines()

    void
    gwy_line_sum_lines (GwyLine *result,
                        GwyLine *operand1,
                        GwyLine *operand2);

Sums two data lines.

The result and either operand (or both of them) can be the same line.

#### Parameters

result | A data line to put the result to. |
operand1 | First data line operand (summand). |
operand2 | Second data line operand (summand). |

### gwy_line_subtract_lines()

    void
    gwy_line_subtract_lines (GwyLine *result,
                             GwyLine *operand1,
                             GwyLine *operand2);

Subtracts two data lines.

The result and either operand (or both of them) can be the same line.

#### Parameters

result | A data line to put the result to. |
operand1 | First data line operand (minuend). |
operand2 | Second data line operand (subtrahend). |

### gwy_line_multiply_lines()

    void
    gwy_line_multiply_lines (GwyLine *result,
                             GwyLine *operand1,
                             GwyLine *operand2);

Multiplies two data lines.

The result and either operand (or both of them) can be the same line.

#### Parameters

result | A data line to put the result to. |
operand1 | First data line operand (factor). |
operand2 | Second data line operand (factor). |

### gwy_line_linear_combination()

    void
    gwy_line_linear_combination (GwyLine *result,
                                 gdouble coeff1,
                                 GwyLine *operand1,
                                 gdouble coeff2,
                                 GwyLine *operand2,
                                 gdouble constant);

Computes point-wise general linear combination of two data lines.

The result is formally `coeff1` ×`operand1` + `coeff2` ×`operand2` + `constant` .

The result and either operand (or both of them) can be the same line.

#### Parameters

result | A data line to put the result to. |
constant | Constant term to add to the result. |
operand1 | First data line operand. |
coeff1 | Factor to multiply the first operand with. |
operand2 | Second data line operand. |
coeff2 | Factor to multiply the second operand with. |

### gwy_field_sum_fields()

    void
    gwy_field_sum_fields (GwyField *result,
                          GwyField *operand1,
                          GwyField *operand2);

Sums two data fields.

The result and either operand (or both of them) can be the same field.

#### Parameters

result | A data field to put the result to. |
operand1 | First data field operand (summand). |
operand2 | Second data field operand (summand). |

### gwy_field_subtract_fields()

    void
    gwy_field_subtract_fields (GwyField *result,
                               GwyField *operand1,
                               GwyField *operand2);

Subtracts one data field from another.

The result and either operand (or both of them) can be the same field.

#### Parameters

result | A data field to put the result to. |
operand1 | First data field operand (minuend). |
operand2 | Second data field operand (subtrahend). |

### gwy_field_divide_fields()

    void
    gwy_field_divide_fields (GwyField *result,
                             GwyField *operand1,
                             GwyField *operand2);

Divides one data field with another.

The result and either operand (or both of them) can be the same field.

#### Parameters

result | A data field to put the result to. |
operand1 | First data field operand (dividend). |
operand2 | Second data field operand (divisor). |

### gwy_field_multiply_fields()

    void
    gwy_field_multiply_fields (GwyField *result,
                               GwyField *operand1,
                               GwyField *operand2);

Multiplies two data fields.

The result and either operand (or both of them) can be the same field.

#### Parameters

result | A data field to put the result to. |
operand1 | First data field operand (factor). |
operand2 | Second data field operand (factor). |

### gwy_field_min_of_fields()

    void
    gwy_field_min_of_fields (GwyField *result,
                             GwyField *operand1,
                             GwyField *operand2);

Finds point-wise maxima of two data fields.

The result and either operand (or both of them) can be the same field.

#### Parameters

result | A data field to put the result to. |
operand1 | First data field operand. |
operand2 | Second data field operand. |

### gwy_field_max_of_fields()

    void
    gwy_field_max_of_fields (GwyField *result,
                             GwyField *operand1,
                             GwyField *operand2);

Finds point-wise minima of two data fields.

The result and either operand (or both of them) can be the same field.

#### Parameters

result | A data field to put the result to. |
operand1 | First data field operand. |
operand2 | Second data field operand. |

### gwy_field_hypot_of_fields()

    void
    gwy_field_hypot_of_fields (GwyField *result,
                               GwyField *operand1,
                               GwyField *operand2);

Finds point-wise hypotenuse of two data fields.

The result and either operand (or both of them) can be the same field.

#### Parameters

result | A data field to put the result to. |
operand1 | First data field operand. |
operand2 | Second data field operand. |

### gwy_field_linear_combination()

    void
    gwy_field_linear_combination (GwyField *result,
                                  gdouble coeff1,
                                  GwyField *operand1,
                                  gdouble coeff2,
                                  GwyField *operand2,
                                  gdouble constant);

Computes point-wise general linear combination of two data fields.

The result is formally `coeff1` ×`operand1` + `coeff2` ×`operand2` + `constant` .

The result and either operand (or both of them) can be the same field.

#### Parameters

result | A data field to put the result to. |
constant | Constant term to add to the result. |
operand1 | First data field operand. |
coeff1 | Factor to multiply the first operand with. |
operand2 | Second data field operand. |
coeff2 | Factor to multiply the second operand with. |

### gwy_line_is_incompatible()

    GwyDataMismatchFlags
    gwy_line_is_incompatible (GwyLine *line1,
                              GwyLine *line2,
                              GwyDataMismatchFlags check);

Checks whether two data lines are compatible.

#### Parameters

line1 | A data line. |
line2 | Another data line. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if data lines are not compatible in some of the tested aspects.

### gwy_field_is_incompatible()

    GwyDataMismatchFlags
    gwy_field_is_incompatible (GwyField *field1,
                               GwyField *field2,
                               GwyDataMismatchFlags check);

Checks whether two data fields are compatible.

#### Parameters

field1 | A data field. |
field2 | Another data field. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if data fields are not compatible in some of the tested aspects.

### gwy_nield_is_incompatible()

    GwyDataMismatchFlags
    gwy_nield_is_incompatible (GwyNield *nield1,
                               GwyNield *nield2,
                               GwyDataMismatchFlags check);

Checks whether two number fields are compatible.

#### Parameters

nield1 | A number field. |
nield2 | Another number field. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if number fields are not compatible in some of the tested aspects.

### gwy_brick_is_incompatible()

    GwyDataMismatchFlags
    gwy_brick_is_incompatible (GwyBrick *brick1,
                               GwyBrick *brick2,
                               GwyDataMismatchFlags check);

Checks whether two data bricks are compatible.

Real dimensions are checked without regard to calibration. Calibrations are considered compatible if either both exist and are identical or none exists.

#### Parameters

brick1 | A data brick. |
brick2 | Another data brick. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if bricks are not compatible in some of the tested aspects.

### gwy_scatter_is_incompatible()

    GwyDataMismatchFlags
    gwy_scatter_is_incompatible (GwyScatter *scatter1,
                                 GwyScatter *scatter2,
                                 GwyDataMismatchFlags check);

Checks whether two scattered data are compatible.

Scattered data do not have pixels, so the only meaningful tests are for units, `GWY_DATA_MISMATCH_POINTS` for matching XY coordinate sets and `GWY_DATA_MISMATCH_NCURVES` to check if the number of values is the same. The last is is barely meaningful -- if you check for data units, it already implies the same number of values.

#### Parameters

scatter1 | A scattered data. |
scatter2 | Another scattered data. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if scattered data are not compatible in some of the tested aspects.

### gwy_lawn_is_incompatible()

    GwyDataMismatchFlags
    gwy_lawn_is_incompatible (GwyLawn *lawn1,
                              GwyLawn *lawn2,
                              GwyDataMismatchFlags check);

Checks whether two data lawns are compatible.

Dimensions are checked only in the plane. To check if the curve lengths match, use the `GWY_DATA_MISMATCH_CURVELEN` flag. Use `GWY_DATA_MISMATCH_NCURVES` to check if the two lawns have the same number of curves.

#### Parameters

lawn1 | A data lawn. |
lawn2 | Another data lawn. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if curve maps are not compatible in some of the tested aspects.

### gwy_field_is_incompatible_with_brick_xy()

    GwyDataMismatchFlags
    gwy_field_is_incompatible_with_brick_xy
                                   (GwyField *field,
                                    GwyBrick *brick,
                                    GwyDataMismatchFlags check);

Checks whether a data field is compatible with brick XY-planes.

#### Parameters

field | A two-dimensional data field. |
brick | A three-dimensional data brick. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if the data objects are not compatible in some of the tested aspects.

### gwy_line_is_incompatible_with_brick_z()

    GwyDataMismatchFlags
    gwy_line_is_incompatible_with_brick_z (GwyLine *line,
                                           GwyBrick *brick,
                                           GwyDataMismatchFlags check);

Checks whether a data line is compatible with brick Z-profiles.

If `check` includes `GWY_DATA_MISMATCH_REAL` or `GWY_DATA_MISMATCH_LATERAL` but not `GWY_DATA_MISMATCH_AXISCAL`, `line` is simply compared to `brick` in the Z direction.

If you include `GWY_DATA_MISMATCH_AXISCAL` and `brick` has a Z-calibration data line, then the value range and units of this data line are compared to `line` . This may not be very useful.

#### Parameters

line | A one-dimensional data line. |
brick | A three-dimensional data brick. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if the data objects are not compatible in some of the tested aspects.

### gwy_field_is_incompatible_with_lawn()

    GwyDataMismatchFlags
    gwy_field_is_incompatible_with_lawn (GwyField *field,
                                         GwyLawn *lawn,
                                         GwyDataMismatchFlags check);

Checks whether a data field is compatible with lawn in the XY-plane.

Field value units are not compared to curves. Value-related flags are invalid in `check` .

#### Parameters

field | A two-dimensional data field. |
lawn | A lawn curve map object. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if the data objects are not compatible in some of the tested aspects.

### gwy_nield_is_incompatible_with_field()

    GwyDataMismatchFlags
    gwy_nield_is_incompatible_with_field (GwyNield *nield,
                                          GwyField *field,
                                          GwyDataMismatchFlags check);

Checks whether a number field is compatible with a data field.

Since a GwyNield does not have real dimensions and units, only pixel resolutions make sense to check.

#### Parameters

nield | A two-dimensional number field. |
field | A two-dimensional data field. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if the data objects are not compatible in some of the tested aspects.

### gwy_nield_is_incompatible_with_brick_xy()

    GwyDataMismatchFlags
    gwy_nield_is_incompatible_with_brick_xy
                                   (GwyNield *nield,
                                    GwyBrick *brick,
                                    GwyDataMismatchFlags check);

Checks whether a number field is compatible with brick XY-planes.

Since a GwyNield does not have real dimensions and units, only pixel resolutions make sense to check.

#### Parameters

nield | A two-dimensional number field. |
brick | A three-dimensional data brick. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if the data objects are not compatible in some of the tested aspects.

### gwy_nield_is_incompatible_with_lawn()

    GwyDataMismatchFlags
    gwy_nield_is_incompatible_with_lawn (GwyNield *nield,
                                         GwyLawn *lawn,
                                         GwyDataMismatchFlags check);

Checks whether a number field is compatible with lawn in the XY-plane.

Since a GwyNield does not have real dimensions and units, only pixel resolutions make sense to check.

#### Parameters

nield | A two-dimensional number field. |
lawn | A lawn curve map object. |
check | The compatibility tests to perform. |

#### Returns

Zero if all tested properties are compatible. Flags corresponding to failed tests if the data objects are not compatible in some of the tested aspects.

## Types and Values

### enum GwyDataMismatchFlags

Compatibility flags for data objects, such as lines, fields, bricks or lawns.

The flag set defines all possible incompatibilities that can be checked. However, for every object only a subset is meaningful: images have pixes but do not have curve lengths, scattered data have lateral units but do not have pixels, etc.

#### Members

GWY_DATA_MISMATCH_RES | Pixel sizes. |
GWY_DATA_MISMATCH_REAL | Real (physical) dimensions. |
GWY_DATA_MISMATCH_MEASURE | Real to pixel ratios. |
GWY_DATA_MISMATCH_LATERAL | Units of lateral dimensions. |
GWY_DATA_MISMATCH_VALUE | Units of values (for all curves in the case of lawns). |
GWY_DATA_MISMATCH_AXISCAL | Axis calibrations. At present it only makes sense for GwyBrick which can have Z-calibrations. |
GWY_DATA_MISMATCH_NCURVES | The number of lawn curves. |
GWY_DATA_MISMATCH_CURVELEN | Lengths of curves in all lawn pixels. |
GWY_DATA_MISMATCH_POINTS | Abscissa points or coordinates for irregular data (e.g. GwyScatter). |