@loaders.gl/core 5.0.0-alpha.12 → 5.0.0-alpha.13

package/src/schema/categories/category-texture.ts

@@ -0,0 +1,259 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ImageType} from './category-image';
+import type {TypedArray} from '../types/types';
+
+/**
+ * These represent the main compressed texture formats
+ * Each format typically has a number of more specific subformats
+ */
+export type GPUTextureFormat =
+  | 'dxt'
+  | 'dxt-srgb'
+  | 'etc1'
+  | 'etc2'
+  | 'pvrtc'
+  | 'atc'
+  | 'astc'
+  | 'rgtc';
+
+export type TextureFormat = TextureFormatColorUncompressed | TextureFormatCompressed;
+
+export type TextureFormatColorUncompressed =
+  | 'r8unorm'
+  | 'rg8unorm'
+  | 'rgb8unorm-webgl'
+  | 'rgba8unorm'
+  | 'rgba8unorm-srgb'
+  | 'r8snorm'
+  | 'rg8snorm'
+  | 'rgb8snorm-webgl'
+  | 'rgba8snorm'
+  | 'r8uint'
+  | 'rg8uint'
+  | 'rgba8uint'
+  | 'r8sint'
+  | 'rg8sint'
+  | 'rgba8sint'
+  | 'bgra8unorm'
+  | 'bgra8unorm-srgb'
+  | 'r16unorm'
+  | 'rg16unorm'
+  | 'rgb16unorm-webgl'
+  | 'rgba16unorm'
+  | 'r16snorm'
+  | 'rg16snorm'
+  | 'rgb16snorm-webgl'
+  | 'rgba16snorm'
+  | 'r16uint'
+  | 'rg16uint'
+  | 'rgba16uint'
+  | 'r16sint'
+  | 'rg16sint'
+  | 'rgba16sint'
+  | 'r16float'
+  | 'rg16float'
+  | 'rgba16float'
+  | 'r32uint'
+  | 'rg32uint'
+  | 'rgba32uint'
+  | 'r32sint'
+  | 'rg32sint'
+  | 'rgba32sint'
+  | 'r32float'
+  | 'rg32float'
+  | 'rgb32float-webgl'
+  | 'rgba32float'
+  | 'rgba4unorm-webgl'
+  | 'rgb565unorm-webgl'
+  | 'rgb5a1unorm-webgl'
+  | 'rgb9e5ufloat'
+  | 'rg11b10ufloat'
+  | 'rgb10a2unorm'
+  | 'rgb10a2uint';
+
+export type TextureFormatCompressed =
+  | 'bc1-rgb-unorm-webgl'
+  | 'bc1-rgb-unorm-srgb-webgl'
+  | 'pvrtc-rgb4unorm-webgl'
+  | 'pvrtc-rgba4unorm-webgl'
+  | 'pvrtc-rgb2unorm-webgl'
+  | 'pvrtc-rgba2unorm-webgl'
+  | 'etc1-rgb-unorm-webgl'
+  | 'atc-rgb-unorm-webgl'
+  | 'atc-rgba-unorm-webgl'
+  | 'atc-rgbai-unorm-webgl'
+  | 'bc1-rgba-unorm'
+  | 'bc1-rgba-unorm-srgb'
+  | 'bc2-rgba-unorm'
+  | 'bc2-rgba-unorm-srgb'
+  | 'bc3-rgba-unorm'
+  | 'bc3-rgba-unorm-srgb'
+  | 'bc4-r-unorm'
+  | 'bc4-r-snorm'
+  | 'bc5-rg-unorm'
+  | 'bc5-rg-snorm'
+  | 'bc6h-rgb-ufloat'
+  | 'bc6h-rgb-float'
+  | 'bc7-rgba-unorm'
+  | 'bc7-rgba-unorm-srgb'
+  | 'etc2-rgb8unorm'
+  | 'etc2-rgb8unorm-srgb'
+  | 'etc2-rgb8a1unorm'
+  | 'etc2-rgb8a1unorm-srgb'
+  | 'etc2-rgba8unorm'
+  | 'etc2-rgba8unorm-srgb'
+  | 'eac-r11unorm'
+  | 'eac-r11snorm'
+  | 'eac-rg11unorm'
+  | 'eac-rg11snorm'
+  | 'astc-4x4-unorm'
+  | 'astc-4x4-unorm-srgb'
+  | 'astc-5x4-unorm'
+  | 'astc-5x4-unorm-srgb'
+  | 'astc-5x5-unorm'
+  | 'astc-5x5-unorm-srgb'
+  | 'astc-6x5-unorm'
+  | 'astc-6x5-unorm-srgb'
+  | 'astc-6x6-unorm'
+  | 'astc-6x6-unorm-srgb'
+  | 'astc-8x5-unorm'
+  | 'astc-8x5-unorm-srgb'
+  | 'astc-8x6-unorm'
+  | 'astc-8x6-unorm-srgb'
+  | 'astc-8x8-unorm'
+  | 'astc-8x8-unorm-srgb'
+  | 'astc-10x5-unorm'
+  | 'astc-10x5-unorm-srgb'
+  | 'astc-10x6-unorm'
+  | 'astc-10x6-unorm-srgb'
+  | 'astc-10x8-unorm'
+  | 'astc-10x8-unorm-srgb'
+  | 'astc-10x10-unorm'
+  | 'astc-10x10-unorm-srgb'
+  | 'astc-12x10-unorm'
+  | 'astc-12x10-unorm-srgb'
+  | 'astc-12x12-unorm'
+  | 'astc-12x12-unorm-srgb';
+
+/** Application-facing metadata attached to texture payloads. */
+export type TextureMetadata = Record<string, unknown>;
+
+/** Return type of `texture` category loaders. */
+export type Texture<MetadataT extends TextureMetadata = TextureMetadata> =
+  | Texture1D<MetadataT>
+  | Texture2D<MetadataT>
+  | Texture3D<MetadataT>
+  | TextureCube<MetadataT>
+  | Texture2DArray<MetadataT>
+  | TextureCubeArray<MetadataT>;
+
+/** One-dimensional texture with mip levels. */
+export type Texture1D<MetadataT extends TextureMetadata = TextureMetadata> = {
+  /** loaders.gl shape tag identifying texture payloads. */
+  shape: 'texture';
+  /** Application-facing format metadata, when provided by the loader. */
+  metadata?: MetadataT;
+  /** Texture dimensionality. */
+  type: '1d';
+  /** Canonical loaders.gl texture format for the texture payload. */
+  format: TextureFormat;
+  /** Mip levels that make up the texture. */
+  data: TextureLevel[];
+};
+
+/** Two-dimensional texture with mip levels. */
+export type Texture2D<MetadataT extends TextureMetadata = TextureMetadata> = {
+  /** loaders.gl shape tag identifying texture payloads. */
+  shape: 'texture';
+  /** Application-facing format metadata, when provided by the loader. */
+  metadata?: MetadataT;
+  /** Texture dimensionality. */
+  type: '2d';
+  /** Canonical loaders.gl texture format for the texture payload. */
+  format: TextureFormat;
+  /** Mip levels that make up the texture. */
+  data: TextureLevel[];
+};
+
+/** Three-dimensional texture with mip levels for each depth slice. */
+export type Texture3D<MetadataT extends TextureMetadata = TextureMetadata> = {
+  /** loaders.gl shape tag identifying texture payloads. */
+  shape: 'texture';
+  /** Application-facing format metadata, when provided by the loader. */
+  metadata?: MetadataT;
+  /** Texture dimensionality. */
+  type: '3d';
+  /** Canonical loaders.gl texture format for the texture payload. */
+  format: TextureFormat;
+  /** Mip levels grouped by depth slice. */
+  data: TextureLevel[][];
+};
+
+/** Cube texture with mip levels for each face. */
+export type TextureCube<MetadataT extends TextureMetadata = TextureMetadata> = {
+  /** loaders.gl shape tag identifying texture payloads. */
+  shape: 'texture';
+  /** Application-facing format metadata, when provided by the loader. */
+  metadata?: MetadataT;
+  /** Texture dimensionality. */
+  type: 'cube';
+  /** Canonical loaders.gl texture format for the texture payload. */
+  format: TextureFormat;
+  /** Mip levels grouped by cube face. */
+  data: TextureLevel[][];
+};
+
+/** Array of two-dimensional textures with mip levels for each layer. */
+export type Texture2DArray<MetadataT extends TextureMetadata = TextureMetadata> = {
+  /** loaders.gl shape tag identifying texture payloads. */
+  shape: 'texture';
+  /** Application-facing format metadata, when provided by the loader. */
+  metadata?: MetadataT;
+  /** Texture dimensionality. */
+  type: '2d-array';
+  /** Canonical loaders.gl texture format for the texture payload. */
+  format: TextureFormat;
+  /** Mip levels grouped by array layer. */
+  data: TextureLevel[][];
+};
+
+/** Array of cube textures with mip levels for each face in each layer. */
+export type TextureCubeArray<MetadataT extends TextureMetadata = TextureMetadata> = {
+  /** loaders.gl shape tag identifying texture payloads. */
+  shape: 'texture';
+  /** Application-facing format metadata, when provided by the loader. */
+  metadata?: MetadataT;
+  /** Texture dimensionality. */
+  type: 'cube-array';
+  /** Canonical loaders.gl texture format for the texture payload. */
+  format: TextureFormat;
+  /** Mip levels grouped by cube-array layer and face. */
+  data: TextureLevel[][][];
+};
+
+/** A TextureLevel holds data for one texture mip level */
+export type TextureLevel = {
+  /** loaders.gl shape tag identifying texture level payloads */
+  shape: 'texture-level';
+  /** WebGPU texture format corresponding the format of the data in this TextureLevel */
+  textureFormat?: TextureFormat;
+  /** Numeric API-specific format constant, currently used for WebGL/OpenGL upload paths */
+  format?: number;
+  /** Whether the texture is compressed */
+  compressed: boolean;
+  /** Width in texels */
+  width: number;
+  /** Height in texels */
+  height: number;
+  /** Optional bitmap handle for image-backed texture levels */
+  imageBitmap?: ImageBitmap;
+  /** Byte array or float pixel data. Will be a dummy length 0 array if imageBitmap is provided */
+  data: TypedArray;
+  levelSize?: number;
+  hasAlpha?: boolean;
+};
+
+export type TextureOrImage = ImageType | (TextureLevel | ImageType);

