ArcGIS Runtime SDK for iOS: AGSSpatialReference Class Reference
ArcGIS Runtime SDK for iOS  100.15
AGSSpatialReference Class Reference

Description

Represents the spatial reference of a geometry.

A spatial reference determines how map coordinates, or the x,y,z-coordinates in the vertices of geometries, correspond to locations in real-world space. Therefore, it is very important to associate geometries representing spatial data with corresponding spatial references.

Each spatial reference can be represented by either a well-known ID (WKID), or a well-known text (WKT). Spatial references define the spatial properties of a geometry, for instance the coordinate system it uses. There are 2 broad classes of coordinate systems - Geographic & Projected. A Geographic Coordinate system uses a 3-dimensional spherical surface to define locations on the earth. A Projected Coordinate system on the other hand uses a flat, 2-dimensional surface.

Learn more about coordinate systems

Since
100
See also
AGSGeometry for geometry types
+ projectGeometry:toSpatialReference: (AGSGeometryEngine) to project geometries from one spatial reference to another
Inheritance diagram for AGSSpatialReference:
AGSObject <AGSJSONSerializable>

Instance Methods

(double) - convergenceAngleWithPoint:
 
(nullable instancetype) - initWithWKID:
 
(nullable instancetype) - initWithWKID:verticalWKID:
 
(nullable instancetype) - initWithWKText:
 
(BOOL) - isEqualToSpatialReference:
 
(nullable id) - toJSON:
 

Class Methods

(nullable id< AGSJSONSerializable >) + fromJSON:error:
 
(nullable instancetype) + spatialReferenceWithWKID:
 
(nullable instancetype) + spatialReferenceWithWKID:verticalWKID:
 
(nullable instancetype) + spatialReferenceWithWKText:
 
(AGSSpatialReference *) + webMercator
 
(AGSSpatialReference *) + WGS84
 

Properties

AGSSpatialReferencebaseGeographic
 
BOOL geographic
 
BOOL hasVertical
 
BOOL pannable
 
BOOL projected
 
AGSUnitunit
 
NSDictionary< NSString *, id > * unknownJSON
 
NSDictionary< NSString *, id > * unsupportedJSON
 
AGSLinearUnitverticalUnit
 
NSInteger verticalWKID
 
NSInteger WKID
 
NSString * WKText
 

Method Documentation

◆ convergenceAngleWithPoint:

- (double) convergenceAngleWithPoint: (AGSPoint *)  point

Calculate the grid convergence for a spatial reference at a given point.

Remarks

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 will be transformed automatically to the given spatial reference
    Parameters
    pointThe point at which to calculate the convergence angle.
    Returns
    The grid convergence in degrees.
    Since
    100.3

◆ fromJSON:error:

+ (nullable id<AGSJSONSerializable>) fromJSON: (id)  JSONObject
error: (NSError **)  error 
staticrequiredinherited

Initializes and returns an object from its JSON representation.

Parameters
JSONObjectNSDictionary or NSArray containing the JSON.
errorencountered during the operation, if any.
Since
100

◆ initWithWKID:

- (nullable instancetype) initWithWKID: (NSInteger)  WKID

Creates a spatial reference with the given well-known ID (WKID).

Parameters
WKIDThe well-known ID.
Since
100

◆ initWithWKID:verticalWKID:

- (nullable instancetype) initWithWKID: (NSInteger)  WKID
verticalWKID: (NSInteger)  verticalWKID 

Creates a spatial reference with the given well-known ID (WKID) and a vertical well-known ID.

Since
100

◆ initWithWKText:

- (nullable instancetype) initWithWKText: (NSString *)  WKText

Creates a spatial reference with the given well-known text (WKT).

Parameters
WKTextThe well-known text.
Since
100

◆ isEqualToSpatialReference:

- (BOOL) isEqualToSpatialReference: (AGSSpatialReference *)  other

Compares whether two spatial references are equal. They are equal if they have the same WKID or #WKT.

Parameters
otherThe other spatial reference to compare this one to.
Returns
YES if the spatial references are equal.
Since
100

◆ spatialReferenceWithWKID:

+ (nullable instancetype) spatialReferenceWithWKID: (NSInteger)  WKID

Creates a spatial reference with the given well-known ID (WKID).

Parameters
WKIDThe well-known ID
Returns
A new spatial reference object.
Since
100

