IAffineTransformation2D Interface

Provides access to members that define and manipulate affine transformations.

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.

Members

Name Description
Method DefineFromControlPoints Defines the best affine transformation between two sets of points. Can be used to register paper maps on a digitizer.
Method DefineFromControlPointsEx Defines the best affine transformation between two sets of points. Can be used to register paper maps on a digitizer.
Method DefineFromEnvelopes Defines a transformation that maps a point relative to one envelope to a similar position relative to another envelope.
Method DefineFromEnvelopesEx Defines a transformation that maps a point relative to one envelope to a similar position relative to another envelope.
Method DefineReflection Defines a transformation that can perform a reflection about the line l.
Method GetControlPointError 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.
Method GetRMSError 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.
Read-only property IsReflective Indicates if the transformation contains a reflection (determinant is negative).
Method Move Incorporates a translation factor into the transformation.
Write-only property MoveOrigin The origin of accumulated transformations used when projecting an affine transformation to a different spatial reference system.
Method MoveVector Performs an X and Y translation defined by a 2D vector.
Method PostMultiply Post-multiplies the transformation by another transformation.
Method PreMultiply Pre-multiplies the transformation by another transformation.
Method Project 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.
Method Reset Resets the tranformation.
Method Rotate Incorporates a rotation (in radians) into the transformation.
Read-only property Rotation The rotation angle. Will not be able if different x/y scale factors have been incorporated into the transformation.
Method Scale Incorporates scale factors into the transformation.
Read/write property SpatialReference The spatial reference in which this transformation is meaningful.
Method TransformMeasuresFF Transforms floating point measures to floating point measures (or do the inverse).
Method TransformMeasuresFI Transforms floating point measures to integer measures (or do the inverse).
Method TransformMeasuresIF Transforms integer measures to floating point measures (or do the inverse).
Method TransformMeasuresII Transforms integer measures to integer measures (or do the inverse).
Method TransformPointsFF Transforms floating point points to floating point points (or do the inverse).
Method TransformPointsFI Transforms floating point points to integer points (or do the inverse).
Method TransformPointsIF Transforms integer points to floating point points (or do the inverse).
Method TransformPointsII Transforms integer points to integer points (or do the inverse).
Read-only property XScale The scale along the X axis.
Read-only property XTranslation The translation along the X axis.
Read-only property YScale The scale along the Y axis.
Read-only property YTranslation The translation along the Y axis.

IAffineTransformation2D.DefineFromControlPoints Method

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

Public Sub DefineFromControlPoints ( _
    ByVal numPoints As Integer, _
    ByRef fromPoints As IPoint, _
    ByRef toPoints As IPoint _
)
public void DefineFromControlPoints (
    int numPoints,
    ref IPoint fromPoints,
    ref IPoint toPoints
);

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.

Errors Returned

A minimum of 3 points are needed. If this condition is not met, the error E_GEOMETRY_INSUFFICIENT_CONTROLPOINTS is returned.

IAffineTransformation2D.DefineFromControlPointsEx Method

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

Public Sub DefineFromControlPointsEx ( _
    ByVal numPoints As Integer, _
    ByRef fromPoints As WKSPoint, _
    ByRef toPoints As WKSPoint _
)
public void DefineFromControlPointsEx (
    int numPoints,
    ref WKSPoint fromPoints,
    ref WKSPoint toPoints
);

IAffineTransformation2D.DefineFromEnvelopes Method

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

Public Sub DefineFromEnvelopes ( _
    ByVal from As IEnvelope, _
    ByVal to As IEnvelope _
)
public void DefineFromEnvelopes (
    IEnvelope from,
    IEnvelope to
);

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.

IAffineTransformation2D.DefineFromEnvelopesEx Method

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

