com.flagstone.transform
Class FSCoordTransform

java.lang.Object
  extended by com.flagstone.transform.FSTransformObject
      extended by com.flagstone.transform.FSCoordTransform
All Implemented Interfaces:
java.lang.Cloneable

public class FSCoordTransform
extends FSTransformObject

FSCoordTransform is used to specify two-dimensional coordinate transforms, allowing an object to be scaled, rotated or moved without changing the original definition of how the object is drawn.

A two-dimensional transform is defined using a 3x3 matrix and the new values for a pair of coordinates (x,y) are calculated using the following matrix multiplication:

Different transformations such as scaling, rotation, shearing and translation can be performed using the above matrix multiplication. More complex transformations can be defined by performing successive matrix multiplications in a process known as compositing. This allows a complex transformations to performed on an object.

The FSCoordTransform contains a 3x3 array for defining the transformations. However when it is encoded the matrix is reduced to the following set attributes:

Attributes
scaleX The value to scale the shape in the x direction combined with the cosine component of any rotation.
scaleY The value to scale the shape in the x direction combined with the cosine component of any rotation.
rotate0 The sine component of any rotation applied to the shape.
rotate1 The negative sine component of any rotation applied to the shape.
translateX The x-coordinate of any translation applied to the shape.
translateY The y-coordinate of any translation applied to the shape.

Examples

The FSCoordTransform provides a set of methods for generating the matrices that will perform specific transformations. Methods are provided that represent matrices for performing translation, scaling, rotation and shearing transformations.

 FSCoordTransform = new FSCoordTransform();
 
 transform.scale(2.0, 2.0); // scale(x,y)
 transform.rotate(30.0); // rotate(degrees)
 transform.shear(1.2, 0.9); // shear(x, y)
 

The composite method can be used to multiply two matrices together to create complex transformations though successive compositing steps. For example to place a new object on the screen first rotating it by 30 degrees and scaling it to twice its original size the required transform can be constructed using the following steps:

  FSCoordTransform transform = new FSCoordTranform();
 
  transform.scale(2.0, 2.0);
  transform.rotate(30.0);
 
  int layer = 1;
  int identifier = movie.newIdentifier();
 
  FSDefineShape shape = new FSDefineShape(identifier, ...);
 
  FSPlaceObject2 placeShape = new FSPlaceObject2(identifier, layer, transform);
 

Compositing transforms are not commutative, the order in which transformations are applied will affect the final result. For example consider the following pair if transforms:

FSCoordTransform transform = new FSCoordTransform(); transform.translate(100, 100); transform.scale(2.0, 2.0);

The composite transform places an object at the coordinates (100,100) then scales it to twice its original size. If the transform was composited in the opposite order:

 FSCoordTransform transform = new FSCoordTransform();
 
 transform.scale(2.0, 2.0);
 transform.translate(100, 100);
 

Then the coordinates for the object's location would also be scaled, placing the object at (200,200).

Arbitrary coordinate transforms are created by specifying the 3 by 3 array of floating-point values in the constructor:

 float[][] matrix = new float[][] {
        {0.923f, 0.321f, 1000.0f },
        {0.868f, 0.235f, 1000.0f },
        {0.000f, 0.000f, 1.0000f } 
 };
 
 FSCoordTransform transform = new FSCoordTransform(matrix);
 

A constructor is also provided to handle the most common composite transform - scaling and translating an object at the same time:

 FSCoordTransform composite = new FSCoordTransform(100, 150, 2.0, 2.0);
 

Will place the object at the twip coordinates (100, 150) and scale the object to twice its original size.

History

The FSCoordTransform class represents the Matrix data structure from the Macromedia Flash (SWF) File Format Specification. It was introduced in Flash 1.


Constructor Summary
FSCoordTransform()
          Constructs an FSCoordTransform object defining a unity transform.
FSCoordTransform(float[][] aMatrix)
          Constructs an FSCoordTransform object with the specified transformation matrix.
FSCoordTransform(FSCoder coder)
          Construct an FSCoordTransform object and initialise it with values decoded from a binary encoded FSCoordTransform object.
FSCoordTransform(FSCoordTransform obj)
          Construct an FSCoordTransform object by copying an existing object.
FSCoordTransform(int x, int y)
          Constructs an FSCoordTransform object defining a translation transform that will change an objects location to the specified coordinates.
FSCoordTransform(int x, int y, double scaleX, double scaleY)
          Constructs an FSCoordTransform object defining translation and scaling transforms that will change an object's location and size.
 
Method Summary
 void appendDescription(java.lang.StringBuffer buffer, int depth)
          AppendDescription is used to present a string description of the object including all nested objects up to a specified depth.
 void composite(FSCoordTransform transform)
          Composite the 3 X 3 matrix with the FSCoordTransform argument.
 void decode(FSCoder coder)
           
 void encode(FSCoder coder)
           
 boolean equals(java.lang.Object anObject)
          Returns true if anObject is equal to this one.
 float[][] getMatrix()
          Gets the 3 X 3 array that is used to store the transformation values.
 boolean isUnityTransform()
          Returns true if the values in the transformation matrix represent a unity transform - one which will not change the physical appearance or location of a shape.
 int length(FSCoder coder)
           
 void rotate(double angle)
          Sets the angle which the transform will rotate an object.
 void scale(double x, double y)
          Sets the scaling factor for the transform.
 void setMatrix(float[][] aMatrix)
          Sets the values in the 3 X 3 array that is used to store the transformation values.
 void shear(double x, double y)
          Sets the shearing factor for the transform.
 int[] transformPoint(int x, int y)
          Applies the transformation to the coordinates of a point.
 void translate(int x, int y)
          Sets the translation points of the transform.
 
