com.esri.arcgis.geometry
Interface IAffineTransformation2D

All Superinterfaces:

ITransformation, java.io.Serializable

All Known Subinterfaces:

IAffineTransformation2D2, IAffineTransformation2D3

All Known Implementing Classes:

AffineTransformation2D, IAffineTransformation2D2Proxy, IAffineTransformation2D3Proxy, IAffineTransformation2DProxy

public interface IAffineTransformation2D

extends ITransformation, java.io.Serializable

Provides access to members that define and manipulate affine transformations.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Description

The IAffineTransformation2D interface defines the function of a transformation, that is, how the coordinates of a Geometry are altered by the transformation. Use the DefineFromControlPoints, DefineFromEnvelopes, DefineFromEnvelopesEx, DefineReflection, Move, MoveVector, Project, Rotate, or Scale methods to define transformation functions for the AffineTransformation2D.

Method Summary

void	defineFromControlPoints(int numPoints, IPoint fromPoints, IPoint toPoints) Defines the best affine transformation between two sets of points.
void	defineFromEnvelopes(IEnvelope from, IEnvelope to) Defines a transformation that maps a point relative to one envelope to a similar position relative to another envelope.
void	defineFromEnvelopesEx(IEnvelope from, IEnvelope to, IEnvelope outFrom, boolean assumeFalseOrigin, boolean keepAspect, boolean flipIt) Defines a transformation that maps a point relative to one envelope to a similar position relative to another envelope.
void	defineReflection(ILine l) Defines a transformation that can perform a reflection about the line l.
void	getControlPointError(int i, double[] fromError, double[] toError) Returns the errors involved in moving control point i from the 'from' to 'to' system.
void	getRMSError(double[] fromError, double[] toError) RMS (Root Mean Square) error expressed relative to the 'from' and 'to' points defining the transformation.
double	getRotation() The rotation angle.
ISpatialReference	getSpatialReference() The spatial reference in which this transformation is meaningful.
double	getXScale() The scale along the X axis.
double	getXTranslation() The translation along the X axis.
double	getYScale() The scale along the Y axis.
double	getYTranslation() The translation along the Y axis.
boolean	isReflective() Indicates if the transformation contains a reflection (determinant is negative).
void	move(double dx, double dy) Incorporates a translation factor into the transformation.
void	moveVector(ILine movementVector) Performs an X and Y translation defined by a 2D vector.
void	postMultiply(IAffineTransformation2D postTransform) Post-multiplies the transformation by another transformation.
void	preMultiply(IAffineTransformation2D preTransform) Pre-multiplies the transformation by another transformation.
void	project(ISpatialReference newSpatialReference) Moves this transformation into another spatial reference.
void	reset() Resets the tranformation.
void	rotate(double da) Incorporates a rotation (in radians) into the transformation.
void	scale(double dx, double dy) Incorporates scale factors into the transformation.
void	setMoveOrigin(IPoint rhs1) The origin of accumulated transformations used when projecting an affine transformation to a different spatial reference system.
void	setSpatialReferenceByRef(ISpatialReference sR) The spatial reference in which this transformation is meaningful.

Methods inherited from interface com.esri.arcgis.geometry.ITransformation

transformMeasuresFF, transformMeasuresFI, transformMeasuresIF, transformMeasuresII, transformPointsFF, transformPointsFI, transformPointsIF, transformPointsII

Method Detail

setSpatialReferenceByRef

public void setSpatialReferenceByRef(ISpatialReference sR)
                              throws java.io.IOException,
                                     AutomationException

The spatial reference in which this transformation is meaningful.

Parameters:

sR - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSpatialReference

public ISpatialReference getSpatialReference()
                                      throws java.io.IOException,
                                             AutomationException

The spatial reference in which this transformation is meaningful.

Supported Platforms

Windows, Solaris, Linux

Description

The IAffineTransformation2D::SpatialReference property allows to set/get the spatial reference of the AffineTransformation2D object. The spatial reference defines in which coordinate system the transformation is valid.

Returns:

A reference to a com.esri.arcgis.geometry.ISpatialReference

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

reset

public void reset()
           throws java.io.IOException,
                  AutomationException

Resets the tranformation.

Supported Platforms

Windows, Solaris, Linux

Description

Resets the AffineTransformation matrix and corresponding transformations. A Reset AffineTransformation2D object corresponds to an identity transformation.

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

