Concepts

Concepts

Background and theory behind MaplatTransform: compiled data formats, strict and loose modes, topology preservation, coordinate systems, and the Processing model (Processings 1–4).

Table of Contents

• V2 and V3 Compiled Formats
• Strict and Loose Modes
• Topology Preservation
• Coordinate Systems
• Processings 1–4
• See Also

---

V2 and V3 Compiled Formats

The compiled transformation definition that Transform.setCompiled() accepts has two modern versions:

• V2 — uses 4 fixed boundary vertices derived from the map bounding box. Simpler, sufficient for most rectangular maps.
• V3 — uses N boundary vertices (≥4) for more precise boundary definition, improving transformation accuracy especially near map edges.

setCompiled() auto-detects which format is in use. V3 compiled data is generated by @maplat/tin version 3 or later.

The library also accepts a legacy compiled format for backwards compatibility with maps produced before V2.

Strict and Loose Modes

MaplatTransform guarantees a bidirectional bijective (one-to-one and onto) transform when the generated TIN network maintains topology in both directions. The current state is exposed via Transform static constants and the strict_status property.

State	strict_status	Behavior
Topology preserved	STATUS_STRICT	Bidirectional bijection guaranteed
Topology broken, strict mode	STATUS_ERROR	Forward transform only; transform(..., true) throws
Topology broken, loose mode	STATUS_LOOSE	Bidirectional transform possible, but bijection is not guaranteed

Transform.MODE_STRICT, Transform.MODE_AUTO, and Transform.MODE_LOOSE control how the library picks a mode when the TIN cannot preserve topology. This is the core theoretical guarantee that lets the Maplat ecosystem overlay historical maps on accurate modern maps without distorting the original image.

Topology Preservation

The transform is nonlinear but homeomorphic (topology-preserving): two coordinates that are close in the source space map to coordinates that are close in the target space, and the mapping is continuous in both directions. This is what makes real-time overlay and GPS collaboration possible without visually deforming the source map.

A topology-preserving TIN is not always constructible from arbitrary ground control points. When it cannot be, the library falls back to the behavior described in Strict and Loose Modes.

Coordinate Systems

MaplatTransform handles several source coordinate system flavors via the Transform.VERTEX_* and Transform.YAXIS_* static constants:

• VERTEX_PLAIN — standard orthogonal plane coordinate system
• VERTEX_BIRDEYE — bird's-eye view coordinate system with perspective-like distortion
• YAXIS_FOLLOW — Y axis direction is preserved as-is
• YAXIS_INVERT — Y axis direction is inverted (e.g. screen pixel space)

All transforms output EPSG:3857 (Web Mercator) when used through MapTransform.

Processings 1–4

MaplatTransform organizes its coordinate operations into four "Processings":

Processing	Class	Purpose
Processing 1	Transform	Basic coordinate transform (pixel XY <-> target XY)
Processing 2	MapTransform	Sub-map selection + coordinate transform across overlapping TINs
Processing 3	MapTransform	Viewport transform (pixel viewport <-> EPSG:3857 five points)
Processing 4	MapTransform	Cross-map viewport sync via the shared EPSG:3857 space

Processings 2–4 build on top of Processing 1. See Tutorials for the concrete code patterns and API-Reference for the lifecycle concepts. The full API signatures live in docs/api/ in the repository.

---

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

See Also

• Home
• Tutorials — concrete usage patterns (Processings 2–4)
• API-Reference — lifecycle concepts and usage patterns
• Transform Internals — runtime notes
• README