Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.flagstone.transform
Class FSCoordTransform

    java.lang.Object
      com.flagstone.transform.FSTransformObject
          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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD