@loaders.gl/pointclouds 0.0.0-stage → 5.0.0-beta.1

package/src/las/lib/las-types.ts

@@ -0,0 +1,206 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LASCompatibilityLayout} from './las-compatibility';
+import type {Mesh} from '@loaders.gl/core/schema';
+import type {WKTCRSDefinition} from '@math.gl/geospatial/crs';
+
+/** LAS Variable Length Record metadata and payload. */
+export type LASVariableLengthRecord = {
+  /** Reserved VLR field. */
+  reserved: number;
+  /** LAS VLR user id. */
+  userId: string;
+  /** LAS VLR record id. */
+  recordId: number;
+  /** VLR description string. */
+  description: string;
+  /** Byte offset of the VLR header in the source file. */
+  offset: number;
+  /** Raw VLR payload bytes. */
+  data: Uint8Array;
+};
+
+/** LAS Extended Variable Length Record metadata and payload. */
+export type LASExtendedVariableLengthRecord = {
+  /** Reserved EVLR field. */
+  reserved: number;
+  /** LAS EVLR user id. */
+  userId: string;
+  /** LAS EVLR record id. */
+  recordId: number;
+  /** EVLR description string. */
+  description: string;
+  /** Byte offset of the EVLR header in the source file. */
+  offset: number;
+  /** Raw EVLR payload bytes when available in memory. */
+  data?: Uint8Array;
+  /** Byte offset of the EVLR payload in the source file. */
+  dataOffset: number;
+  /** Byte length of the EVLR payload. */
+  dataLength: number;
+};
+
+/** LAS Extra Bytes descriptor parsed from an Extra Bytes VLR. */
+export type LASExtraBytesDescriptor = {
+  /** Extra Bytes data type code. */
+  dataType: number;
+  /** Extra Bytes options bit mask. */
+  options: number;
+  /** Extra Bytes field name. */
+  name: string;
+  /** Extra Bytes field description. */
+  description: string;
+  /** First descriptor scale value, used when option bit 3 is set. */
+  scale: number;
+  /** First descriptor offset value, used when option bit 4 is set. */
+  offset: number;
+  /** Per-component descriptor scale values for scalar and vector fields. */
+  scales: [number, number, number];
+  /** Per-component descriptor offset values for scalar and vector fields. */
+  offsets: [number, number, number];
+  /** Raw 192-byte descriptor payload. */
+  data: Uint8Array;
+};
+
+/** LAS waveform packet descriptor parsed from a waveform descriptor VLR. */
+export type LASWaveformPacketDescriptor = {
+  /** Waveform descriptor record id. */
+  recordId: number;
+  /** Number of bits per waveform sample. */
+  bitsPerSample: number;
+  /** Waveform compression type. */
+  compressionType: number;
+  /** Number of samples in the waveform packet. */
+  numberOfSamples: number;
+  /** Temporal sample spacing in picoseconds. */
+  temporalSampleSpacing: number;
+  /** Digitizer gain. */
+  digitizerGain: number;
+  /** Digitizer offset. */
+  digitizerOffset: number;
+};
+
+/** One resolved GeoTIFF GeoKey directory entry from LAS CRS metadata. */
+export type LASGeoTIFFKey = {
+  /** GeoTIFF key identifier. */
+  keyId: number;
+  /** TIFF tag containing the value, or zero when the value is inline. */
+  tiffTagLocation: number;
+  /** Number of values referenced by this key. */
+  count: number;
+  /** Inline value or offset into the referenced GeoTIFF parameter tag. */
+  valueOffset: number;
+  /** Resolved scalar, numeric array, or ASCII value when its source tag is available. */
+  value?: number | number[] | string;
+};
+
+/** Parsed GeoTIFF GeoKey directory header and entries. */
+export type LASGeoTIFFKeyDirectory = {
+  /** GeoKey directory format version. */
+  version: number;
+  /** GeoKey revision. */
+  keyRevision: number;
+  /** GeoKey minor revision. */
+  minorRevision: number;
+  /** Resolved GeoKey entries. */
+  entries: LASGeoTIFFKey[];
+};
+
+/** Typed metadata parsed from a LAS file. */
+export type LASMetadata = {
+  /** File source id from the public header. */
+  fileSourceId: number;
+  /** Global encoding bit field from the public header. */
+  globalEncoding: number;
+  /** Start of the internal waveform data packet record, preserved as an exact uint64. */
+  waveformDataOffset?: bigint;
+  /** Project identifier as a UUID string. */
+  projectId: string;
+  /** System identifier string. */
+  systemIdentifier: string;
+  /** Generating software string. */
+  generatingSoftware: string;
+  /** File creation day of year. */
+  creationDayOfYear: number;
+  /** File creation year. */
+  creationYear: number;
+  /** LAS header byte length. */
+  headerSize: number;
+  /** LAS header extension bytes after the standard 393-byte LAS 1.5 header. */
+  userHeaderData?: Uint8Array;
+  /** Number of VLRs before point data. */
+  vlrCount: number;
+  /** Offset of first EVLR, or zero when absent. */
+  evlrOffset?: number;
+  /** Number of EVLRs after point data. */
+  evlrCount?: number;
+  /** Extended point count by return. */
+  pointsByReturn?: number[];
+  /** LAS 1.5 maximum GPS time. */
+  maxGpsTime?: number;
+  /** LAS 1.5 minimum GPS time. */
+  minGpsTime?: number;
+  /** LAS 1.5 GPS time offset. */
+  timeOffset?: number;
+  /** Parsed VLR records. */
+  vlrs: LASVariableLengthRecord[];
+  /** Parsed EVLR records when available. */
+  evlrs: LASExtendedVariableLengthRecord[];
+  /** WKT coordinate reference system text when present. */
+  wkt?: WKTCRSDefinition;
+  /** WKT math transform text when present. */
+  wktMathTransform?: string;
+  /** GeoTIFF VLRs retained for legacy LAS versions. */
+  geotiff?: {
+    /** GeoKeyDirectoryTag payload. */
+    keys?: Uint16Array;
+    /** GeoDoubleParamsTag payload. */
+    doubles?: Float64Array;
+    /** GeoAsciiParamsTag payload. */
+    ascii?: string;
+    /** Parsed and resolved GeoKey directory entries. */
+    keyDirectory?: LASGeoTIFFKeyDirectory;
+  };
+  /** Validated LASzip compatibility-mode layout and logical format. */
+  compatibility?: LASCompatibilityLayout;
+  /** Extra Bytes descriptors parsed from the Extra Bytes VLR. */
+  extraBytes: LASExtraBytesDescriptor[];
+  /** Waveform packet descriptors parsed from waveform descriptor VLRs. */
+  waveformPacketDescriptors: LASWaveformPacketDescriptor[];
+};
+
+/**
+ * Type for header of the .las file
+ */
+export type LASHeader = {
+  pointsOffset: number;
+  pointsFormatId: number;
+  pointsStructSize: number;
+  pointsCount: number;
+  scale: [number, number, number];
+  offset: [number, number, number];
+  maxs?: number[];
+  mins?: number[];
+  totalToRead: number;
+  totalRead: number;
+  hasColor: boolean;
+  versionAsString?: string;
+  isCompressed?: boolean;
+  headerSize?: number;
+  /** LAS header extension bytes after the standard 393-byte LAS 1.5 header. */
+  userHeaderData?: Uint8Array;
+  vlrCount?: number;
+  metadata?: LASMetadata;
+};
+
+/**
+ * loaders.gl Mesh with Draco specific data
+ */
+export type LASMesh = Mesh & {
+  loader: 'las';
+  loaderData: LASHeader; // Draco specific data
+  topology: 'point-list';
+  mode: 0;
+};

