@navaramap/core 0.0.0

package/src/globe/Globe.ts

@@ -0,0 +1,156 @@
+import type { Globe as GlobeWasm } from "@navaramap/engine";
+
+import { ColorMap, Color } from "../color";
+import type { RemoveFreeRecursively } from "../types";
+/**
+ * Handler for accessing individual Globe properties from WASM.
+ * This provides a reference-based interface instead of copying the entire Globe object.
+ */
+export type GlobeHandler = {
+  getTransparent: () => boolean | undefined;
+  getMaxSse: () => number | undefined;
+  getSegments: () => number | undefined;
+  getColor: () => Color | undefined;
+  getHideUnderground: () => boolean | undefined;
+  getUseNormal: () => boolean | undefined;
+  getOpacity: () => number | undefined;
+  getWireframe: () => boolean | undefined;
+  getElevationColormap: () => Float32Array | undefined;
+  setTransparent: (value: boolean) => void;
+  setMaxSse: (value: number) => void;
+  setSegments: (value: number) => void;
+  setColor: (value: Color) => void;
+  setHideUnderground: (value: boolean) => void;
+  setUseNormal: (value: boolean) => void;
+  setOpacity: (value: number) => void;
+  setWireframe: (value: boolean) => void;
+  setElevationColormap: (value: ColorMap) => void;
+};
+
+export type GlobeOptions = Partial<
+  Omit<GlobeWasm, "constructor" | "free" | "elevationColormap" | "color">
+> & {
+  elevationColormap?: ColorMap;
+  color?: Color;
+};
+
+/**
+ * Globe configuration manager.
+ *
+ * Provides an interface for accessing and modifying globe properties
+ * that are shared across different material types (VectorTile, RasterTile, RasterTerrain).
+ */
+export class Globe implements Omit<
+  RemoveFreeRecursively<GlobeWasm>,
+  "elevationColormap" | "color"
+> {
+  private handler: GlobeHandler;
+  private _elevationColormap?: ColorMap;
+
+  constructor(handler: GlobeHandler, options?: GlobeOptions) {
+    this.handler = handler;
+    this.setOptions(options);
+  }
+
+  setOptions(options?: GlobeOptions) {
+    if (options?.maxSse != null) {
+      this.maxSse = options.maxSse;
+    }
+    if (options?.segments != null) {
+      this.segments = options.segments;
+    }
+    if (options?.color != null) {
+      this.color = options.color;
+    }
+    if (options?.hideUnderground != null) {
+      this.hideUnderground = options.hideUnderground;
+    }
+    if (options?.useNormal != null) {
+      this.useNormal = options.useNormal;
+    }
+    if (options?.transparent != null) {
+      this.transparent = options.transparent;
+    }
+    if (options?.opacity != null) {
+      this.opacity = options.opacity;
+    }
+    if (options?.wireframe != null) {
+      this.wireframe = options.wireframe;
+    }
+    if (options?.elevationColormap != null) {
+      this.elevationColormap = options.elevationColormap;
+    }
+  }
+
+  get maxSse(): number {
+    return this.handler.getMaxSse() ?? 2.0;
+  }
+
+  set maxSse(value: number) {
+    this.handler.setMaxSse(value);
+  }
+
+  get segments(): number {
+    return this.handler.getSegments() ?? 64;
+  }
+  set segments(value: number) {
+    this.handler.setSegments(value);
+  }
+
+  get color(): Color | undefined {
+    return this.handler.getColor();
+  }
+
+  set color(value: Color) {
+    this.handler.setColor(value);
+  }
+
+  get hideUnderground(): boolean {
+    return this.handler.getHideUnderground() ?? true;
+  }
+
+  set hideUnderground(value: boolean) {
+    this.handler.setHideUnderground(value);
+  }
+
+  get useNormal(): boolean {
+    return this.handler.getUseNormal() ?? false;
+  }
+
+  set useNormal(value: boolean) {
+    this.handler.setUseNormal(value);
+  }
+
+  get transparent(): boolean {
+    return this.handler.getTransparent() ?? false;
+  }
+
+  set transparent(value: boolean) {
+    this.handler.setTransparent(value);
+  }
+
+  get opacity(): number {
+    return this.handler.getOpacity() ?? 1.0;
+  }
+
+  set opacity(value: number) {
+    this.handler.setOpacity(value);
+  }
+
+  get wireframe(): boolean {
+    return this.handler.getWireframe() ?? false;
+  }
+
+  set wireframe(value: boolean) {
+    this.handler.setWireframe(value);
+  }
+
+  get elevationColormap(): ColorMap | undefined {
+    return this._elevationColormap;
+  }
+
+  set elevationColormap(value: ColorMap) {
+    this._elevationColormap = value;
+    this.handler.setElevationColormap(value);
+  }
+}

