com.esri.arcgis.geometry
Interface IAffineTransformation2D

All Superinterfaces:
ITransformation, Serializable
All Known Subinterfaces:
IAffineTransformation2D2, IAffineTransformation2D3
All Known Implementing Classes:
AffineTransformation2D

public interface IAffineTransformation2D
extends ITransformation, Serializable

Provides access to members that define and manipulate affine transformations.

Superseded By

IAffineTransformation2D3

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux


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

void setSpatialReferenceByRef(ISpatialReference sR)
                              throws IOException,
                                     AutomationException
The spatial reference in which this transformation is meaningful.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
sR - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSpatialReference

ISpatialReference getSpatialReference()
                                      throws IOException,
                                             AutomationException
The spatial reference in which this transformation is meaningful.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A reference to a com.esri.arcgis.geometry.ISpatialReference
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

reset

void reset()
           throws IOException,
                  AutomationException
Resets the tranformation.

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

defineFromControlPoints

void defineFromControlPoints(int numPoints,
                             IPoint fromPoints,
                             IPoint toPoints)
                             throws IOException,
                                    AutomationException
Defines the best affine transformation between two sets of points. Can be used to register paper maps on a digitizer.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

defineFromEnvelopes

void defineFromEnvelopes(IEnvelope from,
                         IEnvelope to)
                         throws IOException,
                                AutomationException
Defines a transformation that maps a point relative to one envelope to a similar position relative to another envelope.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
from - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
to - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

defineFromEnvelopesEx

void defineFromEnvelopesEx(IEnvelope from,
                           IEnvelope to,
                           IEnvelope outFrom,
                           boolean assumeFalseOrigin,
                           boolean keepAspect,
                           boolean flipIt)
                           throws IOException,
                                  AutomationException
Defines a transformation that maps a point relative to one envelope to a similar position relative to another envelope.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

defineReflection

void defineReflection(ILine l)
                      throws IOException,
                             AutomationException
Defines a transformation that can perform a reflection about the line l.

Description

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

Remarks

IAffineTransformation DefineReflection Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
l - A reference to a com.esri.arcgis.geometry.ILine (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getRMSError

void getRMSError(double[] fromError,
                 double[] toError)
                 throws 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.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
fromError - The fromError (out: use single element array)
toError - The toError (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getControlPointError

void getControlPointError(int i,
                          double[] fromError,
                          double[] toError)
                          throws 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.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
i - The i (in)
fromError - The fromError (out: use single element array)
toError - The toError (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getXScale

double getXScale()
                 throws IOException,
                        AutomationException
The scale along the X axis.

Description

Returns the X Scale factor from the transformation.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The sx
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getYScale

double getYScale()
                 throws IOException,
                        AutomationException
The scale along the Y axis.

Description

Returns the Y Scale factor from the transformation.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The sy
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getXTranslation

double getXTranslation()
                       throws IOException,
                              AutomationException
The translation along the X axis.

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The dx
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getYTranslation

double getYTranslation()
                       throws IOException,
                              AutomationException
The translation along the Y axis.

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The dy
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getRotation

double getRotation()
                   throws IOException,
                          AutomationException
The rotation angle. Will not be able if different x/y scale factors have been incorporated into the transformation.

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The r
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

scale

void scale(double dx,
           double dy)
           throws IOException,
                  AutomationException
Incorporates scale factors into the transformation.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
dx - The dx (in)
dy - The dy (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

setMoveOrigin

void setMoveOrigin(IPoint rhs1)
                   throws IOException,
                          AutomationException
The origin of accumulated transformations used when projecting an affine transformation to a different spatial reference system.

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.

AffineTransformation2D Example

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
rhs1 - A reference to a com.esri.arcgis.geometry.IPoint (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

moveVector

void moveVector(ILine movementVector)
                throws IOException,
                       AutomationException
Performs an X and Y translation defined by a 2D vector.

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).

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
movementVector - A reference to a com.esri.arcgis.geometry.ILine (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

move

void move(double dx,
          double dy)
          throws IOException,
                 AutomationException
Incorporates a translation factor into the transformation.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
dx - The dx (in)
dy - The dy (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

rotate

void rotate(double da)
            throws IOException,
                   AutomationException
Incorporates a rotation (in radians) into the transformation.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
da - The da (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

postMultiply

void postMultiply(IAffineTransformation2D postTransform)
                  throws IOException,
                         AutomationException
Post-multiplies the transformation by another transformation.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
postTransform - A reference to a com.esri.arcgis.geometry.IAffineTransformation2D (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

preMultiply

void preMultiply(IAffineTransformation2D preTransform)
                 throws IOException,
                        AutomationException
Pre-multiplies the transformation by another transformation.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
preTransform - A reference to a com.esri.arcgis.geometry.IAffineTransformation2D (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isReflective

boolean isReflective()
                     throws IOException,
                            AutomationException
Indicates if the transformation contains a reflection (determinant is negative).

Description

Returns TRUE if the affine transformation includes a reflection. Reflections can be explicitly defined using DefineReflection or occur as a combination of rotating and scaling operations.

Remarks

IAffineTransformation IsReflective Example

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
The isReflective
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

project

void project(ISpatialReference newSpatialReference)
             throws 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.

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.

AffineTransformation2D Example

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
newSpatialReference - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.