@loaders.gl/potree 4.3.0-alpha.4 → 4.3.0-alpha.6

package/src/parsers/parse-potree-hierarchy-chunk.ts

@@ -54,32 +54,53 @@ Would have an index looking like this:
 | r36  | `0b00000000` (=0)  | `1`    |
 */
 
-/** @todo these types are an incorrect mess */
+/** Node metadata from index file */
 export type POTreeTileHeader = {
+  /** Number of child nodes */
   childCount: number;
+  /** Human readable name */
   name: string;
+  /** Child availability mask */
   childMask: number;
 };
 
-/** @todo these types are an incorrect mess */
+/** Hierarchical potree node structure */
 export type POTreeNode = {
+  /** Index data */
   header: POTreeTileHeader;
+  /** Human readable name */
   name: string;
+  /** Number of points */
   pointCount: number;
+  /** Node's level in the tree */
+  level: number;
+  /** Has children */
+  hasChildren: boolean;
+  /** Space between points */
+  spacing: number;
+  /** Available children */
   children: POTreeNode[];
+  /** All children including unavailable */
   childrenByIndex: POTreeNode[];
 };
 
-// type POTreeTileNode = POTreeNode;
-
-// load hierarchy
-export function parsePotreeHierarchyChunk(arrayBuffer: ArrayBuffer) {
+/**
+ * load hierarchy
+ * @param arrayBuffer - binary index data
+ * @returns root node
+ **/
+export function parsePotreeHierarchyChunk(arrayBuffer: ArrayBuffer): POTreeNode {
   const tileHeaders = parseBinaryChunk(arrayBuffer);
   return buildHierarchy(tileHeaders);
 }
 
-// Parses the binary rows
-function parseBinaryChunk(arrayBuffer: ArrayBuffer, byteOffset = 0) {
+/**
+ * Parses the binary rows
+ * @param arrayBuffer - binary index data to parse
+ * @param byteOffset - byte offset to start from
+ * @returns flat nodes array
+ * */
+function parseBinaryChunk(arrayBuffer: ArrayBuffer, byteOffset = 0): POTreeNode[] {
   const dataView = new DataView(arrayBuffer);
 
   const stack: POTreeNode[] = [];
@@ -90,8 +111,7 @@ function parseBinaryChunk(arrayBuffer: ArrayBuffer, byteOffset = 0) {
   byteOffset = decodeRow(dataView, byteOffset, topTileHeader);
 
   stack.push(topTileHeader);
-
-  const tileHeaders: POTreeTileHeader[] = [];
+  const tileHeaders: POTreeNode[] = [topTileHeader];
 
   while (stack.length > 0) {
     const snode = stack.shift();
@@ -100,11 +120,10 @@ function parseBinaryChunk(arrayBuffer: ArrayBuffer, byteOffset = 0) {
     for (let i = 0; i < 8; i++) {
       if (snode && (snode.header.childMask & mask) !== 0) {
         // @ts-expect-error
-        const tileHeader: POTreeTileHeader = {};
+        const tileHeader: POTreeNode = {};
         byteOffset = decodeRow(dataView, byteOffset, tileHeader);
         tileHeader.name = snode.name + i;
 
-        // @ts-expect-error
         stack.push(tileHeader);
         tileHeaders.push(tileHeader);
         snode.header.childCount++;
@@ -120,7 +139,14 @@ function parseBinaryChunk(arrayBuffer: ArrayBuffer, byteOffset = 0) {
   return tileHeaders;
 }
 
-function decodeRow(dataView, byteOffset, tileHeader) {
+/**
+ * Reads next row from binary index file
+ * @param dataView - index data
+ * @param byteOffset - current offset in the index data
+ * @param tileHeader - container to read to
+ * @returns new offset
+ */
+function decodeRow(dataView: DataView, byteOffset: number, tileHeader: POTreeNode): number {
   tileHeader.header = tileHeader.header || {};
   tileHeader.header.childMask = dataView.getUint8(byteOffset);
   tileHeader.header.childCount = 0;
@@ -130,16 +156,16 @@ function decodeRow(dataView, byteOffset, tileHeader) {
   return byteOffset;
 }
 
-// Resolves the binary rows into a hierarchy (tree structure)
-function buildHierarchy(tileHeaders, options: {spacing?: number} = {}): POTreeNode {
+/** Resolves the binary rows into a hierarchy (tree structure) */
+function buildHierarchy(flatNodes: POTreeNode[], options: {spacing?: number} = {}): POTreeNode {
   const DEFAULT_OPTIONS = {spacing: 100}; // TODO assert instead of default?
   options = {...DEFAULT_OPTIONS, ...options};
 
-  const topNode = tileHeaders[0];
+  const topNode: POTreeNode = flatNodes[0];
   const nodes = {};
 
-  for (const tileHeader of tileHeaders) {
-    const {name} = tileHeader;
+  for (const node of flatNodes) {
+    const {name} = node;
 
     const index = parseInt(name.charAt(name.length - 1), 10);
     const parentName = name.substring(0, name.length - 1);
@@ -147,20 +173,20 @@ function buildHierarchy(tileHeaders, options: {spacing?: number} = {}): POTreeNo
     const level = name.length - 1;
     // assert(parentNode && level >= 0);
 
-    tileHeader.level = level;
-    tileHeader.hasChildren = tileHeader.header.childCount;
-    tileHeader.children = [];
-    tileHeader.childrenByIndex = new Array(8).fill(null);
-    tileHeader.spacing = (options?.spacing || 0) / Math.pow(2, level);
+    node.level = level;
+    node.hasChildren = Boolean(node.header.childCount);
+    node.children = [];
+    node.childrenByIndex = new Array(8).fill(null);
+    node.spacing = (options?.spacing || 0) / Math.pow(2, level);
     // tileHeader.boundingVolume = Utils.createChildAABB(parentNode.boundingBox, index);
 
     if (parentNode) {
-      parentNode.children.push(tileHeader);
-      parentNode.childrenByIndex[index] = tileHeader;
+      parentNode.children.push(node);
+      parentNode.childrenByIndex[index] = node;
     }
 
     // Add the node to the map
-    nodes[name] = tileHeader;
+    nodes[name] = node;
   }
 
   // First node is the root

package/src/potree-hierarchy-chunk-loader.ts

@@ -7,20 +7,27 @@ import type {POTreeLoaderOptions} from './potree-loader';
 import type {POTreeNode} from './parsers/parse-potree-hierarchy-chunk';
 import {parsePotreeHierarchyChunk} from './parsers/parse-potree-hierarchy-chunk';
 
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
 /** Potree hierarchy chunk loader */
-// @ts-ignore not a valid loader
 export const PotreeHierarchyChunkLoader = {
   dataType: null as unknown as POTreeNode,
   batchType: null as never,
 
-  id: 'potree',
   name: 'potree Hierarchy Chunk',
+  id: 'potree-hrc',
+  module: 'potree',
+  version: VERSION,
   extensions: ['hrc'],
   mimeTypes: ['application/octet-stream'],
   // binary potree files have no header bytes, no content test function possible
   // test: ['...'],
   parse: async (arrayBuffer, options) => parsePotreeHierarchyChunk(arrayBuffer),
   parseSync: (arrayBuffer, options) => parsePotreeHierarchyChunk(arrayBuffer),
+  options: {
+    potree: {}
+  },
   binary: true
-  // @ts-ignore
 } as const satisfies LoaderWithParser<POTreeNode, never, POTreeLoaderOptions>;

package/src/potree-loader.ts

@@ -13,21 +13,20 @@ export type POTreeLoaderOptions = LoaderOptions & {
 };
 
 /** Potree loader */
-// @ts-ignore
 export const PotreeLoader = {
   dataType: null as unknown as any,
   batchType: null as never,
 
-  name: 'potree',
+  name: 'potree metadata',
   id: 'potree',
   module: 'potree',
   version: VERSION,
-  extensions: ['json'],
+  extensions: ['js'],
   mimeTypes: ['application/json'],
   testText: (text) => text.indexOf('octreeDir') >= 0,
+  parse: (data: ArrayBuffer) => JSON.parse(new TextDecoder().decode(data)),
   parseTextSync: (text) => JSON.parse(text),
   options: {
     potree: {}
   }
-  // @ts-ignore
 } as const satisfies LoaderWithParser<any, never, POTreeLoaderOptions>;

package/src/potree-source.ts

@@ -0,0 +1,28 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Source} from '@loaders.gl/loader-utils';
+import {PotreeNodesSource, PotreeNodesSourceProps} from './lib/potree-node-source';
+
+const VERSION = '1.7';
+
+/**
+ * Creates point cloud data sources for Potree urls
+ */
+export const PotreeSource = {
+  name: 'Potree',
+  id: 'potree',
+  module: 'potree',
+  version: VERSION,
+  extensions: ['bin', 'las', 'laz'],
+  mimeTypes: ['application/octet-stream'],
+  options: {url: undefined!, potree: {}},
+  type: 'potree',
+  fromUrl: true,
+  fromBlob: true,
+
+  testURL: (url: string) => url.endsWith('.js'),
+  createDataSource: (url: string | Blob, props: PotreeNodesSourceProps) =>
+    new PotreeNodesSource(url, props)
+} as const satisfies Source<PotreeNodesSource, PotreeNodesSourceProps>;

package/src/types/potree-metadata.ts

@@ -0,0 +1,94 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Bounding box */
+export interface PotreeBoundingBox {
+  /** Min X */
+  lx: number;
+  /** Min Y */
+  ly: number;
+  /** Min Z */
+  lz: number;
+  /** Max X */
+  ux: number;
+  /** Max Y */
+  uy: number;
+  /** Max Z */
+  uz: number;
+}
+
+/** Attribute types for *.bin content */
+export type PotreeAttribute =
+  /** 3 (uint32) numbers: x, y, z */
+  | 'POSITION_CARTESIAN'
+  /** 4 x (uint8) numbers for the color: r, g, b, a */
+  | 'RGBA_PACKED'
+  /** 4 x (uint8) numbers for the color: r, g, b, a */
+  | 'COLOR_PACKED'
+  /** 3 x (uint8) numbers for the color: r, g, b */
+  | 'RGB_PACKED'
+  /** 3 x (float) numbers: x', y', z'  */
+  | 'NORMAL_FLOATS'
+  /** (uint8) number */
+  | 'FILLER_1B'
+  /** (uint16) number specifying the point's intensity */
+  | 'INTENSITY'
+  /** (uint8) id for the class used */
+  | 'CLASSIFICATION'
+  /** Note: might need to be revisited, best don't use */
+  | 'NORMAL_SPHEREMAPPED'
+  /** Note: might need to be revisited, best don't use */
+  | 'NORMAL_OCT16'
+  /** 3 x (float) numbers: x', y', z' */
+  | 'NORMAL';
+
+/** Hierarchy item: [node name leading with 'r', points count
+ * @example [r043, 145]
+] */
+export type HierarchyItem = [string, number];
+
+/**
+ * Potree data set format metadata (cloud.js)
+ * @version 1.7
+ * @link https://github.com/potree/potree/blob/1.7/docs/potree-file-format.md
+ * */
+export interface PotreeMetadata {
+  /** Version number in which this file is written */
+  version: string;
+  /** Folder that is used to load additional data */
+  octreeDir: string;
+  /** Amount of points contained in the whole pointcloud data */
+  points: number;
+  /**
+   * This parameter is used to transform the point data
+   * to the projection system used while visualizing the points. It has to be
+   * in a format that is parsable by [proj.4][proj4].
+   * */
+  projection: string;
+  /** Bounding box of the world used to limit the initial POV. */
+  boundingBox: PotreeBoundingBox;
+  /** Bounding box of the actual points in the data */
+  tightBoundingBox: PotreeBoundingBox;
+  /** Description of point attributes in data files */
+  pointAttributes: 'LAS' | 'LAZ' | PotreeAttribute[];
+  /**
+   * Space between points at the root node.
+   * This value is halved at each octree level.
+   * */
+  spacing: number;
+  /**
+   * Scale applied to convert POSITION_CARTESIAN components
+   * from uint32 values to floating point values. The full transformation
+   * to world coordinates is
+   * position = (POSITION_CARTESIAN * scale) + boundingBox.min
+   * */
+  scale: number;
+  /** Amount of Octree levels before a new folder hierarchy is expected. */
+  hierarchyStepSize: number;
+  /**
+   * The hierarchy of files, now loaded through index files.
+   * @deprecated
+   * */
+  hierarchy: HierarchyItem[];
+}

package/src/utils/parse-version.ts

@@ -0,0 +1,8 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export function parseVersion(version: string): {major: number; minor: number} {
+  const parts = version.split('.').map(Number);
+  return {major: parts[0], minor: parts[1]};
+}