mesh-data-tile

日本語版はこちら (README.ja.md)

Reference implementation for Mesh Tile Format v1 (MTI1) with a TypeScript library package and a separate CLI package.

What are meshtiles?

Meshtiles are binary tiles for numeric grid data. Each tile stores typed values (rows x cols x bands) plus core metadata (dtype, endianness, compression, no-data marker, mesh kind, and tile id) inside the tile itself.

They are designed to deliver highly efficient numerical data in tiles for map/data workflows, including but not limited to XYZ tiles (for example, native JIS X0410 mesh tiles).

Meshtiles vs the alternatives

Topic	Meshtiles (MTI1)	Numerical PNG tiles	Vector tiles (MVT)
Main data model	Typed numeric raster/grid values	Image channels with numeric packing conventions	Vector geometries + feature attributes
Band support	Native multi-band numeric payload (bands in header)	Usually constrained to PNG channel model (typically RGBA) and custom packing	No native raster band model; numeric grids require conversion/workarounds
Metadata	Internal, self-describing tile metadata in the binary header	Commonly external/implicit metadata conventions	Layer/feature properties exist, but not a native raster tile metadata header
JIS mesh support	Native mesh kind + tile identity for jis-x0410	No native JIS mesh identity model	No native JIS mesh identity model

• Specification details: Mesh Tile Format v1 spec
• See a demo using the MapLibre addProtocol adapter

Prerequisites

• Node.js 20+
• pnpm

Workspace packages

• mesh-data-tile (root): library package.
• mesh-data-tile-cli: CLI package.
• mesh-data-tile-maplibre-example: example app package.

Rust reference implementation (minimal)

A Rust reference implementation for MTI1 encode/decode (metadata + payload, no GeoJSON) is available at:

• references/rust

Help

pnpm cli --help

CLI commands

• inspect <input>
• decode <input> [--output <path>]
• encode --output <path> [options]

inspect

Prints parsed header fields as:

Label: value
Label: value

pnpm cli inspect test/fixtures/uncompressed.tile

decode

Decodes a tile and prints data only in CSV format.

Output format:

• Header row: x,y,b0,b1,b2,...
• Data rows: X,Y,A,B,C,...
• X is column index (x), Y is row index (y), both zero-based.
• A,B,C,... are band values for that pixel.

pnpm cli decode test/fixtures/uncompressed.tile

Write decoded CSV to a file:

pnpm cli decode test/fixtures/uncompressed.tile --output decoded.csv

encode

Create a tile from metadata + numeric values.

Required metadata:

• --tile-id <u64>
• --mesh-kind <jis-x0410|xyz>
• --rows <u32>
• --cols <u32>
• --bands <u8>
• --dtype <uint8|int8|uint16|int16|uint32|int32|float32|float64>
• --endianness <little|big>

tile_id semantics:

• mesh_kind=jis-x0410: tile_id is the JIS mesh code integer. Recommendation: use tile_id=0 as a root tile for the full JIS mesh scope (west=122, south=20, east=154, north=46).
• mesh_kind=xyz: tile_id is packed as (zoom << 58) | quadkey_integer, where quadkey_integer is the quadkey interpreted as base-4, and zoom max is 29.

Optional metadata:

• --compression <none|deflate-raw>
• --no-data <number|null>

Values input:

• --values '[1,2,3,4]'
• or --values-file values.json

Example:

pnpm cli encode \
  --output out.tile \
  --tile-id 42 \
  --mesh-kind jis-x0410 \
  --rows 2 \
  --cols 2 \
  --bands 1 \
  --dtype uint16 \
  --endianness little \
  --compression none \
  --values '[10,20,30,40]'

Using a metadata file

You can pass --metadata <json_file> and combine/override with flags.

Example metadata.json:

{
  "tile_id": "42",
  "mesh_kind": "jis-x0410",
  "rows": 2,
  "cols": 2,
  "bands": 1,
  "dtype": "uint16",
  "endianness": "little",
  "compression": "none",
  "no_data": null
}

Run:

pnpm cli encode --metadata metadata.json --values-file values.json --output out.tile

XYZ tile ID helpers

import { encodeXyzTileId, decodeXyzTileId } from 'mesh-data-tile';

const tileId = encodeXyzTileId({ zoom: 12, x: 3639, y: 1612 });
const decoded = decodeXyzTileId(tileId);
// decoded => { zoom: 12, x: 3639, y: 1612, quadkey_integer: ... }

Library API

Use low-level byte APIs:

import { encodeTile, decodeTile, inspectTile } from 'mesh-data-tile';

const encoded = await encodeTile({
  tile_id: '42',
  mesh_kind: 'jis-x0410',
  rows: 2,
  cols: 2,
  bands: 1,
  dtype: 'uint16',
  endianness: 'little',
  compression: 'none',
  data: [10, 20, 30, 40],
});

const inspected = inspectTile(encoded.bytes);
const decoded = await decodeTile(encoded.bytes);

Use high-level helpers (core library is runtime-neutral; file I/O is caller-managed):

import {
  decodeTile,
  decodeTileToCsv,
  encodeTile,
  inspectTile,
} from 'mesh-data-tile';
import { readFile, writeFile } from 'node:fs/promises';

const bytes = new Uint8Array(await readFile('in.tile'));
const inspected = inspectTile(bytes);
const { csv } = await decodeTileToCsv(bytes);
const decoded = await decodeTile(bytes);
console.log(inspected.header.tile_id, csv);

const encoded = await encodeTile({
  tile_id: 99n,
  mesh_kind: 'jis-x0410',
  rows: 2,
  cols: 2,
  bands: 1,
  dtype: 'uint8',
  endianness: 'little',
  data: [1, 2, 3, 4],
});
await writeFile('out.tile', encoded.bytes);

For CLI-style inspect text output and file-path based operations, use mesh-data-tile-cli.

MapLibre addProtocol support

import maplibregl from 'maplibre-gl';
import {
  MAPLIBRE_MESH_PROTOCOL_DEFAULT_LAYER_NAME,
  createMapLibreMeshTileProtocol,
} from 'mesh-data-tile/browser';

const protocol = createMapLibreMeshTileProtocol();
maplibregl.addProtocol('meshtiles', protocol);

map.addSource('jismesh-example', {
  type: 'vector',
  url: `meshtiles://https://kotobamedia.github.io/mesh-data-tile/tiles/{jismesh-lv1}.tile`,
});

map.addLayer({
  id: 'jismesh-fill',
  type: 'fill',
  source: 'jismesh-example',
  'source-layer': MAPLIBRE_MESH_PROTOCOL_DEFAULT_LAYER_NAME,
});

Optional zoom constraints can be set in the protocol options:

createMapLibreMeshTileProtocol({
  zoom: { min: 4, max: 12 },
});

By default, zoom is unconstrained.

Browser CDN build

The package ships a browser bundle with vendored runtime deps (@maplibre/geojson-vt, @maplibre/vt-pbf, and japanmesh):

• ESM: mesh-data-tile/cdn
• IIFE/global: mesh-data-tile/cdn/iife (global name: MeshDataTile)

Example ESM usage from an npm CDN:

<script type="module">
  import { createMapLibreMeshTileProtocol } from 'https://unpkg.com/mesh-data-tile/dist/browser/mesh-data-tile-browser.es.js';
  console.log(typeof createMapLibreMeshTileProtocol);
</script>

Run tests

pnpm test

Example app

Run the MapLibre + JIS mesh example app:

pnpm example:maplibre

Then open:

http://localhost:4173

Generate only static example tiles:

pnpm example:maplibre:tiles

GitHub Pages deployment for the example is configured in:

.github/workflows/pages.yml

The example uses createMapLibreMeshTileProtocol(...) with direct protocol source URLs (meshtiles://{relative path} or meshtiles://https://{absolute path}). The handler returns TileJSON and serves tile bytes internally, so tile fetching/decoding/tiling all happen inside the library protocol handler.