Skip to content

SpatialReference Class

  • SpatialReference
  • class Esri::ArcGISRuntime::SpatialReference

    A spatial reference that defines how coordinates correspond to locations in the real world. More...

    Header: #include <SpatialReference.h>
    Since: Esri::ArcGISRuntime 100.0
    Inherits: Esri::ArcGISRuntime::JsonSerializable

    Public Functions

    SpatialReference()
    SpatialReference(const QString &wkText)
    SpatialReference(int wkid)
    SpatialReference(int wkid, int verticalWkid)
    SpatialReference(const Esri::ArcGISRuntime::SpatialReference &other)
    SpatialReference(Esri::ArcGISRuntime::SpatialReference &&other)
    virtual ~SpatialReference() override
    Esri::ArcGISRuntime::SpatialReference baseGeographic() const
    (since Esri::ArcGISRuntime 100.3) double convergenceAngle(const Esri::ArcGISRuntime::Point &point) const
    (since Esri::ArcGISRuntime 100.9) bool hasVertical() const
    bool isEmpty() const
    bool isGeographic() const
    bool isPannable() const
    bool isProjected() const
    (since Esri::ArcGISRuntime 200.8) double resolution() const
    (since Esri::ArcGISRuntime 200.8) double tolerance() const
    Esri::ArcGISRuntime::Unit unit() const
    (since Esri::ArcGISRuntime 200.8) double verticalResolution() const
    (since Esri::ArcGISRuntime 200.8) double verticalTolerance() const
    (since Esri::ArcGISRuntime 100.14) Esri::ArcGISRuntime::LinearUnit verticalUnit() const
    int verticalWkid() const
    QString wkText() const
    int wkid() const
    bool operator!=(const Esri::ArcGISRuntime::SpatialReference &other) const
    Esri::ArcGISRuntime::SpatialReference &operator=(Esri::ArcGISRuntime::SpatialReference &&other)
    Esri::ArcGISRuntime::SpatialReference &operator=(const Esri::ArcGISRuntime::SpatialReference &other)
    bool operator==(const Esri::ArcGISRuntime::SpatialReference &other) const

    Reimplemented Public Functions

    virtual QString toJson() const override
    (deprecated) virtual QJsonObject unknownJson() const override
    (deprecated) virtual QJsonObject unsupportedJson() const override

    Static Public Members

    Esri::ArcGISRuntime::SpatialReference fromJson(const QString &json)
    Esri::ArcGISRuntime::SpatialReference webMercator()
    Esri::ArcGISRuntime::SpatialReference wgs84()

    Detailed Description

    Instances of this class represent a specific coordinate system, identified by a well-known ID (WKID) number or well-known text (WKT) string. SpatialReferences are immutable.

    SpatialReferences allow disparate spatial data to be consistently viewed and analyzed together. Geometry, Layer, and GraphicsOverlay classes have a SpatialReference that determines the system in which the data is stored, and the SpatialReference of each GeoView determines how it displays the data it contains. There are two main categories of coordinate system that can be represented by a SpatialReference:

    • Geographic coordinate systems use a three-dimensional spherical surface to define locations on the earth. Coordinates are defined using angular units such as degrees.
    • Projected coordinate systems use flat, two-dimensional surface to define locations on the earth. Coordinates are defined using linear units such as meters or miles.

    In some cases, more than one WKID value can refer to the same spatial reference. For example, 3857 and 102100 both refer to WGS 1984 Web Mercator (Auxiliary Sphere). There can also be subtle differences between two WKT strings that represent the same spatial reference. To mitigate this situation, the SpatialReference class provides spatial reference comparison methods.

    Use the Create method to create a SpatialReference by specifying the WKID of a coordinate system, or use the members of SpatialReferences to return instances of the most commonly used SpatialReferences.

    SpatialReference ensures that you can accurately view, query, and analyze the layers of a GeoModel.

    The spatial reference value is available from a map or scene after loading has completed, and is immutable. If you want to set this value for a new map or scene, use the Map::Map(const Esri::ArcGISRuntime::SpatialReference&, QObject*) or Scene::Scene(Esri::ArcGISRuntime::SceneViewTilingScheme, QObject*) constructors.

    See Projected Coordinate Systems and Geographic Coordinate Systems for the list of supported spatial references and their corresponding definition strings.

    See https://developers.arcgis.com/documentation/spatial-references/ for more information about spatial references.

    Relevant samples:

    Member Function Documentation

    SpatialReference::SpatialReference()

    Default constructor. Constructs an empty SpatialReference object.

    The WKID and vertical WKID are set to -1 and the WKT is set to an empty string.

    [explicit] SpatialReference::SpatialReference(const QString &wkText)

    Constructor using a wkText (well-known text string) that represents the spatial reference.

    The wkid property is also initialized based on the provided wkText. You can use a wkText extracted from another SpatialReference. If the wkText parameter is a null or empty string, this method creates an empty SpatialReference.

    [explicit] SpatialReference::SpatialReference(int wkid)

    Constructor using a wkid (well-known ID) that represents the spatial reference.

    Tolerance is set to 0.0.

    SpatialReference::SpatialReference(int wkid, int verticalWkid)

    Constructor using a wkid (well-known ID) that represents the spatial reference and a verticalWkid (vertical coordinate system well-known ID).

    SpatialReference::SpatialReference(const Esri::ArcGISRuntime::SpatialReference &other)

    Copy constructor from other SpatialReference.

    [noexcept] SpatialReference::SpatialReference(Esri::ArcGISRuntime::SpatialReference &&other)

    Move constructor from other SpatialReference.

    [override virtual noexcept] SpatialReference::~SpatialReference()

    Destructor.

    Esri::ArcGISRuntime::SpatialReference SpatialReference::baseGeographic() const

    Returns the base geographic coordinate system if this is a projected coordinate system.

    [since Esri::ArcGISRuntime 100.3] double SpatialReference::convergenceAngle(const Esri::ArcGISRuntime::Point &point) const

    Returns the grid convergence in degrees for a spatial reference at a given point.

    The grid convergence is the angle between True-North and Grid-North at a point on a map. The grid convergence can be used to convert a horizontal direction expressed as an azimuth in a geographic coordinate system (relative to True-North) to a direction expressed as a bearing in a projected coordinate system (relative to Grid North), and vice versa.

    Sign convention

    The grid convergence returned by this method is positive when Grid North lies east of True-North. The following formula demonstrates how to obtain a bearing (b) from an azimuth (a) using the grid convergence (c) returned by this method:

    b = a - c

    This sign convention is sometimes named the Gauss-Bomford convention.

    Other notes

    • Returns 0 if the spatial reference is a geographic coordinate system.
    • Returns NaN if the point is outside the projection's horizon or on error.
    • If the point has no spatial reference, it is assumed to be in the given spatial reference.
    • If the point's spatial reference differs from the spatial reference given, its location is transformed automatically to the given spatial reference.

    This function was introduced in Esri::ArcGISRuntime 100.3.

    [static] Esri::ArcGISRuntime::SpatialReference SpatialReference::fromJson(const QString &json)

    Creates a new SpatialReference from an ArcGIS JSON representation.

    • json - The JSON text.

    [since Esri::ArcGISRuntime 100.9] bool SpatialReference::hasVertical() const

    Returns true if spatial reference has a vertical coordinate system set; false otherwise.

    A spatial reference can optionally include a definition for a vertical coordinate system (VCS), which can be used to interpret the z-values of a geometry. A VCS defines linear units of measure, the origin of z-values, and whether z-values are "positive up" (representing heights above a surface) or "positive down" (indicating that values are depths below a surface).

    A SpatialReference may have a VCS set, for example by calling the SpatialReference::SpatialReference(int, int) constructor. SpatialReference::verticalWkid, SpatialReference::wkText, and SpatialReference::verticalUnit provide more information about the specific VCS set on this instance.

    VCSs are used when projecting geometries using a HorizontalVerticalTransformation.

    This function was introduced in Esri::ArcGISRuntime 100.9.

    See also SpatialReference::verticalWkid and SpatialReference::verticalUnit.

    bool SpatialReference::isEmpty() const

    Returns true if this SpatialReference is empty.

    bool SpatialReference::isGeographic() const

    Returns true if this is a geographic coordinate system.

    bool SpatialReference::isPannable() const

    Returns true if this SpatialReference supports wrap around.

    bool SpatialReference::isProjected() const

    Returns true if this SpatialReference is a projected coordinate system.

    [since Esri::ArcGISRuntime 200.8] double SpatialReference::resolution() const

    Returns the minimum distance that separates unique x,y coordinate values when stored in an ArcGISFeatureTable.

    The resolution represents the detail in which a feature class records the location and shape of features, defining the number of decimal places stored. It is the minimum distance that separates x,y coordinate values in the Geometry of an ArcGISFeature. Any coordinates that differ by less than the resolution will be stored as the same coordinate value. The units of resolution are the units of the horizontal coordinate system (unit) defined when this spatial reference was created.

    A separate resolution, verticalResolution, is defined for the distance between z-values.

    Spatial references have default precision properties, and Esri strongly recommends using the default values in most cases. However some high-accuracy workflows customize the default values to preserve their data with higher precision. To store coordinates using a non-default resolution, create a new dataset that uses a custom resolution spatial reference - for example by setting TableDescription::spatialReference when creating a new geodatabase table. See SpatialReferenceBuilder for more information about creating spatial references with custom precision values.

    This function was introduced in Esri::ArcGISRuntime 200.8.

    See also SpatialReferenceBuilder and The properties of a spatial reference.

    [override virtual] QString SpatialReference::toJson() const

    Reimplements: JsonSerializable::toJson() const.

    Returns the SpatialReference as an ArcGIS json SpatialReference representation.

    [since Esri::ArcGISRuntime 200.8] double SpatialReference::tolerance() const

    Returns the minimum distance that determines if two x,y coordinates are considered to be at the same location for relational and topological GeometryEngine operations.

    This value is used in relational and topological GeometryEngine operations when determining whether two points are close enough, in the horizontal plane, to be considered as the same coordinate value when calculating the result. The units of tolerance are the units of the horizontal coordinate system (unit) defined when this spatial reference was created.

    A separate tolerance, verticalTolerance, is defined for the difference between z-values.

    Spatial references have default precision properties, and Esri strongly recommends using the default values in most cases. However some high-accuracy workflows customize the default values to work with a higher precision. To perform operations using a non-default tolerance, create a Geometry with your custom tolerance spatial reference, and pass that geometry to the relational or topological operation. See SpatialReferenceBuilder for more information about creating spatial references with custom precision values.

    This function was introduced in Esri::ArcGISRuntime 200.8.

    See also SpatialReferenceBuilder and The properties of a spatial reference.

    Esri::ArcGISRuntime::Unit SpatialReference::unit() const

    The unit of measure for the horizontal coordinate system of this spatial reference.

    Returns a null Unit if the spatial reference is invalid.

    Also the unit of measure for tolerance and resolution.

    [since Esri::ArcGISRuntime 200.8] double SpatialReference::verticalResolution() const

    Returns the minimum distance that separates unique z-values when stored in an ArcGISFeatureTable.

    The vertical resolution represents the detail in which a feature class records the location and shape of features, defining the number of decimal places or significant digits stored. It is the minimum distance that separates z-values in the Geometry of an ArcGISFeature. Any z-values that differ by less than the vertical resolution will be stored as the same z-value. The units of verticalResolution are the units of the vertical coordinate system (verticalUnit) defined when this spatial reference was created, if one was set.

    A separate resolution, resolution, is defined for the distance between x,y coordinates.

    Spatial references have default precision properties, and Esri strongly recommends using the default values in most cases. However some high-accuracy workflows customize the default values to preserve their data with higher precision. To store coordinates using a non-default resolution, create a new dataset that uses a custom resolution spatial reference - for example by setting TableDescription::spatialReference when creating a new geodatabase table. See SpatialReferenceBuilder for more information about creating spatial references with custom precision values.

    This function was introduced in Esri::ArcGISRuntime 200.8.

    See also SpatialReferenceBuilder and The properties of a spatial reference.

    [since Esri::ArcGISRuntime 200.8] double SpatialReference::verticalTolerance() const

    Returns the minimum distance that determines if two z-values are considered to be at the same location for GeometryEngine operations that compare z-values.

    This value is used in relational and topological GeometryEngine operations when determining whether two z-values are close enough to be considered as the same value when calculating the result. The units of verticalTolerance are the units of the vertical coordinate system (verticalUnit) defined when this spatial reference was created, if one was set.

    Note that verticalTolerance is currently only used by GeometryEngine::simplify(const Esri::ArcGISRuntime::Geometry&) and when the input is a z-aware Polyline; it is not used in other methods.

    A separate tolerance, tolerance, is defined for the difference between x,y coordinates.

    Spatial references have default precision properties, and Esri strongly recommends using the default values in most cases. However some high-accuracy workflows customize the default values to work with a higher precision. To perform operations using a non-default tolerance, create a Geometry with your custom tolerance spatial reference, and pass that geometry to the operation. See SpatialReferenceBuilder for more information about creating spatial references with custom precision values.

    This function was introduced in Esri::ArcGISRuntime 200.8.

    See also SpatialReferenceBuilder and The properties of a spatial reference.

    [since Esri::ArcGISRuntime 100.14] Esri::ArcGISRuntime::LinearUnit SpatialReference::verticalUnit() const

    Returns the unit of measure for the vertical coordinate system of this spatial reference.

    Will return an empty unit if hasVertical is false.

    Also the unit of measure for verticalTolerance and verticalResolution.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    int SpatialReference::verticalWkid() const

    Returns the vertical coordinate system well-known spatial reference identifier (WKID).

    The well-known ID for the vertical coordinate system (VCS), or 0 if the spatial reference has no VCS or has a custom VCS.

    Note: In versions prior to Esri::ArcGISRuntime 100.9. This method returned -1 if no vertical WKID had been specified.

    [static] Esri::ArcGISRuntime::SpatialReference SpatialReference::webMercator()

    Returns a spatial reference representing the WebMercator coordinate system (WKID:102100)

    [static] Esri::ArcGISRuntime::SpatialReference SpatialReference::wgs84()

    Returns a spatial reference representing the WGS84 coordinate system (WKID:4326).

    QString SpatialReference::wkText() const

    Returns the well-known text for the horizontal and vertical coordinate systems.

    If this coordinate system can only be represented in WKT2 format this property returns an empty string.

    Returns the well-known text for the horizontal and vertical coordinate system. Returns an empty string if no WKT has been specified or if the SpatialReference is invalid.

    This method always returns the minimal text representation that uniquely identifies a given SpatialReference.

    int SpatialReference::wkid() const

    Returns the well-known spatial reference identifier (WKID).

    The well-known ID for the horizontal coordinate system, or 0 if the spatial reference has a custom horizontal coordinate system. Returns 0 if no WKID has been specified.

    Note: In versions prior to Esri::ArcGISRuntime 100.9. This method returned -1 if no WKID had been specified.

    bool SpatialReference::operator!=(const Esri::ArcGISRuntime::SpatialReference &other) const

    Inequality operator. Returns true if this object and other are not equal.

    See also SpatialReference::operator==.

    [noexcept] Esri::ArcGISRuntime::SpatialReference &SpatialReference::operator=(Esri::ArcGISRuntime::SpatialReference &&other)

    Move operator from other SpatialReference.

    Esri::ArcGISRuntime::SpatialReference &SpatialReference::operator=(const Esri::ArcGISRuntime::SpatialReference &other)

    Assignment operator from other SpatialReference.

    bool SpatialReference::operator==(const Esri::ArcGISRuntime::SpatialReference &other) const

    Tests and returns true if this object is equal to a second SpatialReference object.

    • other - The 2nd spatial reference to check to see if equal to the 1st.

    This is the only valid way to compare two spatial references. Comparing individual attributes for two objects can return misleading results and should be avoided.

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