GimpMatrix

GimpMatrix — Utilities to set up and manipulate 3x3 transformation matrices.

Functions

Types and Values

Description

When doing image manipulation you will often need 3x3 transformation matrices that define translation, rotation, scaling, shearing and arbitrary perspective transformations using a 3x3 matrix. Here you'll find a set of utility functions to set up those matrices and to perform basic matrix manipulations and tests.

Each matrix class has a 2 dimensional gdouble coeff member. The element for row r and column c of the matrix is coeffr.

Functions

gimp_matrix2_identity ()

void
gimp_matrix2_identity (GimpMatrix2 *matrix);

Sets the matrix to the identity matrix.

Parameters

matrix

A matrix.

 

gimp_matrix2_mult ()

void
gimp_matrix2_mult (const GimpMatrix2 *matrix1,
                   GimpMatrix2 *matrix2);

Multiplies two matrices and puts the result into the second one.

Parameters

matrix1

The first input matrix.

 

matrix2

The second input matrix which will be overwritten by the result.

 

gimp_matrix2_determinant ()

gdouble
gimp_matrix2_determinant (const GimpMatrix2 *matrix);

Calculates the determinant of the given matrix.

Parameters

matrix

The input matrix.

 

Returns

The determinant.

Since: 2.10.16


gimp_matrix2_invert ()

void
gimp_matrix2_invert (GimpMatrix2 *matrix);

Inverts the given matrix.

Parameters

matrix

The matrix that is to be inverted.

 

Since: 2.10.16


gimp_matrix2_transform_point ()

void
gimp_matrix2_transform_point (const GimpMatrix2 *matrix,
                              gdouble x,
                              gdouble y,
                              gdouble *newx,
                              gdouble *newy);

Transforms a point in 2D as specified by the transformation matrix.

Parameters

matrix

The transformation matrix.

 

x

The source X coordinate.

 

y

The source Y coordinate.

 

newx

The transformed X coordinate.

 

newy

The transformed Y coordinate.

 

Since: 2.10.16


gimp_matrix3_identity ()

void
gimp_matrix3_identity (GimpMatrix3 *matrix);

Sets the matrix to the identity matrix.

Parameters

matrix

A matrix.

 

gimp_matrix3_mult ()

void
gimp_matrix3_mult (const GimpMatrix3 *matrix1,
                   GimpMatrix3 *matrix2);

Multiplies two matrices and puts the result into the second one.

Parameters

matrix1

The first input matrix.

 

matrix2

The second input matrix which will be overwritten by the result.

 

gimp_matrix3_translate ()

void
gimp_matrix3_translate (GimpMatrix3 *matrix,
                        gdouble x,
                        gdouble y);

Translates the matrix by x and y.

Parameters

matrix

The matrix that is to be translated.

 

x

Translation in X direction.

 

y

Translation in Y direction.

 

gimp_matrix3_scale ()

void
gimp_matrix3_scale (GimpMatrix3 *matrix,
                    gdouble x,
                    gdouble y);

Scales the matrix by x and y

Parameters

matrix

The matrix that is to be scaled.

 

x

X scale factor.

 

y

Y scale factor.

 

gimp_matrix3_rotate ()

void
gimp_matrix3_rotate (GimpMatrix3 *matrix,
                     gdouble theta);

Rotates the matrix by theta degrees.

Parameters

matrix

The matrix that is to be rotated.

 

theta

The angle of rotation (in radians).

 

gimp_matrix3_xshear ()

void
gimp_matrix3_xshear (GimpMatrix3 *matrix,
                     gdouble amount);

Shears the matrix in the X direction.

Parameters

matrix

The matrix that is to be sheared.

 

amount

X shear amount.

 

gimp_matrix3_yshear ()

void
gimp_matrix3_yshear (GimpMatrix3 *matrix,
                     gdouble amount);

Shears the matrix in the Y direction.

Parameters

matrix

The matrix that is to be sheared.

 

amount

Y shear amount.

 

gimp_matrix3_affine ()

