Class HorizontalVerticalTransformationStep
- java.lang.Object
-
- com.esri.arcgisruntime.geometry.HorizontalVerticalTransformationStep
-
public final class HorizontalVerticalTransformationStep extends java.lang.Object
Represents a step in the process of transforming between horizontal and/or vertical datums.A horizontal-vertical transformation step can be constructed from a well-known ID (WKID) that represents a known horizontal (geographic) or vertical transformation, using the
create(int)
factory method. Alternatively, a custom transformation can be constructed from well-known text usingcreate(String)
. After creating a HorizontalVerticalTransformationStep, one or more steps can be added to aHorizontalVerticalTransformation
, and used toproject
a Geometry.// Create a 3D geometry located in London, UK, with British National Grid spatial reference with Newlyn // vertical coordinate system Point britishNationalGrid3dPt = new Point(538985.355, 177329.516, 154.0, SpatialReference.create(27700, 5701)); // Project the point to WGS84, with WG84 ellipsoidal vertical coordinate system, using the transformation SpatialReference wgsVcsSr = SpatialReference.create(4326, 115700) Point wgs84Pt = (Point) GeometryEngine.project(britishNationalGrid3dPt, wgsVcsSr, transform);
This SDK supports thousands of horizontal and vertical transformation WKIDs, which are documented in the developer Guide on the ArcGIS for Developers site.
Alternatively, horizontal-vertical transformations can be created by using the methods on
TransformationCatalog
.Some transformations rely on supporting files to be present in a known location (see
TransformationCatalog.getProjectionEngineDirectory()
). UseisMissingProjectionEngineFiles()
to identify transformations for which the supporting files are missing. If true, then the transformation cannot be used to project geometries. UsegetProjectionEngineFilenames()
to identify which files are missing for this step.Horizontal-vertical transformation steps are immutable. Use
getInverse()
to get a new step representing the same transformation in the opposite direction.
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static HorizontalVerticalTransformationStep
create(int wkid)
Creates a HorizontalVerticalTransformationStep instance from the given well-known ID (WKID).static HorizontalVerticalTransformationStep
create(java.lang.String wkText)
Creates a HorizontalVerticalTransformationStep instance from the given well-known text (WKT) string.boolean
equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this HorizontalVerticalTransformationStep.HorizontalVerticalTransformationStep
getInverse()
Gets the inverse of this horizontal-vertical transformation step.java.util.List<java.lang.String>
getProjectionEngineFilenames()
Gets the filenames that comprise the supporting dataset for this transformation.int
getWkid()
Gets the well-known ID (WKID) representation of this HorizontalVerticalTransformationStep.java.lang.String
getWkText()
Gets a string containing the well-known text representation of this HorizontalVerticalTransformationStep.int
hashCode()
boolean
isInverse()
Indicates if this transformation step instance is an inverted transformation.boolean
isMissingProjectionEngineFiles()
Indicates if any files needed by the Projection Engine for this horizontal-vertical transformation step are missing from the local file system.
-
-
-
Method Detail
-
create
public static HorizontalVerticalTransformationStep create(int wkid)
Creates a HorizontalVerticalTransformationStep instance from the given well-known ID (WKID).If the WKID defines a grid-based transformation, the transformation can only be used if the supporting files are found on the local file system. See
isMissingProjectionEngineFiles()
.Occasionally, WKIDs may change, and older codes may be deprecated in favor of a new code. Both old (deprecated) and new (latest) WKIDs continue to work for instantiation, as long as they are supported by the Projection Engine. The
getWkid()
property will return the new (latest) WKID code.- Parameters:
wkid
- a WKID of the horizontal-vertical transformation step to create- Returns:
- a HorizontalVerticalTransformationStep instance
- Throws:
ArcGISRuntimeException
- if wkid is invalid (is not a supported WKID). The list of supported WKIDs is documented in the developer Guide.- Since:
- 100.9.0
- See Also:
getWkid()
-
create
public static HorizontalVerticalTransformationStep create(java.lang.String wkText)
Creates a HorizontalVerticalTransformationStep instance from the given well-known text (WKT) string.Some users adjust the components of a transformation to suit their specific needs. These custom transformations use the existing methods of transformation (Position Vector, Geocentric_Translation, and so on) but have different parameter values than the well-known definitions. Create a custom horizontal-vertical transformation object by passing in a text string containing your custom transformation expressed in WKT format. The resulting transformation will have a WKID of zero.
If the WKT defines a grid-based transformation, the transformation can only be used if the supporting files are found on the local file system. See
isMissingProjectionEngineFiles()
.- Parameters:
wkText
- a string containing a WKT representation of a HorizontalVerticalTransformationStep- Returns:
- a HorizontalVerticalTransformationStep instance
- Throws:
java.lang.IllegalArgumentException
- if wkText is null or emptyArcGISRuntimeException
- if wkText is invalid (is not a well-formed transformation text string)- Since:
- 100.9.0
- See Also:
getWkText()
-
getInverse
public HorizontalVerticalTransformationStep getInverse()
Gets the inverse of this horizontal-vertical transformation step.The inverse of a transformation converts coordinates using the same method and parameters, but in the opposite direction of the original object. For example if the original object represents NAD_1983_HARN_To_NAD_1983_NSRS2007_1 transformation, then the inverse will transform from NAD83 (NSRS 2007) to NAD83 (HARN).
To check the input and output SpatialReferences of a transformation step, add the step to a new HorizontalVerticalTransformation, and check
DatumTransformation.getInputSpatialReference()
andDatumTransformation.getOutputSpatialReference()
.- Returns:
- the inverse of this horizontal-vertical transformation step or null if the transformation is not invertible
- Since:
- 100.9.0
-
getWkText
public java.lang.String getWkText()
Gets a string containing the well-known text representation of this HorizontalVerticalTransformationStep.- Returns:
- a well-known text representation of this HorizontalVerticalTransformationStep
- Since:
- 100.9.0
-
getWkid
public int getWkid()
Gets the well-known ID (WKID) representation of this HorizontalVerticalTransformationStep.The list of supported WKIDs is documented in the developer Guide.
Occasionally, WKIDs may change, and an older code may be deprecated in favor of a new code. This property returns the new (latest) WKID code.
- Returns:
- a WKID representation of this HorizontalVerticalTransformationStep, or 0 if this transformation was created from a custom well-known text string, -1 on error.
- Since:
- 100.9.0
-
isInverse
public boolean isInverse()
Indicates if this transformation step instance is an inverted transformation.Transformations have a specific direction that is indicated by the
getWkText()
value. An inverted transformation is used to transform geometries in the opposite direction to that indicated by the Well-Known Text. The GeographicTransformation hasDatumTransformation.getInputSpatialReference()
andDatumTransformation.getOutputSpatialReference()
properties that respect the inverse value of the contained transformation(s).- Returns:
- true if this transformation step instance is an inverted transformation; false otherwise
- Since:
- 100.9.0
-
isMissingProjectionEngineFiles
public boolean isMissingProjectionEngineFiles()
Indicates if any files needed by the Projection Engine for this horizontal-vertical transformation step are missing from the local file system.If true, this indicates that this transformation step is not currently usable; in this case, using the
GeometryEngine.project(Geometry, SpatialReference, DatumTransformation)
method with a transform including this step will throw an exception. In order for a transform step to be usable, two conditions must be satisfied:- In order for any Projection Engine files to be found, the root directory must have been successfully set
before any transforms are used, using
TransformationCatalog.setProjectionEngineDirectory(String)
. For Java SE, if the default Projection Engine directory is found during Runtime initialization, explicitly setting the location is not required. - The specific Projection Engine files required by this step must be found within the Projection Engine
directory. Use
getProjectionEngineFilenames()
to find out the filenames required by this step.
If Projection Engine files are installed at run time, the app will need to be restarted for this value to change.
- Returns:
- true if any required files are missing; false otherwise
- Since:
- 100.9.0
- In order for any Projection Engine files to be found, the root directory must have been successfully set
before any transforms are used, using
-
getProjectionEngineFilenames
public java.util.List<java.lang.String> getProjectionEngineFilenames()
Gets the filenames that comprise the supporting dataset for this transformation.Projection Engine datasets are used by grid-based transformations; equation-based transformations do not require any supporting files.
Each filename includes the path relative to
TransformationCatalog.getProjectionEngineDirectory()
, indicating the subdirectory (or directories) and the filename including extension.- Returns:
- an unmodifiable List of the filenames that comprise the supporting dataset, or an empty List if this step does not require supporting files (is an equation-based transformation).
- Since:
- 100.9.0
-
equals
public boolean equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this HorizontalVerticalTransformationStep. Returns true if the two transformation steps use the same method of transformation, and operate in the same direction.- Overrides:
equals
in classjava.lang.Object
- Parameters:
obj
- the reference HorizontalVerticalTransformationStep with which to compare- Returns:
- true if this object has the same values as the obj argument; false otherwise
- Since:
- 100.9.0
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
-