js-subpcd/CLAUDE.md

🌟 High-performance JavaScript/TypeScript QuadTree point cloud filtering and processing library. Published on npm as js-subpcd with PCL.js compatible API for spatial filtering, subsampling, and nearest neighbor search.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Running the Package
- `npm run demo` - Run the comprehensive demo showcasing all features
- `npm start` - Run the main index.js file
- `npm test` - Run tests (requires test.js file)

### Testing Commands
There are no specific lint, typecheck, or build commands configured. The package runs directly with Node.js.

## Architecture Overview

This is a **JavaScript QuadTree Point Cloud Processing Library** that provides PCL.js compatible APIs for spatial indexing and filtering of 3D point clouds.

### Core Architecture

**Main Entry Point**: `index.js` - Contains all core classes and PCL.js compatible API

**Key Classes**:
- **PointXYZ**: PCL.js compatible 3D point representation with distance calculations
- **PointCloud**: Container for managing collections of points with PCL.js style methods
- **DataLoader**: Handles loading point cloud data from files or ArrayBuffer (PCD format support)
- **QuadTreeManager**: Low-level spatial indexing using js-quadtree library for region queries and nearest neighbor search
- **QuadTreeFilter**: High-level filtering operations with grid-based subsampling and depth-based filtering

### API Design Patterns

**Dual API Support**:
1. **PCL.js Compatible API** (Recommended): Async initialization with `PCL.init()`, compatible with Point Cloud Library JavaScript patterns
2. **Legacy Direct Import**: Direct class instantiation for backward compatibility

**Spatial Operations**:
- Grid-based point subsampling with configurable spacing
- Depth-based filtering using power-of-2 grid hierarchies (2x2, 4x4, 8x8, etc.)
- Region queries within bounding rectangles
- K-nearest neighbor search with distance calculations

### Data Flow

1. **Loading**: DataLoader parses text files or PCD format into PointCloud objects
2. **Indexing**: QuadTreeManager builds spatial index using js-quadtree library
3. **Filtering**: QuadTreeFilter applies grid spacing or depth-based subsampling
4. **Querying**: Spatial queries return Point3D objects or indices

### Dependencies

- **js-quadtree**: ^3.3.6 - Core spatial indexing functionality
- **Node.js**: >=14.0.0 - Runtime requirement

### Performance Characteristics

- Optimized for datasets from thousands to millions of points
- Caching system for repeated operations with same data
- Layer schedule calculation for power-of-2 grid hierarchies
- Memory-efficient coordinate array processing

### File Format Support

- Text files with space/tab separated X Y Z coordinates
- PCD (Point Cloud Data) format via ASCII encoding
- ArrayBuffer input for web compatibility