Arithmetic

Arithmetic — Arithmetic operations with data

Functions

Types and Values

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.


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.


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.


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.


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 lawns are not compatible.


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.


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.


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.


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.


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.


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.

Types and Values

enum GwyDataMismatchFlags

Data line, field, brick and lawn compatibility flags.

It is not correct to pass GWY_DATA_MISMATCH_ALL to a compatibility checking function. Not all flags are meaningful for all data objects and GWY_DATA_MISMATCH_ALL may gain more bits in future versions (even though meaningless flags are generally silently ignored).

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_ALL

Mask of all defined flags.