@vcmap/core 6.1.11 → 6.2.0-rc.1

package/src/panorama/panoramaTileCoordinate.ts

@@ -0,0 +1,166 @@
+import { Math as CesiumMath } from '@vcmap-cesium/engine';
+import type { Extent } from 'ol/extent.js';
+import type { Size } from 'ol/size.js';
+import { cartesian2DDistance } from '../util/math.js';
+
+/**
+ * Tile coordinate in format [x, y, level]
+ */
+export type PanoramaTileCoordinate = {
+  readonly x: number;
+  readonly y: number;
+  readonly level: number;
+  readonly key: string;
+};
+
+/**
+ * Calculates the number of tiles in the given level.
+ * @param level
+ */
+export function getNumberOfTiles(level: number): Size {
+  const maxX = 2 ** level * 2;
+  const maxY = 2 ** level;
+  return [maxX, maxY];
+}
+
+export function createTileCoordinate(
+  x: number,
+  y: number,
+  level: number,
+): PanoramaTileCoordinate {
+  return {
+    x,
+    y,
+    level,
+    key: `${level}/${x}/${y}`,
+  };
+}
+
+/**
+ * Creates a tile coordinate from a the key string of a tile coordinate.
+ * The key is semantic and has the following structure: `level/x/y`
+ * @param key
+ */
+export function createTileCoordinateFromKey(
+  key: string,
+): PanoramaTileCoordinate {
+  const keys = key.split('/').map(Number).filter(Number.isFinite);
+  if (keys.length === 3) {
+    return createTileCoordinate(keys[1], keys[2], keys[0]);
+  }
+  throw new Error(`Provided key "${key}" is not a valid tile coordinate key`);
+}
+
+/**
+ * Calculates the tile size in radians for the given level.
+ * @param level
+ */
+export function tileSizeInRadians(level: number): number {
+  return CesiumMath.PI / 2 ** level;
+}
+
+/**
+ * Calculates the tile coordinates from the given image spherical coordinate & level.
+ * @param spherical
+ * @param level
+ */
+export function tileCoordinateFromImageCoordinate(
+  spherical: [number, number],
+  level: number,
+): PanoramaTileCoordinate {
+  const tileSize = tileSizeInRadians(level);
+  const [numTilesX] = getNumberOfTiles(level);
+  let tileX = numTilesX - 1 - Math.floor(spherical[0] / tileSize);
+  const tileY = Math.floor(spherical[1] / tileSize);
+  if (tileX < 0) {
+    // wrap around 2 * PI
+    tileX = numTilesX + tileX;
+  }
+  return createTileCoordinate(tileX, tileY, level);
+}
+
+/**
+ * Get the tile coordinates of all tiles which intersect the given extent of image coordinates for the given level.
+ * @param extent
+ * @param level
+ */
+export function getTileCoordinatesInImageExtent(
+  extent: Extent,
+  level: number,
+): PanoramaTileCoordinate[] {
+  // the extent is flipped along the X axis, we need to take this into account.
+  const bottomLeft = tileCoordinateFromImageCoordinate(
+    [extent[2], extent[1]],
+    level,
+  );
+  const topRight = tileCoordinateFromImageCoordinate(
+    [extent[0], extent[3]],
+    level,
+  );
+
+  const numberOfLines = topRight.y - bottomLeft.y;
+  const tileCoordinates = new Array<PanoramaTileCoordinate>(
+    (topRight.x - bottomLeft.x) * numberOfLines,
+  );
+  for (let i = bottomLeft.x; i <= topRight.x; i++) {
+    for (let j = bottomLeft.y; j <= topRight.y; j++) {
+      tileCoordinates[
+        (i - bottomLeft.x) * (numberOfLines + 1) + (j - bottomLeft.y)
+      ] = createTileCoordinate(i, j, level);
+    }
+  }
+
+  return tileCoordinates;
+}
+
+/**
+ * Gets the center point of a tile in image spherical coordinates.
+ * @param tileCoordinate
+ */
+export function getTileSphericalCenter(
+  tileCoordinate: PanoramaTileCoordinate,
+): [number, number] {
+  const sizeR = tileSizeInRadians(tileCoordinate.level);
+  const [numTilesX] = getNumberOfTiles(tileCoordinate.level);
+
+  const phi = (numTilesX - 1 - (tileCoordinate.x - 0.5)) * sizeR;
+  const theta = (tileCoordinate.y + 0.5) * sizeR;
+
+  return [phi, theta];
+}
+
+/**
+ * Gets the extent of a tile in image spherical coordinates.
+ * @param tileCoordinate
+ */
+export function getTileSphericalExtent(
+  tileCoordinate: PanoramaTileCoordinate,
+): [number, number, number, number] {
+  const sizeR = tileSizeInRadians(tileCoordinate.level);
+  const [numTilesX] = getNumberOfTiles(tileCoordinate.level);
+
+  const minPhi = (numTilesX - 1 - tileCoordinate.x) * sizeR;
+  const maxPhi = (numTilesX - 1 - (tileCoordinate.x - 1)) * sizeR;
+  const minTheta = tileCoordinate.y * sizeR;
+  const maxTheta = (tileCoordinate.y + 1) * sizeR;
+
+  return [minPhi, minTheta, maxPhi, maxTheta];
+}
+
+/**
+ * @param tileCoordinate - the tile coordinate to calculate the distance to
+ * @param position - the image spherical position to calculate the distance from
+ * @returns the distance in radians. this is only used for relative comparisons.
+ */
+export function getDistanceToTileCoordinate(
+  position: [number, number],
+  tileCoordinate: PanoramaTileCoordinate,
+): number {
+  const center = getTileSphericalCenter(tileCoordinate);
+  const distance = cartesian2DDistance(position, center);
+
+  if (distance > Math.PI) {
+    return Math.abs(CesiumMath.TWO_PI - distance);
+  }
+  return distance;
+}