void
gimp_matrix3_affine (GimpMatrix3 *matrix,
                     gdouble a,
                     gdouble b,
                     gdouble c,
                     gdouble d,
                     gdouble e,
                     gdouble f);

Applies the affine transformation given by six values to matrix . The six values form define an affine transformation matrix as illustrated below:

( a c e ) ( b d f ) ( 0 0 1 )

Parameters

matrix

The input matrix.

 

a

the 'a' coefficient

 

b

the 'b' coefficient

 

c

the 'c' coefficient

 

d

the 'd' coefficient

 

e

the 'e' coefficient

 

f

the 'f' coefficient

 

gimp_matrix3_transform_point ()

void
gimp_matrix3_transform_point (const GimpMatrix3 *matrix,
                              gdouble x,
                              gdouble y,
                              gdouble *newx,
                              gdouble *newy);

Transforms a point in 2D as specified by the transformation matrix.

Parameters

matrix

The transformation matrix.

 

x

The source X coordinate.

 

y

The source Y coordinate.

 

newx

The transformed X coordinate.

 

newy

The transformed Y coordinate.

 

gimp_matrix3_determinant ()

gdouble
gimp_matrix3_determinant (const GimpMatrix3 *matrix);

Calculates the determinant of the given matrix.

Parameters

matrix

The input matrix.

 

Returns

The determinant.


gimp_matrix3_invert ()

void
gimp_matrix3_invert (GimpMatrix3 *matrix);

Inverts the given matrix.

Parameters

matrix

The matrix that is to be inverted.

 

gimp_matrix3_is_identity ()

gboolean
gimp_matrix3_is_identity (const GimpMatrix3 *matrix);

Checks if the given matrix is the identity matrix.

Parameters

matrix

The matrix that is to be tested.

 

Returns

TRUE if the matrix is the identity matrix, FALSE otherwise


gimp_matrix3_is_diagonal ()

gboolean
gimp_matrix3_is_diagonal (const GimpMatrix3 *matrix);

Checks if the given matrix is diagonal.

Parameters

matrix

The matrix that is to be tested.

 

Returns

TRUE if the matrix is diagonal, FALSE otherwise


gimp_matrix3_is_affine ()

gboolean
gimp_matrix3_is_affine (const GimpMatrix3 *matrix);

Checks if the given matrix defines an affine transformation.

Parameters

matrix

The matrix that is to be tested.

 

Returns

TRUE if the matrix defines an affine transformation, FALSE otherwise

Since: 2.4


gimp_matrix3_is_simple ()

gboolean
gimp_matrix3_is_simple (const GimpMatrix3 *matrix);

Checks if we'll need to interpolate when applying this matrix as a transformation.

Parameters

matrix

The matrix that is to be tested.

 

Returns

TRUE if all entries of the upper left 2x2 matrix are either 0 or 1, FALSE otherwise


gimp_matrix3_equal ()

gboolean
gimp_matrix3_equal (const GimpMatrix3 *matrix1,
                    const GimpMatrix3 *matrix2);

Checks if two matrices are equal.

Parameters

matrix1

The first matrix

 

matrix2

The second matrix

 

Returns

TRUE the matrices are equal, FALSE otherwise

Since: 2.10.16


gimp_matrix4_identity ()

void
gimp_matrix4_identity (GimpMatrix4 *matrix);

Sets the matrix to the identity matrix.

Parameters

matrix

A matrix.

 

Since: 2.10.16


gimp_matrix4_mult ()

void
gimp_matrix4_mult (const GimpMatrix4 *matrix1,
                   GimpMatrix4 *matrix2);

Multiplies two matrices and puts the result into the second one.

Parameters

matrix1

The first input matrix.

 

matrix2

The second input matrix which will be overwritten by the result.

 

Since: 2.10.16


gimp_matrix4_to_deg ()

void
gimp_matrix4_to_deg (const GimpMatrix4 *matrix,
                     gdouble *a,
                     gdouble *b,
                     gdouble *c);

gimp_matrix4_transform_point ()

