Package org.apache.pdfbox.util
Class Matrix
- java.lang.Object
-
- org.apache.pdfbox.util.Matrix
-
- All Implemented Interfaces:
java.lang.Cloneable
public final class Matrix extends java.lang.Object implements java.lang.Cloneable
This class will be used for matrix manipulation.- Author:
- Ben Litchfield
-
-
Constructor Summary
Constructors Constructor Description Matrix()
Constructor.Matrix(float a, float b, float c, float d, float e, float f)
Creates a transformation matrix with the given 6 elements.Matrix(java.awt.geom.AffineTransform at)
Creates a matrix with the same elements as the given AffineTransform.Matrix(COSArray array)
Creates a matrix from a 6-element (a b c d e f) COS array.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description Matrix
clone()
Clones this object.void
concatenate(Matrix matrix)
Concatenates (premultiplies) the given matrix to this matrix.static Matrix
concatenate(Matrix a, Matrix b)
Produces a copy of the first matrix, with the second matrix concatenated.java.awt.geom.AffineTransform
createAffineTransform()
Create an affine transform from this matrix's values.static Matrix
createMatrix(COSBase base)
Convenience method to be used when creating a matrix from unverified data.boolean
equals(java.lang.Object obj)
Matrix
extractScaling()
Deprecated.This method is due to be removed, please contact us if you make use of it.Matrix
extractTranslating()
Deprecated.This method is due to be removed, please contact us if you make use of it.static Matrix
getRotateInstance(double theta, float tx, float ty)
Convenience method to create a rotated instance.static Matrix
getScaleInstance(float sx, float sy)
Convenience method to create a scaled instance.float
getScaleX()
Returns the x-scaling element of this matrix.float
getScaleY()
Returns the y-scaling element of this matrix.float
getScalingFactorX()
Returns the x-scaling factor of this matrix.float
getScalingFactorY()
Returns the y-scaling factor of this matrix.float
getShearX()
Returns the x-shear element of this matrix.float
getShearY()
Returns the y-shear element of this matrix.static Matrix
getTranslateInstance(float tx, float ty)
Convenience method to create a translating instance.float
getTranslateX()
Returns the x-translation element of this matrix.float
getTranslateY()
Returns the y-translation element of this matrix.static Matrix
getTranslatingInstance(float tx, float ty)
Deprecated.UsegetTranslateInstance(float, float)
instead.float
getValue(int row, int column)
This will get a matrix value at some point.float[][]
getValues()
Return a single dimension array of all values in the matrix.double[][]
getValuesAsDouble()
Deprecated.UsegetValues()
instead.float
getXPosition()
Deprecated.UsegetTranslateX()
insteadfloat
getYPosition()
Deprecated.UsegetTranslateY()
insteadint
hashCode()
Matrix
multiply(Matrix b)
This will take the current matrix and multiply it with a matrix that is passed in.Matrix
multiply(Matrix other, Matrix result)
This method multiplies this Matrix with the specified other Matrix, storing the product in the specified result Matrix.void
reset()
Deprecated.This method will be removed.void
rotate(double theta)
Rotares this matrix by the given factors.void
scale(float sx, float sy)
Scales this matrix by the given factors.void
setFromAffineTransform(java.awt.geom.AffineTransform af)
Deprecated.Use theMatrix(AffineTransform)
constructor instead.void
setValue(int row, int column, float value)
This will set a value at a position.COSArray
toCOSArray()
Returns a COS array which represent the geometric relevant components of the matrix.java.lang.String
toString()
void
transform(java.awt.geom.Point2D point)
Transforms the given point by this matrix.Vector
transform(Vector vector)
Transforms the given point by this matrix.java.awt.geom.Point2D.Float
transformPoint(float x, float y)
Transforms the given point by this matrix.void
translate(float tx, float ty)
Translates this matrix by the given amount.void
translate(Vector vector)
Translates this matrix by the given vector.
-
-
-
Constructor Detail
-
Matrix
public Matrix()
Constructor. This produces an identity matrix.
-
Matrix
public Matrix(COSArray array)
Creates a matrix from a 6-element (a b c d e f) COS array.- Parameters:
array
-
-
Matrix
public Matrix(float a, float b, float c, float d, float e, float f)
Creates a transformation matrix with the given 6 elements. Transformation matrices are discussed in 8.3.3, "Common Transformations" and 8.3.4, "Transformation Matrices" of the PDF specification. For simple purposes (rotate, scale, translate) it is recommended to use the static methods below.- Parameters:
a
- the X coordinate scaling element (m00) of the 3x3 matrixb
- the Y coordinate shearing element (m10) of the 3x3 matrixc
- the X coordinate shearing element (m01) of the 3x3 matrixd
- the Y coordinate scaling element (m11) of the 3x3 matrixe
- the X coordinate translation element (m02) of the 3x3 matrixf
- the Y coordinate translation element (m12) of the 3x3 matrix- See Also:
getRotateInstance(double, float, float)
,getScaleInstance(float, float)
,getTranslateInstance(float, float)
-
Matrix
public Matrix(java.awt.geom.AffineTransform at)
Creates a matrix with the same elements as the given AffineTransform.- Parameters:
at
-
-
-
Method Detail
-
createMatrix
public static Matrix createMatrix(COSBase base)
Convenience method to be used when creating a matrix from unverified data. If the parameter is a COSArray with at least six numbers, a Matrix object is created from the first six numbers and returned. If not, then the identity Matrix is returned.- Parameters:
base
- a COS object, preferably a COSArray with six numbers.- Returns:
- a Matrix object.
-
reset
@Deprecated public void reset()
Deprecated.This method will be removed.This method resets the numbers in this Matrix to the original values, which are the values that a newly constructed Matrix would have.
-
createAffineTransform
public java.awt.geom.AffineTransform createAffineTransform()
Create an affine transform from this matrix's values.- Returns:
- An affine transform with this matrix's values.
-
setFromAffineTransform
@Deprecated public void setFromAffineTransform(java.awt.geom.AffineTransform af)
Deprecated.Use theMatrix(AffineTransform)
constructor instead.Set the values of the matrix from the AffineTransform.- Parameters:
af
- The transform to get the values from.
-
getValue
public float getValue(int row, int column)
This will get a matrix value at some point.- Parameters:
row
- The row to get the value from.column
- The column to get the value from.- Returns:
- The value at the row/column position.
-
setValue
public void setValue(int row, int column, float value)
This will set a value at a position.- Parameters:
row
- The row to set the value at.column
- the column to set the value at.value
- The value to set at the position.
-
getValues
public float[][] getValues()
Return a single dimension array of all values in the matrix.- Returns:
- The values of this matrix.
-
getValuesAsDouble
@Deprecated public double[][] getValuesAsDouble()
Deprecated.UsegetValues()
instead.Return a single dimension array of all values in the matrix.- Returns:
- The values ot this matrix.
-
concatenate
public void concatenate(Matrix matrix)
Concatenates (premultiplies) the given matrix to this matrix.- Parameters:
matrix
- The matrix to concatenate.
-
translate
public void translate(Vector vector)
Translates this matrix by the given vector.- Parameters:
vector
- 2D vector
-
translate
public void translate(float tx, float ty)
Translates this matrix by the given amount.- Parameters:
tx
- x-translationty
- y-translation
-
scale
public void scale(float sx, float sy)
Scales this matrix by the given factors.- Parameters:
sx
- x-scalesy
- y-scale
-
rotate
public void rotate(double theta)
Rotares this matrix by the given factors.- Parameters:
theta
- The angle of rotation measured in radians
-
multiply
public Matrix multiply(Matrix b)
This will take the current matrix and multiply it with a matrix that is passed in.- Parameters:
b
- The matrix to multiply by.- Returns:
- The result of the two multiplied matrices.
-
multiply
public Matrix multiply(Matrix other, Matrix result)
This method multiplies this Matrix with the specified other Matrix, storing the product in the specified result Matrix. By reusing Matrix instances like this, multiplication chains can be executed without having to create many temporary Matrix objects.It is allowed to have (other == this) or (result == this) or indeed (other == result) but if this is done, the backing float[] matrix values may be copied in order to ensure a correct product.
- Parameters:
other
- the second operand Matrix in the multiplicationresult
- the Matrix instance into which the result should be stored. If result is null, a new Matrix instance is created.- Returns:
- the product of the two matrices.
-
transform
public void transform(java.awt.geom.Point2D point)
Transforms the given point by this matrix.- Parameters:
point
- point to transform
-
transformPoint
public java.awt.geom.Point2D.Float transformPoint(float x, float y)
Transforms the given point by this matrix.- Parameters:
x
- x-coordinatey
- y-coordinate
-
transform
public Vector transform(Vector vector)
Transforms the given point by this matrix.- Parameters:
vector
- 2D vector
-
extractScaling
@Deprecated public Matrix extractScaling()
Deprecated.This method is due to be removed, please contact us if you make use of it.Create a new matrix with just the scaling operators.- Returns:
- A new matrix with just the scaling operators.
-
getScaleInstance
public static Matrix getScaleInstance(float sx, float sy)
Convenience method to create a scaled instance.- Parameters:
sx
- The xscale operator.sy
- The yscale operator.- Returns:
- A new matrix with just the x/y scaling
-
extractTranslating
@Deprecated public Matrix extractTranslating()
Deprecated.This method is due to be removed, please contact us if you make use of it.Create a new matrix with just the translating operators.- Returns:
- A new matrix with just the translating operators.
-
getTranslatingInstance
@Deprecated public static Matrix getTranslatingInstance(float tx, float ty)
Deprecated.UsegetTranslateInstance(float, float)
instead.Convenience method to create a translating instance.- Parameters:
tx
- The x translating operator.ty
- The y translating operator.- Returns:
- A new matrix with just the x/y translating.
-
getTranslateInstance
public static Matrix getTranslateInstance(float tx, float ty)
Convenience method to create a translating instance.- Parameters:
tx
- The x translating operator.ty
- The y translating operator.- Returns:
- A new matrix with just the x/y translating.
-
getRotateInstance
public static Matrix getRotateInstance(double theta, float tx, float ty)
Convenience method to create a rotated instance.- Parameters:
theta
- The angle of rotation measured in radianstx
- The x translation.ty
- The y translation.- Returns:
- A new matrix with the rotation and the x/y translating.
-
concatenate
public static Matrix concatenate(Matrix a, Matrix b)
Produces a copy of the first matrix, with the second matrix concatenated.- Parameters:
a
- The matrix to copy.b
- The matrix to concatenate.
-
clone
public Matrix clone()
Clones this object.- Overrides:
clone
in classjava.lang.Object
- Returns:
- cloned matrix as an object.
-
getScalingFactorX
public float getScalingFactorX()
Returns the x-scaling factor of this matrix. This is calculated from the scale and shear.- Returns:
- The x-scaling factor.
-
getScalingFactorY
public float getScalingFactorY()
Returns the y-scaling factor of this matrix. This is calculated from the scale and shear.- Returns:
- The y-scaling factor.
-
getScaleX
public float getScaleX()
Returns the x-scaling element of this matrix.- See Also:
getScalingFactorX()
-
getShearY
public float getShearY()
Returns the y-shear element of this matrix.
-
getShearX
public float getShearX()
Returns the x-shear element of this matrix.
-
getScaleY
public float getScaleY()
Returns the y-scaling element of this matrix.- See Also:
getScalingFactorY()
-
getTranslateX
public float getTranslateX()
Returns the x-translation element of this matrix.
-
getTranslateY
public float getTranslateY()
Returns the y-translation element of this matrix.
-
getXPosition
@Deprecated public float getXPosition()
Deprecated.UsegetTranslateX()
insteadGet the x position in the matrix. This method is deprecated as it is incorrectly named.- Returns:
- The x-position.
-
getYPosition
@Deprecated public float getYPosition()
Deprecated.UsegetTranslateY()
insteadGet the y position. This method is deprecated as it is incorrectly named.- Returns:
- The y position.
-
toCOSArray
public COSArray toCOSArray()
Returns a COS array which represent the geometric relevant components of the matrix. The last column of the matrix is ignored, only the first two columns are returned. This is analog to the Matrix(COSArray) constructor.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object obj)
- Overrides:
equals
in classjava.lang.Object
-
-