feat(geo): implement support for all raster topo map series projections BM-1160 #3480

tawera-manaena · 2025-07-25T01:27:12Z

This work also fulfills BM-1337.

Motivation

In the near future, we want to process the Antarctic, Offshore Islands, and Pacific region Topo Raster map sheet collections and import them into Basemaps. To enable this, we need to support all of the projections required for each map sheet collection:

Antarctic (ANT)

Title Identifier EPSG

McMurdo Sound Lambert Conformal MSLC2000 5479

New Zealand Offshore Islands (NZOI)

Title	Identifier	EPSG
Auckland Islands Transverse Mercator	AKTM2000	3788
Campbell Island Transverse Mercator	CATM2000	3789
Antipodes Islands Transverse Mercator	AITM2000	3790
Raoul Island Transverse Mercator	RITM2000	3791

Pacific Islands (PI)

Title Identifier EPSG

Universal Transverse Mercator Zone 2s UTM2S 32702

Universal Transverse Mercator Zone 3s UTM3S 32703

Universal Transverse Mercator Zone 4s UTM4S 32704

To support a projection requires several elements (either statically-defined or initialised at runtime):

An EPSG code (Epsg)
A projection definition (ProjJSON)
A tile matrix definition (TileMatrixSet)

Furthermore, to process a map sheet collection via our cli-raster package's topo command requires:

A projected citation geokey mapping to EPSG code. For example:

Geotag EPSG code

McMurdo Sound Lambert Conformal 2000 5479
An EPSG code & map series mapping to a slug. For example:

EPSG code Map Series Slug

3788 topo25 topo25-snares-islands

3788 topo50 topo50-auckland-islands

Modifications

packages/cli-raster
- cli
  - Extended our topo CLI command to support topo25 map series collections.
  - Consolidated the language around map series and scale to map series only. We were using the terms interchangeably, which was a little confusing.
- cogify/topo
  - Added geotag to EPSG mappings to the GeotagToEpsgCode data structure. Updated the matching logic to check against all geotag citations instead of short-circuiting early.
  - Updated the Slugs data structure to allow us to describe slugs based on a given EPSG code and map series name (e.g. 'topo25'). This allows us to assign distinct slugs for different map series collections that resolve the same EPSG code.
  - Added EPSG & map series to slug mappings to the Slugs data structure.
  - You can find a full breakdown of the mappings here (Jira).

packages/geo
- We've graduated from using WKTs. We now use ProjJSONs for initialising Projection instances and for generating TileMatrixSet instances at runtime.
- Added a proj folder containing projection ProjJSON definitions for all of the expected map series projections, organised by collection: ant, nz, and nzoi.
- Added a UTMZone class containing interpolation logic for generating PROJJSONDefintion objects for UTM Zone codes.
- Modified the constructor of the Epsg class to support the EPSGTextMap lookup performed when initialising a new TileMatrixSet instance, specifically for EPSG instances initialised at runtime.
- tms
  - Formalised Blayne's Tile Matrix Generation script. Instead of writing out a JSON file, it now returns a new TileMatrixSet instance at runtime. We use this function as part of topo CLI command for generating tile matrices at runtime.
packages/shared
- scripts
  
  Updated the debug.tile.matrix.ts script to resolve compilation errors.

Verification

The following is an exhaustive list of the topo CLI commands required to process all of the Topo Raster map sheet collections:

Antarctic (ANT)

ANTTopo50_GeoTif_Gridless

node packages/cli-raster/build/bin.js topo s3://linz-topographic-upload/topographic/TopoReleaseArchive/ANTTopo50_GeoTif_Gridless/ --target ./tmp/target/ant-topo50/ --map-series topo50 --output ./tmp/output/ant-topo50/

New Zealand Offshore Islands (NZOI)

NZOITopo25_GeoTif_Gridless

node packages/cli-raster/build/bin.js topo s3://linz-topographic-upload/topographic/TopoReleaseArchive/NZOITopo25_GeoTif_Gridless/ --target ./tmp/target/nzoi-topo25/ --map-series topo25 --output ./tmp/output/nzoi-topo25/

NZOITopo50_GeoTif_Gridless

node packages/cli-raster/build/bin.js topo s3://linz-topographic-upload/topographic/TopoReleaseArchive/NZOITopo50_GeoTif_Gridless/ --target ./tmp/target/nzoi-topo50/ --map-series topo50 --output ./tmp/output/nzoi-topo50/

New Zealand (NZ)

NZTopo250_GeoTif_Gridless

node packages/cli-raster/build/bin.js topo s3://linz-topographic-upload/topographic/TopoReleaseArchive/NZTopo250_GeoTif_Gridless/ --target ./tmp/target/nz-topo250/ --map-series topo250 --output ./tmp/output/nz-topo250/

NZTopo50_GeoTif_Gridless

node packages/cli-raster/build/bin.js topo s3://linz-topographic-upload/topographic/TopoReleaseArchive/NZTopo50_GeoTif_Gridless/ --target ./tmp/target/nz-topo50/ --map-series topo50 --output ./tmp/output/nz-topo50/