Public Sub DefineFromEnvelopesEx ( _
    ByVal from As IEnvelope, _
    ByVal to As IEnvelope, _
    ByVal outFrom As IEnvelope, _
    ByVal assumeFalseOrigin As Boolean, _
    ByVal keepAspect As Boolean, _
    ByVal flipIt As Boolean _
)
public void DefineFromEnvelopesEx (
    IEnvelope from,
    IEnvelope to,
    IEnvelope outFrom,
    bool assumeFalseOrigin,
    bool keepAspect,
    bool flipIt
);

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 spaceto: Input IEnvelope object that represents an envelope in the destination spaceoutFrom: 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.

IAffineTransformation2D.DefineReflection Method

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

Public Sub DefineReflection ( _
    ByVal l As ILine _
)
public void DefineReflection (
    ILine l
);

Description

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

Remarks

IAffineTransformation DefineReflection Example

IAffineTransformation2D.GetControlPointError Method

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.

Public Sub GetControlPointError ( _
    ByVal i As Integer, _
    ByRef fromError As Double, _
    ByRef toError As Double _
)
public void GetControlPointError (
    int i,
    ref double fromError,
    ref double toError
);

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.

IAffineTransformation2D.GetRMSError Method

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.

Public Sub GetRMSError ( _
    ByRef fromError As Double, _
    ByRef toError As Double _
)
public void GetRMSError (
    ref double fromError,
    ref double toError
);

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.

IAffineTransformation2D.IsReflective Property

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

Public ReadOnly Property IsReflective As Boolean
public bool IsReflective {get;}

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

IAffineTransformation2D.Move Method

Incorporates a translation factor into the transformation.

Public Sub Move ( _
    ByVal dx As Double, _
    ByVal dy As Double _
)
public void Move (
    double dx,
    double dy
);

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.

IAffineTransformation2D.MoveOrigin Property

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

Public WriteOnly Property MoveOrigin
public void MoveOrigin {set;}

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.

IAffineTransformation2D.MoveVector Method

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

Public Sub MoveVector ( _
    ByVal movementVector As ILine _
)
public void MoveVector (
    ILine movementVector
);

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

IAffineTransformation2D.PostMultiply Method

Post-multiplies the transformation by another transformation.

Public Sub PostMultiply ( _
    ByVal postTransform As IAffineTransformation2D _
)
public void PostMultiply (
    IAffineTransformation2D postTransform
);

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.

IAffineTransformation2D.PreMultiply Method

Pre-multiplies the transformation by another transformation.

Public Sub PreMultiply ( _
    ByVal preTransform As IAffineTransformation2D _
)
public void PreMultiply (
    IAffineTransformation2D preTransform
);

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.

IAffineTransformation2D.Project Method

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.

Public Sub Project ( _
    ByVal newSpatialReference As ISpatialReference _
)
public void Project (
    ISpatialReference newSpatialReference
);

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.

IAffineTransformation2D.Reset Method

Resets the tranformation.

Public Sub Reset ( _
)
public void Reset (
);

Description

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

IAffineTransformation2D.Rotate Method

Incorporates a rotation (in radians) into the transformation.

Public Sub Rotate ( _
    ByVal da As Double _
)
public void Rotate (
    double da
);

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.

private void RotateAroundPoint()

