API Reference

API Reference

Concepts and usage patterns for the Transform and MapTransform API. This page focuses on release-independent explanatory material (ADR-0012). For the complete and up-to-date API signature list, see docs/api/ in the repository.

Table of Contents

• Class Lifecycle
• Processings 1–4 at the Concept Level
• Usage Patterns
• API Signature Reference
• See Also

---

Class Lifecycle

MaplatTransform exposes two classes:

Transform (Processing 1)

1. Construction — new Transform() returns a stateless instance.
2. Load — setCompiled(compiled) imports a compiled definition (V2, V3, or legacy) and builds the internal lookup structures. Calling setCompiled again replaces the previous definition.
3. Transform — transform(apoint, backward?, ignoreBounds?) performs the forward or backward coordinate transform.
4. State save/restore — the compiled state can be reloaded via setCompiled to restore a saved transform snapshot.

MapTransform (Processings 2–4)

1. Construction — new MapTransform() returns a stateless instance.
2. Load — setMapData(mapData) loads the main TIN and optional sub-map TINs (sub_maps). maxxy is computed from maxZoom.
3. Use — call xy2Merc / merc2Xy (Processing 1 level via the main TIN), xy2MercWithLayer / merc2XyWithLayer (Processing 2), or viewpoint2Mercs / mercs2Viewpoint (Processing 3). Processing 4 is a composition of two MapTransform instances (see Tutorials).

Both classes are stateless until setCompiled / setMapData is called. They are safe to reuse: load a new definition to replace the previous one.

Processings 1–4 at the Concept Level

• Processing 1 — Transform: single-plane coordinate transform between the source XY and the target XY using one TIN definition.
• Processing 2 — MapTransform: when a single map image contains multiple overlapping TIN regions (sub_maps), the library automatically selects the appropriate TIN based on region boundaries, priority, and importance. Forward returns a single hit; reverse returns up to two layers ordered by importance.
• Processing 3 — MapTransform: converts a display viewport (center, zoom, rotation) in pixel coordinate space to/from five EPSG:3857 points (center + four cardinal offsets). This is the building block for synchronizing the pixel-space view with the geographic view.
• Processing 4 — MapTransform: cross-map viewport sync. Two MapTransform instances share the EPSG:3857 space; Processing 3 forward on map A, then Processing 3 reverse on map B yields the equivalent viewport on map B.

See Concepts for the theory behind topology preservation and strict / loose modes.

Usage Patterns

Pattern 1: CDN minimal usage

For a quick embed without a bundler, load the UMD bundle from a CDN. The version must match the installed / intended release.

<script src="https://cdn.jsdelivr.net/npm/@maplat/transform@0.5.3/dist/maplat_transform.umd.js"></script>
<script>
  var t = new MaplatTransform.Transform();
  t.setCompiled(compiledData);
  var out = t.transform([100, 100], false);
</script>

When upgrading, replace 0.5.3 with the installed version. There is no OpenLayers dependency to load separately.

Pattern 2: npm ESM import

import { Transform, MapTransform } from '@maplat/transform';

const t = new Transform();
t.setCompiled(compiledData);
const out = t.transform([100, 100], false);

Pattern 3: Framework integration

When integrating into React, Vue, or similar, construct the Transform / MapTransform instance on mount and call setCompiled / setMapData before rendering the map. Keep the instance for the component lifetime and release it on unmount; both classes hold no external resources beyond their internal lookup tables.

Do not share a single MapTransform instance across two independent maps — Processing 4 requires two instances, each with its own map data.

API Signature Reference

The complete API signature list (constructors, methods, static constants, accessors, exported types, utility functions, format version export) is maintained in docs/api/ in the repository. This Wiki page intentionally does not duplicate the signatures to avoid divergence from the source of truth.

See:

• docs/api/ — authoritative API signatures
• README §API reference — overview and links

---

日本語版はこちら / Read this page in Japanese

See Also

• Home
• Concepts — V2/V3, strict/loose, topology, coordinate systems
• Tutorials — concrete usage patterns (Processings 2–4)
• README — install and quick start