package/src/schema/deprecated/mesh-utils.ts

@@ -0,0 +1,46 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {MeshAttributes} from '../categories/category-mesh';
+
+type BoundingBox = [[number, number, number], [number, number, number]];
+
+/**
+ * Get the (axis aligned) bounding box of a mesh.
+ * @param attributes Mesh attributes.
+ * @returns The axis aligned bounding box as minimum and maximum vectors.
+ * @deprecated Import `getMeshBoundingBox` from `@loaders.gl/core/schema-utils` instead. This root
+ * export remains temporarily for deck.gl 9.4 compatibility.
+ */
+// eslint-disable-next-line complexity
+export function getMeshBoundingBox(attributes: MeshAttributes): BoundingBox {
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+
+  const positions = attributes.POSITION ? attributes.POSITION.value : [];
+  const length = positions && positions.length;
+
+  for (let index = 0; index < length; index += 3) {
+    const x = positions[index];
+    const y = positions[index + 1];
+    const z = positions[index + 2];
+
+    minX = x < minX ? x : minX;
+    minY = y < minY ? y : minY;
+    minZ = z < minZ ? z : minZ;
+
+    maxX = x > maxX ? x : maxX;
+    maxY = y > maxY ? y : maxY;
+    maxZ = z > maxZ ? z : maxZ;
+  }
+
+  return [
+    [minX, minY, minZ],
+    [maxX, maxY, maxZ]
+  ];
+}