◆ spatialReferenceWithWKID:verticalWKID:

+ (nullable instancetype) spatialReferenceWithWKID: (NSInteger)  WKID
verticalWKID: (NSInteger)  verticalWKID 

Creates a spatial reference with the given well-known ID (WKID) and a vertical well-known ID.

Parameters
WKIDThe well-known ID of the horizontal coordinate system. Must be a positive value.
verticalWKIDThe well-known ID of the vertical coordinate system. Must be a non negative value.
Returns
A new spatial reference object.
Since
100

◆ spatialReferenceWithWKText:

+ (nullable instancetype) spatialReferenceWithWKText: (NSString *)  WKText

Creates a spatial reference with the given well-known text (WKT).

Parameters
WKTextThe well-known text
Returns
A new spatial reference object.
Since
100

◆ toJSON:

- (nullable id) toJSON: (NSError **)  error
requiredinherited

Returns JSON representation for this object.

Parameters
errorencountered during the operation, if any.
Returns
NSDictionary or NSArray containing the JSON.
Since
100

Reimplemented in AGSPortalItem.

◆ webMercator

+ (AGSSpatialReference*) webMercator

A spatial reference representing the Web Mercator coordinate system (WKID:3857, equivalent to WKID:102113).

Since
100

◆ WGS84

+ (AGSSpatialReference*) WGS84

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

Since
100

Property Documentation

◆ baseGeographic

- (AGSSpatialReference*) baseGeographic
readnonatomicstrong

If the given spatial reference is a projected coordinate system, then this will return the geographic coordinate system of that system.

If the spatial reference is a projected coordinate system, then a spatial reference object representing the underlying geographic coordinate system is returned. Every projected coordinate system has an underlying geographic coordinate system. If the spatial reference is a geographic coordinate system, then a reference to itself is returned. If the spatial reference is a local spatial reference, a nil is returned.

Since
100.0

◆ geographic

- (BOOL) geographic
readnonatomicassign

YES if spatial reference is a Geographic Coordinate System.

Since
100.0

◆ hasVertical

- (BOOL) hasVertical
readnonatomicassign

YES if spatial reference has a vertical coordinate system set; NO 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).

An AGSSpatialReference may have a VCS set, for example by calling the initWithWKID:verticalWKID: constructor. AGSSpatialReference::verticalWKID and AGSSpatialReference::WKText provide more information about the specific VCS set on this instance.

VCSs are used when projecting geometries using an AGSHorizontalVerticalTransformation.

See also
AGSSpatialReference::verticalWKID, AGSSpatialReference::verticalUnit
Since
100.9

◆ pannable

- (BOOL) pannable
readnonatomicassign

YES if coordinate system is horizontally pannable.

Since
100.0

◆ projected

- (BOOL) projected
readnonatomicassign

YES if spatial reference is a Projected Coordinate System.

Since
100.0

◆ unit

- (AGSUnit*) unit
readnonatomicstrong

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

Since
100

◆ unknownJSON

- (NSDictionary<NSString*,id>*) unknownJSON
readrequirednonatomiccopyinherited

A dictionary of values that was in the source JSON but was unparsed by API.

Returns
NSDictionary containing the unknown JSON.
Since
100

◆ unsupportedJSON

- (NSDictionary<NSString*,id>*) unsupportedJSON
readnonatomiccopyinherited

A dictionary of values that are supported by the REST API, but not exposed through the SDK API.

Returns
NSDictionary containing the unsupported JSON.
Since
100

◆ verticalUnit

- (AGSLinearUnit*) verticalUnit
readnonatomicstrong

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

Is nil if the AGSSpatialReference::hasVertical property is NO.

Since
100.14

◆ verticalWKID

- (NSInteger) verticalWKID
readnonatomicassign

The well-known ID for the vertical coordinate system.

The well-known ID for the vertical coordinate system (VCS) set on this AGSSpatialReference.

Returns 0 if there is no VCS set, if there is a custom VCS set.

See also
- initWithWKID:verticalWKID:
Since
100.0

◆ WKID

- (NSInteger) WKID
readnonatomicassign

The well-known ID for the horizontal coordinate system.

The well-known ID for the horizontal coordinate system. Will return 0 if an error occurs.

Since
100

◆ WKText

- (NSString*) WKText
readnonatomiccopy

The well-known text of the spatial reference.

Since
100