arithmetic

arithmetic — Arithmetic opetations on data fields

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_data_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_data_field_is_incompatible(), gwy_data_line_check_compatibility() and gwy_brick_is_incompatible() simplify testing compatibility of data fields, lines and bricks, respectively.

Functions

gwy_data_line_sum_lines()

void
gwy_data_line_sum_lines (GwyDataLine *result,
                         GwyDataLine *operand1,
                         GwyDataLine *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_data_line_subtract_lines()

void
gwy_data_line_subtract_lines (GwyDataLine *result,
                              GwyDataLine *operand1,
                              GwyDataLine *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_data_line_multiply_lines()

void
gwy_data_line_multiply_lines (GwyDataLine *result,
                              GwyDataLine *operand1,
                              GwyDataLine *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_data_line_linear_combination()

void
gwy_data_line_linear_combination (GwyDataLine *result,
                                  gdouble coeff1,
                                  GwyDataLine *operand1,
                                  gdouble coeff2,
                                  GwyDataLine *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_data_field_sum_fields()

void
gwy_data_field_sum_fields (GwyDataField *result,
                           GwyDataField *operand1,
                           GwyDataField *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_data_field_subtract_fields()

void
gwy_data_field_subtract_fields (GwyDataField *result,
                                GwyDataField *operand1,
                                GwyDataField *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_data_field_divide_fields()

void
gwy_data_field_divide_fields (GwyDataField *result,
                              GwyDataField *operand1,
                              GwyDataField *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_data_field_multiply_fields()

void
gwy_data_field_multiply_fields (GwyDataField *result,
                                GwyDataField *operand1,
                                GwyDataField *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_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.

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

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

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

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_data_field_is_incompatible()

GwyDataMismatchFlags
gwy_data_field_is_incompatible (GwyDataField *data_field1,
                                GwyDataField *data_field2,
                                GwyDataMismatchFlags 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_is_incompatible()

GwyDataMismatchFlags
gwy_data_line_is_incompatible (GwyDataLine *line1,
                               GwyDataLine *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_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_data_field_is_incompatible_with_brick_xy()

GwyDataMismatchFlags
gwy_data_field_is_incompatible_with_brick_xy
                               (GwyDataField *data_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_data_line_is_incompatible_with_brick_z()

GwyDataMismatchFlags
gwy_data_line_is_incompatible_with_brick_z
                               (GwyDataLine *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_data_field_is_incompatible_with_lawn()

GwyDataMismatchFlags
gwy_data_field_is_incompatible_with_lawn
                               (GwyDataField *data_field,
                                GwyLawn *lawn,
                                GwyDataMismatchFlags 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

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.

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.