package/src/schema/float16.ts

@@ -0,0 +1,111 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getFloat16ArrayConstructor, NativeFloat16ArrayConstructor} from '@math.gl/core/types';
+
+/** Array storage used for logical Float16 values. */
+export type Float16ArrayStorage = Float16Array | Uint16Array;
+
+/** Create native Float16 storage when the runtime supports it. */
+export function createFloat16Array(length: number): Float16ArrayStorage {
+  const ArrayConstructor = getFloat16ArrayConstructor();
+  return new ArrayConstructor(length) as Float16ArrayStorage;
+}
+
+/** Check whether an array is backed by the native Float16Array implementation. */
+export function isNativeFloat16Array(value: unknown): value is Float16Array {
+  return Boolean(NativeFloat16ArrayConstructor && value instanceof NativeFloat16ArrayConstructor);
+}
+
+/** Write a numeric value into native or binary16 fallback storage. */
+export function setFloat16Value(array: Float16ArrayStorage, index: number, value: number): void {
+  if (isNativeFloat16Array(array)) {
+    array[index] = value;
+  } else {
+    array[index] = encodeFloat16(value);
+  }
+}
+
+/** Read a numeric value from native or binary16 fallback storage. */
+export function getFloat16Value(array: Float16ArrayStorage, index: number): number {
+  if (isNativeFloat16Array(array)) {
+    return array[index];
+  }
+  return decodeFloat16(array[index]);
+}
+
+/** Return the binary16 words used by Apache Arrow and GPU APIs. */
+export function getFloat16Storage(array: Float16ArrayStorage): Uint16Array {
+  return isNativeFloat16Array(array)
+    ? new Uint16Array(array.buffer, array.byteOffset, array.length)
+    : array;
+}
+
+/** Convert byte- or word-scaled color components to logical Float16 values. */
+export function convertColorArrayToFloat16(
+  values: ArrayLike<number>,
+  sourceScale: number
+): Float16ArrayStorage {
+  const result = createFloat16Array(values.length);
+  for (let index = 0; index < values.length; index++) {
+    setFloat16Value(result, index, values[index] / sourceScale);
+  }
+  return result;
+}
+
+/** Convert byte- or word-scaled color components to logical Float32 values. */
+export function convertColorArrayToFloat32(
+  values: ArrayLike<number>,
+  sourceScale: number
+): Float32Array {
+  return Float32Array.from(values, value => value / sourceScale);
+}
+
+/** Encode a JavaScript number as an IEEE-754 binary16 bit pattern. */
+export function encodeFloat16(value: number): number {
+  if (!Number.isFinite(value)) {
+    return value === Infinity ? 0x7c00 : value === -Infinity ? 0xfc00 : 0x7e00;
+  }
+
+  const sign = value < 0 || Object.is(value, -0) ? 0x8000 : 0;
+  const absoluteValue = Math.abs(value);
+  if (absoluteValue === 0) {
+    return sign;
+  }
+
+  // Values at or above the midpoint between the largest finite half and
+  // infinity round to infinity using IEEE-754 round-to-nearest-even.
+  if (absoluteValue >= 65520) {
+    return sign | 0x7c00;
+  }
+  if (absoluteValue >= 65504) {
+    return sign | 0x7bff;
+  }
+
+  const exponent = Math.floor(Math.log2(absoluteValue));
+  if (exponent < -14) {
+    return sign | Math.round(absoluteValue / 2 ** -24);
+  }
+
+  const normalizedExponent = exponent + 15;
+  const mantissa = Math.round((absoluteValue / 2 ** exponent - 1) * 1024);
+  if (mantissa === 1024) {
+    return sign | ((normalizedExponent + 1) << 10);
+  }
+  return sign | (normalizedExponent << 10) | mantissa;
+}
+
+/** Decode an IEEE-754 binary16 bit pattern. */
+function decodeFloat16(value: number): number {
+  const sign = value & 0x8000 ? -1 : 1;
+  const exponent = (value >> 10) & 0x1f;
+  const mantissa = value & 0x3ff;
+  if (exponent === 0) {
+    return sign * mantissa * 2 ** -24;
+  }
+  if (exponent === 0x1f) {
+    return mantissa ? NaN : sign * Infinity;
+  }
+  return sign * (1 + mantissa / 1024) * 2 ** (exponent - 15);
+}