gdouble
gimp_matrix4_transform_point (const GimpMatrix4 *matrix,
                              gdouble x,
                              gdouble y,
                              gdouble z,
                              gdouble *newx,
                              gdouble *newy,
                              gdouble *newz);

Transforms a point in 3D as specified by the transformation matrix.

Parameters

matrix

The transformation matrix.

 

x

The source X coordinate.

 

y

The source Y coordinate.

 

z

The source Z coordinate.

 

newx

The transformed X coordinate.

 

newy

The transformed Y coordinate.

 

newz

The transformed Z coordinate.

 

Returns

The transformed W coordinate.

Since: 2.10.16


GIMP_IS_PARAM_SPEC_MATRIX2()

#define GIMP_IS_PARAM_SPEC_MATRIX2(pspec)  (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), GIMP_TYPE_PARAM_MATRIX2))

gimp_param_spec_matrix2 ()

GParamSpec *
gimp_param_spec_matrix2 (const gchar *name,
                         const gchar *nick,
                         const gchar *blurb,
                         const GimpMatrix2 *default_value,
                         GParamFlags flags);

Creates a param spec to hold a GimpMatrix2 value. See g_param_spec_internal() for more information.

Parameters

name

Canonical name of the param

 

nick

Nickname of the param

 

blurb

Brief description of param.

 

default_value

Value to use if none is assigned.

 

flags

a combination of GParamFlags

 

Returns

a newly allocated GParamSpec instance

Since: 2.4


GIMP_VALUE_HOLDS_MATRIX2()

#define GIMP_VALUE_HOLDS_MATRIX2(value) (G_TYPE_CHECK_VALUE_TYPE ((value), GIMP_TYPE_MATRIX2))

GIMP_IS_PARAM_SPEC_MATRIX3()

#define GIMP_IS_PARAM_SPEC_MATRIX3(pspec)  (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), GIMP_TYPE_PARAM_MATRIX3))

gimp_param_spec_matrix3 ()

GParamSpec *
gimp_param_spec_matrix3 (const gchar *name,
                         const gchar *nick,
                         const gchar *blurb,
                         const GimpMatrix3 *default_value,
                         GParamFlags flags);

Creates a param spec to hold a GimpMatrix3 value. See g_param_spec_internal() for more information.

Parameters

name

Canonical name of the param

 

nick

Nickname of the param

 

blurb

Brief description of param.

 

default_value

Value to use if none is assigned.

 

flags

a combination of GParamFlags

 

Returns

a newly allocated GParamSpec instance

Since: 2.8


GIMP_VALUE_HOLDS_MATRIX3()

#define GIMP_VALUE_HOLDS_MATRIX3(value) (G_TYPE_CHECK_VALUE_TYPE ((value), GIMP_TYPE_MATRIX3))

Types and Values

struct GimpMatrix2

struct GimpMatrix2 {
  gdouble coeff[2][2];
};

A two by two matrix.

Members

gdouble coeff[2][2];

the coefficients

 

struct GimpMatrix3

struct GimpMatrix3 {
  gdouble coeff[3][3];
};

A three by three matrix.

Members

gdouble coeff[3][3];

the coefficients

 

struct GimpMatrix4

struct GimpMatrix4 {
  gdouble coeff[4][4];
};

A four by four matrix.

Members

gdouble coeff[4][4];

the coefficients

 

GIMP_TYPE_MATRIX2

#define GIMP_TYPE_MATRIX2               (gimp_matrix2_get_type ())

GIMP_TYPE_PARAM_MATRIX2

#define GIMP_TYPE_PARAM_MATRIX2            (gimp_param_matrix2_get_type ())

GIMP_TYPE_MATRIX3

#define GIMP_TYPE_MATRIX3               (gimp_matrix3_get_type ())

GIMP_TYPE_PARAM_MATRIX3

#define GIMP_TYPE_PARAM_MATRIX3            (gimp_param_matrix3_get_type ())

See Also

GimpVector2, GimpVector3, GimpVector4