GimpMatrix: GIMP Math Library Reference Manual

+ + +

GimpMatrix

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

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+void +	+gimp_matrix2_identity () +
+void +	+gimp_matrix2_mult () +
+gdouble +	+gimp_matrix2_determinant () +
+void +	+gimp_matrix2_invert () +
+void +	+gimp_matrix2_transform_point () +
+void +	+gimp_matrix3_identity () +
+void +	+gimp_matrix3_mult () +
+void +	+gimp_matrix3_translate () +
+void +	+gimp_matrix3_scale () +
+void +	+gimp_matrix3_rotate () +
+void +	+gimp_matrix3_xshear () +
+void +	+gimp_matrix3_yshear () +
+void +	+gimp_matrix3_affine () +
+void +	+gimp_matrix3_transform_point () +
+gdouble +	+gimp_matrix3_determinant () +
+void +	+gimp_matrix3_invert () +
+gboolean +	+gimp_matrix3_is_identity () +
+gboolean +	+gimp_matrix3_is_diagonal () +
+gboolean +	+gimp_matrix3_is_affine () +
+gboolean +	+gimp_matrix3_is_simple () +
+gboolean +	+gimp_matrix3_equal () +
+void +	+gimp_matrix4_identity () +
+void +	+gimp_matrix4_mult () +
+void +	+gimp_matrix4_to_deg () +
+gdouble +	+gimp_matrix4_transform_point () +
#define	+GIMP_IS_PARAM_SPEC_MATRIX2() +
+GParamSpec * +	+gimp_param_spec_matrix2 () +
#define	+GIMP_VALUE_HOLDS_MATRIX2() +
#define	+GIMP_IS_PARAM_SPEC_MATRIX3() +
+GParamSpec * +	+gimp_param_spec_matrix3 () +
#define	+GIMP_VALUE_HOLDS_MATRIX3() +

Types and Values

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

struct	GimpMatrix2
struct	GimpMatrix3
struct	GimpMatrix4
#define	GIMP_TYPE_MATRIX2
#define	GIMP_TYPE_PARAM_MATRIX2
#define	GIMP_TYPE_MATRIX3
#define	GIMP_TYPE_PARAM_MATRIX3

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