defineFromControlPoints

public void defineFromControlPoints(int numPoints,
                                    IPoint fromPoints,
                                    IPoint toPoints)
                             throws java.io.IOException,
                                    AutomationException

Defines the best affine transformation between two sets of points. Can be used to register paper maps on a digitizer.

Supported Platforms

Windows, Solaris, Linux

Description

The DefineFromControlPoints method may be particularly useful if you wish to register a set of control points from a digitizer to existing known control points. This method calculates a ‘best fit’ affine transformation to map one set of control points onto another. Please see the AffineTransformation2D coclass for a description of the mathematical model.

Parameters:

numPoints - The numPoints (in)

fromPoints - A reference to a com.esri.arcgis.geometry.IPoint (in)

toPoints - A reference to a com.esri.arcgis.geometry.IPoint (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

defineFromEnvelopes

public void defineFromEnvelopes(IEnvelope from,
                                IEnvelope to)
                         throws java.io.IOException,
                                AutomationException

Defines a transformation that maps a point relative to one envelope to a similar position relative to another envelope.

Supported Platforms

Windows, Solaris, Linux

Description

The IAffineTransformation2D::DefineFromEnvelopes allows to define an AffineTransformation based on two envelopes. This method can be used to create a quick adjustment containing only translation and scale. Since envelope cannot be rotated, it doesn't allow defining a rotation.

Parameters:

from - A reference to a com.esri.arcgis.geometry.IEnvelope (in)

to - A reference to a com.esri.arcgis.geometry.IEnvelope (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

defineFromEnvelopesEx

public void defineFromEnvelopesEx(IEnvelope from,
                                  IEnvelope to,
                                  IEnvelope outFrom,
                                  boolean assumeFalseOrigin,
                                  boolean keepAspect,
                                  boolean flipIt)
                           throws java.io.IOException,
                                  AutomationException

Defines a transformation that maps a point relative to one envelope to a similar position relative to another envelope.

Supported Platforms

Windows, Solaris, Linux

Description

The IAffineTransformation2D::DefineFromEnvelopesEx allows to define an AffineTransformation based on two envelopes. This method can be used to make it easy to set up a drawing transformation if you're not using maps/display transforms.

Remarks

Parameters:

from: Input IEnvelope object that represents an envelope in the origin space
to: Input IEnvelope object that represents an envelope in the destination space
outFrom: Output IEnvelope object. If provided (can be nothing) this envelope is populated with a from envelope having the same aspect ratio as the to envelope.
assumeFalseOrigin: If assumeFalseOrigin is TRUE, then the transform will assume that an input point with coordinates (0, 0) is actually located at (from.xmin, from.ymin). Otherwise, the transform will include elements that shift each point by (-from.xmin, -from .ymin) before scaling.
keepAspect: Input Boolean value if TRUE the transformation will have the same XScale and YScale.
flipIt: Input Boolean value if TRUE, the transformation will contain an horizontal reflection.

Parameters:

from - A reference to a com.esri.arcgis.geometry.IEnvelope (in)

to - A reference to a com.esri.arcgis.geometry.IEnvelope (in)

outFrom - A reference to a com.esri.arcgis.geometry.IEnvelope (in)

assumeFalseOrigin - The assumeFalseOrigin (in)

keepAspect - The keepAspect (in)

flipIt - The flipIt (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

defineReflection

public void defineReflection(ILine l)
                      throws java.io.IOException,
                             AutomationException

Defines a transformation that can perform a reflection about the line l.

Supported Platforms

Windows, Solaris, Linux

Description

Applies a reflection across the input line to the existing affine transformation.

Remarks

Parameters:

l - A reference to a com.esri.arcgis.geometry.ILine (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getRMSError

public void getRMSError(double[] fromError,
                        double[] toError)
                 throws java.io.IOException,
                        AutomationException

RMS (Root Mean Square) error expressed relative to the 'from' and 'to' points defining the transformation. These error terms are valid after using DefineFromControlPoints/Ex to define the transformation.

Supported Platforms

Windows, Solaris, Linux

Description

IAffineTransformation2D::GetRMSError returns the 'Root Mean Square' error associated with a given transformation defined using the IAffineTransformation2D::DefineFromControlPoints/Ex method. The fromError describes the distance deviations resulting from putting the 'to' control points into the 'from' space using a "best-fit" affine transformation. The toError describes the distance deviations resulting from putting the 'from' points into the 'to' space using another best-fit transformation.

Remarks

Note: The fromError is in the units of the from space, and the toError is in the units of the 'to' space.

Parameters:

fromError - The fromError (out: use single element array)

toError - The toError (out: use single element array)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getControlPointError

public void getControlPointError(int i,
                                 double[] fromError,
                                 double[] toError)
                          throws java.io.IOException,
                                 AutomationException

Returns the errors involved in moving control point i from the 'from' to 'to' system. These error terms are valid after using DefineFromControlPoints/Ex to define the transformation.

Supported Platforms

Windows, Solaris, Linux

Description

IAffineTransformation2D::GetControlPointError returns the distance error associated with a given control point of a transformation defined using the IAffineTransformation2D::DefineFromControlPoints/methods. For example, this information could be used to determine which control point causes the more error for a given adjustment. The adjustment could then be refined starting by this point.

Remarks

Note: The from error is in 'from' space units, and the to error is in 'to' space units.

Parameters:

i - The i (in)

fromError - The fromError (out: use single element array)

toError - The toError (out: use single element array)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getXScale

public double getXScale()
                 throws java.io.IOException,
                        AutomationException

The scale along the X axis.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the X Scale factor from the transformation.

Returns:

The sx

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getYScale

public double getYScale()
                 throws java.io.IOException,
                        AutomationException

The scale along the Y axis.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the Y Scale factor from the transformation.

Returns:

The sy

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getXTranslation

public double getXTranslation()
                       throws java.io.IOException,
                              AutomationException

The translation along the X axis.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the X Translation (Move) factor from the transformation.

Returns:

The dx

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getYTranslation

public double getYTranslation()
                       throws java.io.IOException,
                              AutomationException

The translation along the Y axis.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the Y Translation (Move) factor from the transformation.

Returns:

The dy

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getRotation

public double getRotation()
                   throws java.io.IOException,
                          AutomationException

The rotation angle. Will not be able if different x/y scale factors have been incorporated into the transformation.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the Rotation factor from the transformation. Rotation is in radians.

Returns:

The r

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

scale

public void scale(double dx,
                  double dy)
           throws java.io.IOException,
                  AutomationException

Incorporates scale factors into the transformation.

Supported Platforms

Windows, Solaris, Linux

Description

Scales (Multiplies) the existing affine transformation matrix by dx in the X direction and dy in the Y direction.

Remarks

Note: The Move, Scale, and Rotate transformations are cumulative they add the transformation specified to any existing transformation in an AffineTransformation2D object.

Parameters:

dx - The dx (in)

dy - The dy (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setMoveOrigin

public void setMoveOrigin(IPoint rhs1)
                   throws java.io.IOException,
                          AutomationException

The origin of accumulated transformations used when projecting an affine transformation to a different spatial reference system.

Supported Platforms

Windows, Solaris, Linux

Remarks

Projecting a distance from one spatial reference to another is meaningless without specifying where the distance is measured. A line that is one unit in length in one spatial reference can map to a varying number of units on another spatial reference depending upon the location of the end points. For this reason, when your AffineTransformation2D has a translation (i.e., a Move), it is important to specify a point as the Origin for this move. This is done using the MoveOrigin property.

When the AffineTransformation2D you are projecting has a rotation, specifying a MoveOrigin is not necessary as the origin (or center) of the rotation is considered to be the origin of any translations as well.

Using a MoveOrigin that is closest to the geometry that you are projecting results in a more accurate transformation. In the following illustration, a point P1 is transformed by an AffineTransformation2D to the point P2. Both P1 and the Affine Transformation have the same spatial reference. P2 when projected to another spatial reference results in PP2.

If you project P1 and the Affine Transformation into PP2's spatial reference, and transform the projected point PP1 using the projected transformation, you will get the point PP2 provided you set the MoveOrigin of the AffineTransformation to P1 before projecting it. The results of this transformation will be more accurate when the MoveOrigin is closer to P1.

For the code illustrating this, see the example for this topic.

For an AffineTransformation2D to be projected, its MoveOrigin should be set so that it is within the horizons of the new projection.

Parameters:

rhs1 - A reference to a com.esri.arcgis.geometry.IPoint (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

moveVector

public void moveVector(ILine movementVector)
                throws java.io.IOException,
                       AutomationException

Performs an X and Y translation defined by a 2D vector.

Supported Platforms

Windows, Solaris, Linux

Description

Translates (Shifts) the existing affine transformation as defined by the coordinates of the input MoveVector (where the FromPoint of the MoveVector serves as the origin point of the translation).

Parameters:

movementVector - A reference to a com.esri.arcgis.geometry.ILine (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

move

public void move(double dx,
                 double dy)
          throws java.io.IOException,
                 AutomationException

Incorporates a translation factor into the transformation.

Supported Platforms

Windows, Solaris, Linux

Description

Translates (Shifts) the existing affine transformation by adding dx units in the X direction and dy units in the Y direction.

Remarks

Note: The Move, Scale, and Rotate transformations are cumulative they add the transformation specified to any existing transformation in an AffineTransformation2D object.

Parameters:

dx - The dx (in)

dy - The dy (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

rotate

public void rotate(double da)
            throws java.io.IOException,
                   AutomationException

Incorporates a rotation (in radians) into the transformation.

Supported Platforms

Windows, Solaris, Linux

Description

Rotates the existing affine transformation by da radians around (0,0).

Remarks

Note: The Move, Scale, and Rotate transformations are cumulative they add the transformation specified to any existing transformation in an AffineTransformation2D object.

Parameters:

da - The da (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

postMultiply

public void postMultiply(IAffineTransformation2D postTransform)
                  throws java.io.IOException,
                         AutomationException

Post-multiplies the transformation by another transformation.

Supported Platforms

Windows, Solaris, Linux

Description

Multiplies the existing affine transformation matrix with another affine transformation matrix. The multiplication occurs after the existing transformation is applied. This is a right side matrix multiplication.

Parameters:

postTransform - A reference to a com.esri.arcgis.geometry.IAffineTransformation2D (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

preMultiply

public void preMultiply(IAffineTransformation2D preTransform)
                 throws java.io.IOException,
                        AutomationException

Pre-multiplies the transformation by another transformation.

Supported Platforms

Windows, Solaris, Linux

Description

Multiplies the existing affine transformation matrix with another affine transformation matrix. The multiplication occurs after the other transformation is first applied. This is a left side matrix multiplication.

Parameters:

preTransform - A reference to a com.esri.arcgis.geometry.IAffineTransformation2D (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isReflective

public boolean isReflective()
                     throws java.io.IOException,
                            AutomationException

Indicates if the transformation contains a reflection (determinant is negative).

Returns:

The isReflective

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

project

public void project(ISpatialReference newSpatialReference)
             throws java.io.IOException,
                    AutomationException

Moves this transformation into another spatial reference. If the transformations contains only translations, then use the MoveOrigin property to define an equivalent translation in the new spatial reference.

Supported Platforms

Windows, Solaris, Linux

Remarks

Projecting a distance from one spatial reference to another is meaningless without specifying where the distance is measured. A line that is one unit in length in one spatial reference can map to a varying number of units on another spatial reference depending upon the location of the end points. For this reason, when your AffineTransformation2D has a translation (i.e., a Move), it is important to specify a point as the Origin for this move. This is done using the MoveOrigin property.

When the AffineTransformation2D you are projecting has a rotation, specifying a MoveOrigin is not necessary as the origin (or center) of the rotation is considered to be the origin of any translations as well.

Using a MoveOrigin that is closest to the geometry that you are projecting results in a more accurate transformation. In the following illustration, a point P1 is transformed by an AffineTransformation2D to the point P2. Both P1 and the Affine Transformation have the same spatial reference. P2 when projected to another spatial reference results in PP2.

If you project P1 and the Affine Transformation into PP2's spatial reference, and transform the projected point PP1 using the projected transformation, you will get the point PP2 provided you set the MoveOrigin of the AffineTransformation to P1 before projecting it. The results of this transformation will be more accurate when the MoveOrigin is closer to P1.

For the code illustrating this, see the example for this topic.

When the scaling is not uniform on the X and the Y axes, no projection takes place.

For an AffineTransformation2D to be projected, its MoveOrigin should be set so that it is within the horizons of the new projection. As the default MoveOrigin of (0,0) might not be within the horizons of the new projection, it is important to explicitly set MoveOrigin before you project.

Parameters:

newSpatialReference - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.