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

package/src/las/lib/get-las-schema.ts

@@ -0,0 +1,55 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Schema, MeshAttributes} from '@loaders.gl/core/schema';
+import {deduceMeshSchema} from '@loaders.gl/core/schema-utils';
+import type {LASHeader} from './las-types';
+
+/**
+ * Gets schema from LAS header
+ * @param lasHeader
+ * @param metadata
+ * @returns Schema
+ */
+export function getLASSchema(lasHeader: LASHeader, attributes: MeshAttributes): Schema {
+  const metadataMap = makeMetadataFromLasHeader(lasHeader);
+  const schema = deduceMeshSchema(attributes, metadataMap);
+  return schema;
+}
+
+/**
+ * Make arrow like schema metadata by LASHeader properties
+ * @param lasHeader
+ * @returns
+ */
+export function makeMetadataFromLasHeader(lasHeader: LASHeader): Record<string, string> {
+  const metadata: Record<string, string> = {};
+  /* eslint-disable camelcase */
+  metadata.las_pointsOffset = lasHeader.pointsOffset.toString(10);
+  metadata.las_pointsFormatId = lasHeader.pointsFormatId.toString(10);
+  metadata.las_pointsStructSize = lasHeader.pointsStructSize.toString(10);
+  metadata.las_pointsCount = lasHeader.pointsCount.toString(10);
+  metadata.las_scale = JSON.stringify(lasHeader.scale);
+  metadata.las_offset = JSON.stringify(lasHeader.offset);
+  if (lasHeader.maxs !== undefined) {
+    metadata.las_maxs = JSON.stringify(lasHeader.maxs);
+  }
+  if (lasHeader.mins !== undefined) {
+    metadata.las_mins = JSON.stringify(lasHeader.mins);
+  }
+  metadata.las_totalToRead = lasHeader.totalToRead.toString(10);
+  metadata.las_pointsFortotalReadmatId = lasHeader.totalRead.toString(10);
+  if (lasHeader.versionAsString !== undefined) {
+    metadata.las_versionAsString = lasHeader.versionAsString;
+  }
+  if (lasHeader.isCompressed !== undefined) {
+    metadata.las_isCompressed = lasHeader.isCompressed.toString();
+  }
+  if (lasHeader.metadata?.wkt) metadata.las_wkt = lasHeader.metadata.wkt;
+  if (lasHeader.metadata?.wktMathTransform)
+    metadata.las_wktMathTransform = lasHeader.metadata.wktMathTransform;
+  if (lasHeader.metadata?.geotiff)
+    metadata.las_geotiff = JSON.stringify(lasHeader.metadata.geotiff);
+  return metadata;
+}

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

