Grid references decline dates and short words in capitals: MGRS to 100 m or finer, within its zone, not spelling a month; UTM N reads as the northern hemisphere

This commit is contained in:
Sameh Khamis committed 2026-11-15 09:48:35 -08:00
1 parent d91c513e07
commit 262de71fec
2 files changed
+103 -23

No files matched your search

+61 -18
View File
@@ -3,14 +3,17 @@
*
* Strict, like the decimal parser: a reference either reads exactly or is
* declined. UTM is `18T 585628 4511322` (zone, latitude band, easting,
* northing); MGRS is `18T WL 85650 11369`, spaced or not, with 1 to 5 digits
* each for easting and northing. MGRS letters are capitals, as references are
* printed, unless written unspaced to 100 m or finer (`18twl856113`):
* lower-case `1 jan 2023` or `3 usa 12` is ordinary text, not a grid square. The polar UPS bands (A, B,
* Y, Z) and the zones Svalbard does not use (32X, 34X, 36X) decline. A UTM `S`
* is the 32°N–40°N band when its northing falls in that band, and otherwise
* the southern hemisphere, as UTM is also written; a southern reference
* between about 50°S and 58°S written that way reads as band S.
* northing); MGRS is `18T WL 85650 11369`, spaced or not, with 3 to 5 digits
* each for easting and northing (100 m to 1 m). Coarser MGRS (`18T WL 8511`)
* declines: written that way, `1 JAN 2023`, `3 USA 12` or `20 KPH 1000` would
* read as grid squares. MGRS letters are capitals, as references are printed,
* unless written unspaced (`18twl856113`), and the square must lie in its
* zone. Letters that spell a month (`1 JAN 2023 1200`) decline: a date is far
* likelier than one of those few squares. The polar UPS bands (A, B, Y, Z) and the zones Svalbard does not use
* (32X, 34X, 36X) decline. A UTM `N` or `S` is the latitude band when its
* northing falls in that band, and otherwise the hemisphere, as UTM is also
* written (`33N 500000 4500000`); a southern reference between about 50°S and
* 58°S written with `S` reads as band S.
*/
/** WGS84. */
@@ -112,6 +115,21 @@ function zoneExists(zone, band) {
return !(band === 'X' && (zone === 32 || zone === 34 || zone === 36));
}
/** Svalbard's widened zones in band X, as [west, east] longitudes. */
const SVALBARD_ZONES = { 31: [0, 9], 33: [9, 21], 35: [21, 33], 37: [33, 42] };
/**
* The longitudes a zone covers in a band: 6° each, except southwest Norway
* (31V is 0°–3°E, 32V is 3°E–12°E) and Svalbard (band X).
*/
function zoneLongitudes(zone, band) {
if (band === 'V' && zone === 31) return [0, 3];
if (band === 'V' && zone === 32) return [3, 12];
if (band === 'X' && SVALBARD_ZONES[zone]) return SVALBARD_ZONES[zone];
const west = (zone - 1) * 6 - 180;
return [west, west + 6];
}
/** UTM `18T 585628 4511322` (or `18 T 585628 4511322`), or null. */
function parseUtm(text) {
const match =
@@ -136,9 +154,13 @@ function parseUtm(text) {
const asBand = utmToLatLon(zone, easting, northing, range.south < 0);
const bandFits = inBand(asBand.lat, range);
if (bandFits) return asBand;
// `S` is also how UTM is written for the southern hemisphere. Where both
// `N` and `S` are also how UTM is written for the hemispheres. Where both
// fit, the 32°N–40°N band (Tokyo, Los Angeles, the Mediterranean) is far
// likelier than 50°S–58°S, so the band wins above.
if (letter === 'N') {
const north = utmToLatLon(zone, easting, northing, false);
if (north.lat >= 0 && north.lat <= 84) return north;
}
if (letter === 'S') {
const south = utmToLatLon(zone, easting, northing, true);
if (south.lat < 0 && south.lat >= -80) return south;
@@ -173,13 +195,26 @@ const BAND_MIN_NORTHING = {
X: 7900000,
};
/** Month abbreviations a band and square could spell (`JAN`, `SEP`, …). */
const MONTHS = new Set([
'JAN',
'FEB',
'MAR',
'MAY',
'JUN',
'JUL',
'SEP',
'NOV',
'DEC',
]);
/**
* MGRS as `18TWL8565011369`, `18T WL 8565011369` or `18T WL 85650 11369`
* (easting and northing the same length), or null.
*/
function parseMgrs(text) {
const match =
/^(\d{1,2})\s*([C-HJ-NP-X])\s*([A-HJ-NP-Z])([A-HJ-NP-V])(?:\s*(\d{2,10})|\s*(\d{1,5})\s+(\d{1,5}))$/i.exec(
/^(\d{1,2})\s*([C-HJ-NP-X])\s*([A-HJ-NP-Z])([A-HJ-NP-V])(?:\s*(\d{6,10})|\s*(\d{3,5})\s+(\d{3,5}))$/i.exec(
text,
);
if (!match) return null;
@@ -187,8 +222,8 @@ function parseMgrs(text) {
const band = match[2].toUpperCase();
const column = match[3].toUpperCase();
const row = match[4].toUpperCase();
let east = '';
let north = '';
let east;
let north;
if (match[5]) {
if (match[5].length % 2) return null;
east = match[5].slice(0, match[5].length / 2);
@@ -200,8 +235,8 @@ function parseMgrs(text) {
if (zone < 1 || zone > 60 || !zoneExists(zone, band)) return null;
const precision = east.length;
const letters = text.replace(/[\d\s]/g, '');
if (letters !== letters.toUpperCase() && (precision < 3 || /\s/.test(text)))
return null;
if (MONTHS.has(letters.toUpperCase())) return null;
if (letters !== letters.toUpperCase() && /\s/.test(text)) return null;
const columnIndex = COLUMN_SETS[(zone - 1) % 3].indexOf(column);
if (columnIndex < 0) return null;
// Rows start at A in odd zones and at F in even ones.
@@ -210,13 +245,21 @@ function parseMgrs(text) {
const scale = 10 ** (5 - precision);
// The centre of the square the digits name; a 1 m reference is its corner.
const half = precision < 5 ? scale / 2 : 0;
const easting = (columnIndex + 1) * 100000 + Number(east || 0) * scale + half;
let northing = rowIndex * 100000 + Number(north || 0) * scale + half;
const easting = (columnIndex + 1) * 100000 + Number(east) * scale + half;
let northing = rowIndex * 100000 + Number(north) * scale + half;
while (northing < BAND_MIN_NORTHING[band]) northing += 2000000;
const range = bandRange(band);
const point = utmToLatLon(zone, easting, northing, range.south < 0);
// Slack of the square's size in degrees of latitude.
return inBand(point.lat, range, scale / 111000) ? point : null;
// Slack of the square's size in degrees of latitude, and in longitude at
// that latitude.
const slack = scale / 111000;
if (!inBand(point.lat, range, slack)) return null;
const [zoneWest, zoneEast] = zoneLongitudes(zone, band);
const lonSlack =
slack / Math.max(Math.cos((point.lat * Math.PI) / 180), 0.01);
return point.lon >= zoneWest - lonSlack && point.lon <= zoneEast + lonSlack
? point
: null;
}
/**
+42 -5
View File
@@ -226,7 +226,7 @@ test('MGRS and UTM references read to within a metre in every latitude band', ()
}
});
test('MGRS reads spaced, unspaced and at every precision', () => {
test('MGRS reads spaced and unspaced, to 100 m or finer', () => {
const times = { lat: 40.74882, lon: -73.98543 };
for (const text of [
'18TWL8565011369',
@@ -237,10 +237,35 @@ test('MGRS reads spaced, unspaced and at every precision', () => {
assert.ok(metres(parseGridReference(text), times) < 1, text);
// Coarser references name the centre of their square.
assert.ok(metres(parseGridReference('18TWL856113'), times) < 71, '100 m');
assert.ok(metres(parseGridReference('18TWL8511'), times) < 710, '1 km');
assert.ok(metres(parseGridReference('18TWL81'), times) < 7100, '10 km');
// A square with no digits is not enough to go on.
assert.equal(parseGridReference('18TWL'), null);
assert.ok(metres(parseGridReference('18T WL 856 113'), times) < 71, '100 m');
assert.ok(metres(parseGridReference('18TWL85651136'), times) < 8, '10 m');
// 1 km and 10 km squares, and a square alone, read too much ordinary text.
for (const text of ['18TWL8511', '18T WL 85 11', '18TWL81', '18TWL'])
assert.equal(parseGridReference(text), null, text);
});
test('MGRS squares across a zone edge, Norway and Svalbard', () => {
// Paris, the Eiffel Tower.
assert.ok(
metres(parseGridReference('31U DQ 48251 11932'), {
lat: 48.85819,
lon: 2.29449,
}) < 1,
);
// 32V is widened to 3°E–12°E, 33X to 9°E–21°E.
assert.ok(parseGridReference('32V NM 12345 54321'));
assert.ok(parseGridReference('33X VG 12345 67890'));
// A square that lands outside its zone's longitudes.
assert.equal(parseGridReference('18T SL 50000 50000'), null);
});
test('a UTM N is the northern hemisphere where band N does not fit', () => {
const point = parseGridReference('33N 500000 4500000');
assert.ok(
Math.abs(point.lon - 15) < 1e-9 && point.lat > 40 && point.lat < 41,
);
// Within 0°–8°N it is band N, the same projection.
assert.ok(parseGridReference('33N 500000 500000').lat < 5);
});
test('a UTM S is the 32°N–40°N band where it fits, else the southern hemisphere', () => {
@@ -278,6 +303,18 @@ test('malformed grid references are refused', () => {
'1the12',
'60 jun 202311',
'18t wl 85650 11369',
// The same text in capitals, as dates and units are often written.
'1 JAN 2023',
'01 JAN 2023',
'1JAN2023',
'31 DEC 1999',
'25 DEC 2025',
'1 JAN 2023 1200',
'15 SEP 2024 0630',
'3 USA 12',
'4 GAS 12',
'33 UTC 12',
'20 KPH 1000',
// Zones Svalbard does not use.
'32X 500000 8700000',
'34X NG 12 34',