coordinateconversion

This bundle provides a tool that allows converting coordinates on the fly as well as searching for coordinates and picking them from the map. Therefore it uses the CoordinateConversion widget from the ArcGIS Maps SDK for JavaScript. This widget is extended to provide conversions to Gauss Krueger and UTM as well.

Usage

To make the coordinate conversion available to the user, add the tool ID coordinateconversionToggleTool to a tool set.

The widget is registered at the component system with the widget role coordinateconversion.

Configuration reference

The following code sample shows the configurable properties and its default values:

"coordinateconversion": {
    "Config": {
        "defaultFormat" : "wgs84-lat-lon",
        "multipleConversions": true,
        "orientation": "auto",
        "availableFormats": [
            "wgs84-lat-lon",
            "wgs84-decimal-degrees",
            "wgs84-pseudo-mercator",
            "utm-32",
            "utm-33",
            "gauss-krueger"
        ],
        "locationSymbol": {
            "type": "picture-marker",
            "url": "resource('images/search-symbol-32.png')",
            "height": 24,
            "width": 24,
            "xoffset": 0,
            "yoffset": 0
        }        
    }
}

Property	Type	Description
`defaultFormat`	String	ID of the format initially selected. A list of possible values is shown in the following table.
`multipleConversions`	Boolean	By default, multiple conversions can be displayed. To allow only the display of one conversion, set this property to `false`.
`orientation`	String	Defines, if the widget expands up or down. If set to `auto`, the widget is oriented based on its position in the view. Possible values are `auto`, `expand-up` and `expand-down`.
`availableFormats`	Array of Strings	A list of format IDs that can be selected for coordinate transformation (use IDs from the following table). If the list of available formats is empty, all formats listed in the following table are available.
`locationSymbol`	SimpleMarkerSymbol or PictureMarkerSymbol	The property `locationSymbol` allows to change the default symbol used to visualize the current location. See CoordinateConversion for details.

Well-known conversion formats

Name	ID	Description
WGS 84 (lat/lon)	wgs84-lat-lon	WGS84 based coordinates in Degree, Minute and Seconds format
WGS 84 (decimal degrees)	wgs84-decimal-degrees	WGS84 based coordinates in Decimal Degrees format
WGS 84 (pseudo-mercator)	wgs84-pseudo-mercator	WGS84 with pseudo-mercator base coordinates
ETRS89/UTM zone 32N	utm-32	Universal Transverse Mercator zone 32N
ETRS89/UTM zone 33N	utm-33	Universal Transverse Mercator zone 33N
Gauss Krueger (Auto)	gauss-krueger	The German Gauss Krueger format. The format switches between the different strips 2, 3, 4 & 5 automatically.
Gauss Krueger (Zone)	gauss-krueger-[2\|3\|4\|5]	The German Gauss Krueger format for a specific zone (such as `gauss-krueger-2`).
XY	xy	Longitude, Latitude (WGS84)
MGRS	mgrs	Military Grid Reference System
UTM	utm	Universal Transverse Mercator
DD	dd	Decimal Degrees
DDM	ddm	Degrees Decimal Minutes
DMS	dms	Degrees Minutes Seconds
Basemap	basemap	X, Y in the coordinate system used by the current Basemap in the units used by the Basemap. Web Mercator is the standard for Esri-provided basemaps.

Use Cases

How to register custom formats

To register custom formats for coordinate conversion, you need to implement the interface esri/widgets/CoordinateConversion/support/Format from the ArcGIS Maps SDK for JavaScript.

Note: This interface might be changed by Esri in future versions of the API. Therefore, we cannot guarantee, that it is stable and backward compatible.

The following code sample shows how to add a custom lat/lon format:

import Format from "esri/widgets/CoordinateConversion/support/Format";
import Point from "esri/geometry/Point";
import { webMercatorToGeographic } from "esri/geometry/support/webMercatorUtils";
export default XYFormatFactory;

function XYFormatFactory() {
    return {
        /**
         * @see https://developers.arcgis.com/javascript/latest/sample-code/widgets-coordinateconversion-custom/index.html
         */
        createInstance() {
            // Regular expression to find a number
            let numberSearchPattern = /-?\d+[\.]?\d*/;
            return new Format({
                // used to identify the format. This key is used in the defaultFormat option of the widget.
                // it is only required if the name is localized and has no stable value.
                id: "xy-custom",
                // The format's name should be unique with respect to other formats used by the widget
                name: "XY (Custom)",
                conversionInfo: {
                    // Define a convert function
                    // Point -> Position
                    convert(point) {
                        let returnPoint = point.spatialReference.isWGS84 ? point : webMercatorToGeographic(point);
                        let x = returnPoint.x.toFixed(4);
                        let y = returnPoint.y.toFixed(4);
                        return {
                            location: returnPoint,
                            coordinate: `${x}, ${y}`
                        };
                    },
                    // Define a reverse convert function
                    // String -> Point
                    reverseConvert(string) {
                        try {
                            let parts = string.split(",");
                            return new Point({
                                x: parseFloat(parts[0]),
                                y: parseFloat(parts[1]),
                                spatialReference: { wkid: 4326 }
                            });
                        } catch (e) {
                            // Esri widget to display error message
                            return undefined;
                        }
                    }
                },
                // Define each segment of the coordinate
                coordinateSegments: [
                    {
                        alias: "X",
                        description: "Longitude",
                        searchPattern: numberSearchPattern
                    },
                    {
                        alias: "Y",
                        description: "Latitude",
                        searchPattern: numberSearchPattern
                    }
                ],
                defaultPattern: "X\u00B0, Y\u00B0"
            });
        }
    };
}

Finally, register the format component as service coordinateconversion.Format in a manifest.json file as in the following code sample:

{
    "name": "XYFormatFactory",
    "provides": ["coordinateconversion.Format"],
    "instanceFactory": true
}