{

    //Point to be rotated

    IPoint rotatePoint = new ESRI.ArcGIS.Geometry.Point();

    rotatePoint.PutCoords(2, 2);

    //Point around which to rotate

    IPoint centerPoint = new ESRI.ArcGIS.Geometry.Point();

    centerPoint.PutCoords(1, 1);

    //Rotation Angle

    double angle = 45 * Math.PI / 180.0;

    //Rotate Around pCenter

    IAffineTransformation2D3GEN affineTransformation = new AffineTransformation2D() as IAffineTransformation2D3GEN;

    affineTransformation.Move(-centerPoint.X, -centerPoint.Y);

    affineTransformation.Rotate(angle);

    affineTransformation.Move(centerPoint.X, centerPoint.Y);

    ITransform2D transformator = rotatePoint as ITransform2D;

    transformator.Transform(esriTransformDirection.esriTransformForward, affineTransformation as ITransformation);

    //Set up Comparison Point

    //This is the point the transformation should result in

    IPoint comparePoint = new ESRI.ArcGIS.Geometry.Point();

    comparePoint.PutCoords(2, 2);

    transformator = comparePoint as ITransform2D;

    transformator.Rotate(centerPoint, angle);

    System.Windows.Forms.MessageBox.Show(

        "Using IAffineTransformation2D.Rotate:  Point X:" + rotatePoint.X + ", Y:" + rotatePoint.Y + "\n" +

        "Using IAffineTransformation2D::Rotate,  Point X:" + rotatePoint.X + ", Y:" + rotatePoint.Y + "\n" +

        "Using ITransform2D::Rotate,  Point X: " + comparePoint.X + ", Y:" + comparePoint.Y + "\n" +

        "Did X coordinates match? " + (rotatePoint.X == comparePoint.X) + "\n" +

        "Did Y coordinates match? " + (rotatePoint.Y == comparePoint.Y)

    );

}
Private Sub RotateAroundPoint()

        'Point to be rotated

        Dim pPt As IPoint

        pPt = New Point

        pPt.PutCoords(2, 2)

        'Point around which to rotate

        Dim pCenter As IPoint

        pCenter = New Point

        pCenter.PutCoords(1, 1)

        'Rotation Angle

        Dim dAngle As Double

        Dim dPi As Double

        dPi = 4 * Math.Atan(1)

        dAngle = 45 * dPi / 180

        'Rotate Around pCenter

        Dim pA2D As IAffineTransformation2D

        pA2D = New AffineTransformation2D

        pA2D.Move(-pCenter.x, -pCenter.y)

        pA2D.Rotate(dAngle)

        pA2D.Move(pCenter.x, pCenter.y)

        Dim pT2D As ITransform2D

        pT2D = pPt

        pT2D.Transform(esriTransformDirection.esriTransformForward, pA2D)

        'Set up Comparison Point

        'This is the point the transformation should result in

        Dim pComparePt As IPoint

        pComparePt = New Point

        pComparePt.PutCoords(2, 2)

        pT2D = pComparePt

        pT2D.Rotate(pCenter, dAngle)

        Debug.Print("Using IAffineTransformation2D::Rotate,  Point X:" & pPt.x & ", Y:" & pPt.y)

        Debug.Print("Using ITransform2D::Rotate,  Point X:" & pComparePt.x & ", Y:" & pComparePt.y)

        Debug.Print("Did X coordinates match? " & (pPt.x = pComparePt.x))

        Debug.Print("Did Y coordinates match? " & (pPt.y = pComparePt.y))

    End Sub

IAffineTransformation2D.Rotation Property

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

Public ReadOnly Property Rotation As Double
public double Rotation {get;}

Description

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

IAffineTransformation2D.Scale Method

Incorporates scale factors into the transformation.

Public Sub Scale ( _
    ByVal dx As Double, _
    ByVal dy As Double _
)
public void Scale (
    double dx,
    double dy
);

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.

IAffineTransformation2D.SpatialReference Property

The spatial reference in which this transformation is meaningful.

Public Property SpatialReference As ISpatialReference
public ISpatialReference SpatialReference {get; set;}

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.

IAffineTransformation2D.XScale Property

The scale along the X axis.

Public ReadOnly Property XScale As Double
public double XScale {get;}

Description

Returns the X Scale factor from the transformation.

IAffineTransformation2D.XTranslation Property

The translation along the X axis.

Public ReadOnly Property XTranslation As Double
public double XTranslation {get;}

Description

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

IAffineTransformation2D.YScale Property

The scale along the Y axis.

Public ReadOnly Property YScale As Double
public double YScale {get;}

Description

Returns the Y Scale factor from the transformation.

IAffineTransformation2D.YTranslation Property

The translation along the Y axis.

Public ReadOnly Property YTranslation As Double
public double YTranslation {get;}

Description

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

Inherited Interfaces

Interfaces Description
ITransformation Provides access to members that apply a function (or its inverse) to a set of points or measures. The suffix of each method indicates the type of parameters operated on.

Classes that implement IAffineTransformation2D

Classes Description
AffineTransformation2D A two dimensional affine transformation.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.