@arcgis/core

/** * Converts between [points](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/) and formatted coordinates notation strings * such as: * * decimal degrees * * degrees, minutes, and seconds * * U.S. National Grid (USNG) * * Military Grid Reference System (MGRS). * * To use the conversion methods, the [load()](https://developers.arcgis.com/javascript/latest/references/core/geometry/coordinateFormatter/#load) method must be called first * if [isLoaded()](https://developers.arcgis.com/javascript/latest/references/core/geometry/coordinateFormatter/#isLoaded) is `false`. * * > [!WARNING] * > * > **Known Limitations** * > * > The browser must support [WebAssembly](https://caniuse.com/#feat=wasm) for this module to work. * > The methods that convert formatted strings to [points](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/) expect the spatial reference * > parameter to be a [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). * > The methods that convert [points](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/) to formatted strings expect the point's * > [Point.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/#spatialReference) to be a * > [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). * * @since 4.7 * @example * // Assign a latitude/longitude string to a const. * const latlon = "55 56 39.123N 003 09 43.034W"; * * // Load dependencies. * await coordinateFormatter.load(); * * // Use the `fromLatitudeLongitude` method to convert the latitude/longitude string to a point geometry. * const point = coordinateFormatter.fromLatitudeLongitude(latlon); */ import type Point from "./Point.js"; import type SpatialReference from "./SpatialReference.js"; import type { LatitudeLongitudeFormat } from "./types.js"; export type MgrsConversionMode = "automatic" | "new-180-in-zone-01" | "new-180-in-zone-60" | "old-180-in-zone-01" | "old-180-in-zone-60"; export type UtmConversionMode = "latitude-band-indicators" | "north-south-indicators"; /** * Indicates if all dependencies of this module have been loaded. * * @returns Returns `true` if this module's dependencies have been loaded. */ export function isLoaded(): boolean; /** * Indicates if this module is supported in the current browser. * The browser must support [WebAssembly](https://caniuse.com/#feat=wasm). * * @returns Returns `true` if this module is supported in the current browser. */ export function isSupported(): boolean; /** * Load this module's dependencies. * * @returns Resolves when the dependencies have been loaded. * @see [isLoaded()](https://developers.arcgis.com/javascript/latest/references/core/geometry/coordinateFormatter/#isLoaded) */ export function load(): Promise<void>; /** * Parses coordinates in latitude/longitude notation, and returns a [Point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/) representing that location. * The coordinates may use decimal degrees, degrees and decimal minutes, or degrees, minutes, and seconds format. * 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 in WGS84. * * #### Supported characters * | Symbol | Character | Name | Unicode number | HTML code | * |---|---|---|---|---| * | Degree | * | Asterisk | U+002A | &#42; | * | | ^ | Circumflex Accent | U+005E | &#94; | * | | ~ | Tilde | U+007E | &#126; | * | | ° | Degree Sign | U+00B0 | &#176; | * | | º | Masculine Ordinal Indicator | U+00BA | &#186; | * | Minute | ' | Apostrophe | U+0027 | &#39; | * | | ′ | Prime | U+2032 | &#8242; | * | Second | " | Quotation Mark | U+0022 | &#34; | * | | ″ | Double prime | U+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′39″N 3°09′43″W * - 55~56.65205', -003~09.71723' * - 55.9442008* | -3.1619539* * * @param coordinates - The latitude/longitude notation string for the coordinates. * @param spatialReference - A spatial reference object representing a * [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). * If `null`, WGS84 will be used. * @returns Returns a point with the location from the coordinates string in the spatial reference provided. */ export function fromLatitudeLongitude(coordinates: string, spatialReference?: SpatialReference | null): Point | null | undefined; /** * Parses coordinates in Military Grid Reference System (MGRS) notation, and returns a [Point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/) representing that location. * 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 WGS84. * * 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 * * @param coordinates - The MGRS notation string for the coordinates. * @param spatialReference - A spatial reference object representing * a [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm) referenced by the MGRS coordinates. * If `null`, WGS84 will be used. * @param conversionMode - The mode used by the given MGRS coordinates. * @returns Returns a point with the location from the MGRS string in the spatial reference provided. */ export function fromMgrs(coordinates: string, spatialReference: SpatialReference | null | undefined, conversionMode: MgrsConversionMode): Point | null | undefined; /** * Parses coordinates in United States National Grid (USNG) notation, and returns a [Point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/) representing that location. * * 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 WGS84. * * USNG notation examples: * - 13TFJ 23 59 * - 13TFJ2374159574 * * @param coordinates - The USNG notation string for the coordinates. * @param spatialReference - A spatial reference object representing a * [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm) that the USNG coordinates are in. * If `null`, WGS84 will be used. * @returns Returns a point with the location from the USNG string in the spatial reference provided. */ export function fromUsng(coordinates: string, spatialReference?: SpatialReference | null): Point | null | undefined; /** * Parses coordinates in Universal Transverse Mercator (UTM) notation, and returns a [Point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/) representing that location. * 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 WGS84. 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) * * @param coordinates - The UTM notation string for the coordinates. * @param spatialReference - A spatial reference object representing a * [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm) that the UTM coordinates are in. * If `null`, WGS84 will be used. * @param conversionMode - The latitude notation scheme used by the given UTM coordinates, * either a latitudinal band, or a hemisphere designator. * @returns Returns a point with the location from the UTM string in the spatial reference provided. */ export function fromUtm(coordinates: string, spatialReference: SpatialReference | null | undefined, conversionMode: UtmConversionMode): Point | null | undefined; /** * Returns formatted coordinates in latitude/longitude notation representing the given point's location. * * The latitude/longitude string will contain a space separating the latitude from the longitude value, * and the characters 'N' or 'S', and 'E' or '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 `decimalPlaces` parameters. * * For example: * | Decimal places | Format | Example output | Angular precision | Linear precision | * |---|---|---|---|---| * | 0 | dd | 56N 003W | 1° | ~100km | * | 1 | dd | 55.9N 003.2W | 0.1° | ~10km | * | 2 | dd | 55.94N 003.16W | 0.01° | ~1km | * | 3 | dd | 55.944N 003.162W | 0.001° | ~100m | * | 0 | ddm | 55 57N 003 10W | 1' | ~2km | * | 1 | ddm | 55 56.7N 003 09.7W | 0.1' | ~200m | * | 2 | ddm | 55 56.65N 003 09.72W | 0.01' | ~20m | * | 3 | ddm | 55 56.650N 003 09.717W | 0.001' | ~2m | * | 0 | dms | 55 56 39N 003 09 43W | 1" | ~30m | * | 1 | dms | 55 56 39.1N 003 09 43.0W | 0.1" | ~3m | * | 2 | dms | 55 56 39.12N 003 09 43.03W | 0.01" | ~300mm | * | 3 | dms | 55 56 39.123N 003 09 43.034W | 0.001" | ~30mm | * * @param point - The location to be represented as a formatted latitude/longitude string. * The point's [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/#spatialReference) should either be WGS84 or another * [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). * @param format - The mode to use when formatting the latitude/longitude string. * @param decimalPlaces - The number of decimal places to use, it should be an integer from 0 to 16. * @returns Returns a string representing the latitude/longitude of the given point. */ export function toLatitudeLongitude(point: Point, format: LatitudeLongitudeFormat, decimalPlaces?: number): string | null | undefined; /** * Returns formatted coordinates in Military Grid Reference System (MGRS) notation representing the given point's location. * * 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: * | precision | add_spaces | Example output | Approximate precision | * | --- | --- | --- | --- | * | 0 | false | 30UVG | 100km | * | 1 | false | 30UVG89 | 10km | * | 2 | false | 30UVG8999 | 1km | * | 3 | false | 30UVG898998 | 100m | * | 4 | false | 30UVG89889988 | 10m | * | 5 | false | 30UVG8988499881 | 1m | * | 0 | true | 30U VG | 100km | * | 1 | true | 30U VG 8 9 | 10m | * | 2 | true | 30U VG 89 99 | 1km | * | 3 | true | 30U VG 898 998 | 100m | * | 4 | true | 30U VG 8988 9988 | 10m | * | 5 | true | 30U VG 89884 99881 | 1m | * * @param point - The location to be represented in MGRS notation. * The point's [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/#spatialReference) should either be WGS84 or another * [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm) * @param conversionMode - The mode to use for the returned MGRS notation string. * @param precision - The precision with which to represent the coordinates, it should be an integer from 0 to 8. * @param addSpaces - If `false`, the generated string will contain no spaces. If `true`, a space separates * the grid zone designator, the 100km square identifier, and the numerical easting and northing values. * @returns Returns a MGRS notation string representing the position of the given point. */ export function toMgrs(point: Point, conversionMode: MgrsConversionMode, precision?: number, addSpaces?: boolean): string | null | undefined; /** * Returns formatted coordinates in United States National Grid (USNG) notation representing the given point's location. * The precision value controls the number of digits used to represent each numerical easting and northing value within the USNG string. * * For example: * | precision | add_spaces | Example output | Approximate precision | * | --- | --- | --- | --- | * | 0 | false | 13TFJ | 100km | * | 1 | false | 13TFJ25 | 10km | * | 2 | false | 13TFJ2359 | 1km | * | 3 | false | 13TFJ237595 | 100m | * | 4 | false | 13TFJ23745951 | 10m | * | 5 | false | 13TFJ2374359512 | 1m | * | 0 | true | 13T FJ | 100km | * | 1 | true | 13T FJ 2 5 | 10m | * | 2 | true | 13T FJ 23 59 | 1km | * | 3 | true | 13T FJ 237 595 | 100m | * | 4 | true | 13T FJ 2374 5951 | 10m | * | 5 | true | 13T FJ 23743 59512 | 1m | * | 4* | false | 13TFJ23795929 (NAD 27) | 10m | * | 2* | true | 13T FJ 23 59 (NAD 27) | 1km | * * &ast; *When the point's spatial reference is based on NAD 27.* * * @param point - The location to be represented in USNG notation. * The point's [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/#spatialReference) should either be WGS84 or another * [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm). * @param precision - The precision with which to represent the coordinates, it should be an integer from 0 to 8. * @param addSpaces - If `false`, the generated string will contain no spaces. If `true`, a space separates * the grid zone designator, the 100km square identifier, and the numerical easting and northing values. * @returns Returns a USNG notation string representing the position of the given point. */ export function toUsng(point: Point, precision?: number, addSpaces?: boolean): string | null | undefined; /** * Returns formatted coordinates in Universal Transverse Mercator (UTM) notation representing the given point's location. * * Example output for a point in the southern hemisphere: * | conversionMode | add_spaces | Example output | * | --- | --- | --- | * | latitude-band-indicators | false | 30U4898846199881 | * | latitude-band-indicators | true | 30U 489884 6199881 | * | north-south-indicators | false | 30N4898846199881 | * | north-south-indicators | true | 30N 489884 6199881 | * * @param point - The location to be represented in UTM notation. * The point's [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/#spatialReference) should either be WGS84 or another * [geographic coordinate system](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references.htm) * @param conversionMode - The latitude notation scheme to use in the returned UTM notation string, * either a latitudinal band, or a hemisphere designator. * @param addSpaces - If `false`, the generated string will contain no spaces. If `true`, a space separates * the UTM zone and latitude designator and each numerical easting and northing value. * @returns Returns a UTM notation string representing the position of the given point. */ export function toUtm(point: Point, conversionMode: UtmConversionMode, addSpaces?: boolean): string | null | undefined;