Pacific Islands (PI)

PITopo25_GeoTif_Gridless

node packages/cli-raster/build/bin.js topo s3://linz-topographic-upload/topographic/TopoReleaseArchive/PITopo25_GeoTif_Gridless/ --target ./tmp/target/pi-topo25/ --map-series topo25 --output ./tmp/output/pi-topo25/

PITopo50_GeoTif_Gridless

node packages/cli-raster/build/bin.js topo s3://linz-topographic-upload/topographic/TopoReleaseArchive/PITopo50_GeoTif_Gridless/ --target ./tmp/target/pi-topo50/ --map-series topo50 --output ./tmp/output/pi-topo50/

End-to-End Argo Test

I've conducted an end-to-end Argo test for the ANTTopo50 map series collection:

2193
3857

packages/geo/src/xy.order.ts

… runtime

packages/geo/src/epsg.ts

packages/geo/src/tms/tms.loader.ts

packages/geo/src/xy.order.ts

packages/cli-raster/src/cogify/topo/extract.ts

packages/cli-raster/src/cogify/topo/slug.ts

packages/cli-raster/src/cogify/cli/cli.topo.ts

packages/cli-raster/src/cogify/topo/extract.ts

…x generation

tawera-manaena · 2025-08-20T03:56:01Z

Auto-generating `ProjJSON` definitions for UTM Zones

@blacha - I've added a UTMZone class containing interpolation logic for generating PROJJSONDefintion objects for UTM Zone codes:

basemaps/packages/geo/src/proj/utmzone.ts

Line 205 in 23aa85b

