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