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 undefinded;
                        }
                    }
                },
                // 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
}