package/src/schema/geometry/arrow-binary-features.ts

@@ -0,0 +1,54 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type * as arrow from 'apache-arrow';
+import type {BinaryFeatureCollection, BinaryProperties} from './binary-features';
+import type {BinaryGeometryType} from './binary-geometries';
+
+/** One Arrow-backed binary feature family table. */
+export type ArrowBinaryFeatureTable = {
+  /** Geometry family stored in this table. */
+  type: BinaryGeometryType;
+  /** Arrow table wrapper for the family. */
+  table: arrow.Table;
+  /** Original feature-level properties sidecar from the binary feature collection. */
+  properties: BinaryProperties['properties'];
+  /** Optional original feature fields sidecar. */
+  fields?: BinaryProperties['fields'];
+};
+
+/** Arrow-backed wrapper for binary point features. */
+export type ArrowBinaryPointFeature = ArrowBinaryFeatureTable & {
+  type: 'Point';
+};
+
+/** Arrow-backed wrapper for binary line features. */
+export type ArrowBinaryLineFeature = ArrowBinaryFeatureTable & {
+  type: 'LineString';
+};
+
+/** Arrow-backed wrapper for binary polygon features. */
+export type ArrowBinaryPolygonFeature = ArrowBinaryFeatureTable & {
+  type: 'Polygon';
+};
+
+/**
+ * Arrow-backed wrapper for a binary feature collection.
+ *
+ * This mirrors the existing `BinaryFeatureCollection` family split while exposing the
+ * renderable arrays through Arrow nested list columns.
+ */
+export type ArrowBinaryFeatureCollection = {
+  /** Discriminator for Arrow-backed binary feature collections. */
+  shape: 'arrow-binary-feature-collection';
+  /** Optional Arrow-backed point family table. */
+  points?: ArrowBinaryPointFeature;
+  /** Optional Arrow-backed line family table. */
+  lines?: ArrowBinaryLineFeature;
+  /** Optional Arrow-backed polygon family table. */
+  polygons?: ArrowBinaryPolygonFeature;
+};
+
+/** Supported binary feature collection wrapper shapes. */
+export type BinaryFeatureCollectionLike = BinaryFeatureCollection | ArrowBinaryFeatureCollection;

