@navaramap/three 0.0.1 → 0.0.3

package/src/passes/CustomRenderPass.ts

@@ -2,11 +2,13 @@ import { Globe } from "@navaramap/core";
 import { DepthCopyPass } from "postprocessing";
 import {
   Color,
+  DepthStencilFormat,
   DepthTexture,
   HalfFloatType,
   NearestFilter,
   RGBADepthPacking,
   Scene,
+  UnsignedInt248Type,
   WebGLRenderTarget,
   type PerspectiveCamera,
   type WebGLRenderer,
@@ -90,7 +92,20 @@ export class CustomRenderPass extends RenderPass {
     emissiveTexture.type = HalfFloatType;
     this.gbufferRenderTarget.textures.push(emissiveTexture);
 
+    // The gbuffer owns its depth texture instead of sharing the composer's one
+    // (postprocessing >= 6.39 no longer exposes a writable shared depth
+    // texture). Depth is propagated to the composer's input buffer explicitly
+    // by the copy pass below. Stencil is required for draped-mesh rendering.
+    const gbufferDepthTexture = new DepthTexture(
+      this.gbufferRenderTarget.width,
+      this.gbufferRenderTarget.height,
+      UnsignedInt248Type,
+    );
+    gbufferDepthTexture.format = DepthStencilFormat;
+    this.gbufferRenderTarget.depthTexture = gbufferDepthTexture;
+
     this.copyPass = new RenderTargetCopyPass(this.gbufferRenderTarget);
+    this.copyPass.setDepthTexture(gbufferDepthTexture);
 
     this.globeDepthCopyPass = new DepthCopyPass({
       depthPacking: RGBADepthPacking,
@@ -240,11 +255,12 @@ export class CustomRenderPass extends RenderPass {
     this.allDepthCopyPass.render(renderer, null, null);
   }
 
-  setDepthTexture(depthTexture: DepthTexture): void {
-    this.gbufferRenderTarget.depthTexture = depthTexture;
-    this.globeDepthCopyPass.setDepthTexture(depthTexture.clone());
-    this.copyPass.setDepthTexture(depthTexture);
-  }
+  // The composer-provided depth texture is intentionally ignored: the gbuffer
+  // owns its depth texture and depth is copied into the input buffer by the
+  // copy pass. `needsDepthTexture` stays true so the composer still attaches a
+  // depth texture to the input buffer, which `allDepthCopyPass` reads after
+  // the opaque scene has been rendered.
+  setDepthTexture(): void {}
 
   setSize(width: number, height: number) {
     this.gbufferRenderTarget.setSize(width, height);

package/src/passes/RenderTargetCopyPass.ts

@@ -1,6 +1,7 @@
 import PostProcessingCommon from "@shaders/glsl/postprocessingCommon.vert.glsl";
 import { Pass } from "postprocessing";
 import {
+  AlwaysDepth,
   NoBlending,
   ShaderMaterial,
   Texture,
@@ -10,13 +11,18 @@ import {
 
 const fragmentShader = `
 uniform sampler2D color;
+
+#ifdef COPY_DEPTH
 uniform sampler2D depth;
+#endif
 
 varying vec2 vUv;
 
 void main() {
   gl_FragColor = texture2D(color, vUv);
-  gl_FragDepth = texture2D(color, vUv).r;
+  #ifdef COPY_DEPTH
+  gl_FragDepth = texture2D(depth, vUv).r;
+  #endif
 }
 `;
 
@@ -71,8 +77,24 @@ export class RenderTargetCopyPass extends Pass {
     this._material.uniforms.color.value = texture;
   }
 
-  setDepthTexture(texture: Texture): void {
+  /**
+   * When a depth texture is set, the pass copies its depth into the target's
+   * depth buffer via gl_FragDepth. Depth test must be enabled (with AlwaysDepth)
+   * because GL discards depth writes while the depth test is disabled.
+   */
+  setDepthTexture(texture: Texture | null): void {
     this._material.uniforms.depth.value = texture;
+    const copyDepth = texture !== null;
+    if ("COPY_DEPTH" in this._material.defines === copyDepth) return;
+    if (copyDepth) {
+      this._material.defines.COPY_DEPTH = "";
+    } else {
+      delete this._material.defines.COPY_DEPTH;
+    }
+    this._material.depthWrite = copyDepth;
+    this._material.depthTest = copyDepth;
+    this._material.depthFunc = AlwaysDepth;
+    this._material.needsUpdate = true;
   }
 
   render(

package/src/solar.test.ts

@@ -2,6 +2,8 @@ import { AstroTime, Body, HourAngle, Observer } from "astronomy-engine";
 import { describe, expect, it } from "vitest";
 
 import {
+  dateForSolarTime,
+  getSolarTime,
   getSunElevation,
   shiftDateToElevation,
   shiftDateToHourAngle,
@@ -66,6 +68,37 @@ describe("shiftDateToElevation", () => {
   });
 });
 
+describe("getSolarTime / dateForSolarTime", () => {
+  it("reads ~12 (solar noon) at Tokyo solar noon", () => {
+    // Tokyo solar noon ≈ 02:43 UTC on 2024-06-21
+    const date = new Date("2024-06-21T02:43:00Z");
+    expect(getSolarTime(date, 139.69)).toBeCloseTo(12, 1);
+  });
+
+  it("reads ~0 (solar midnight) at Tokyo solar midnight", () => {
+    // Tokyo solar midnight ≈ 14:43 UTC on 2024-06-21
+    const date = new Date("2024-06-21T14:43:00Z");
+    const t = getSolarTime(date, 139.69);
+    expect(Math.min(t, 24 - t)).toBeCloseTo(0, 1);
+  });
+
+  it("round-trips: dateForSolarTime then getSolarTime returns the input", () => {
+    for (const hours of [0, 6.3, 12, 18.75]) {
+      const date = dateForSolarTime(BASE_DATE, 139.69, hours);
+      // Compare on the 24h circle so 0 and 24 count as equal.
+      const diff = Math.abs(getSolarTime(date, 139.69) - hours);
+      expect(Math.min(diff, 24 - diff)).toBeCloseTo(0, 2);
+    }
+  });
+
+  it("puts the sun above the horizon at midday and below at midnight", () => {
+    const noon = dateForSolarTime(BASE_DATE, 139.69, 12);
+    expect(getSunElevation(noon, 35.68, 139.69)).toBeGreaterThan(0);
+    const midnight = dateForSolarTime(BASE_DATE, 139.69, 0);
+    expect(getSunElevation(midnight, 35.68, 139.69)).toBeLessThan(0);
+  });
+});
+
 describe("getSunElevation", () => {
   it("returns positive elevation at solar noon", () => {
     // Tokyo solar noon ≈ 02:43 UTC on 2024-06-21

package/src/solar.ts

@@ -20,6 +20,37 @@ export function getSunElevation(date: Date, lat: number, lng: number): number {
   return Horizon(time, observer, eq.ra, eq.dec, "normal").altitude;
 }
 
+/**
+ * Returns the local apparent solar time at `lng` for `date`, in hours in the
+ * range [0, 24) where 12 is solar noon. Derived from the sun's hour angle, so
+ * it accounts for the equation of time.
+ */
+export function getSolarTime(date: Date, lng: number): number {
+  const ha = HourAngle(Body.Sun, new AstroTime(date), new Observer(0, lng, 0));
+  return (ha + 12) % 24;
+}
+
+/**
+ * Returns a new Date on the same UTC-anchored solar day such that the local
+ * apparent solar time at `lng` equals `hours` (0–24). Inverse of
+ * {@link getSolarTime}.
+ */
+export function dateForSolarTime(date: Date, lng: number, hours: number): Date {
+  const targetHourAngle = (((hours - 12) % 24) + 24) % 24;
+  const dayStart = new AstroTime(
+    new Date(
+      Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
+    ),
+  );
+  return SearchHourAngle(
+    Body.Sun,
+    new Observer(0, lng, 0),
+    targetHourAngle,
+    dayStart,
+    1,
+  ).time.date;
+}
+
 /**
  * Returns a new Date such that the sun's hour angle at `targetLng` matches the
  * hour angle currently at `fromLng`.

package/src/test-utils/engine.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+
+import { Core, initSync } from "@navaramap/engine";
+
+import type { TileHandler } from "../event/context";
+import { createTileHandler } from "../event/tileHandler";
+
+let engineInitialized = false;
+
+/**
+ * Initialize the engine WASM once per vitest worker. The web-target module
+ * normally streams the binary over `fetch` (`initCore`), which Node cannot do
+ * for workspace files — so the bytes are read from the `@navaramap/engine`
+ * package and compiled synchronously. Repeat calls are no-ops; every test
+ * file that touches Rust-backed functions can call this without coordination.
+ */
+export function initTestEngine(): void {
+  if (engineInitialized) return;
+  const require = createRequire(import.meta.url);
+  const wasmPath = require.resolve("@navaramap/engine/navara_wasm_bg.wasm");
+  initSync({ module: readFileSync(wasmPath) });
+  engineInitialized = true;
+}
+
+let sharedCore: Core | undefined;
+
+/**
+ * Lazily created `Core` shared across a vitest worker's test files.
+ * `Core::new` only builds the Bevy app (no DOM access), so it is safe in the
+ * Node test environment. Shared deliberately: tests exercise Rust-backed
+ * queries against one engine instead of paying a per-file world setup.
+ */
+export function getTestCore(): Core {
+  initTestEngine();
+  sharedCore ??= new Core("navara-test");
+  return sharedCore;
+}
+
+/**
+ * The production {@link TileHandler} assembled over the shared test engine —
+ * tests reach the same Rust functions (e.g. `mercatorY`) the app wires through
+ * the event context, instead of stubbing them. The `Core` is created lazily on
+ * first Core-backed call, so pure-function consumers never construct it.
+ */
+export function createTestTileHandler(): TileHandler {
+  initTestEngine();
+  return createTileHandler({
+    getCore: () => getTestCore(),
+    getVectorRevision: () => 0,
+    getRasterRevision: () => 0,
+  });
+}

package/src/tileTexture/TileTextureCompositor.test.ts

@@ -2,6 +2,7 @@ import { Mesh, BoxGeometry, MeshBasicMaterial } from "three";
 import { describe, expect, it, vi } from "vitest";
 
 import { TexturizedSceneByTileCoordinates } from "../scene";
+import { createTestTileHandler } from "../test-utils/engine";
 
 import { TileTextureCompositor } from "./TileTextureCompositor";
 import type { AtlasFactory, CompositeAtlas } from "./types";
@@ -47,6 +48,7 @@ function setup() {
       typeof TileTextureCompositor
     >[0]["renderer"],
     texturizedSceneByTileCoordinates: texturizedScenes,
+    mercatorY: createTestTileHandler().mercatorY,
     atlasFactory: fakeFactory,
   });
   return { compositor, renderer, texturizedScenes };

package/src/tileTexture/TileTextureCompositor.ts

@@ -77,6 +77,10 @@ export const defaultAtlasFactory =
 export type TileTextureCompositorOptions = {
   renderer: WebGLRenderer;
   texturizedSceneByTileCoordinates: TexturizedSceneByTileCoordinates;
+  /** Rust's clamped WebMercator northing (`TileHandler.mercatorY`), handed to
+   * the core uniform mutates so the paste-side reprojection constants come
+   * from the same implementation as the Rust bake affine. */
+  mercatorY: (lat: number) => number;
   /** Atlas RT side length (defaults to 512). */
   size?: number;
   /** Test seam: replace MRT RT creation. */
@@ -142,6 +146,7 @@ export class TileTextureCompositor {
    * per-tile GPU byte cost it reports to the memory ledger. */
   readonly size: number;
   private readonly texturizedScenes: TexturizedSceneByTileCoordinates;
+  private readonly mercatorY: (lat: number) => number;
   // Single camera shared by every drape bake (vector and raster), re-framed
   // per source by `frameBakeCamera`. Ancestor fallback is resolved in Rust,
   // so no per-tile camera transform is needed.
@@ -189,6 +194,7 @@ export class TileTextureCompositor {
   constructor(opts: TileTextureCompositorOptions) {
     this.renderer = opts.renderer;
     this.texturizedScenes = opts.texturizedSceneByTileCoordinates;
+    this.mercatorY = opts.mercatorY;
     this.size = opts.size ?? 512;
     this.cache = new TileTextureCache({
       size: this.size,
@@ -560,7 +566,7 @@ export class TileTextureCompositor {
     // uniform ownership: each active enhancer attaches its own uniform refs and
     // contributes the matching GLSL, so a new expression touches only its module.
     const chain = createCompositeLayerEnhancers(features);
-    const core = createCoreUniformMutates();
+    const core = createCoreUniformMutates(this.mercatorY);
 
     const uniforms: CompositeUniformTarget = {};
     core.attachUniforms(uniforms, numTextures, placeholderTexture);

package/src/utils/fixedGpuFootprint.test.ts

@@ -0,0 +1,110 @@
+import type { EffectComposer, Pass } from "postprocessing";
+import { DepthTexture, HalfFloatType, WebGLRenderTarget } from "three";
+import { describe, expect, it } from "vitest";
+
+import { estimateFixedGpuBytes } from "./fixedGpuFootprint";
+
+const W = 100;
+const H = 10;
+const PX = W * H;
+
+function composerWith(
+  input: WebGLRenderTarget,
+  output: WebGLRenderTarget,
+): EffectComposer {
+  return { inputBuffer: input, outputBuffer: output } as EffectComposer;
+}
+
+function rgba8Target(): WebGLRenderTarget {
+  return new WebGLRenderTarget(W, H, { depthBuffer: false });
+}
+
+describe("estimateFixedGpuBytes", () => {
+  it("sums composer buffers by texture type and depth attachment", () => {
+    const input = new WebGLRenderTarget(W, H, {
+      type: HalfFloatType,
+      depthBuffer: true,
+    });
+    const output = new WebGLRenderTarget(W, H, { depthBuffer: false });
+    const bytes = estimateFixedGpuBytes(composerWith(input, output), []);
+    // input: RGBA16F (8) + depth (4); output: RGBA8 (4)
+    expect(bytes).toBe(PX * (8 + 4) + PX * 4);
+  });
+
+  it("counts a render target reachable from two passes only once", () => {
+    const shared = rgba8Target();
+    const passes = [
+      { renderTarget: shared } as unknown as Pass,
+      { anotherRef: shared } as unknown as Pass,
+    ];
+    const bytes = estimateFixedGpuBytes(
+      composerWith(rgba8Target(), rgba8Target()),
+      passes,
+    );
+    expect(bytes).toBe(PX * 4 * 3);
+  });
+
+  it("finds targets nested in pass properties and arrays", () => {
+    const nested = { copyPass: { target: rgba8Target() } } as unknown as Pass;
+    const inArray = {
+      effects: [{ renderTarget: rgba8Target() }],
+    } as unknown as Pass;
+    const bytes = estimateFixedGpuBytes(
+      composerWith(rgba8Target(), rgba8Target()),
+      [nested, inArray],
+    );
+    expect(bytes).toBe(PX * 4 * 4);
+  });
+
+  it("adds MSAA renderbuffer bytes on multisampled targets", () => {
+    const msaa = new WebGLRenderTarget(W, H, {
+      samples: 4,
+      depthBuffer: true,
+    });
+    const bytes = estimateFixedGpuBytes(composerWith(msaa, rgba8Target()), []);
+    // msaa: RGBA8 resolve (4) + depth (4) + 4 samples × (4 + 4); output: 4
+    expect(bytes).toBe(PX * (4 + 4 + 4 * 8) + PX * 4);
+  });
+
+  it("counts every MRT attachment and depth textures in the MSAA term", () => {
+    const mrt = new WebGLRenderTarget(W, H, {
+      count: 2,
+      samples: 2,
+      depthBuffer: false,
+    });
+    mrt.textures[1].type = HalfFloatType;
+    mrt.depthTexture = new DepthTexture(W, H);
+    const bytes = estimateFixedGpuBytes(composerWith(mrt, rgba8Target()), []);
+    // mrt: RGBA8 (4) + RGBA16F (8) + depth texture (4)
+    //      + 2 samples × (4 + 8 + 4); output: 4
+    expect(bytes).toBe(PX * (4 + 8 + 4 + 2 * 16) + PX * 4);
+  });
+
+  it("skips render targets that are not GL-allocated yet", () => {
+    const allocated = rgba8Target();
+    const lazy = rgba8Target();
+    const composer = {
+      inputBuffer: allocated,
+      outputBuffer: lazy,
+      getRenderer: () => ({
+        properties: {
+          get: (object: object) =>
+            object === allocated ? { __webglFramebuffer: {} } : {},
+        },
+      }),
+    } as unknown as EffectComposer;
+    expect(estimateFixedGpuBytes(composer, [])).toBe(PX * 4);
+  });
+
+  it("does not walk into typed arrays or huge buffers", () => {
+    const pass = {
+      geometryData: new Float32Array(1_000_000),
+      target: rgba8Target(),
+    } as unknown as Pass;
+    const bytes = estimateFixedGpuBytes(
+      composerWith(rgba8Target(), rgba8Target()),
+      [pass],
+    );
+    expect(bytes).toBe(PX * 4 * 3);
+  });
+});

package/src/utils/fixedGpuFootprint.ts

@@ -0,0 +1,162 @@
+import type { EffectComposer, Pass } from "postprocessing";
+import {
+  FloatType,
+  HalfFloatType,
+  Material,
+  Object3D,
+  Texture,
+  WebGLRenderTarget,
+} from "three";
+
+const DEPTH_BYTES_PER_TEXEL = 4; // DEPTH24_STENCIL8 / DEPTH_COMPONENT32F
+const MIPMAP_FACTOR = 1.33;
+
+function bytesPerTexel(type: number): number {
+  switch (type) {
+    case FloatType:
+      return 16; // RGBA32F
+    case HalfFloatType:
+      return 8; // RGBA16F
+    default:
+      return 4; // RGBA8 and friends
+  }
+}
+
+function renderTargetBytes(target: WebGLRenderTarget): number {
+  const pixels = target.width * target.height;
+  let bytes = 0;
+  for (const texture of target.textures) {
+    let textureBytes = pixels * bytesPerTexel(texture.type);
+    if (texture.generateMipmaps) {
+      textureBytes = Math.floor(textureBytes * MIPMAP_FACTOR);
+    }
+    bytes += textureBytes;
+  }
+  if (target.depthBuffer || target.depthTexture) {
+    bytes += pixels * DEPTH_BYTES_PER_TEXEL;
+  }
+  if (target.samples > 0) {
+    // MSAA renderbuffers exist alongside the resolve textures: one per color
+    // attachment, plus a depth renderbuffer whether depth is a plain buffer
+    // or a depth texture.
+    let msaaBytesPerPixel = 0;
+    for (const texture of target.textures) {
+      msaaBytesPerPixel += bytesPerTexel(texture.type);
+    }
+    if (target.depthBuffer || target.depthTexture) {
+      msaaBytesPerPixel += DEPTH_BYTES_PER_TEXEL;
+    }
+    bytes += target.samples * pixels * msaaBytesPerPixel;
+  }
+  return bytes;
+}
+
+function collectRenderTargets(
+  value: unknown,
+  targets: Set<WebGLRenderTarget>,
+  visited: Set<object>,
+  depth: number,
+): void {
+  if (value === null || typeof value !== "object" || visited.has(value)) {
+    return;
+  }
+  visited.add(value);
+
+  if (value instanceof WebGLRenderTarget) {
+    targets.add(value);
+    return;
+  }
+
+  // Prune subtrees that cannot contain render targets: scene graphs,
+  // materials, textures, and raw buffers (Object.keys on a large typed array
+  // would enumerate every element).
+  if (
+    depth <= 0 ||
+    ArrayBuffer.isView(value) ||
+    value instanceof ArrayBuffer ||
+    value instanceof Object3D ||
+    value instanceof Material ||
+    value instanceof Texture
+  ) {
+    return;
+  }
+
+  // Shallow property scan, mirroring postprocessing's Pass.dispose() search.
+  // Recursion is bounded so nested passes/effects (e.g. CustomRenderPass's
+  // copy passes, EffectPass's effects) are covered without walking the scene.
+  for (const key of Object.keys(value)) {
+    const child = (value as Record<string, unknown>)[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        collectRenderTargets(item, targets, visited, depth - 1);
+      }
+    } else {
+      collectRenderTargets(child, targets, visited, depth - 1);
+    }
+  }
+}
+
+/**
+ * Returns whether the render target has actually been allocated on the GPU.
+ * Three.js allocates lazily on first `setRenderTarget`, so targets that a
+ * pipeline never renders into (e.g. a `CopyPass` used with `renderToScreen`,
+ * the composer's output buffer while no pass swaps, mode-dependent merge
+ * targets) hold no GPU memory and must not be charged to the ledger.
+ * `renderer.properties` is an internal-but-stable API (postprocessing itself
+ * relies on it); when it is unavailable, assume allocated.
+ */
+function isAllocated(renderer: unknown, target: WebGLRenderTarget): boolean {
+  const properties = (
+    renderer as {
+      properties?: { get(object: object): { __webglFramebuffer?: unknown } };
+    } | null
+  )?.properties;
+  if (!properties) return true;
+  return properties.get(target).__webglFramebuffer !== undefined;
+}
+
+/**
+ * Estimates the resident GPU bytes of the fixed (screen-sized, non-tile)
+ * render-target stack: the composer's ping-pong and depth buffers plus every
+ * render target reachable from the registered passes and their effects.
+ * Targets not yet allocated on the GPU are skipped, so the estimate should be
+ * re-taken after rendering (allocations happen lazily during the first frames
+ * that exercise a code path).
+ *
+ * The result is an estimate in the same accuracy class as the ledger's
+ * `gpu_bytes_est`: texture formats are mapped to nominal byte sizes and
+ * driver padding is ignored.
+ */
+export function estimateFixedGpuBytes(
+  composer: EffectComposer,
+  passes: Iterable<Pass>,
+): number {
+  const targets = new Set<WebGLRenderTarget>();
+  const visited = new Set<object>();
+
+  collectRenderTargets(composer.inputBuffer, targets, visited, 0);
+  collectRenderTargets(composer.outputBuffer, targets, visited, 0);
+  // Stable-depth target (postprocessing >= 6.39); private, hence the cast.
+  collectRenderTargets(
+    (composer as unknown as { depthRenderTarget?: WebGLRenderTarget | null })
+      .depthRenderTarget,
+    targets,
+    visited,
+    0,
+  );
+
+  for (const pass of passes) {
+    collectRenderTargets(pass, targets, visited, 3);
+  }
+
+  const renderer = (
+    composer as unknown as { getRenderer?: () => unknown }
+  ).getRenderer?.();
+
+  let bytes = 0;
+  for (const target of targets) {
+    if (!isAllocated(renderer, target)) continue;
+    bytes += renderTargetBytes(target);
+  }
+  return bytes;
+}

package/src/worker/tasks/toCreasedNormals.ts

@@ -1,15 +1,10 @@
 // Ref: https://github.com/takram-design-engineering/geovanni/blob/ee91f675ba2558ee3099f635dfa30bbe3adfe103/libs/3d-tiles/src/toCreasedNormalsAsync.ts
 
-/* eslint-env worker */
-
 import { transfer } from "@navaramap/worker";
 import { toCreasedNormals as toCreasedNormalsImpl } from "three-stdlib";
 
-import {
-  fromBufferGeometryLike,
-  toBufferGeometryLike,
-  type BufferGeometryLike,
-} from "../../utils";
+import { fromBufferGeometryLike, toBufferGeometryLike } from "../../utils";
+import type { BufferGeometryLike } from "../../utils";
 
 export function toCreasedNormals(
   input: BufferGeometryLike,