MGRS utilities

The map-sheet package exports the MGRS functions it uses for grids and registration marks. Use them to parse user input, show grid references, or snap positions to grid lines. They run on GeographicLib's UTM/UPS implementation and handle the Norway and Svalbard zone exceptions and the polar UPS regions.

Positions are GeoJSON [longitude, latitude] pairs.

Parse a reference

import { parseMgrsReference } from "@orbat-mapper/tactical-map-sheet";

const ref = parseMgrsReference("30u wv 33924 48309");
ref.normalized; // "30UWV3392448309"
ref.precision; // 5 (1 m)
ref.crs; // { kind: "utm", zone: 30, hemisphere: "north" }
ref.easting; // 533924 (meters)
ref.northing; // 5448309
ref.position; // [-2.5345, 49.1866]

Input may use any case and spacing; the normalized form is compact and upper case. Invalid references throw.

A reference names the southwest corner of its grid square, not its center. "30UWV3448" is the corner of a 1 km square, so its position is that corner.

Focused variants return one part of the result:

Function	Returns
normalizeMgrsReference(ref)	The normalized string.
mgrsToGeographic(ref)	[longitude, latitude] of the southwest corner.
mgrsToProjected(ref)	{ crs, easting, northing }.

Format a position

import { geographicToMgrs } from "@orbat-mapper/tactical-map-sheet";

geographicToMgrs([-2.5, 49.2]); // "30UWV3642449809" (1 m)
geographicToMgrs([-2.5, 49.2], 2); // "30UWV3649" (1 km)

Precision runs from 0 (100 km square only) to 5 (1 m). The default is 5. projectedToMgrs({ crs, easting, northing }, precision?) does the same for a projected coordinate; the crs must name its UTM zone and hemisphere, or its UPS hemisphere.

Precision	Digits	Resolution
0	0	100 km
1	1 + 1	10 km
2	2 + 2	1 km
3	3 + 3	100 m
4	4 + 4	10 m
5	5 + 5	1 m

Snap to the grid

snapGeographicToMgrs(position, interval) and snapProjectedToMgrs(coordinate, interval) move a point to the nearest grid intersection and return a full parsed reference at the matching precision:

import { snapGeographicToMgrs } from "@orbat-mapper/tactical-map-sheet";

const corner = snapGeographicToMgrs([-2.533, 49.184], 1_000);
corner.normalized; // "30UWV3448"
corner.position; // [-2.5334, 49.1839], the intersection

interval is 100, 1,000, 10,000, or 100,000 meters. A point already on an intersection stays put; a point exactly halfway moves toward increasing easting and northing.