package/src/las/lib/las-waveform.ts

@@ -0,0 +1,292 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ReadableFile} from '@loaders.gl/core/loader-utils';
+import type {LASMetadata, LASWaveformPacketDescriptor} from './las-types';
+
+const WAVEFORM_PACKET_REFERENCE_BYTE_LENGTH = 29;
+const INTERNAL_WAVEFORM_DATA_MASK = 1 << 1;
+const EXTERNAL_WAVEFORM_DATA_MASK = 1 << 2;
+
+/** Location of waveform packet data selected by the LAS global-encoding field. */
+export type LASWaveformStorage = 'internal' | 'external';
+
+/** Lossless fields stored in one PDRF 4, 5, 9, or 10 waveform packet reference. */
+export type LASWaveformPacketReference = {
+  /** Waveform descriptor index; descriptor VLR record id is this value plus 99. */
+  descriptorIndex: number;
+  /** Packet byte offset relative to the waveform data packet record. */
+  byteOffset: bigint;
+  /** Packet byte length. */
+  byteLength: number;
+  /** Temporal offset in picoseconds from the waveform anchor to this return. */
+  returnPointLocation: number;
+  /** Parametric XYZ offsets per picosecond. */
+  parametricOffset: [number, number, number];
+};
+
+/** Decoded waveform packet and the metadata required to interpret its samples. */
+export type LASWaveformPacket = {
+  /** Original lossless point-record reference. */
+  reference: LASWaveformPacketReference;
+  /** Descriptor selected by the packet reference. */
+  descriptor: LASWaveformPacketDescriptor;
+  /** Absolute byte offset read from the supplied LAS or WDP source. */
+  sourceByteOffset: bigint;
+  /** Exact packet bytes read from the source. */
+  data: Uint8Array;
+  /** Unsigned integer sample values decoded from the packet. */
+  samples: Uint32Array;
+  /** Sample amplitudes after applying descriptor gain and offset. */
+  amplitudes: Float64Array;
+};
+
+/** Options for waveform packet range reads. */
+export type LASWaveformReadOptions = {
+  /** Abort signal forwarded to the underlying range read. */
+  signal?: AbortSignal;
+  /** Maximum simultaneous reads used by `readLASWaveformPackets`. */
+  concurrency?: number;
+};
+
+/**
+ * Parses one fixed-width LAS waveform packet reference without losing its 64-bit offset.
+ * @param data Buffer or view containing the reference.
+ * @param byteOffset Byte offset of the reference within `data`.
+ * @returns Parsed packet reference.
+ */
+export function parseLASWaveformPacketReference(
+  data: ArrayBuffer | ArrayBufferView,
+  byteOffset = 0
+): LASWaveformPacketReference {
+  const bytes = getUint8Array(data);
+  if (
+    !Number.isInteger(byteOffset) ||
+    byteOffset < 0 ||
+    byteOffset + WAVEFORM_PACKET_REFERENCE_BYTE_LENGTH > bytes.byteLength
+  ) {
+    throw new Error('LAS waveform packet reference is truncated');
+  }
+  const dataView = new DataView(
+    bytes.buffer,
+    bytes.byteOffset + byteOffset,
+    WAVEFORM_PACKET_REFERENCE_BYTE_LENGTH
+  );
+  return {
+    descriptorIndex: dataView.getUint8(0),
+    byteOffset: dataView.getBigUint64(1, true),
+    byteLength: dataView.getUint32(9, true),
+    returnPointLocation: dataView.getFloat32(13, true),
+    parametricOffset: [
+      dataView.getFloat32(17, true),
+      dataView.getFloat32(21, true),
+      dataView.getFloat32(25, true)
+    ]
+  };
+}
+
+/**
+ * Returns the waveform storage selected by LAS global-encoding bits.
+ * @param metadata Parsed LAS metadata.
+ * @returns Internal or external storage, or `null` when the file declares neither.
+ */
+export function getLASWaveformStorage(metadata: LASMetadata): LASWaveformStorage | null {
+  const hasInternalData = Boolean(metadata.globalEncoding & INTERNAL_WAVEFORM_DATA_MASK);
+  const hasExternalData = Boolean(metadata.globalEncoding & EXTERNAL_WAVEFORM_DATA_MASK);
+  if (hasInternalData && hasExternalData) {
+    throw new Error('LAS waveform data cannot be both internal and external');
+  }
+  return hasInternalData ? 'internal' : hasExternalData ? 'external' : null;
+}
+
+/**
+ * Decodes uncompressed 2-32 bit LAS waveform samples.
+ * @param data Exact waveform packet bytes.
+ * @param descriptor Waveform descriptor selected by the point record.
+ * @returns Unsigned integer waveform samples.
+ */
+export function decodeLASWaveformSamples(
+  data: Uint8Array,
+  descriptor: LASWaveformPacketDescriptor
+): Uint32Array {
+  const requiredByteLength = validateLASWaveformDescriptor(descriptor);
+  if (data.byteLength < requiredByteLength) {
+    throw new Error(
+      `LAS waveform packet is truncated: expected ${requiredByteLength} bytes, received ${data.byteLength}`
+    );
+  }
+
+  const bitsPerSample = descriptor.bitsPerSample;
+  const samples = new Uint32Array(descriptor.numberOfSamples);
+  const sampleDivisor = 2 ** bitsPerSample;
+  let bitBuffer = 0;
+  let availableBitCount = 0;
+  let sourceByteIndex = 0;
+  for (let sampleIndex = 0; sampleIndex < samples.length; sampleIndex++) {
+    while (availableBitCount < bitsPerSample) {
+      bitBuffer += data[sourceByteIndex++] * 2 ** availableBitCount;
+      availableBitCount += 8;
+    }
+    samples[sampleIndex] = bitBuffer % sampleDivisor;
+    bitBuffer = Math.floor(bitBuffer / sampleDivisor);
+    availableBitCount -= bitsPerSample;
+  }
+  return samples;
+}
+
+/** Validates one waveform descriptor and returns its uncompressed packet byte length. */
+function validateLASWaveformDescriptor(descriptor: LASWaveformPacketDescriptor): number {
+  if (descriptor.compressionType !== 0) {
+    throw new Error(`LAS waveform compression type ${descriptor.compressionType} is not supported`);
+  }
+  const bitsPerSample = descriptor.bitsPerSample;
+  if (!Number.isInteger(bitsPerSample) || bitsPerSample < 2 || bitsPerSample > 32) {
+    throw new Error(
+      `LAS waveform bits per sample must be between 2 and 32; received ${bitsPerSample}`
+    );
+  }
+  if (!Number.isInteger(descriptor.numberOfSamples) || descriptor.numberOfSamples < 0) {
+    throw new Error(`LAS waveform sample count ${descriptor.numberOfSamples} is invalid`);
+  }
+  const requiredByteLength = Math.ceil((descriptor.numberOfSamples * bitsPerSample) / 8);
+  if (!Number.isSafeInteger(requiredByteLength) || requiredByteLength < 0) {
+    throw new Error(`LAS waveform sample count ${descriptor.numberOfSamples} is invalid`);
+  }
+  return requiredByteLength;
+}
+
+/**
+ * Applies waveform descriptor gain and offset to integer samples.
+ * @param samples Unsigned integer waveform samples.
+ * @param descriptor Waveform descriptor containing gain and offset.
+ * @returns Scaled sample amplitudes.
+ */
+export function scaleLASWaveformSamples(
+  samples: Uint32Array,
+  descriptor: LASWaveformPacketDescriptor
+): Float64Array {
+  const amplitudes = new Float64Array(samples.length);
+  for (let sampleIndex = 0; sampleIndex < samples.length; sampleIndex++) {
+    amplitudes[sampleIndex] =
+      descriptor.digitizerOffset + descriptor.digitizerGain * samples[sampleIndex];
+  }
+  return amplitudes;
+}
+
+/**
+ * Range-reads and decodes one internal LAS or external WDP waveform packet.
+ *
+ * Supply the LAS file when `metadata.globalEncoding` declares internal waveform data and the
+ * companion WDP file when it declares external waveform data.
+ *
+ * @param source Random-access LAS or WDP source selected by the file's global-encoding field.
+ * @param reference Lossless waveform packet reference from a point record.
+ * @param metadata Parsed metadata from the owning LAS file.
+ * @param options Range-read options.
+ * @returns Decoded waveform packet.
+ */
+export async function readLASWaveformPacket(
+  source: ReadableFile,
+  reference: LASWaveformPacketReference,
+  metadata: LASMetadata,
+  options: LASWaveformReadOptions = {}
+): Promise<LASWaveformPacket> {
+  const storage = getLASWaveformStorage(metadata);
+  if (!storage) {
+    throw new Error('LAS file does not declare internal or external waveform data');
+  }
+  if (reference.descriptorIndex === 0) {
+    throw new Error('LAS waveform descriptor index 0 does not reference a waveform packet');
+  }
+  const descriptorRecordId = reference.descriptorIndex + 99;
+  const descriptor = metadata.waveformPacketDescriptors.find(
+    candidate => candidate.recordId === descriptorRecordId
+  );
+  if (!descriptor) {
+    throw new Error(`LAS waveform descriptor VLR ${descriptorRecordId} is missing`);
+  }
+  const requiredByteLength = validateLASWaveformDescriptor(descriptor);
+  if (!Number.isInteger(reference.byteLength) || reference.byteLength < requiredByteLength) {
+    throw new Error(
+      `LAS waveform packet size ${reference.byteLength} is smaller than the descriptor requires (${requiredByteLength})`
+    );
+  }
+  const sourceByteOffset =
+    storage === 'internal'
+      ? getInternalWaveformSourceOffset(metadata) + reference.byteOffset
+      : reference.byteOffset;
+  const arrayBuffer = await source.read(sourceByteOffset, reference.byteLength, options.signal);
+  if (arrayBuffer.byteLength !== reference.byteLength) {
+    throw new Error(
+      `LAS waveform range read returned ${arrayBuffer.byteLength} bytes; expected ${reference.byteLength}`
+    );
+  }
+  const data = new Uint8Array(arrayBuffer);
+  const samples = decodeLASWaveformSamples(data, descriptor);
+  return {
+    reference,
+    descriptor,
+    sourceByteOffset,
+    data,
+    samples,
+    amplitudes: scaleLASWaveformSamples(samples, descriptor)
+  };
+}
+
+/**
+ * Range-reads multiple waveform packets with bounded concurrency.
+ * @param source Random-access LAS or WDP source selected by the file's global-encoding field.
+ * @param references Waveform packet references in desired result order.
+ * @param metadata Parsed metadata from the owning LAS file.
+ * @param options Range-read and concurrency options.
+ * @returns Decoded waveform packets in input order.
+ */
+export async function readLASWaveformPackets(
+  source: ReadableFile,
+  references: Iterable<LASWaveformPacketReference>,
+  metadata: LASMetadata,
+  options: LASWaveformReadOptions = {}
+): Promise<LASWaveformPacket[]> {
+  const referenceArray = Array.from(references);
+  const concurrency = options.concurrency ?? 8;
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new Error(
+      `LAS waveform read concurrency must be a positive integer; received ${concurrency}`
+    );
+  }
+  const packets = new Array<LASWaveformPacket>(referenceArray.length);
+  let nextReferenceIndex = 0;
+
+  /** Reads packet references from the shared index until none remain. */
+  const readNextPackets = async (): Promise<void> => {
+    while (nextReferenceIndex < referenceArray.length) {
+      const referenceIndex = nextReferenceIndex++;
+      packets[referenceIndex] = await readLASWaveformPacket(
+        source,
+        referenceArray[referenceIndex],
+        metadata,
+        options
+      );
+    }
+  };
+
+  const workerCount = Math.min(concurrency, referenceArray.length);
+  await Promise.all(Array.from({length: workerCount}, () => readNextPackets()));
+  return packets;
+}
+
+/** Return the exact internal waveform packet-record base offset from the LAS public header. */
+function getInternalWaveformSourceOffset(metadata: LASMetadata): bigint {
+  if (metadata.waveformDataOffset === undefined) {
+    throw new Error('LAS internal waveform data offset is missing from the public header');
+  }
+  return metadata.waveformDataOffset;
+}
+
+/** Create a byte view that preserves an input view's byte offset and byte length. */
+function getUint8Array(data: ArrayBuffer | ArrayBufferView): Uint8Array {
+  return data instanceof ArrayBuffer
+    ? new Uint8Array(data)
+    : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}