@@ -0,0 +1,178 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT AND Apache-2.0
+// Copyright (c) vis.gl contributors
+// Compatibility reconstruction follows LASzip, copyright rapidlasso GmbH.
+// See LASZIP-LICENSE and LASZIP-NOTICE in this directory.
+
+import type {LASHeader, LASMetadata} from './las-types';
+
+/** Descriptor offsets for LASzip's legacy representation of modern point records. */
+export type LASCompatibilityLayout = {
+  /** Logical modern point format, while the source header retains its physical legacy format. */
+  pointDataRecordFormat: number;
+  /** Logical LAS version stored in the compatibility VLR. */
+  version: '1.4' | '1.5';
+  /** Packed Extra Bytes offset of the scan angle remainder. */
+  scanAngleByteOffset: number;
+  /** Packed Extra Bytes offset of the return increments. */
+  returnsByteOffset: number;
+  /** Packed Extra Bytes offset of the classification increment. */
+  classificationByteOffset: number;
+  /** Packed Extra Bytes offset of overlap and scanner channel. */
+  flagsByteOffset: number;
+  /** Packed Extra Bytes offset of optional NIR data. */
+  nirByteOffset?: number;
+};
+
+/** Selected column targets that can be reconstructed from compatibility Extra Bytes. */
+export type LASCompatibilityTarget = {
+  /** Classification codes. */
+  classifications: Uint8Array | null;
+  /** Return numbers. */
+  returnNumbers: Uint8Array | null;
+  /** Return counts. */
+  numberOfReturns: Uint8Array | null;
+  /** Scan angles in modern 0.006-degree units. */
+  scanAngles: Int16Array | null;
+  /** Overlap flags. */
+  overlapFlags: Uint8Array | null;
+  /** Scanner channels. */
+  scannerChannels: Uint8Array | null;
+  /** Optional NIR values. */
+  nir: Uint16Array | null;
+};
+
+/** Validate the explicit compatibility marker and locate its descriptor-defined fields. */
+export function getLASCompatibilityLayout(
+  header: LASHeader,
+  metadata: LASMetadata
+): LASCompatibilityLayout | undefined {
+  const record = metadata.vlrs.find(
+    variableLengthRecord =>
+      variableLengthRecord.userId === 'lascompatible' && variableLengthRecord.recordId === 22204
+  );
+  if (!record) return undefined;
+  if (
+    !['1.0', '1.1', '1.2', '1.3'].includes(header.versionAsString || '') ||
+    ![1, 3, 4, 5].includes(header.pointsFormatId)
+  ) {
+    throw new Error('LASLoader: compatibility mode requires a legacy LAS point format');
+  }
+  const view = new DataView(record.data.buffer, record.data.byteOffset, record.data.byteLength);
+  if (view.byteLength < 4) throw new Error('LASLoader: truncated LASzip compatibility VLR');
+  const version = view.getUint16(2, true);
+  if ((version !== 3 && version !== 4) || view.byteLength !== (version === 3 ? 156 : 174)) {
+    throw new Error(`LASLoader: unsupported LASzip compatibility VLR version ${version} or length`);
+  }
+  const offsets = new Map<string, {byteOffset: number; dataType: number}>();
+  let byteOffset = 0;
+  for (const descriptor of metadata.extraBytes) {
+    const scalarDataType =
+      descriptor.dataType > 20
+        ? descriptor.dataType - 20
+        : descriptor.dataType > 10
+          ? descriptor.dataType - 10
+          : descriptor.dataType;
+    const size = descriptor.dataType > 20 ? 3 : descriptor.dataType > 10 ? 2 : 1;
+    const byteLength =
+      descriptor.dataType === 0
+        ? descriptor.options
+        : scalarDataType <= 2
+          ? size
+          : scalarDataType <= 4
+            ? 2 * size
+            : scalarDataType <= 6 || scalarDataType === 9
+              ? 4 * size
+              : 8 * size;
+    if (descriptor.dataType > 30 || !byteLength)
+      throw new Error('LASLoader: invalid compatibility Extra Bytes layout');
+    offsets.set(descriptor.name, {byteOffset, dataType: descriptor.dataType});
+    byteOffset += byteLength;
+  }
+  const baseLength = {1: 28, 3: 34, 4: 57, 5: 63}[header.pointsFormatId]!;
+  if (byteOffset !== header.pointsStructSize - baseLength)
+    throw new Error('LASLoader: compatibility descriptors do not match point record length');
+  const scanAngleByteOffset = getCompatibilityFieldOffset(offsets, 'LAS 1.4 scan angle', 4);
+  const returnsByteOffset = getCompatibilityFieldOffset(offsets, 'LAS 1.4 extended returns', 1);
+  const classificationByteOffset = getCompatibilityFieldOffset(
+    offsets,
+    'LAS 1.4 classification',
+    1
+  );
+  const flagsByteOffset = getCompatibilityFieldOffset(offsets, 'LAS 1.4 flags and channel', 1);
+  const nirByteOffset = offsets.has('LAS 1.4 NIR band')
+    ? getCompatibilityFieldOffset(offsets, 'LAS 1.4 NIR band', 3)
+    : undefined;
+  const pointDataRecordFormat =
+    header.pointsFormatId === 1
+      ? 6
+      : header.pointsFormatId === 3
+        ? nirByteOffset === undefined
+          ? 7
+          : 8
+        : header.pointsFormatId === 4
+          ? 9
+          : 10;
+  if (header.pointsFormatId === 5 && nirByteOffset === undefined)
+    throw new Error('LASLoader: compatibility waveform color points require NIR');
+  return {
+    pointDataRecordFormat,
+    version: version === 3 ? '1.4' : '1.5',
+    scanAngleByteOffset,
+    returnsByteOffset,
+    classificationByteOffset,
+    flagsByteOffset,
+    nirByteOffset
+  };
+}
+
+/** Require the named field to have the scalar representation used by LASzip. */
+function getCompatibilityFieldOffset(
+  offsets: Map<string, {byteOffset: number; dataType: number}>,
+  name: string,
+  dataType: number
+): number {
+  const field = offsets.get(name);
+  if (!field || field.dataType !== dataType)
+    throw new Error(`LASLoader: missing or invalid compatibility field ${name}`);
+  return field.byteOffset;
+}
+
+/** Restore selected modern fields from one legacy record without changing raw point bytes. */
+export function populateLASCompatibilityPoint(
+  view: DataView,
+  extraByteOffset: number,
+  pointIndex: number,
+  layout: LASCompatibilityLayout,
+  target: LASCompatibilityTarget
+): void {
+  if (
+    !target.classifications &&
+    !target.returnNumbers &&
+    !target.numberOfReturns &&
+    !target.scanAngles &&
+    !target.overlapFlags &&
+    !target.scannerChannels &&
+    !target.nir
+  )
+    return;
+  const extendedReturns = view.getUint8(extraByteOffset + layout.returnsByteOffset);
+  const flags = view.getUint8(extraByteOffset + layout.flagsByteOffset);
+  if (target.classifications)
+    target.classifications[pointIndex] += view.getUint8(
+      extraByteOffset + layout.classificationByteOffset
+    );
+  if (target.returnNumbers) target.returnNumbers[pointIndex] += extendedReturns >> 4;
+  if (target.numberOfReturns) target.numberOfReturns[pointIndex] += extendedReturns & 15;
+  if (target.scanAngles) {
+    const rank = target.scanAngles[pointIndex];
+    const prediction = Math.fround(rank / Math.fround(0.006));
+    const quantized = Math.sign(prediction) * Math.floor(Math.abs(prediction) + 0.5);
+    target.scanAngles[pointIndex] =
+      quantized + view.getInt16(extraByteOffset + layout.scanAngleByteOffset, true);
+  }
+  if (target.overlapFlags) target.overlapFlags[pointIndex] = flags & 1;
+  if (target.scannerChannels) target.scannerChannels[pointIndex] = (flags >> 1) & 3;
+  if (target.nir && layout.nirByteOffset !== undefined)
+    target.nir[pointIndex] = view.getUint16(extraByteOffset + layout.nirByteOffset, true);
+}

