arithmetic: Gwyddion Data Processing Library Reference Manual

## arithmetic arithmetic — Arithmetic opetations on data fields |

## Functions

void | gwy_data_field_sum_fields ()
void | gwy_data_field_subtract_fields ()
void | gwy_data_field_divide_fields ()
void | gwy_data_field_multiply_fields ()
void | gwy_data_field_min_of_fields ()
void | gwy_data_field_max_of_fields ()
void | gwy_data_field_hypot_of_fields ()
void | gwy_data_field_linear_combination ()
GwyDataCompatibilityFlags | gwy_data_field_check_compatibility ()
GwyDataCompatibilityFlags | gwy_data_line_check_compatibility ()
GwyDataCompatibilityFlags | gwy_brick_check_compatibility ()
GwyDataCompatibilityFlags | gwy_lawn_check_compatibility ()
GwyDataCompatibilityFlags | gwy_data_field_check_compatibility_with_brick_xy ()
GwyDataCompatibilityFlags | gwy_data_line_check_compatibility_with_brick_z ()
GwyDataCompatibilityFlags | gwy_data_field_check_compatibility_with_lawn ()
GwyDataField * | gwy_data_field_extend ()

## Includes

    #include <libprocess/gwyprocess.h>

## Description

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

Functions `gwy_data_field_check_compatibility()`, `gwy_data_line_check_compatibility()` and `gwy_brick_check_compatibility()` simplify testing compatibility of data fields, lines and bricks, respectively.

## Functions

### gwy_data_field_sum_fields ()

    void
    gwy_data_field_sum_fields (GwyDataField *result,
                               GwyDataField *operand1,
                               GwyDataField *operand2);

Sums two data fields.

#### Parameters

result | A data field to put the result to. May be one of `operand1` , `operand2` . |
operand1 | First data field operand. |
operand2 | Second data field operand. |

### gwy_data_field_subtract_fields ()

    void
    gwy_data_field_subtract_fields (GwyDataField *result,
                                    GwyDataField *operand1,
                                    GwyDataField *operand2);

Subtracts one data field from another.

#### Parameters

result | A data field to put the result to. May be one of `operand1` , `operand2` . |
operand1 | First data field operand. |
operand2 | Second data field operand. |

### gwy_data_field_divide_fields ()

    void
    gwy_data_field_divide_fields (GwyDataField *result,
                                  GwyDataField *operand1,
                                  GwyDataField *operand2);

Divides one data field with another.

#### Parameters

result | A data field to put the result to. May be one of `operand1` , `operand2` . |
operand1 | First data field operand. |
operand2 | Second data field operand. |

### gwy_data_field_multiply_fields ()

    void
    gwy_data_field_multiply_fields (GwyDataField *result,
                                    GwyDataField *operand1,
                                    GwyDataField *operand2);

Multiplies two data fields.

#### Parameters

result | A data field to put the result to. May be one of `operand1` , `operand2` . |
operand1 | First data field operand. |
operand2 | Second data field operand. |

### gwy_data_field_min_of_fields ()

    void
    gwy_data_field_min_of_fields (GwyDataField *result,
                                  GwyDataField *operand1,
                                  GwyDataField *operand2);

Finds point-wise maxima of two data fields.

#### Parameters

result | A data field to put the result to. May be one of `operand1` , `operand2` . |
operand1 | First data field operand. |
operand2 | Second data field operand. |

### gwy_data_field_max_of_fields ()

    void
    gwy_data_field_max_of_fields (GwyDataField *result,
                                  GwyDataField *operand1,
                                  GwyDataField *operand2);

Finds point-wise minima of two data fields.

#### Parameters

result | A data field to put the result to. May be one of `operand1` , `operand2` . |
operand1 | First data field operand. |
operand2 | Second data field operand. |

### gwy_data_field_hypot_of_fields ()

    void
    gwy_data_field_hypot_of_fields (GwyDataField *result,
                                    GwyDataField *operand1,
                                    GwyDataField *operand2);

Finds point-wise hypotenuse of two data fields.

#### Parameters

