|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface IAffineTransformation2D
Provides access to members that define and manipulate affine transformations.
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 |
|---|
void setSpatialReferenceByRef(ISpatialReference sR)
throws IOException,
AutomationException
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.
sR - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
ISpatialReference getSpatialReference()
throws IOException,
AutomationException
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void reset()
throws IOException,
AutomationException
Resets the AffineTransformation matrix and corresponding transformations. A Reset AffineTransformation2D object corresponds to an identity transformation.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void defineFromControlPoints(int numPoints,
IPoint fromPoints,
IPoint toPoints)
throws IOException,
AutomationException
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.
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)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void defineFromEnvelopes(IEnvelope from,
IEnvelope to)
throws IOException,
AutomationException
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.
from - A reference to a com.esri.arcgis.geometry.IEnvelope (in)to - A reference to a com.esri.arcgis.geometry.IEnvelope (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void defineFromEnvelopesEx(IEnvelope from,
IEnvelope to,
IEnvelope outFrom,
boolean assumeFalseOrigin,
boolean keepAspect,
boolean flipIt)
throws IOException,
AutomationException
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.
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.
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)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void defineReflection(ILine l)
throws IOException,
AutomationException
Applies a reflection across the input line to the existing affine transformation.
l - A reference to a com.esri.arcgis.geometry.ILine (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void getRMSError(double[] fromError,
double[] toError)
throws IOException,
AutomationException
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.
Note: The fromError is in the units of the from space, and the toError is in the units of the 'to' space.
fromError - The fromError (out: use single element array)toError - The toError (out: use single element array)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void getControlPointError(int i,
double[] fromError,
double[] toError)
throws IOException,
AutomationException
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.
Note: The from error is in 'from' space units, and the to error is in 'to' space units.
i - The i (in)fromError - The fromError (out: use single element array)toError - The toError (out: use single element array)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
double getXScale()
throws IOException,
AutomationException
Returns the X Scale factor from the transformation.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
double getYScale()
throws IOException,
AutomationException
Returns the Y Scale factor from the transformation.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
double getXTranslation()
throws IOException,
AutomationException
Returns the X Translation (Move) factor from the transformation.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
double getYTranslation()
throws IOException,
AutomationException
Returns the Y Translation (Move) factor from the transformation.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
double getRotation()
throws IOException,
AutomationException
Returns the Rotation factor from the transformation. Rotation is in radians.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void scale(double dx,
double dy)
throws IOException,
AutomationException
Scales (Multiplies) the existing affine transformation matrix by dx in the X direction and dy in the Y direction.
Note: The Move, Scale, and Rotate transformations are cumulative they add the transformation specified to any existing transformation in an AffineTransformation2D object.
dx - The dx (in)dy - The dy (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void setMoveOrigin(IPoint rhs1)
throws IOException,
AutomationException
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.
rhs1 - A reference to a com.esri.arcgis.geometry.IPoint (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void moveVector(ILine movementVector)
throws IOException,
AutomationException
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).
movementVector - A reference to a com.esri.arcgis.geometry.ILine (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void move(double dx,
double dy)
throws IOException,
AutomationException
Translates (Shifts) the existing affine transformation by adding dx units in the X direction and dy units in the Y direction.
Note: The Move, Scale, and Rotate transformations are cumulative they add the transformation specified to any existing transformation in an AffineTransformation2D object.
dx - The dx (in)dy - The dy (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void rotate(double da)
throws IOException,
AutomationException
Rotates the existing affine transformation by da radians around (0,0).
Note: The Move, Scale, and Rotate transformations are cumulative they add the transformation specified to any existing transformation in an AffineTransformation2D object.
da - The da (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void postMultiply(IAffineTransformation2D postTransform)
throws IOException,
AutomationException
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.
postTransform - A reference to a com.esri.arcgis.geometry.IAffineTransformation2D (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void preMultiply(IAffineTransformation2D preTransform)
throws IOException,
AutomationException
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.
preTransform - A reference to a com.esri.arcgis.geometry.IAffineTransformation2D (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
boolean isReflective()
throws IOException,
AutomationException
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.
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
void project(ISpatialReference newSpatialReference)
throws IOException,
AutomationException
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.
newSpatialReference - A reference to a com.esri.arcgis.geometry.ISpatialReference (in)
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||