Tutorials

Tutorials

Step-by-step guides for using MaplatTransform. The examples here cover the Basic usage of the Transform class and the MapTransform usage patterns (Processings 2–4) that were kept out of the README to keep it short.

Table of Contents

• Basic Usage
• Processing 2 — Sub-map selection
• Processing 3 — Viewport transformation
• Processing 4 — Cross-map viewport sync
• Error Handling
• See Also

---

Basic Usage

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

// Load a compiled transformation definition generated by Maplat
const transform = new Transform();
transform.setCompiled(compiledData);

// Forward transformation (source -> target coordinate system)
const transformed = transform.transform([100, 100], false);

// Backward transformation (target -> source coordinate system)
const restored = transform.transform(transformed, true);

The setCompiled call accepts V2, V3, and legacy compiled formats and auto-detects which one is in use.

Processing 2 — Sub-map selection

When a single map image contains multiple overlapping TIN definitions (sub_maps), use MapTransform to automatically select the correct TIN and transform coordinates.

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

const mt = new MapTransform();
mt.setMapData({
  compiled: mainCompiledData,   // Main TIN compiled data
  sub_maps: [
    { compiled: sub0Data, priority: 1, importance: 1 },
    { compiled: sub1Data, priority: 2, importance: 2 },
  ],
});

// Forward: pixel XY -> EPSG:3857 (returns [layerIndex, mercCoord] or false)
const result = mt.xy2MercWithLayer([320, 240]);
if (result) {
  const [layerIndex, merc] = result;
  console.log('layer:', layerIndex, 'merc:', merc);
}

// Reverse: EPSG:3857 -> pixel XY (returns up to 2 layers, each [layerIndex, xyCoord] or undefined)
const results = mt.merc2XyWithLayer([15000000, 4000000]);
results.forEach((r, i) => {
  if (r) console.log(`result ${i}: layer ${r[0]}, xy`, r[1]);
});

Processing 3 — Viewport transformation

Convert a pixel-map viewport (center position, zoom level, rotation angle) to and from a geographic viewport in EPSG:3857. The viewport is represented as five Mercator points (center + four cardinal offsets).

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

const mt = new MapTransform();
mt.setMapData({ compiled: compiledData });

const canvasSize = [800, 600];   // [width, height] in pixels

// Pixel viewport -> EPSG:3857 five points
const viewpoint = {
  center: [15000000, 4000000],  // EPSG:3857 center of the pixel-space viewport
  zoom: 14,
  rotation: 0,
};
const mercs = mt.viewpoint2Mercs(viewpoint, canvasSize);
// mercs: [[cx,cy], [north], [east], [south], [west]]  (EPSG:3857)

// EPSG:3857 five points -> pixel viewport
const vp = mt.mercs2Viewpoint(mercs, canvasSize);
console.log(vp.center, vp.zoom, vp.rotation);

Processing 4 — Cross-map viewport sync

Convert the display viewport of one pixel map to the corresponding viewport of another pixel map, using the shared EPSG:3857 space as an intermediary.

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

const mtA = new MapTransform();
mtA.setMapData({ compiled: compiledDataA });

const mtB = new MapTransform();
mtB.setMapData({ compiled: compiledDataB });

const canvasSize = [800, 600];

// Map A viewport (pixel space A)
const vpA = { center: [15000000, 4000000], zoom: 14, rotation: 0 };

// Pixel space A -> EPSG:3857 five points (Processing 3 forward)
const mercs = mtA.viewpoint2Mercs(vpA, canvasSize);

// EPSG:3857 five points -> Map B viewport (Processing 3 reverse)
const vpB = mtB.mercs2Viewpoint(mercs, canvasSize);
console.log('Map B viewport:', vpB);

Error Handling

The library may throw errors in the following cases:

• Transformation errors in strict mode
• Attempting backward transformation when not allowed
• Invalid data structure during transformation

If errors occur, the transformation definition data needs to be modified. Use editor tools that incorporate @maplat/tin to modify transformation definitions. See Concepts for the strict/loose mode behavior.

---

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

See Also

• Home
• Concepts — V2/V3, strict/loose, topology, coordinate systems
• API-Reference — concepts and usage patterns
• README — install and quick start