package/src/las/lib/las-extra-bytes.ts

@@ -0,0 +1,276 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LASExtraBytesDescriptor} from './las-types';
+
+/** Typed-array values supported for LAS Extra Bytes Arrow attributes. */
+export type LASTypedExtraBytesValue =
+  | Uint8Array
+  | Int8Array
+  | Uint16Array
+  | Int16Array
+  | Uint32Array
+  | Int32Array
+  | Float32Array
+  | Float64Array
+  | BigInt64Array
+  | BigUint64Array;
+
+/** Prepared typed LAS Extra Bytes attribute and its source-record layout. */
+export type LASTypedExtraBytesAttribute = {
+  /** Stable Arrow attribute name. */
+  name: string;
+  /** Typed output values. */
+  value: LASTypedExtraBytesValue;
+  /** Number of components per point. */
+  size: number;
+  /** LAS scalar data type code. */
+  scalarDataType: number;
+  /** Byte offset within the packed Extra Bytes record. */
+  byteOffset: number;
+  /** Total source byte length per point. */
+  byteLength: number;
+  /** Per-component scales. */
+  scales: number[];
+  /** Per-component offsets. */
+  offsets: number[];
+  /** Whether transformed integer values require Float64 output. */
+  outputFloat64: boolean;
+};
+
+/** Parse the 192-byte descriptors in an LAS Extra Bytes VLR payload. */
+export function parseLASExtraBytes(data: Uint8Array): LASExtraBytesDescriptor[] {
+  if (data.byteLength % 192 !== 0) {
+    throw new Error(`LAS Extra Bytes VLR length ${data.byteLength} is not a multiple of 192`);
+  }
+  const descriptors: LASExtraBytesDescriptor[] = [];
+  const dataView = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  for (let descriptorOffset = 0; descriptorOffset < data.byteLength; descriptorOffset += 192) {
+    const scales: [number, number, number] = [
+      dataView.getFloat64(descriptorOffset + 112, true),
+      dataView.getFloat64(descriptorOffset + 120, true),
+      dataView.getFloat64(descriptorOffset + 128, true)
+    ];
+    const offsets: [number, number, number] = [
+      dataView.getFloat64(descriptorOffset + 136, true),
+      dataView.getFloat64(descriptorOffset + 144, true),
+      dataView.getFloat64(descriptorOffset + 152, true)
+    ];
+    descriptors.push({
+      dataType: data[descriptorOffset + 2],
+      options: data[descriptorOffset + 3],
+      name: readLASString(data, descriptorOffset + 4, 32),
+      description: readLASString(data, descriptorOffset + 160, 32),
+      scale: scales[0],
+      offset: offsets[0],
+      scales,
+      offsets,
+      data: data.slice(descriptorOffset, descriptorOffset + 192)
+    });
+  }
+  return descriptors;
+}
+
+/** Allocate typed Arrow attributes described by an LAS Extra Bytes VLR. */
+export function createLASTypedExtraBytesAttributes(
+  pointCount: number,
+  descriptors: readonly LASExtraBytesDescriptor[],
+  extraByteCount: number
+): LASTypedExtraBytesAttribute[] {
+  let byteOffset = 0;
+  const usedNames = new Set<string>();
+  const attributes: LASTypedExtraBytesAttribute[] = [];
+  for (let descriptorIndex = 0; descriptorIndex < descriptors.length; descriptorIndex++) {
+    const descriptor = descriptors[descriptorIndex];
+    const scalarDataType = getExtraBytesScalarDataType(descriptor.dataType);
+    const size = getExtraBytesComponentCount(descriptor.dataType);
+    const scalarByteLength = getExtraBytesScalarByteLength(scalarDataType);
+    const byteLength = scalarByteLength * size;
+    if (descriptor.dataType < 1 || descriptor.dataType > 30 || !byteLength) {
+      throw new Error(`Unsupported typed LAS Extra Bytes data type ${descriptor.dataType}`);
+    }
+    let name = `EXTRA_BYTES_${sanitizeExtraBytesName(descriptor.name)}`;
+    if (name === 'EXTRA_BYTES_') {
+      name = `EXTRA_BYTES_${descriptorIndex}`;
+    }
+    const baseName = name;
+    let suffix = 1;
+    while (usedNames.has(name)) {
+      name = `${baseName}_${suffix++}`;
+    }
+    usedNames.add(name);
+    const scales =
+      descriptor.options & 0x08 ? descriptor.scales.slice(0, size) : new Array(size).fill(1);
+    const offsets =
+      descriptor.options & 0x10 ? descriptor.offsets.slice(0, size) : new Array(size).fill(0);
+    const isBigInt = scalarDataType === 7 || scalarDataType === 8;
+    const outputFloat64 =
+      scalarDataType !== 10 &&
+      (isBigInt
+        ? scales.some(scale => scale !== 1) || offsets.some(offset => offset !== 0)
+        : Boolean(descriptor.options & 0x18));
+    attributes.push({
+      name,
+      value: createLASTypedExtraBytesValue(scalarDataType, pointCount * size, outputFloat64),
+      size,
+      scalarDataType,
+      byteOffset,
+      byteLength,
+      outputFloat64,
+      scales,
+      offsets
+    });
+    byteOffset += byteLength;
+  }
+  if (byteOffset !== extraByteCount) {
+    throw new Error(
+      `LAS Extra Bytes descriptors use ${byteOffset} bytes; point records provide ${extraByteCount}`
+    );
+  }
+  return attributes;
+}
+
+/** Populate typed attributes from packed Extra Bytes records. */
+export function populateLASTypedExtraBytes(
+  rawExtraBytes: Uint8Array,
+  pointCount: number,
+  extraByteCount: number,
+  attributes: readonly LASTypedExtraBytesAttribute[]
+): void {
+  if (rawExtraBytes.byteLength < pointCount * extraByteCount) {
+    throw new Error('Packed LAS Extra Bytes data is truncated');
+  }
+  const dataView = new DataView(
+    rawExtraBytes.buffer,
+    rawExtraBytes.byteOffset,
+    rawExtraBytes.byteLength
+  );
+  for (let pointIndex = 0; pointIndex < pointCount; pointIndex++) {
+    const recordOffset = pointIndex * extraByteCount;
+    for (const attribute of attributes) {
+      const targetOffset = pointIndex * attribute.size;
+      const sourceOffset = recordOffset + attribute.byteOffset;
+      const scalarByteLength = getExtraBytesScalarByteLength(attribute.scalarDataType);
+      for (let componentIndex = 0; componentIndex < attribute.size; componentIndex++) {
+        populateLASTypedExtraBytesComponent(
+          dataView,
+          sourceOffset + componentIndex * scalarByteLength,
+          attribute,
+          targetOffset + componentIndex,
+          componentIndex
+        );
+      }
+    }
+  }
+}
+
+function readLASString(bytes: Uint8Array, offset: number, length: number): string {
+  const decoded = new TextDecoder().decode(bytes.subarray(offset, offset + length));
+  let end = decoded.length;
+  while (end > 0 && decoded[end - 1] === '\0') {
+    end--;
+  }
+  return decoded.slice(0, end).trim();
+}
+
+function sanitizeExtraBytesName(name: string): string {
+  return name.trim().replace(/[^A-Za-z0-9_]+/g, '_');
+}
+
+function getExtraBytesScalarDataType(dataType: number): number {
+  return dataType > 20 ? dataType - 20 : dataType > 10 ? dataType - 10 : dataType;
+}
+
+function getExtraBytesComponentCount(dataType: number): number {
+  return dataType > 20 ? 3 : dataType > 10 ? 2 : 1;
+}
+
+function getExtraBytesScalarByteLength(dataType: number): number {
+  if (dataType <= 2) return 1;
+  if (dataType <= 4) return 2;
+  if (dataType <= 6 || dataType === 9) return 4;
+  if (dataType === 7 || dataType === 8 || dataType === 10) return 8;
+  return 0;
+}
+
+function readExtraBytesValue(
+  dataView: DataView,
+  offset: number,
+  scalarDataType: number
+): number | bigint {
+  switch (scalarDataType) {
+    case 1:
+      return dataView.getUint8(offset);
+    case 2:
+      return dataView.getInt8(offset);
+    case 3:
+      return dataView.getUint16(offset, true);
+    case 4:
+      return dataView.getInt16(offset, true);
+    case 5:
+      return dataView.getUint32(offset, true);
+    case 6:
+      return dataView.getInt32(offset, true);
+    case 7:
+      return dataView.getBigUint64(offset, true);
+    case 8:
+      return dataView.getBigInt64(offset, true);
+    case 9:
+      return dataView.getFloat32(offset, true);
+    case 10:
+      return dataView.getFloat64(offset, true);
+    default:
+      throw new Error(`Unsupported typed LAS Extra Bytes scalar data type ${scalarDataType}`);
+  }
+}
+
+/** Allocate the typed-array representation for one LAS Extra Bytes scalar type. */
+export function createLASTypedExtraBytesValue(
+  scalarDataType: number,
+  length: number,
+  outputFloat64: boolean
+): LASTypedExtraBytesValue {
+  if (outputFloat64 && scalarDataType !== 10) return new Float64Array(length);
+  switch (scalarDataType) {
+    case 1:
+      return new Uint8Array(length);
+    case 2:
+      return new Int8Array(length);
+    case 3:
+      return new Uint16Array(length);
+    case 4:
+      return new Int16Array(length);
+    case 5:
+      return new Uint32Array(length);
+    case 6:
+      return new Int32Array(length);
+    case 7:
+      return new BigUint64Array(length);
+    case 8:
+      return new BigInt64Array(length);
+    case 9:
+      return new Float32Array(length);
+    case 10:
+      return new Float64Array(length);
+    default:
+      throw new Error(`Unsupported typed LAS Extra Bytes scalar data type ${scalarDataType}`);
+  }
+}
+
+/** Decode one descriptor component, retaining integer precision unless a transform is requested. */
+export function populateLASTypedExtraBytesComponent(
+  dataView: DataView,
+  sourceOffset: number,
+  attribute: LASTypedExtraBytesAttribute,
+  targetOffset: number,
+  componentIndex: number
+): void {
+  const value = readExtraBytesValue(dataView, sourceOffset, attribute.scalarDataType);
+  if (attribute.value instanceof BigInt64Array || attribute.value instanceof BigUint64Array) {
+    attribute.value[targetOffset] = value as bigint;
+  } else {
+    attribute.value[targetOffset] =
+      Number(value) * attribute.scales[componentIndex] + attribute.offsets[componentIndex];
+  }
+}