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 * Strict, like the decimal parser: a reference either reads exactly or is
* declined. UTM is `18T 585628 4511322` (zone, latitude band, easting, * 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 * northing); MGRS is `18T WL 85650 11369`, spaced or not, with 3 to 5 digits
* each for easting and northing. MGRS letters are capitals, as references are * each for easting and northing (100 m to 1 m). Coarser MGRS (`18T WL 8511`)
* printed, unless written unspaced to 100 m or finer (`18twl856113`): * declines: written that way, `1 JAN 2023`, `3 USA 12` or `20 KPH 1000` would
* lower-case `1 jan 2023` or `3 usa 12` is ordinary text, not a grid square. The polar UPS bands (A, B, * read as grid squares. MGRS letters are capitals, as references are printed,
* Y, Z) and the zones Svalbard does not use (32X, 34X, 36X) decline. A UTM `S` * unless written unspaced (`18twl856113`), and the square must lie in its
* is the 32°N–40°N band when its northing falls in that band, and otherwise * zone. Letters that spell a month (`1 JAN 2023 1200`) decline: a date is far
* the southern hemisphere, as UTM is also written; a southern reference * likelier than one of those few squares. The polar UPS bands (A, B, Y, Z) and the zones Svalbard does not use
* between about 50°S and 58°S written that way reads as band S. * (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. */ /** WGS84. */
@@ -112,6 +115,21 @@ function zoneExists(zone, band) {
return !(band === 'X' && (zone === 32 || zone === 34 || zone === 36)); 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. */ /** UTM `18T 585628 4511322` (or `18 T 585628 4511322`), or null. */
function parseUtm(text) { function parseUtm(text) {
const match = const match =
@@ -136,9 +154,13 @@ function parseUtm(text) {
const asBand = utmToLatLon(zone, easting, northing, range.south < 0); const asBand = utmToLatLon(zone, easting, northing, range.south < 0);
const bandFits = inBand(asBand.lat, range); const bandFits = inBand(asBand.lat, range);
if (bandFits) return asBand; 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 // 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. // 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') { if (letter === 'S') {
const south = utmToLatLon(zone, easting, northing, true); const south = utmToLatLon(zone, easting, northing, true);
if (south.lat < 0 && south.lat >= -80) return south; if (south.lat < 0 && south.lat >= -80) return south;
@@ -173,13 +195,26 @@ const BAND_MIN_NORTHING = {
X: 7900000, 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` * MGRS as `18TWL8565011369`, `18T WL 8565011369` or `18T WL 85650 11369`
* (easting and northing the same length), or null. * (easting and northing the same length), or null.
*/ */
function parseMgrs(text) { function parseMgrs(text) {
const match = 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, text,
); );
if (!match) return null; if (!match) return null;
@@ -187,8 +222,8 @@ function parseMgrs(text) {
const band = match[2].toUpperCase(); const band = match[2].toUpperCase();
const column = match[3].toUpperCase(); const column = match[3].toUpperCase();
const row = match[4].toUpperCase(); const row = match[4].toUpperCase();
let east = ''; let east;
let north = ''; let north;
if (match[5]) { if (match[5]) {
if (match[5].length % 2) return null; if (match[5].length % 2) return null;
east = match[5].slice(0, match[5].length / 2); 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; if (zone < 1 || zone > 60 || !zoneExists(zone, band)) return null;
const precision = east.length; const precision = east.length;
const letters = text.replace(/[\d\s]/g, ''); const letters = text.replace(/[\d\s]/g, '');
if (letters !== letters.toUpperCase() && (precision < 3 || /\s/.test(text))) if (MONTHS.has(letters.toUpperCase())) return null;
return null; if (letters !== letters.toUpperCase() && /\s/.test(text)) return null;
const columnIndex = COLUMN_SETS[(zone - 1) % 3].indexOf(column); const columnIndex = COLUMN_SETS[(zone - 1) % 3].indexOf(column);
if (columnIndex < 0) return null; if (columnIndex < 0) return null;
// Rows start at A in odd zones and at F in even ones. // 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); const scale = 10 ** (5 - precision);
// The centre of the square the digits name; a 1 m reference is its corner. // The centre of the square the digits name; a 1 m reference is its corner.
const half = precision < 5 ? scale / 2 : 0; const half = precision < 5 ? scale / 2 : 0;
const easting = (columnIndex + 1) * 100000 + Number(east || 0) * scale + half; const easting = (columnIndex + 1) * 100000 + Number(east) * scale + half;
let northing = rowIndex * 100000 + Number(north || 0) * scale + half; let northing = rowIndex * 100000 + Number(north) * scale + half;
while (northing < BAND_MIN_NORTHING[band]) northing += 2000000; while (northing < BAND_MIN_NORTHING[band]) northing += 2000000;
const range = bandRange(band); const range = bandRange(band);
const point = utmToLatLon(zone, easting, northing, range.south < 0); const point = utmToLatLon(zone, easting, northing, range.south < 0);
// Slack of the square's size in degrees of latitude. // Slack of the square's size in degrees of latitude, and in longitude at
return inBand(point.lat, range, scale / 111000) ? point : null; // 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 }; const times = { lat: 40.74882, lon: -73.98543 };
for (const text of [ for (const text of [
'18TWL8565011369', '18TWL8565011369',
@@ -237,10 +237,35 @@ test('MGRS reads spaced, unspaced and at every precision', () => {
assert.ok(metres(parseGridReference(text), times) < 1, text); assert.ok(metres(parseGridReference(text), times) < 1, text);
// Coarser references name the centre of their square. // Coarser references name the centre of their square.
assert.ok(metres(parseGridReference('18TWL856113'), times) < 71, '100 m'); assert.ok(metres(parseGridReference('18TWL856113'), times) < 71, '100 m');
assert.ok(metres(parseGridReference('18TWL8511'), times) < 710, '1 km'); assert.ok(metres(parseGridReference('18T WL 856 113'), times) < 71, '100 m');
assert.ok(metres(parseGridReference('18TWL81'), times) < 7100, '10 km'); assert.ok(metres(parseGridReference('18TWL85651136'), times) < 8, '10 m');
// A square with no digits is not enough to go on. // 1 km and 10 km squares, and a square alone, read too much ordinary text.
assert.equal(parseGridReference('18TWL'), null); 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', () => { 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', '1the12',
'60 jun 202311', '60 jun 202311',
'18t wl 85650 11369', '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. // Zones Svalbard does not use.
'32X 500000 8700000', '32X 500000 8700000',
'34X NG 12 34', '34X NG 12 34',