tile_id = 0 for the full extent of JIS mesh

Author: keichan34

README.ja.md

@@ -95,7 +95,7 @@ pnpm cli decode test/fixtures/uncompressed.tile --output decoded.csv
 
 `tile_id` の意味:
 
-- `mesh_kind=jis-x0410`: `tile_id` は JIS メッシュコード整数です。
+- `mesh_kind=jis-x0410`: `tile_id` は JIS メッシュコード整数です。推奨: `tile_id=0` を JIS ルートタイル（JIS メッシュ対象範囲全体: `west=122`, `south=20`, `east=154`, `north=46`）として扱います。
 - `mesh_kind=xyz`: `tile_id` は `(zoom << 58) | quadkey_integer` でパックされます。`quadkey_integer` は quadkey を base-4 整数として解釈した値で、zoom の最大値は `29` です。
 
 任意メタデータ:

README.md

@@ -101,7 +101,7 @@ Required metadata:
 
 `tile_id` semantics:
 
-- `mesh_kind=jis-x0410`: `tile_id` is the JIS mesh code integer.
+- `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:

references/rust/README.md

@@ -13,6 +13,11 @@ Out of scope:
 - GeoJSON/vector conversion.
 - Map rendering integrations.
 
+JIS root-tile recommendation:
+- For `mesh_kind=JisX0410`, `tile_id=0` is a recommended convention for a root tile
+  representing the full JIS mesh scope (`west=122`, `south=20`, `east=154`, `north=46`).
+- This crate treats `tile_id` as metadata for JIS tiles and accepts `0` as a valid value.
+
 ## Run tests
 
 From repository root:

spec/tile-format-v1.md

@@ -63,6 +63,8 @@ File := FixedHeaderV1 || Payload
 ### 4.4 `tile_id` (u64) by `mesh_kind`
 
 - `mesh_kind=JIS_X0410` (`1`): `tile_id` is the JIS mesh code value as an unsigned integer.
+  Recommended convention for interoperability: `tile_id=0` may be used as a JIS root tile meaning
+  the full JIS mesh scope (`west=122`, `south=20`, `east=154`, `north=46`).
 - `mesh_kind=XYZ` (`2`): `tile_id` stores zoom + quadkey integer in a single u64.
 - Bits `63..58` (most significant 6 bits): `zoom` (`0..29`)
 - Bits `57..0`: `quadkey_integer` (the XYZ tile quadkey interpreted as base-4 integer)

src/browser.ts

@@ -20,6 +20,8 @@ export type {
 export {
   JIS_MESH_LEVELS,
   JIS_MESH_PLACEHOLDER_LEVELS,
+  JIS_MESH_ROOT_TILE_ID,
+  JIS_MESH_SCOPE_BOUNDS,
   toJisMeshLevel,
   toJisMeshCode,
   toJisMeshPoint,

src/index.ts

@@ -20,6 +20,8 @@ export type {
 export {
   JIS_MESH_LEVELS,
   JIS_MESH_PLACEHOLDER_LEVELS,
+  JIS_MESH_ROOT_TILE_ID,
+  JIS_MESH_SCOPE_BOUNDS,
   toJisMeshLevel,
   toJisMeshCode,
   toJisMeshPoint,

src/jismesh.ts

@@ -22,7 +22,18 @@ export interface JisMeshBounds {
   west: number;
 }
 
+export const JIS_MESH_ROOT_TILE_ID = 0n;
+
+// Recommended JIS root tile extent (`tile_id=0`) used by this repository.
+export const JIS_MESH_SCOPE_BOUNDS: Readonly<JisMeshBounds> = Object.freeze({
+  west: 122,
+  south: 20,
+  east: 154,
+  north: 46,
+});
+
 const JIS_MESH_LEVEL_SET = new Set<number>(Object.values(JIS_MESH_LEVELS));
+const JIS_MESH_ROOT_TILE_CODE = JIS_MESH_ROOT_TILE_ID.toString();
 
 export const JIS_MESH_PLACEHOLDER_LEVELS: Readonly<Record<string, JisMeshLevel>> = Object.freeze({
   lv1: JIS_MESH_LEVELS.lv1,
@@ -91,6 +102,33 @@ export function toJisMeshPoint(
   level?: JisMeshLevel
 ): [number, number] {
   const code = normalizeMeshCode(meshCode);
+  if (code === JIS_MESH_ROOT_TILE_CODE) {
+    if (level !== undefined) {
+      throw createError(
+        'INVALID_FIELD_VALUE',
+        'JIS root tile "0" does not have a JIS mesh level. Omit the level argument.'
+      );
+    }
+
+    switch (point) {
+      case 'sw':
+        return [JIS_MESH_SCOPE_BOUNDS.south, JIS_MESH_SCOPE_BOUNDS.west];
+      case 'nw':
+        return [JIS_MESH_SCOPE_BOUNDS.north, JIS_MESH_SCOPE_BOUNDS.west];
+      case 'ne':
+        return [JIS_MESH_SCOPE_BOUNDS.north, JIS_MESH_SCOPE_BOUNDS.east];
+      case 'se':
+        return [JIS_MESH_SCOPE_BOUNDS.south, JIS_MESH_SCOPE_BOUNDS.east];
+      case 'center':
+        return [
+          (JIS_MESH_SCOPE_BOUNDS.north + JIS_MESH_SCOPE_BOUNDS.south) / 2,
+          (JIS_MESH_SCOPE_BOUNDS.east + JIS_MESH_SCOPE_BOUNDS.west) / 2,
+        ];
+      default:
+        throw createError('INVALID_FIELD_VALUE', `Unsupported JIS mesh point "${point as string}".`);
+    }
+  }
+
   const detectedLevel = toJisMeshLevel(code);
   if (detectedLevel === null) {
     throw createError('INVALID_FIELD_VALUE', `Invalid JIS mesh code "${code}".`);

test/maplibre-source.test.ts

@@ -5,13 +5,16 @@ import { describe, it } from 'node:test';
 import { fromGeojsonVt } from '@maplibre/vt-pbf';
 import {
   JIS_MESH_LEVELS,
+  JIS_MESH_ROOT_TILE_ID,
+  JIS_MESH_SCOPE_BOUNDS,
   MAPLIBRE_MESH_PROTOCOL_DEFAULT_LAYER_NAME,
   MAPLIBRE_MESH_PROTOCOL_DEFAULT_VECTOR_EXTENT,
   MAPLIBRE_MESH_PROTOCOL_DEFAULT_VECTOR_VERSION,
   createMapLibreMeshTileProtocol,
   createMapLibreSourceHandler,
   decodeTile,
   decodedMeshTileToGeoJson,
+  encodeTile,
   getJisMeshCodesWithinBounds,
   renderMeshTileUrlTemplate,
   toJisMeshCode,
@@ -88,6 +91,19 @@ describe('maplibre source helpers', () => {
     assertAlmostEqual(center[1], 139.71875);
   });
 
+  it('maps tile_id=0 to the recommended JIS root-tile scope', () => {
+    const sw = toJisMeshPoint(JIS_MESH_ROOT_TILE_ID, 'sw');
+    const ne = toJisMeshPoint(JIS_MESH_ROOT_TILE_ID, 'ne');
+    const center = toJisMeshPoint(JIS_MESH_ROOT_TILE_ID, 'center');
+
+    assert.deepEqual(sw, [JIS_MESH_SCOPE_BOUNDS.south, JIS_MESH_SCOPE_BOUNDS.west]);
+    assert.deepEqual(ne, [JIS_MESH_SCOPE_BOUNDS.north, JIS_MESH_SCOPE_BOUNDS.east]);
+    assert.deepEqual(center, [
+      (JIS_MESH_SCOPE_BOUNDS.north + JIS_MESH_SCOPE_BOUNDS.south) / 2,
+      (JIS_MESH_SCOPE_BOUNDS.east + JIS_MESH_SCOPE_BOUNDS.west) / 2,
+    ]);
+  });
+
   it('resolves japanmesh codes within bounds', () => {
     const codes = getJisMeshCodesWithinBounds(
       {
@@ -173,6 +189,33 @@ describe('maplibre source helpers', () => {
     });
   });
 
+  it('converts decoded JIS root tile (tile_id=0) to full-scope GeoJSON polygons', async () => {
+    const encoded = await encodeTile({
+      tile_id: JIS_MESH_ROOT_TILE_ID,
+      mesh_kind: 'jis-x0410',
+      rows: 1,
+      cols: 1,
+      bands: 1,
+      dtype: 'uint8',
+      endianness: 'little',
+      compression: 'none',
+      no_data: null,
+      data: [7],
+    });
+
+    const decoded = await decodeTile(encoded.bytes);
+    const geojson = decodedMeshTileToGeoJson(decoded);
+
+    assert.equal(geojson.features.length, 1);
+    assert.deepEqual(geojson.features[0].geometry.coordinates[0], [
+      [JIS_MESH_SCOPE_BOUNDS.west, JIS_MESH_SCOPE_BOUNDS.south],
+      [JIS_MESH_SCOPE_BOUNDS.east, JIS_MESH_SCOPE_BOUNDS.south],
+      [JIS_MESH_SCOPE_BOUNDS.east, JIS_MESH_SCOPE_BOUNDS.north],
+      [JIS_MESH_SCOPE_BOUNDS.west, JIS_MESH_SCOPE_BOUNDS.north],
+      [JIS_MESH_SCOPE_BOUNDS.west, JIS_MESH_SCOPE_BOUNDS.south],
+    ]);
+  });
+
   it('fetches, decodes, and converts tiles via maplibre source handler', async () => {
     const fixturePath = join(process.cwd(), 'test', 'fixtures', 'xyz-uncompressed.tile');
     const bytes = new Uint8Array(await fs.readFile(fixturePath));