package/src/schema/geometry/binary-features.ts

@@ -0,0 +1,43 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// GIS
+import type {TypedArray} from '../types/types';
+import type {
+  BinaryPointGeometry,
+  BinaryLineGeometry,
+  BinaryPolygonGeometry
+} from './binary-geometries';
+
+export type BinaryAttribute = {
+  value: TypedArray;
+  size: number;
+};
+
+/**
+ * Represent a collection of Features, similar to a GeoJSON FeatureCollection
+ * But in columnar format, with binary columns when possible
+ */
+export type BinaryFeatureCollection = {
+  shape: 'binary-feature-collection';
+  points?: BinaryPointFeature;
+  lines?: BinaryLineFeature;
+  polygons?: BinaryPolygonFeature;
+};
+
+/** Binary feature + binary attributes */
+export type BinaryFeature = BinaryPointFeature | BinaryLineFeature | BinaryPolygonFeature;
+
+export type BinaryPointFeature = BinaryPointGeometry & BinaryProperties;
+export type BinaryLineFeature = BinaryLineGeometry & BinaryProperties;
+export type BinaryPolygonFeature = BinaryPolygonGeometry & BinaryProperties;
+
+/** Common properties for binary geometries */
+export type BinaryProperties = {
+  featureIds: BinaryAttribute;
+  globalFeatureIds: BinaryAttribute;
+  numericProps: Record<string, BinaryAttribute>;
+  properties: Record<string, any>[];
+  fields?: Record<string, any>[];
+};

package/src/schema/geometry/binary-geometries.ts

