Interface IAffineTransformation2D

Namespace
ESRI.ArcGIS.Geometry
Assembly
ESRI.Server.Geometry.dll

Provides access to members that define and manipulate affine transformations.

[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
[Guid("D12F81B4-D263-11D2-9F29-00C04F6BDD7F")]
public interface IAffineTransformation2D : ITransformation

Properties

IsReflective

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

bool IsReflective { get; }

Property Value

bool

Remarks

 

IAffineTransformation IsReflective Example

MoveOrigin

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

IPoint MoveOrigin { set; }

Property Value

IPoint

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.

Rotation

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

double Rotation { get; }

Property Value

double

SpatialReference

The spatial reference in which this transformation is meaningful.

ISpatialReference SpatialReference { get; set; }

Property Value

ISpatialReference

XScale

The scale along the X axis.

double XScale { get; }

Property Value

double

XTranslation

The translation along the X axis.

double XTranslation { get; }

Property Value

double

YScale

The scale along the Y axis.

double YScale { get; }

Property Value

double

YTranslation

The translation along the Y axis.

double YTranslation { get; }

Property Value

double

Methods

DefineFromControlPoints(int, ref IPoint, ref IPoint)

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

void DefineFromControlPoints(int numPoints, ref IPoint fromPoints, ref IPoint toPoints)

Parameters

numPoints int
fromPoints IPoint
toPoints IPoint

DefineFromControlPointsEx(int, ref WKSPoint, ref WKSPoint)

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

void DefineFromControlPointsEx(int numPoints, ref WKSPoint fromPoints, ref WKSPoint toPoints)

Parameters

numPoints int
fromPoints WKSPoint
toPoints WKSPoint

DefineFromEnvelopes(IEnvelope, IEnvelope)

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

void DefineFromEnvelopes(IEnvelope from, IEnvelope to)

Parameters

from IEnvelope
to IEnvelope

DefineFromEnvelopesEx(IEnvelope, IEnvelope, IEnvelope, bool, bool, bool)

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, bool assumeFalseOrigin, bool keepAspect, bool flipIt)

Parameters

from IEnvelope
to IEnvelope
outFrom IEnvelope
assumeFalseOrigin bool
keepAspect bool
flipIt bool

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.




DefineReflection(ILine)

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

void DefineReflection(ILine l)

Parameters

l ILine

Remarks

 

IAffineTransformation DefineReflection Example

GetControlPointError(int, out double, out double)

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.

void GetControlPointError(int i, out double fromError, out double toError)

Parameters

i int
fromError double
toError double

Remarks

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

GetRMSError(out double, out double)

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.

void GetRMSError(out double fromError, out double toError)

Parameters

fromError double
toError double

Remarks

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

Move(double, double)

Incorporates a translation factor into the transformation.

void Move(double dx, double dy)

Parameters

dx double
dy double

Remarks

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

MoveVector(ILine)

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

void MoveVector(ILine movementVector)

Parameters

movementVector ILine

PostMultiply(IAffineTransformation2D)

Post-multiplies the transformation by another transformation.

void PostMultiply(IAffineTransformation2D postTransform)

Parameters

postTransform IAffineTransformation2D

PreMultiply(IAffineTransformation2D)

Pre-multiplies the transformation by another transformation.

void PreMultiply(IAffineTransformation2D preTransform)

Parameters

preTransform IAffineTransformation2D

Project(ISpatialReference)

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.

void Project(ISpatialReference newSpatialReference)

Parameters

newSpatialReference ISpatialReference

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.

Reset()

Resets the tranformation.

void Reset()

Rotate(double)

Incorporates a rotation (in radians) into the transformation.

void Rotate(double da)

Parameters

da double

Remarks

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

[C#]

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)
    );
}

























[Visual Basic .NET]

    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




Scale(double, double)

Incorporates scale factors into the transformation.

void Scale(double dx, double dy)

Parameters

dx double
dy double

Remarks

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

TransformMeasuresFF(esriTransformDirection, int, ref double, ref double)

void TransformMeasuresFF(esriTransformDirection Direction, int cMeasures, ref double inMeasures, ref double outMeasures)

Parameters

Direction esriTransformDirection
cMeasures int
inMeasures double
outMeasures double

TransformMeasuresFI(esriTransformDirection, int, ref double, ref int)

void TransformMeasuresFI(esriTransformDirection Direction, int cMeasures, ref double inMeasures, ref int outMeasures)

Parameters

Direction esriTransformDirection
cMeasures int
inMeasures double
outMeasures int

TransformMeasuresIF(esriTransformDirection, int, ref int, ref double)

void TransformMeasuresIF(esriTransformDirection Direction, int cMeasures, ref int inMeasures, ref double outMeasures)

Parameters

Direction esriTransformDirection
cMeasures int
inMeasures int
outMeasures double

TransformMeasuresII(esriTransformDirection, int, ref int, ref int)

void TransformMeasuresII(esriTransformDirection Direction, int cMeasures, ref int inMeasures, ref int outMeasures)

Parameters

Direction esriTransformDirection
cMeasures int
inMeasures int
outMeasures int

TransformPointsFF(esriTransformDirection, int, ref double, ref double)

void TransformPointsFF(esriTransformDirection Direction, int cPoints, ref double inPoints, ref double outPoints)

Parameters

Direction esriTransformDirection
cPoints int
inPoints double
outPoints double

TransformPointsFI(esriTransformDirection, int, ref double, ref int)

void TransformPointsFI(esriTransformDirection Direction, int cPoints, ref double inPoints, ref int outPoints)

Parameters

Direction esriTransformDirection
cPoints int
inPoints double
outPoints int

TransformPointsIF(esriTransformDirection, int, ref int, ref double)

void TransformPointsIF(esriTransformDirection Direction, int cPoints, ref int inPoints, ref double outPoints)

Parameters

Direction esriTransformDirection
cPoints int
inPoints int
outPoints double

TransformPointsII(esriTransformDirection, int, ref int, ref int)

void TransformPointsII(esriTransformDirection Direction, int cPoints, ref int inPoints, ref int outPoints)

Parameters

Direction esriTransformDirection
cPoints int
inPoints int
outPoints int