CoordinateFormatter Class

  • CoordinateFormatter
  • class Esri::ArcGISRuntime::CoordinateFormatter

    Converts between points and formatted coordinate notation strings. More...

    Header: #include <CoordinateFormatter.h>
    Since: Esri::ArcGISRuntime 100.1
    Inherits: Esri::ArcGISRuntime::Object

    Public Functions

    virtual ~CoordinateFormatter() override

    Static Public Members

    Esri::ArcGISRuntime::Point fromGars(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference, Esri::ArcGISRuntime::GarsConversionMode garsConversionMode)
    Esri::ArcGISRuntime::Point fromGeoRef(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference)
    Esri::ArcGISRuntime::Point fromLatitudeLongitude(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference)
    Esri::ArcGISRuntime::Point fromMgrs(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference, Esri::ArcGISRuntime::MgrsConversionMode mgrsConversionMode)
    Esri::ArcGISRuntime::Point fromUsng(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference)
    Esri::ArcGISRuntime::Point fromUtm(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference, Esri::ArcGISRuntime::UtmConversionMode utmConversionMode)
    Esri::ArcGISRuntime::CoordinateFormatter *instance()
    QString toGars(const Esri::ArcGISRuntime::Point &point)
    QString toGeoRef(const Esri::ArcGISRuntime::Point &point, int precision)
    QString toLatitudeLongitude(const Esri::ArcGISRuntime::Point &point, Esri::ArcGISRuntime::LatitudeLongitudeFormat format, int decimalPlaces)
    QString toMgrs(const Esri::ArcGISRuntime::Point &point, Esri::ArcGISRuntime::MgrsConversionMode mgrsConversionMode, int precision, bool addSpaces)
    QString toUsng(const Esri::ArcGISRuntime::Point &point, int precision, bool addSpaces)
    QString toUtm(const Esri::ArcGISRuntime::Point &point, Esri::ArcGISRuntime::UtmConversionMode utmConversionMode, bool addSpaces)

    Detailed Description

    Supported notations are:

    • Latitude-longitude in degrees.
    • Global Area Reference System (GARS).
    • World Geographic Reference System (GEOREF).
    • Military Grid Reference System (MGRS).
    • United States National Grid (USNG).
    • Universal Transverse Mercator (UTM).

    Member Function Documentation

    [override virtual] CoordinateFormatter::~CoordinateFormatter()

    Destructor.

    [static] Esri::ArcGISRuntime::Point CoordinateFormatter::fromGars(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference, Esri::ArcGISRuntime::GarsConversionMode garsConversionMode)

    Parses a coordinate in Global Area Reference System (GARS) notation, and returns a Point representing that location.

    • coordinates - The GARS notation string for the coordinate.
    • spatialReference - A spatial reference that defines the datum and ellipsoid referenced by the GARS coordinate.
    • garsConversionMode - Select whether the returned point's location represents the south-west corner of the GARS cell the coordinate lies within, or its center.

    The spatial reference provided must have an ellipsoid and datum matching those used by the source of the GARS string. If no spatial reference is provided, it is assumed the GARS string is referenced to WGS 84. The GARS string must not contain any whitespace. Returns an empty Point on error, including when the given string is not valid GARS notation.

    Returns a point with the location from the GEOREF string in the spatial reference provided. Returns an empty Point if the input text could not be parsed.

    GARS notation examples
    354ND
    354ND22

    [static] Esri::ArcGISRuntime::Point CoordinateFormatter::fromGeoRef(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference)

    Parses a coordinate in World Geographic Reference System (GEOREF) notation, and returns a Point representing that location.

    • coordinates - The GEOREF notation string for the coordinate.
    • spatialReference - A spatial reference that defines the datum and ellipsoid referenced by the GEOREF coordinate.

    Returns a point with the location from the GEOREF string in the spatial reference provided. Returns an empty Point if the input text could not be parsed.

    The spatial reference provided must have an ellipsoid and datum matching those used by the source of the GEOREF string. If no spatial reference is provided, it is assumed the GEOREF string is referenced to WGS 84. The GEOREF string may contain leading and trailing whitespace.

    GEOREF notation examples
    MKML5056
    MKML50285665

    Returns an empty Point on error, including when the given string is not valid GEOREF notation.

    [static] Esri::ArcGISRuntime::Point CoordinateFormatter::fromLatitudeLongitude(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference)

    Parses a coordinate in latitude-longitude notation, and returns a Point representing that location.

    • coordinates - The latitude-longitude notation string for the coordinate. The coordinate may use decimal degrees, degrees and decimal minutes, or degrees-minutes-seconds format.
    • spatialReference - A spatial reference that defines the datum and ellipsoid referenced by the latitude-longitude coordinate.

    Returns a point with the location from the latitude/longitude string in the spatial reference provided. Returns an empty Point if the input text could not be parsed.

    The spatial reference provided must have an ellipsoid and datum matching those used by the source of the latitude-longitude string. If no spatial reference is provided, it is assumed the latitude-longitude coordinates are referenced to WGS 84.

    Supported characters

    SymbolCharacterNameUnicode numberHTML code
    Degree*AsteriskU+002A&#42;
    ^Circumflex AccentU+005E&#94;
    ~TildeU+007E&#126;
    °Degree SignU+00B0&#176;
    ºMasculine Ordinal IndicatorU+00BA&#186;
    ˚Ring AboveU+02DA&#730;
    Superscript ZeroU+2070&#8304;
    Minute'ApostropheU+0027&#39;
    ᾿Right Single Quotation MarkU+2019&#8127;
    PrimeU+2032&#8242;
    Second"Quotation MarkU+0022&#34;
    ˝Double Acute AccentU+02DD&#733;
    Right Double Quotation MarkU+201D&#8221;
    Double PrimeU+2033&#8243;

    The latitude-longitude string may contain leading and trailing whitespace, and may also contain a space, comma, or vertical bar symbol to separate the latitude from the longitude. It may also contain the characters 'N', 'S', 'E' and 'W', or use a minus (-) symbol to indicate the hemisphere of each value.

    Latitude-longitude notation examples
    55 56 39.123N 003 09 43.034W
    55°56′39″N 3°09′43″W
    55~56.65205', -003~09.71723'
    55.9442008* | -3.1619539*

    Returns an empty Point on error, including when the given string cannot be interpreted.

    [static] Esri::ArcGISRuntime::Point CoordinateFormatter::fromMgrs(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference, Esri::ArcGISRuntime::MgrsConversionMode mgrsConversionMode)

    Parses a coordinate in Military Grid Reference System (MGRS) notation, and returns a Point representing that location.

    • coordinates - The MGRS notation string for the coordinate.
    • spatialReference - A spatial reference that defines the datum and ellipsoid referenced by the MGRS coordinate.
    • mgrsConversionMode - The mode used by the given MGRS coordinates.

    Returns a point with the location from the MGRS string in the spatial reference provided. The spatial reference provided must have an ellipsoid and datum matching those used by the source of the MGRS string. If no spatial reference is provided, it is assumed the MGRS string is referenced to WGS 84. Returns an empty Point if the input text could not be parsed.

    For an explanation of the different modes for interpreting an MGRS notation string, please see MgrsConversionMode. Note that the choice between zone 01 and 60 has no impact when reading from an MGRS notation string.

    The MGRS string can contain leading and trailing whitespace and can have whitespace between the grid zone designator, the 100km square identifier, and the numerical eastings and northings.

    MGRS notation examples
    30UVG898998
    30UVG 89885 99877

    Returns an empty Point on error, including when the given string is not valid MGRS notation.

    See also MgrsConversionMode.

    [static] Esri::ArcGISRuntime::Point CoordinateFormatter::fromUsng(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference)

    Parses a coordinate in United States National Grid (USNG) notation, and returns a Point representing that location.

    • coordinates - The USNG notation string for the coordinate.
    • spatialReference - A spatial reference that defines the datum and ellipsoid referenced by the USNG coordinate.

    Return a point with the location from the USNG string in the spatial reference provided. Returns an empty Point if the input text could not be parsed.

    The spatial reference provided must have an ellipsoid and datum matching those used by the source of the USNG string. If no spatial reference is provided and the USNG string is suffixed with "(NAD 27)", it is assumed the USNG string is referenced to NAD 27. If no spatial reference is provided and no such suffix exists, it is assumed the USNG string is referenced to WGS 84.

    The USNG string can contain leading and trailing whitespace and can have whitespace between the grid zone designator, the 100km square identifier and the numerical eastings and northings.

    USNG notation examples
    13TFJ 23 59
    13TFJ2374159574

    Returns an empty Point on error, including when the given string is not valid USNG notation.

    See also MgrsConversionMode.

    [static] Esri::ArcGISRuntime::Point CoordinateFormatter::fromUtm(const QString &coordinates, const Esri::ArcGISRuntime::SpatialReference &spatialReference, Esri::ArcGISRuntime::UtmConversionMode utmConversionMode)

    Parses a coordinate in Universal Transverse Mercator (UTM) notation, and returns a Point representing that location.

    • coordinates - The UTM notation string for the coordinate.
    • spatialReference - A spatial reference that defines the datum and ellipsoid referenced by the UTM coordinate.
    • utmConversionMode - The latitude notation scheme used by the given UTM coordinate, either a latitudinal band, or a hemisphere designator.

    Returns a point with the location from the UTM string in the spatial reference provided. Returns an empty Point on error, including when the given string is not valid UTM notation.

    The spatial reference provided must have an ellipsoid and datum matching those used by the source of the UTM string. If no spatial reference is provided, it is assumed the UTM string is referenced to WGS 84.

    The UTM string can contain leading and trailing whitespace and can have whitespace between the zone and latitude designator and the numerical eastings and northings.

    UTM notation examples
    30U 489885 6199877
    30U4898856199877
    30N 489885 6199877 (using N/S indicator)
    489885.32,6199877.36,30U (this form supports sub-meter precision)

    Returns an empty Point on error, including when the given string is not valid UTM notation.

    See also MgrsConversionMode.

    [static] Esri::ArcGISRuntime::CoordinateFormatter *CoordinateFormatter::instance()

    The instance getter for CoordinateFormatter.

    This can be used to check for errors.

    See also Object::errorOccurred.

    [static] QString CoordinateFormatter::toGars(const Esri::ArcGISRuntime::Point &point)

    Returns a formatted coordinate in Global Area Reference System (GARS) notation representing the given point's location.

    • point - The location to be represented in GARS notation. The point must have a spatial reference.

    Returns a GARS notation string representing the GARS cell containing the given point. Returns an empty QString on error.

    [static] QString CoordinateFormatter::toGeoRef(const Esri::ArcGISRuntime::Point &point, int precision)

    Returns a formatted coordinate in World Geographic Reference System (GEOREF) notation representing the given point's location.

    • point - The location to be represented in GEOREF notation. The point must have a spatial reference.
    • precision - The precision with which to represent the coordinate. The 'precision' should be in the interval [0, 9].

    Returns A GEOREF notation string representing the position of the given point. Returns an empty QString on error.

    The precision value controls the number of digits used to represent the fractional part of the coordinate's latitude and longitude, expressed in minutes. For example:

    PrecisionExample outputAngular precisionApprox precision*
    0MKML50561min2km
    1MKML50561min2km
    2MKML50561min2km
    3MKML5025660.1min200m
    4MKML502856650.01min20m
    5MKML50282566520.001min2m

    At the equator to 1 significant figure. The 'precision' should be in the interval [0, 9]. The point must have a spatial reference. Returns an empty QString on error.

    [static] QString CoordinateFormatter::toLatitudeLongitude(const Esri::ArcGISRuntime::Point &point, Esri::ArcGISRuntime::LatitudeLongitudeFormat format, int decimalPlaces)

    Returns a formatted coordinate in latitude-longitude notation representing the given point's location.

    • point - The location to be represented as a formatted latitude-longitude string. The point must have a spatial reference.
    • format - The mode to use when formatting the latitude-longitude string.
    • decimalPlaces - The number of decimal places to use.

    Returns a string representing the latitude-longitude of the given point. Returns an empty QString on error.

    The latitude-longitude string contains a space separating the latitude from the longitude value, and the characters 'N' or 'S', and 'E' and 'W', to indicate the hemisphere of each value. The string will also contain spaces separating the components (degrees, minutes, seconds) of each value. The precision of the output is controlled by both the 'format' and 'decimal_places' parameters. For example:

    decimalPlacesLatitudeLongitudeFormatExample outputAngular precisionApprox precision*
    0DecimalDegrees056N 0003W1deg100km
    1DecimalDegrees55.9N 003.2W0.1deg10km
    2DecimalDegrees55.94N 003.16W0.01deg1km
    3DecimalDegrees55.944N 003.162W0.001deg100m
    0DegreesDecimalMinutes55 057N 003 010W1min2km
    1DegreesDecimalMinutes55 56.7N 003 09.7W0.1min200m
    2DegreesDecimalMinutes55 56.65N 003 09.72W0.01min20m
    3DegreesDecimalMinutes55 56.650N 003 09.717W0.001min2m
    0DegreesMinutesSeconds55 56 039N 003 09 043W1sec30m
    1DegreesMinutesSeconds55 56 39.1N 003 09 43.0W0.1sec3m
    2DegreesMinutesSeconds55 56 39.12N 003 09 43.03W0.01sec300mm
    3DegreesMinutesSeconds55 56 39.123N 003 09 43.034W0.001sec30mm

    * At the equator to 1 significant figure. The 'decimal_places' should be in the interval [0, 16]. The point must have a spatial reference. Returns nullptr on error.

    See also LatitudeLongitudeFormat.

    [static] QString CoordinateFormatter::toMgrs(const Esri::ArcGISRuntime::Point &point, Esri::ArcGISRuntime::MgrsConversionMode mgrsConversionMode, int precision, bool addSpaces)

    Returns a formatted coordinate in Military Grid Reference System (MGRS) notation representing the given point's location.

    • point - The location to be represented in MGRS notation. The point must have a spatial reference.
    • mgrsConversionMode - The mode to use for the returned MGRS notation string.
    • precision - The precision with which to represent the coordinate. The 'precision' should be in the interval [0, 8].
    • addSpaces - If false, the generated string contains no spaces. If true, a space separates the grid zone designator, the 100km square identifier, and the numerical easting and northing values.

    Returns an MGRS notation string representing the position of the given point. Returns an empty QString on error.

    For an explanation of the different modes for interpreting an MGRS notation string, please see MgrsConversionMode. Note that the choice between zone 01 and 60 has an impact only when generating the MGRS notation string for a point with longitude of exactly 180deg.

    The precision value controls the number of digits used to represent each numerical easting and northing value within the MGRS string. For example:

    precisionaddSpacesExample outputApprox precision
    0false30UVG100km
    1false30UVG8910km
    2false30UVG89991km
    3false30UVG898998100m
    4false30UVG8988998810m
    5false30UVG89884998811m
    0true30U VG100km
    1true30U VG 8 910km
    2true30U VG 89 991km
    3true30U VG 898 998100m
    4true30U VG 8988 998810m
    5true30U VG 89884 998811m

    The 'precision' should be in the interval [0, 8]. The point must have a spatial reference. Returns an empty QString on error.

    [static] QString CoordinateFormatter::toUsng(const Esri::ArcGISRuntime::Point &point, int precision, bool addSpaces)

    Returns a formatted coordinate in United States National Grid (USNG) notation representing the given point's location.

    • point - The coordinate to be represented in MGRS notation. The point must have a spatial reference.
    • precision - The precision with which to represent the coordinate. The 'precision' should be in the interval [0, 8].
    • addSpaces - If false, the generated string contains no spaces. If true, a space separates the grid zone designator, the 100km square identifier, and the numerical easting and northing values.

    Returns a USNG notation string representing the position of the given point. Returns an empty QString on error.

    The precision value controls the number of digits used to represent each numerical easting and northing value within the USNG string. For example:

    precisionaddSpacesExample outputApprox precision
    0false13TFJ100km
    1false13TFJ2510km
    2false13TFJ23591km
    3false13TFJ237595100m
    4false13TFJ2374595110m
    5false13TFJ23743595121m
    0true13T FJ100km
    1true13T FJ 2 510km
    2true13T FJ 23 591km
    3true13T FJ 237 595100m
    4true13T FJ 2374 595110m
    5true13T FJ 23743 595121m

    If the point's SpatialReference is NAD 27, then a suffix is added to the end of the formatted string. For example:

    precisionaddSpacesExample outputApprox precision
    4false13TFJ23795929 (NAD 27)10m
    2true13T FJ 23 59 (NAD 27)1km

    When the point's spatial reference is based on NAD 27. The 'precision' should be in the interval [0, 8]. The point must have a spatial reference. Returns an empty QString on error.

    [static] QString CoordinateFormatter::toUtm(const Esri::ArcGISRuntime::Point &point, Esri::ArcGISRuntime::UtmConversionMode utmConversionMode, bool addSpaces)

    Returns a formatted coordinate in Universal Transverse Mercator (UTM) notation representing the given point's location.

    • point - The coordinate to be represented in UTM notation. The point must have a spatial reference.
    • utmConversionMode - The latitude notation scheme to use in the returned UTM notation string, either a latitudinal band, or a hemisphere designator.
    • addSpaces - If false, the generated string contains no spaces. If true, a space separates the UTM zone and latitude designator, and each numerical easting and northing value.

    Returns a UTM notation string representing the position of the given point. Returns and empty QString on error.

    Example output for a point in the southern hemisphere:

    UtmConversionModeaddSpacesExample output
    LatitudeBandIndicatorsfalse30U4898846199881
    LatitudeBandIndicatorstrue30U 489884 6199881
    NorthSouthIndicatorsfalse30N4898846199881
    NorthSouthIndicatorstrue30N 489884 6199881

    The point must have a spatial reference. Returns an empty QString on error.

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