result | A data field to put the result to. May be one of `operand1` , `operand2` . |
operand1 | First data field operand. |
operand2 | Second data field operand. |

Since: 2.31

### gwy_data_field_linear_combination ()

    void
    gwy_data_field_linear_combination (GwyDataField *result,
                                       gdouble coeff1,
                                       GwyDataField *operand1,
                                       gdouble coeff2,
                                       GwyDataField *operand2,
                                       gdouble constant);

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

#### Parameters

result | A data field to put the result to. May be one of `operand1` , `operand2` . |
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. |

Since: 2.59

### gwy_data_field_check_compatibility ()

    GwyDataCompatibilityFlags
    gwy_data_field_check_compatibility (GwyDataField *data_field1,
                                        GwyDataField *data_field2,
                                        GwyDataCompatibilityFlags check);

Checks whether two data fields are compatible.

#### Parameters

data_field1 | A data field. |
data_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.

### gwy_data_line_check_compatibility ()

    GwyDataCompatibilityFlags
    gwy_data_line_check_compatibility (GwyDataLine *data_line1,
                                       GwyDataLine *data_line2,
                                       GwyDataCompatibilityFlags check);

Checks whether two data lines are compatible.

#### Parameters

data_line1 | A data line. |
data_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.

### gwy_brick_check_compatibility ()

    GwyDataCompatibilityFlags
    gwy_brick_check_compatibility (GwyBrick *brick1,
                                   GwyBrick *brick2,
                                   GwyDataCompatibilityFlags 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.

Since: 2.51

### gwy_lawn_check_compatibility ()

    GwyDataCompatibilityFlags
    gwy_lawn_check_compatibility (GwyLawn *lawn1,
                                  GwyLawn *lawn2,
                                  GwyDataCompatibilityFlags 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_COMPATIBILITY_CURVELEN` flag. Use `GWY_DATA_COMPATIBILITY_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 lawns are not compatible.

Since: 2.60

### gwy_data_field_check_compatibility_with_brick_xy ()

    GwyDataCompatibilityFlags
    gwy_data_field_check_compatibility_with_brick_xy
                                   (GwyDataField *data_field,
                                    GwyBrick *brick,
                                    GwyDataCompatibilityFlags check);

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

#### Parameters

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

Since: 2.51

### gwy_data_line_check_compatibility_with_brick_z ()

    GwyDataCompatibilityFlags
    gwy_data_line_check_compatibility_with_brick_z
                                   (GwyDataLine *data_line,
                                    GwyBrick *brick,
                                    GwyDataCompatibilityFlags check);

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

If `check` includes `GWY_DATA_COMPATIBILITY_REAL` or `GWY_DATA_COMPATIBILITY_LATERAL` but not `GWY_DATA_COMPATIBILITY_AXISCAL`, `data_line` is simply compared to `brick` in the Z direction.

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

#### Parameters

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

Since: 2.51

### gwy_data_field_check_compatibility_with_lawn ()

    GwyDataCompatibilityFlags
    gwy_data_field_check_compatibility_with_lawn
                                   (GwyDataField *data_field,
                                    GwyLawn *lawn,
                                    GwyDataCompatibilityFlags check);

### gwy_data_field_extend ()

    GwyDataField *
    gwy_data_field_extend (GwyDataField *data_field,
                           guint left,
                           guint right,
                           guint up,
                           guint down,
                           GwyExteriorType exterior,
                           gdouble fill_value,
                           gboolean keep_offsets);

Creates a new data field by extending another data field using the specified method of exterior handling.

#### Parameters

data_field | A two-dimensional data field. |
left | Number of pixels to extend to the left (towards lower column indices). |
right | Number of pixels to extend to the right (towards higher column indices). |
up | Number of pixels to extend up (towards lower row indices). |
down | Number of pixels to extend down (towards higher row indices). |
exterior | Exterior pixels handling. |
fill_value | The value to use with `GWY_EXTERIOR_FIXED_VALUE` exterior. |
keep_offsets | `TRUE` to set the X and Y offsets of the new field using `field` offsets. `FALSE` to set offsets of the new field to zeroes. |

#### Returns

A newly created data field.

Since: 2.36