package/src/globe/index.ts

@@ -0,0 +1 @@
+export * from "./Globe";

package/src/id.ts

@@ -0,0 +1,9 @@
+import type { EntityEvent } from "@navaramap/engine";
+
+export function generate_id_from_entity(entity: EntityEvent) {
+  return `${entity.ind}_${entity.gen}`;
+}
+
+export function isEntityEvent(v: unknown): v is EntityEvent {
+  return !!v && typeof v === "object" && "ind" in v && "gen" in v;
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from "./id";
+export * from "./event";
+export * from "./assertions";
+export * from "./utils";
+export * from "./constants";
+export * from "./eventHandler";
+export * from "./batch";
+export * from "./error";
+export * from "./types";
+export * from "./namedIndexMap";
+export * from "./observed";
+export * from "./abstracts";
+export * from "./color";
+export * from "./globe";
+export * from "./plugin";

package/src/namedIndexMap.test.ts

@@ -0,0 +1,268 @@
+import { describe, it, expect, beforeEach } from "vitest";
+
+import { NamedIndexMap } from "./namedIndexMap";
+
+type TestItem = {
+  name: string;
+  value: number;
+};
+
+describe("NamedIndexMap", () => {
+  let map: NamedIndexMap<TestItem>;
+
+  beforeEach(() => {
+    map = new NamedIndexMap<TestItem>();
+  });
+
+  describe("add", () => {
+    it("should add items to the list and indexMap", () => {
+      const item1 = { name: "first", value: 1 };
+      const item2 = { name: "second", value: 2 };
+
+      map.add(item1);
+      map.add(item2);
+
+      expect(map.list).toEqual([item1, item2]);
+      expect(map.indexMap).toEqual({ first: 0, second: 1 });
+    });
+
+    it("should throw error for duplicate names", () => {
+      const item1 = { name: "duplicate", value: 1 };
+      const item2 = { name: "duplicate", value: 2 };
+
+      map.add(item1);
+      expect(() => map.add(item2)).toThrow("duplicate name: duplicate");
+    });
+  });
+
+  describe("insertBefore", () => {
+    beforeEach(() => {
+      map.add({ name: "first", value: 1 });
+      map.add({ name: "second", value: 2 });
+      map.add({ name: "third", value: 3 });
+    });
+
+    it("should insert item before target", () => {
+      const newItem = { name: "new", value: 10 };
+      map.insertBefore("second", newItem);
+
+      expect(map.list.map((item) => item.name)).toEqual([
+        "first",
+        "new",
+        "second",
+        "third",
+      ]);
+      expect(map.indexMap).toEqual({ first: 0, new: 1, second: 2, third: 3 });
+    });
+
+    it("should insert before first item", () => {
+      const newItem = { name: "new", value: 10 };
+      map.insertBefore("first", newItem);
+
+      expect(map.list.map((item) => item.name)).toEqual([
+        "new",
+        "first",
+        "second",
+        "third",
+      ]);
+      expect(map.indexMap).toEqual({ new: 0, first: 1, second: 2, third: 3 });
+    });
+
+    it("should throw error for non-existent target", () => {
+      const newItem = { name: "new", value: 10 };
+      expect(() => map.insertBefore("nonexistent", newItem)).toThrow(
+        "target not found: nonexistent",
+      );
+    });
+
+    it("should throw error for duplicate name", () => {
+      const newItem = { name: "first", value: 10 };
+      expect(() => map.insertBefore("second", newItem)).toThrow(
+        "duplicate name: first",
+      );
+    });
+  });
+
+  describe("insertAfter", () => {
+    beforeEach(() => {
+      map.add({ name: "first", value: 1 });
+      map.add({ name: "second", value: 2 });
+      map.add({ name: "third", value: 3 });
+    });
+
+    it("should insert item after target", () => {
+      const newItem = { name: "new", value: 10 };
+      map.insertAfter("second", newItem);
+
+      expect(map.list.map((item) => item.name)).toEqual([
+        "first",
+        "second",
+        "new",
+        "third",
+      ]);
+      expect(map.indexMap).toEqual({ first: 0, second: 1, new: 2, third: 3 });
+    });
+
+    it("should insert after last item", () => {
+      const newItem = { name: "new", value: 10 };
+      map.insertAfter("third", newItem);
+
+      expect(map.list.map((item) => item.name)).toEqual([
+        "first",
+        "second",
+        "third",
+        "new",
+      ]);
+      expect(map.indexMap).toEqual({ first: 0, second: 1, third: 2, new: 3 });
+    });
+
+    it("should throw error for non-existent target", () => {
+      const newItem = { name: "new", value: 10 };
+      expect(() => map.insertAfter("nonexistent", newItem)).toThrow(
+        "target not found: nonexistent",
+      );
+    });
+
+    it("should throw error for duplicate name", () => {
+      const newItem = { name: "second", value: 10 };
+      expect(() => map.insertAfter("first", newItem)).toThrow(
+        "duplicate name: second",
+      );
+    });
+  });
+
+  describe("insertAt", () => {
+    beforeEach(() => {
+      map.add({ name: "first", value: 1 });
+      map.add({ name: "second", value: 2 });
+      map.add({ name: "third", value: 3 });
+    });
+
+    it("should insert at beginning", () => {
+      const newItem = { name: "new", value: 10 };
+      (map as any).insertAt(0, newItem);
+
+      expect(map.list.map((item) => item.name)).toEqual([
+        "new",
+        "first",
+        "second",
+        "third",
+      ]);
+      expect(map.indexMap).toEqual({ new: 0, first: 1, second: 2, third: 3 });
+    });
+
+    it("should insert at middle", () => {
+      const newItem = { name: "new", value: 10 };
+      (map as any).insertAt(2, newItem);
+
+      expect(map.list.map((item) => item.name)).toEqual([
+        "first",
+        "second",
+        "new",
+        "third",
+      ]);
+      expect(map.indexMap).toEqual({ first: 0, second: 1, new: 2, third: 3 });
+    });
+
+    it("should insert at end", () => {
+      const newItem = { name: "new", value: 10 };
+      (map as any).insertAt(3, newItem);
+
+      expect(map.list.map((item) => item.name)).toEqual([
+        "first",
+        "second",
+        "third",
+        "new",
+      ]);
+      expect(map.indexMap).toEqual({ first: 0, second: 1, third: 2, new: 3 });
+    });
+
+    it("should throw error for negative index", () => {
+      const newItem = { name: "new", value: 10 };
+      expect(() => (map as any).insertAt(-1, newItem)).toThrow(
+        "index out of range: -1",
+      );
+    });
+
+    it("should throw error for index greater than length", () => {
+      const newItem = { name: "new", value: 10 };
+      expect(() => (map as any).insertAt(4, newItem)).toThrow(
+        "index out of range: 4",
+      );
+    });
+
+    it("should throw error for duplicate name", () => {
+      const newItem = { name: "first", value: 10 };
+      expect(() => (map as any).insertAt(1, newItem)).toThrow(
+        "duplicate name: first",
+      );
+    });
+  });
+
+  describe("findIndex", () => {
+    beforeEach(() => {
+      map.add({ name: "first", value: 1 });
+      map.add({ name: "second", value: 2 });
+    });
+
+    it("should return correct index for existing name", () => {
+      expect((map as any).findIndex("first")).toBe(0);
+      expect((map as any).findIndex("second")).toBe(1);
+    });
+
+    it("should throw error for non-existent name", () => {
+      expect(() => (map as any).findIndex("nonexistent")).toThrow(
+        "target not found: nonexistent",
+      );
+    });
+  });
+
+  describe("assertUnique", () => {
+    beforeEach(() => {
+      map.add({ name: "existing", value: 1 });
+    });
+
+    it("should not throw for unique name", () => {
+      expect(() => (map as any).assertUnique("unique")).not.toThrow();
+    });
+
+    it("should throw for duplicate name", () => {
+      expect(() => (map as any).assertUnique("existing")).toThrow(
+        "duplicate name: existing",
+      );
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle empty map", () => {
+      expect(map.list).toEqual([]);
+      expect(map.indexMap).toEqual({});
+    });
+
+    it("should handle single item", () => {
+      const item = { name: "single", value: 1 };
+      map.add(item);
+
+      expect(map.list).toEqual([item]);
+      expect(map.indexMap).toEqual({ single: 0 });
+    });
+
+    it("should maintain correct indices after multiple insertions", () => {
+      map.add({ name: "a", value: 1 });
+      map.add({ name: "b", value: 2 });
+      map.add({ name: "c", value: 3 });
+
+      map.insertBefore("b", { name: "x", value: 10 });
+      map.insertAfter("c", { name: "y", value: 20 });
+
+      expect(map.list.map((item) => item.name)).toEqual([
+        "a",
+        "x",
+        "b",
+        "c",
+        "y",
+      ]);
+      expect(map.indexMap).toEqual({ a: 0, x: 1, b: 2, c: 3, y: 4 });
+    });
+  });
+});

package/src/namedIndexMap.ts

@@ -0,0 +1,50 @@
+export class NamedIndexMap<T extends { name: string }> {
+  list: T[] = [];
+  indexMap: Record<string, number> = {};
+
+  add(v: T): void {
+    this.assertUnique(v.name);
+    const idx = this.list.length;
+    this.list.push(v);
+    this.indexMap[v.name] = idx;
+  }
+
+  insertBefore(targetName: string, v: T): number {
+    const idx = this.findIndex(targetName);
+    return this.insertAt(idx, v);
+  }
+
+  insertAfter(targetName: string, v: T): number {
+    const idx = this.findIndex(targetName);
+    return this.insertAt(idx + 1, v);
+  }
+
+  private insertAt(index: number, v: T): number {
+    this.assertUnique(v.name);
+    if (index < 0 || index > this.list.length) {
+      throw new RangeError(`index out of range: ${index}`);
+    }
+
+    this.list.splice(index, 0, v);
+
+    for (let i = index; i < this.list.length; i++) {
+      this.indexMap[this.list[i].name] = i;
+    }
+
+    return index;
+  }
+
+  private findIndex(name: string): number {
+    const idx = this.indexMap[name];
+    if (idx === undefined) {
+      throw new Error(`target not found: ${name}`);
+    }
+    return idx;
+  }
+
+  private assertUnique(name: string): void {
+    if (this.indexMap[name] !== undefined) {
+      throw new Error(`duplicate name: ${name}`);
+    }
+  }
+}

package/src/observed.ts

@@ -0,0 +1,30 @@
+import { EventHandler } from "./eventHandler";
+
+export type ObservedEvent<T> = {
+  changed: (v: T) => void;
+};
+
+export class Observed<T> extends EventHandler<ObservedEvent<T>> {
+  private _value: T;
+  constructor(v: T) {
+    super();
+    this._value = v;
+  }
+
+  get value() {
+    return this._value;
+  }
+
+  set value(v: T) {
+    this._value = v;
+    this.emit("changed", v);
+  }
+
+  changed(f: (v: T) => void) {
+    const wrap = (v: T) => {
+      f(v);
+      this.off("changed", wrap);
+    };
+    this.on("changed", wrap);
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,15 @@
+/**
+ * Base `Plugin` abstract class.
+ * This class doesn't have a logic, but has interfaces.
+ * ```
+ * class MyPlugin extends Plugin<ThreeView<MyCustomDescriptions>, ViewContext> {
+ *   async init(view, ctx) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+// DO NOT add a logic to this class as much as possible.
+export abstract class Plugin<TView = unknown, TCtx = unknown> {
+  abstract init(view: TView, ctx: TCtx): Promise<void>;
+}

package/src/time.ts

@@ -0,0 +1,3 @@
+export function wait(t: number) {
+  return new Promise((r) => setTimeout(r, t));
+}

package/src/types/buffer.ts

@@ -0,0 +1,4 @@
+export type TypedArrayLike = {
+  [index: number]: number;
+  readonly length: number;
+};

package/src/types/camera.ts

@@ -0,0 +1,16 @@
+import type { CameraOrientation as EngineCameraOrientation } from "@navaramap/engine";
+
+import type { LatLngHeight } from "./unit";
+import type { NormalizeWASMClass } from "./utils";
+
+export type CameraOrientation = Partial<
+  NormalizeWASMClass<EngineCameraOrientation>
+>;
+
+export type CameraPosition = Partial<LatLngHeight> &
+  CameraOrientation & {
+    /** Distance from the target point (lng/lat/height) along the camera forward direction (meters).
+     *  When specified, the camera is placed so its forward ray reaches the target point from this distance.
+     *  If `height` is omitted, the target elevation defaults to 0 (sea level). */
+    distance?: number;
+  };

package/src/types/cameraFrustum.ts

@@ -0,0 +1,5 @@
+import type { CameraFrustum as EngineCameraFrustum } from "@navaramap/engine-api";
+
+import type { NormalizeWASMClass } from "./utils";
+
+export type CameraFrustum = Required<NormalizeWASMClass<EngineCameraFrustum>>;

package/src/types/feature.ts

@@ -0,0 +1 @@
+export type FeatureSetId = bigint;

package/src/types/index.ts

@@ -0,0 +1,13 @@
+export * from "./buffer";
+export * from "./feature";
+export * from "./tile";
+export * from "./camera";
+export * from "./utils";
+export * from "./unit";
+export * from "./window";
+export * from "./transform";
+export * from "./cameraFrustum";
+export * from "./plane";
+export * from "./ray";
+export * from "./vec";
+export * from "./layer";

package/src/types/layer.ts

@@ -0,0 +1 @@
+export type LayerId = string;

package/src/types/plane.ts

@@ -0,0 +1,5 @@
+import type { Plane as EnginePlane } from "@navaramap/engine-api";
+
+import type { NormalizeWASMClass } from "./utils";
+
+export type Plane = Required<NormalizeWASMClass<EnginePlane>>;

package/src/types/ray.ts

@@ -0,0 +1,5 @@
+import type { Ray as EngineRay } from "@navaramap/engine-api";
+
+import type { NormalizeWASMClass } from "./utils";
+
+export type Ray = Required<NormalizeWASMClass<EngineRay>>;

package/src/types/tile.ts

@@ -0,0 +1 @@
+export type TileHandle = bigint;

package/src/types/transform.ts

@@ -0,0 +1,5 @@
+import type { Transform as EngineTransform } from "@navaramap/engine-api";
+
+import type { NormalizeWASMClass } from "./utils";
+
+export type Transform = Required<NormalizeWASMClass<EngineTransform>>;

package/src/types/unit.ts

@@ -0,0 +1,7 @@
+import type { LLE } from "@navaramap/engine";
+
+import type { NormalizeWASMClass } from "./utils";
+
+export type XYZ = { x: number; y: number; z: number };
+export type LatLngHeight = Required<NormalizeWASMClass<LLE>>;
+export type LatLng = Omit<LatLngHeight, "height">;

package/src/types/utils.ts

@@ -0,0 +1,20 @@
+export type Nullable<T> = T | null | undefined;
+
+export type RemoveFreeRecursively<T> = T extends { free: unknown }
+  ? {
+      [K in keyof T as K extends "free" | symbol | number
+        ? never
+        : K]: RemoveFreeRecursively<T[K]>;
+    }
+  : T;
+
+// wasm-bindgen generate a getter and setter, so need to extract it as a property.
+export type ExtractProperties<T> = {
+  [K in keyof T]?: T[K] extends (...args: any) => any
+    ? ReturnType<T[K]> extends (...args: any) => any
+      ? ExtractProperties<ReturnType<T[K]>>
+      : ReturnType<T[K]>
+    : Partial<T[K]>;
+};
+
+export type NormalizeWASMClass<C> = ExtractProperties<RemoveFreeRecursively<C>>;

package/src/types/vec.ts

@@ -0,0 +1,9 @@
+import type {
+  Vec2 as EngineVec2,
+  Vec3 as EngineVec3,
+} from "@navaramap/engine-api";
+
+import type { NormalizeWASMClass } from "./utils";
+
+export type Vec2 = Required<NormalizeWASMClass<EngineVec2>>;
+export type Vec3 = Required<NormalizeWASMClass<EngineVec3>>;

package/src/types/window.ts

@@ -0,0 +1,5 @@
+import type { Window as EngineWindow } from "@navaramap/engine";
+
+import type { NormalizeWASMClass } from "./utils";
+
+export type Window = Required<NormalizeWASMClass<EngineWindow>>;