Methods inherited from class com.flagstone.transform.FSTransformObject
clone, name, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

FSCoordTransform

public FSCoordTransform(FSCoder coder)
Construct an FSCoordTransform object and initialise it with values decoded from a binary encoded FSCoordTransform object.

Parameters:
coder - an FSCoder object containing an FSColor encoded as binary data.

FSCoordTransform

public FSCoordTransform()
Constructs an FSCoordTransform object defining a unity transform. If the transform is applied to a shape its location or appearance will not change.


FSCoordTransform

public FSCoordTransform(int x,
                        int y)
Constructs an FSCoordTransform object defining a translation transform that will change an objects location to the specified coordinates.

Parameters:
x - the x-coordinate where the object will be displayed.
y - the y-coordinate where the object will be displayed.

FSCoordTransform

public FSCoordTransform(int x,
                        int y,
                        double scaleX,
                        double scaleY)
Constructs an FSCoordTransform object defining translation and scaling transforms that will change an object's location and size.

Parameters:
x - the x-coordinate where the object will be displayed.
y - the y-coordinate where the object will be displayed.
scaleX - value to scale the object in the x direction.
scaleY - value to scale the object in the y direction.

FSCoordTransform

public FSCoordTransform(float[][] aMatrix)
Constructs an FSCoordTransform object with the specified transformation matrix.

Parameters:
aMatrix - a 3x3 array of floats containing the values defining the transform.

FSCoordTransform

public FSCoordTransform(FSCoordTransform obj)
Construct an FSCoordTransform object by copying an existing object.

Method Detail

translate

public void translate(int x,
                      int y)
Sets the translation points of the transform.

Parameters:
x - the x-coordinate where the object will be displayed.
y - the y-coordinate where the object will be displayed.

scale

public void scale(double x,
                  double y)
Sets the scaling factor for the transform.

Parameters:
x - value to scale the object in the x direction.
y - value to scale the object in the y direction.

rotate

public void rotate(double angle)
Sets the angle which the transform will rotate an object.

Parameters:
angle - value, in degrees, to rotate the object clockwise.

shear

public void shear(double x,
                  double y)
Sets the shearing factor for the transform.

Parameters:
x - value to shear the object in the x direction.
y - value to shear the object in the y direction.

transformPoint

public int[] transformPoint(int x,
                            int y)
Applies the transformation to the coordinates of a point.

Parameters:
x - x-coordinate of a point.
y - x-coordinate of a point.
Returns:
an array containing the transformed point.

getMatrix

public float[][] getMatrix()
Gets the 3 X 3 array that is used to store the transformation values.

Returns:
an array, float[3][3], containing the values for the transformation matrix.

setMatrix

public void setMatrix(float[][] aMatrix)
Sets the values in the 3 X 3 array that is used to store the transformation values.

Parameters:
aMatrix - a 3x3 array of floats containing the values defining the transform.

composite

public void composite(FSCoordTransform transform)
Composite the 3 X 3 matrix with the FSCoordTransform argument. This method is used to create multiple transformation effects that can be applied to an object in a single step. Using the instance method fixes the order in which the transforms are composited. Since matrix multiplication is not commutative this limits the number of complex transforms that can be generated when compared to the class method.

Parameters:
transform - an FSCoordTransform object to composite with this instance.

equals

public boolean equals(java.lang.Object anObject)
Returns true if anObject is equal to this one. Objects are considered equal if they would generate identical binary data when they are encoded to a Flash file.

Overrides:
equals in class FSTransformObject
Returns:
true if this object would be identical to anObject when encoded.

appendDescription

public void appendDescription(java.lang.StringBuffer buffer,
                              int depth)
Description copied from class: FSTransformObject
AppendDescription is used to present a string description of the object including all nested objects up to a specified depth. This method provide a more controlled way of creating a string representation of an object since large objects such as font or shape definitions can contain dozens of nested objects. The representation of the object is appended to the StringBuffer, showing the name of the class and values of the attributes it contains. If the object contains any attributes that are objects then the object graph will be traversed up to the specified depth. If objects are nested at a level less than specified depth then the full string representation of the object is displayed. For objects at the specified depth only the name of the class is displayed. Any objects below this depth are not displayed.

Specified by:
appendDescription in class FSTransformObject
Parameters:
buffer - a StringBuffer to which the description of each object is appended.
depth - the maximum level of nesting up to which objects will be displayed.

length

public int length(FSCoder coder)
Specified by:
length in class FSTransformObject

encode

public void encode(FSCoder coder)
Specified by:
encode in class FSTransformObject

decode

public void decode(FSCoder coder)
Specified by:
decode in class FSTransformObject

isUnityTransform

public boolean isUnityTransform()
Returns true if the values in the transformation matrix represent a unity transform - one which will not change the physical appearance or location of a shape.

Returns:
true if the object represents a unity transform, false otherwise.