package/src/panorama/panoramaTileMaterial.ts

@@ -0,0 +1,323 @@
+import type {
+  Context,
+  TextureMagnificationFilter,
+  TextureMinificationFilter,
+} from '@vcmap-cesium/engine';
+import {
+  Cartesian2,
+  Cartesian3,
+  Color,
+  Material,
+  PixelDatatype,
+  PixelFormat,
+  Sampler,
+  Texture,
+} from '@vcmap-cesium/engine';
+import type { Size } from 'ol/size.js';
+import {
+  getNumberOfTiles,
+  type PanoramaTileCoordinate,
+} from './panoramaTileCoordinate.js';
+import source from './panoramaTileMaterialFS.shader.js';
+import type {
+  PanoramaResourceData,
+  PanoramaResourceType,
+} from './panoramaTileProvider.js';
+
+export const defaultCursorColor = 'rgba(255, 206, 0, 0.33)';
+
+/**
+ * The overlay mode for panorama tiles.
+ */
+export enum PanoramaOverlayMode {
+  None = 0,
+  Intensity = 1,
+  Depth = 2,
+}
+
+export type PanoramaTileMaterialUniforms = {
+  u_rgb: ImageBitmap | string;
+  u_intensity: ImageBitmap | string;
+  u_depth: Texture | string;
+  u_debug: HTMLCanvasElement | string;
+  u_cursorPosition: Cartesian3;
+  u_minUV: Cartesian2;
+  u_maxUV: Cartesian2;
+  u_opacity: number;
+  u_overlay: PanoramaOverlayMode;
+  u_overlayOpacity: number;
+  u_overlayNaNColor: Color;
+  u_showDebug: boolean;
+  u_depthReady: boolean;
+  u_imageReady: boolean;
+  u_intensityReady: boolean;
+  u_cursorColor: Color;
+};
+
+function createDebugCanvas(tileSize: Size, text: string): HTMLCanvasElement {
+  const canvas = document.createElement('canvas');
+  canvas.width = tileSize[0];
+  canvas.height = tileSize[1];
+
+  const ctx = canvas.getContext('2d')!;
+  ctx.strokeStyle = 'hotpink';
+  ctx.lineWidth = 5;
+  ctx.strokeRect(0, 0, tileSize[0], tileSize[1]);
+
+  ctx.translate(tileSize[0], 0);
+  ctx.scale(-1, 1); // Flip the context horizontally
+
+  ctx.fillStyle = 'hotpink';
+  ctx.font = '60px Arial';
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+  ctx.fillText(text, tileSize[0] / 2, tileSize[1] / 2);
+
+  return canvas;
+}
+
+function getUniformForType(
+  type: PanoramaResourceType,
+): 'u_rgb' | 'u_intensity' | 'u_depth' {
+  return `u_${type}`;
+}
+
+export function getDefaultPanoramaTileMaterialUniforms(): PanoramaTileMaterialUniforms {
+  return {
+    u_rgb: Material.DefaultImageId,
+    u_intensity: Material.DefaultImageId,
+    u_depth: Material.DefaultImageId,
+    u_debug: Material.DefaultImageId,
+    u_minUV: new Cartesian2(),
+    u_maxUV: new Cartesian2(),
+    u_opacity: 1,
+    u_overlay: PanoramaOverlayMode.Intensity,
+    u_overlayOpacity: 1,
+    u_showDebug: false,
+    u_cursorPosition: new Cartesian3(-1, -1, -1),
+    u_imageReady: false,
+    u_intensityReady: false,
+    u_depthReady: false,
+    u_overlayNaNColor: Color.RED,
+    u_cursorColor: Color.fromCssColorString(defaultCursorColor),
+  };
+}
+
+export default class PanoramaTileMaterial extends Material {
+  declare private _loadedImages: { id: string }[];
+
+  /**
+   * The uniforms used by the panorama tile material. These are not intended to be modified directly
+   * but rather through the provided properties.
+   */
+  declare uniforms: PanoramaTileMaterialUniforms;
+
+  declare private _minificationFilter: TextureMinificationFilter;
+
+  declare private _magnificationFilter: TextureMagnificationFilter;
+
+  private _depthData: Float32Array | undefined;
+
+  constructor(
+    public readonly tileCoordinate: PanoramaTileCoordinate,
+    private _tileSize: Size,
+  ) {
+    const [numx, numy] = getNumberOfTiles(tileCoordinate.level);
+    const sizeX = 1 / numx;
+    const sizeY = 1 / numy;
+
+    const { x, y } = tileCoordinate;
+    const minUV = new Cartesian2(x * sizeX, 1 - (y * sizeY + sizeY));
+    const maxUV = new Cartesian2(x * sizeX + sizeX, 1 - y * sizeY);
+
+    super({
+      fabric: {
+        type: 'TileImage',
+        uniforms: {
+          ...getDefaultPanoramaTileMaterialUniforms(),
+          u_minUV: minUV,
+          u_maxUV: maxUV,
+        },
+        source,
+      },
+      translucent: false,
+    });
+  }
+
+  /**
+   * Shows the debug overlay on the panorama tile.
+   */
+  get showDebug(): boolean {
+    return this.uniforms.u_showDebug;
+  }
+
+  set showDebug(value: boolean) {
+    this.uniforms.u_showDebug = value;
+    if (value && this.uniforms.u_debug === Material.DefaultImageId) {
+      this.uniforms.u_debug = createDebugCanvas(
+        this._tileSize,
+        this.tileCoordinate.key,
+      );
+    }
+  }
+
+  /**
+   * Display the overlay on the panorama tile.
+   */
+  get overlay(): PanoramaOverlayMode {
+    return this.uniforms.u_overlay;
+  }
+
+  set overlay(value: PanoramaOverlayMode) {
+    this.uniforms.u_overlay = value;
+  }
+
+  /**
+   * The opacity of the overlay on the panorama tile.
+   */
+  get overlayOpacity(): number {
+    return this.uniforms.u_overlayOpacity;
+  }
+
+  set overlayOpacity(value: number) {
+    this.uniforms.u_overlayOpacity = value;
+  }
+
+  /**
+   * The color used where overlay values are 0.
+   */
+  get overlayNaNColor(): Color {
+    return this.uniforms.u_overlayNaNColor;
+  }
+
+  set overlayNaNColor(value: Color) {
+    this.uniforms.u_overlayNaNColor = value;
+  }
+
+  /**
+   * The global opacity of the panorama tile.
+   */
+  get opacity(): number {
+    return this.uniforms.u_opacity;
+  }
+
+  set opacity(value: number) {
+    this.uniforms.u_opacity = value;
+  }
+
+  /**
+   * The position of the cursor in the panorama tile. Internal API to render the depth cursor.
+   * (-1, -1, -1) means no data is available.
+   * It should be a valid position in the panorama tiles cartesian coordinate system, scaled by the normalized depth.
+   */
+  get cursorPosition(): Cartesian3 {
+    return this.uniforms.u_cursorPosition;
+  }
+
+  set cursorPosition(value: Cartesian3) {
+    this.uniforms.u_cursorPosition = value;
+  }
+
+  /**
+   * The color of the cursor in the panorama tile.
+   */
+  get cursorColor(): Color {
+    return this.uniforms.u_cursorColor;
+  }
+
+  set cursorColor(value: Color) {
+    this.uniforms.u_cursorColor = value;
+  }
+
+  /**
+   * Sets the texture for the given panorama resource type.
+   * @param type
+   * @param data
+   */
+  setTexture<T extends PanoramaResourceType>(
+    type: T,
+    data: PanoramaResourceData<T>,
+  ): void {
+    if (this.hasTexture(type)) {
+      throw new Error(`Texture for ${type} can only be set once!`);
+    }
+
+    const uniformType = getUniformForType(type);
+    if (uniformType === 'u_depth') {
+      this._depthData = data as Float32Array;
+    } else {
+      this.uniforms[uniformType] = data as ImageBitmap;
+    }
+  }
+
+  hasTexture(type: PanoramaResourceType): boolean {
+    const uniform = getUniformForType(type);
+    if (uniform === 'u_depth') {
+      return this._depthData !== undefined;
+    }
+    return this.uniforms[uniform] !== Material.DefaultImageId;
+  }
+
+  /**
+   * Returns the normalized depth value [0, 1] at the given pixel coordinates in the panorama tile.
+   * @param x
+   * @param y
+   */
+  getDepthAtPixel(x: number, y: number): number | undefined {
+    if (!this._depthData) {
+      return undefined;
+    }
+
+    const index = y * this._tileSize[0] + x;
+    return this._depthData[index];
+  }
+
+  /**
+   * Internal cesium API to update the material.
+   * @param context
+   */
+  update(context: Context): void {
+    const resolveImage =
+      !this.uniforms.u_imageReady &&
+      this._loadedImages?.some((i) => i.id === 'u_rgb');
+    const resolveIntensity =
+      !this.uniforms.u_intensityReady &&
+      this._loadedImages?.find((i) => i.id === 'u_intensity');
+
+    if (this.uniforms.u_depth === Material.DefaultImageId && this._depthData) {
+      const sampler = new Sampler({
+        minificationFilter: this._minificationFilter,
+        magnificationFilter: this._magnificationFilter,
+      });
+
+      this.uniforms.u_depth = new Texture({
+        context,
+        pixelDatatype: PixelDatatype.FLOAT,
+        pixelFormat: PixelFormat.RED,
+        source: {
+          arrayBufferView: this._depthData,
+          width: this._tileSize[0],
+          height: this._tileSize[1],
+        },
+        sampler,
+      });
+    } else if (
+      !this.uniforms.u_depthReady &&
+      this.uniforms.u_depth !== Material.DefaultImageId
+    ) {
+      this.uniforms.u_depthReady = true;
+    }
+
+    // @ts-expect-error is actually private
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    super.update(context);
+
+    if (resolveImage) {
+      this.uniforms.u_imageReady = true;
+    }
+
+    if (resolveIntensity) {
+      this.uniforms.u_intensityReady = true;
+    }
+  }
+}