export class UtmZone {

I've refactored the ProjectionLoader class to support special handling for UTM Zone codes. I've also moves the ProjJSON fetching logic into a standalone function so that I can use it in my unit tests:

basemaps/packages/geo/src/proj/projection.loader.ts

Line 46 in 23aa85b

static async fetchProjJson(code: number): Promise<PROJJSONDefinition> {

I've added a unit test that compares our generated ProjJSON objects against those fetched from spatialreference.org. It is a heavy test, so not sure whether we want to keep it. I added it just to really be sure the numbers were right for all 60 zones:

basemaps/packages/geo/src/proj/json/__tests__/proj.json.test.ts

Line 32 in 23aa85b

    
           it('should generate a ProjJSON for each UTM Zone EPSG code that matches the spatialreference.org ProjJSON', async () => {

Open to all feedback, let me know.

Update: Action items from feedback

tawera-manaena · 2025-08-24T22:27:10Z

Action Items

#3480 (comment)

Replace the fetchProjJson third-party API function call with a mocked function (i.e. TestContext).
Test against a select number of zones, rather than all 60.

basemaps/packages/geo/src/proj/json/__tests__/proj.json.test.ts

Line 32 in 3af1c77

    
           it('should generate a ProjJSON for a UTM Zone EPSG code that matches the spatialreference.org ProjJSON', async (t: TestContext) => {

…PI call

# [8.8.0](v8.7.0...v8.8.0) (2025-09-07) ### Bug Fixes * add required permissions for release please github action ([#3497](#3497)) ([a6155c9](a6155c9)) * **cli-vector:** Fix the tmp path of download layers and add try catch. BM-1352 ([#3494](#3494)) ([3769175](3769175)) * intermittent unit tests ([#3503](#3503)) ([1e942af](1e942af)) * stop using GITHUB_TOKEN for release-please ([#3495](#3495)) ([198cb29](198cb29)) ### Features * **cli-raster:** Fetch chart imagery metadata from backup location.BM-1345 ([#3492](#3492)) ([2b42fa7](2b42fa7)) * **cli-raster:** New cli to standardise charts map. BM-1338 ([#3483](#3483)) ([35b7854](35b7854)) * **geo:** implement support for all raster topo map series projections BM-1160 ([#3480](#3480)) ([8652578](8652578)) * **geo:** support tile matrixes that are not square ([#3484](#3484)) ([7720d02](7720d02)) * **lambda-tiler:** support one band uint16 lerc tiffs ([#3489](#3489)) ([906d016](906d016)) * **landing:** quick change cycles through more basemaps BM-1293 ([#3493](#3493)) ([4bfba36](4bfba36))

### Motivation Attempting to process imagery with a projection code of `4326` guarantees a runtime error. In a recent [piece of work], we modernised our processes for parsing EPSG codes and projections. With that work, we neglected to re-ensure support for the WGS84 geographic coordinate system (`EPSG:4326`). This work re-introduces that support via our new strategy. [piece of work]: #3480 [Slack thread](https://linz.slack.com/archives/C5TCTQUJG/p1757376768654719) ### Modifications - **packages/geo** - `projection.ts` - Added a key-value pair for WGS84 (`EPSG:4326`) to the `Projections` map. ### Verification - **packages/geo** - `proj.json.test.ts` - Added a new test to ensure that all supported EPSG codes have an `Epsg` and `Projection` instance. - Updated the existing tests to use each respective class's `get` function, rather than the `tryGet` function, to allow asserting based on whether the `get` function throws an error.

# [8.9.0](v8.7.0...v8.9.0) (2025-09-09) ### Bug Fixes * add required permissions for release please github action ([#3497](#3497)) ([a6155c9](a6155c9)) * **cli-vector:** Fix the tmp path of download layers and add try catch. BM-1352 ([#3494](#3494)) ([3769175](3769175)) * **geo:** ensure all supported epsg codes have a projection ([#3508](#3508)) ([23a9243](23a9243)) * intermittent unit tests ([#3503](#3503)) ([1e942af](1e942af)) * remove release-please from prod deploy ([#3506](#3506)) ([05b6f95](05b6f95)) * stop using GITHUB_TOKEN for release-please ([#3495](#3495)) ([198cb29](198cb29)) ### Features * **cli-raster:** Fetch chart imagery metadata from backup location.BM-1345 ([#3492](#3492)) ([2b42fa7](2b42fa7)) * **cli-raster:** New cli to standardise charts map. BM-1338 ([#3483](#3483)) ([35b7854](35b7854)) * **geo:** implement support for all raster topo map series projections BM-1160 ([#3480](#3480)) ([8652578](8652578)) * **geo:** support tile matrixes that are not square ([#3484](#3484)) ([7720d02](7720d02)) * **lambda-tiler:** support one band uint16 lerc tiffs ([#3489](#3489)) ([906d016](906d016)) * **landing:** quick change cycles through more basemaps BM-1293 ([#3493](#3493)) ([4bfba36](4bfba36))

### Motivation In a [recent piece of work], we added the remaining _GeoTag to EPSG_ mappings necessary to process all of the Topo Raster map series collections (ANT, NZOI, PI). In the work, we mistakenly matched the following GeoTags to the wrong EPSG: | GeoTag | EPSG | | - | - | | Chatham Islands Transverse Mercator 2000 | 2193 | | New Zealand Transverse Mercator 2000 | 3793 | [recent piece of work]: #3480 This PR corrects the mistake: | GeoTag | EPSG | | - | - | | New Zealand Transverse Mercator 2000 | 2193 | | Chatham Islands Transverse Mercator 2000 | 3793 | ### Modifications - **packages/cli-raster** - `cogify/topo/extract.ts` - Adjusted the _GeoTag to EPSG_ mappings. ### Verification I've run the following `topo` CLI commands to ensure the generated directories and STAC Items contain the expected map sheets: - **New Zealand (NZ)** - **NZTopo250_GeoTif_Gridless** ``` node packages/cli-raster/build/bin.js topo s3://linz-topographic-upload/topographic/TopoReleaseArchive/NZTopo250_GeoTif_Gridless/ --target ./tmp/target/nz-topo250/ --map-series topo250 --output ./tmp/output/nz-topo250/ ``` - **NZTopo50_GeoTif_Gridless** ``` node packages/cli-raster/build/bin.js topo s3://linz-topographic-upload/topographic/TopoReleaseArchive/NZTopo50_GeoTif_Gridless/ --target ./tmp/target/nz-topo50/ --map-series topo50 --output ./tmp/output/nz-topo50/

tawera-manaena added 3 commits July 25, 2025 13:24

fix(shared): refine tile matrix creator script

b0c9ba4

feat(geo): support ant, nzoi, and pi topo raster projections

cdbd1d3

fix(geo): complete support the all topo raster projections

b50ed45

tawera-manaena changed the title ~~feat(geo): implement support for the antarctic, offshore island, and pacific island raster topo projections BM-1160~~ feat(geo): implement support for all raster topo map series projections BM-1160 Jul 25, 2025

tawera-manaena marked this pull request as ready for review July 25, 2025 02:48

tawera-manaena requested a review from a team as a code owner July 25, 2025 02:48

tawera-manaena requested review from Wentao-Kuang and ccbblin July 25, 2025 02:48

blacha reviewed Jul 25, 2025

View reviewed changes

packages/geo/src/xy.order.ts Outdated Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view

fix(geo): use set for yx ordered codes

eee5901

ccbblin previously approved these changes Jul 29, 2025

View reviewed changes

Wentao-Kuang previously approved these changes Jul 30, 2025

View reviewed changes

This comment was marked as outdated.

Sign in to view

tawera-manaena marked this pull request as draft July 31, 2025 21:22

tawera-manaena added 4 commits August 5, 2025 14:27

feat(geo): implement function for auto-generating tile matrix sets at…

418cffb

… runtime

feat(geo): refine tile matrix generation function

ea4abe1

fix(geo): remove new topo raster projections

f820dfc

feat(cli-raster): refine topo cli command geotag and slug processes

6e172ae

tawera-manaena dismissed stale reviews from Wentao-Kuang and ccbblin via 6e172ae August 5, 2025 20:55

fix(geo): remove new epsg codes

4ef6cce