@@ -0,0 +1,45 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// GIS
+import type {TypedArray} from '../types/types';
+
+// BINARY FORMAT GEOMETRY
+
+export type BinaryGeometryType = 'Point' | 'LineString' | 'Polygon';
+
+/**
+ * Similar to an apache arrow FixedSizeList,
+ * contains the contiguous array and the number of values in each element  */
+export type BinaryFixedSizeList = {
+  value: TypedArray;
+  size: number;
+};
+
+/**
+ * Represent a single Geometry, similar to a GeoJSON Geometry
+ */
+export type BinaryGeometry = BinaryPointGeometry | BinaryLineGeometry | BinaryPolygonGeometry;
+
+/** Binary point geometry: an array of positions */
+export type BinaryPointGeometry = {
+  type: 'Point';
+  positions: BinaryFixedSizeList;
+};
+
+/** Binary line geometry, array of positions and indices to the start of each line */
+export type BinaryLineGeometry = {
+  type: 'LineString';
+  positions: BinaryFixedSizeList;
+  pathIndices: BinaryFixedSizeList;
+};
+
+/** Binary polygon geometry, an array of positions to each primitite polygon and polygon */
+export type BinaryPolygonGeometry = {
+  type: 'Polygon';
+  positions: BinaryFixedSizeList;
+  polygonIndices: BinaryFixedSizeList;
+  primitivePolygonIndices: BinaryFixedSizeList;
+  triangles?: BinaryFixedSizeList;
+};

package/src/schema/geometry/flat-geometries.ts

@@ -0,0 +1,72 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// FLAT GEOJSON FORMAT GEOMETRY
+import type {Feature, Geometry} from 'geojson';
+
+/**
+ * Generic flat geometry data storage type
+ * (an intermediate "Flat GeoJSON"
+ * data format, which maps closely to the binary data buffers.
+ * It is similar to GeoJSON, but rather than storing the coordinates
+ * in multidimensional arrays, we have a 1D `data` with all the
+ * coordinates, and then index into this using the `indices`
+ * parameter
+ *
+ * Thus the indices member lets us look up the relevant range
+ * from the data array.
+ * The Multi* versions of the above types share the same data
+ * structure, just with multiple elements in the indices array
+ *
+ * @example
+ *
+ * geometry: {
+ *   type: 'Point', data: [1,2], indices: [0]
+ * }
+ * geometry: {
+ *   type: 'LineString', data: [1,2,3,4,...], indices: [0]
+ * }
+ * geometry: {
+ *   type: 'Polygon', data: [1,2,3,4,...], indices: [[0, 2]]
+ * }
+ */
+export type FlatIndexedGeometry = {
+  data: number[];
+  indices: number[];
+};
+
+/** Flat geometry type */
+export type FlatGeometryType = 'Point' | 'LineString' | 'Polygon';
+
+/** GeoJSON geometry with coordinate data flattened into `data` array and indexed by 2D `indices` */
+export type FlatGeometry = FlatPoint | FlatLineString | FlatPolygon;
+
+/** GeoJSON (Multi)Point geometry with coordinate data flattened into `data` array and indexed by `indices` */
+export type FlatPoint = {
+  type: 'Point';
+  data: number[];
+  indices: number[];
+};
+
+/** GeoJSON (Multi)LineString geometry with coordinate data flattened into `data` array and indexed by `indices` */
+export type FlatLineString = {
+  type: 'LineString';
+  data: number[];
+  indices: number[];
+};
+
+/** GeoJSON (Multi)Polygon geometry with coordinate data flattened into `data` array and indexed by 2D `indices` */
+export type FlatPolygon = {
+  type: 'Polygon';
+  data: number[];
+  indices: number[][];
+  areas: number[][];
+};
+
+type FlattenGeometry<Type> = {
+  [Property in keyof Type]: Type[Property] extends Geometry ? FlatGeometry : Type[Property];
+};
+
+/** GeoJSON Feature with Geometry replaced by FlatGeometry */
+export type FlatFeature = FlattenGeometry<Feature>;