package/src/panorama/panoramaTileMaterialFS.glsl

@@ -0,0 +1,165 @@
+/**
+ * Fragment shader for panorama tile rendering
+ *
+ * This shader handles rendering of panorama tiles with support for:
+ * - RGB image display
+ * - Intensity data visualization
+ * - Depth information processing
+ * - Debug mode overlays
+ * - Interactive cursor highlighting
+ *
+ * @uniform {sampler2D} u_rgb - RGB panorama texture
+ * @uniform {sampler2D} u_intensity - Intensity data texture
+ * @uniform {sampler2D} u_depth - Depth data texture (16-bit encoded in RG channels)
+ * @uniform {sampler2D} u_debug - Debug visualization texture
+ * @uniform {vec3} u_cursorPosition - 3D cursor position for interaction
+ * @uniform {vec2} u_minUV, u_maxSt - Texture coordinate bounds
+ * @unifrom {vec3} u_maxUV - Texture coordinate bounds
+ * @uniform {float} u_opacity - Overall opacity of the material
+ * @uniform {float} u_overlayIntensity - Overlay intensity (for both modes)
+ * @uniform {int} u_overlay - Overlay mode (0 = intensity, 1 = depth)
+ * @uniform {bool} u_imageReady - Flag indicating if image data is ready
+ * @uniform {bool} u_intensityReady - Flag indicating if intensity data is ready
+ * @uniform {bool} u_depthReady - Flag indicating if depth data is ready
+ * @uniform {vec4} u_overlayNaNColor - Color used for missing/NaN overlay values
+ */
+
+#define OVERLAY_INTENSITY 1.0
+#define OVERLAY_DEPTH 2.0
+
+/**
+ * hardcoded constants for cursor rendering. calculated as follows:
+ * radius = 0.01
+ * number_of_rings = 3
+ * width = (radius * 2) / ((number_of_rings * 2) + 1)
+ * jerks = [width / 2];
+ * num_jerks = number_of_rings * 2 - 1;
+ * for (let i = 1; i < num_jerks; i++) {
+ *   jerks.push(jerks[i - 1] + width);
+ * }
+ */
+#define CURSOR_CENTER_RADIUS 0.00111111111111111
+#define CURSOR_WIDTH_1_IN 0.00333333333333333
+#define CURSOR_WIDTH_1_OUT  0.0055555555555555
+#define CURSOR_WIDTH_2_IN  0.00777777777777777
+#define CURSOR_WIDTH_2_OUT  0.01
+
+/**
+ * Converts spherical texture coordinates (x, y) to Cartesian coordinates. see spherical coordinates for more details on the coordinate system.
+ * @param {float} st_x - spherical texture coordinates .
+ * @param {float} st_y - spherical texture coordinates y.
+ * @returns {vec3} - Cartesian coordinates
+ */
+vec3 getCartesian(float st_x, float st_y)
+{
+    float phi = st_x * 2.0 * 3.14159265359;
+    // texture coordinates are flipped in y axis
+    float theta = 3.14159265359 - st_y * 3.14159265359;
+    return vec3(
+        sin(theta) * cos(phi),
+        sin(theta) * sin(phi),
+        cos(theta)
+    );
+}
+
+/**
+ * Fetches the texel value from the intensity or depth texture.
+ * @param {sampler2D} source - The texture to sample from (intensity or depth).
+ * @param {vec2} scaled_st - Scaled texture coordinates.
+ * @returns {float} - The sampled value.
+ */
+float get_texel_value(sampler2D source, vec2 scaled_uv)
+{
+    ivec2 texSize = textureSize(source, 0);
+    ivec2 pixelCoord = ivec2(scaled_uv * vec2(texSize));
+
+    vec4 texel_value = texelFetch(source, pixelCoord, 0);
+
+    float sample_value = 0.0;
+    sample_value = texel_value.r;
+
+    return sample_value;
+}
+
+czm_material czm_getMaterial(czm_materialInput materialInput)
+{
+    czm_material m = czm_getDefaultMaterial(materialInput);
+    if (!u_imageReady) {
+        m.alpha = 0.0;
+        return m;
+    }
+
+    vec2 clamped_uv = clamp(materialInput.st, u_minUV, u_maxUV);
+    vec2 scaled_uv = (clamped_uv - u_minUV) / (u_maxUV - u_minUV);
+
+    vec4 t_color = texture(u_rgb, scaled_uv);
+    if (u_intensityReady && u_overlay == OVERLAY_INTENSITY)
+    {
+        float inensity_value = get_texel_value(u_intensity, scaled_uv);
+        vec4 intensity_color;
+        if (inensity_value > 0.0)
+        {
+            intensity_color = vec4(inensity_value, inensity_value, inensity_value, 1.0);
+        }
+        else
+        {
+            intensity_color = u_overlayNaNColor;
+        }
+        t_color = mix(t_color, intensity_color, u_overlayOpacity);
+    }
+
+    bool has_position = u_cursorPosition != vec3(-1.0, -1.0, -1.0) && u_cursorColor.a > 0.0;
+    bool show_depth = u_overlay == OVERLAY_DEPTH;
+    if (u_depthReady && (show_depth || has_position))
+    {
+        float avg_depth = get_texel_value(u_depth, scaled_uv);
+        if (show_depth)
+        {
+            vec4 depth_color;
+            if (avg_depth > 0.0)
+            {
+                depth_color = vec4(avg_depth, avg_depth, avg_depth, 1.0);
+            }
+            else
+            {
+                depth_color = u_overlayNaNColor;
+            }
+            t_color = mix(t_color, depth_color, u_overlayOpacity);
+        }
+
+        if (has_position && avg_depth > 0.0)
+        {
+            vec3 fragment_position = getCartesian(materialInput.st.x, materialInput.st.y);
+            fragment_position *= avg_depth;
+            float dist_to_cursor = distance(fragment_position, u_cursorPosition);
+
+            if (dist_to_cursor < CURSOR_CENTER_RADIUS)
+            {
+                t_color = mix(t_color, u_cursorColor, u_cursorColor.a);
+            }
+            else if (dist_to_cursor > CURSOR_WIDTH_1_IN && dist_to_cursor < CURSOR_WIDTH_1_OUT)
+            {
+                t_color = mix(t_color, u_cursorColor, u_cursorColor.a);
+            }
+            else if (dist_to_cursor > CURSOR_WIDTH_2_IN && dist_to_cursor < CURSOR_WIDTH_2_OUT)
+            {
+                t_color = mix(t_color, u_cursorColor, u_cursorColor.a);
+            }
+        }
+    }
+
+    if (u_showDebug)
+    {
+        vec4 debug = texture(u_debug, scaled_uv);
+        if (debug.a > 0.0)
+        {
+            t_color = vec4(debug.r, debug.g, debug.b, 1.0);
+        }
+    }
+
+    m.diffuse = t_color.rgb;
+    m.specular = 0.5;
+    m.emission = t_color.rgb * vec3(0.5);
+    m.alpha = u_opacity;
+    return m;
+}