@2112-lab/pathfinder

Central Plant Pathfinder

A 3D pathfinding system that finds orthogonal paths between objects in Central Plant scenes.

Directory Structure

pathfinder/
├── src/                    # Core pathfinder library
│   ├── index.js           # Main Pathfinder class  
│   ├── Vector3.js         # 3D vector utilities
│   ├── SceneManager.js    # Scene management
│   ├── GridSystem.js      # Grid-based pathfinding
│   ├── ConnectorManager.js # Connection clustering
│   ├── PathManager.js     # A* pathfinding algorithm
│   └── TreePathManager.js # Tree-based path optimization
├── package.json          # ES module configuration
├── README.md            # This file - main documentation
└── GATEWAY_DOCUMENTATION.md # API documentation

Quick Start

Using the Core Library

import { Pathfinder } from './src/index.js';

const pathfinder = new Pathfinder({
  grid: {
    size: 0.5,
    safetyMargin: 0,
    minSegmentLength: 0.5,
    timeout: 1000
  }
});

const results = pathfinder.findPaths(scene, connections);

Using the Command-Line Interface

cd cli/
node cli.js --help
node cli.js --input test-scene.json --format summary

Features

• 3D Pathfinding: Finds orthogonal paths between objects in 3D space
• Gateway Optimization: Automatically creates gateway points for complex multi-object connections
• Grid-based Algorithm: Uses A* pathfinding on a configurable 3D grid
• Obstacle Avoidance: Respects object bounding boxes and safety margins
• Flexible Configuration: Customizable grid size, timeouts, and path constraints
• CLI Interface: Command-line tool for automation and batch processing

Input Format

The pathfinder expects scene objects with worldBoundingBox data:

{
  "scene": {
    "children": [
      {
        "uuid": "OBJECT-ID",
        "userData": {
          "worldBoundingBox": {
            "min": [x, y, z],
            "max": [x, y, z]
          }
        }
      }
    ]
  },
  "connections": [
    {"from": "OBJECT-ID-1", "to": "OBJECT-ID-2"}
  ]
}

Output Format

Returns paths, rewired connections, and gateway information:

{
  "paths": [
    {
      "from": "OBJECT-1",
      "to": "OBJECT-2",
      "path": [
        {"x": 0, "y": 0, "z": 0},
        {"x": 1, "y": 0, "z": 0}
      ]
    }
  ],
  "rewiredConnections": [...],
  "gateways": [...]
}

Installation

Core Library Only

The core pathfinder library is ready to use - just import from ./src/index.js.

CLI Tool

cd cli/
./install.sh

For global CLI installation:

cd cli/
npm install -g .

Documentation

• API Documentation: See GATEWAY_DOCUMENTATION.md
• CLI Documentation: See cli/README.md
• Usage Examples: See cli/EXAMPLES.md
• Feature Summary: See cli/SUMMARY.md

Testing

Core Library

Test the core pathfinder functionality using the CLI:

cd cli/
node cli.js --input test-scene.json --verbose

CLI Tool

Run the comprehensive test suite:

cd cli/
node test.js

Integration

The pathfinder can be used both programmatically and via CLI:

Programmatic Use:

import { Pathfinder } from './src/index.js';
// Use in your application

CLI Use:

node cli/cli.js --input scene.json --output results.json

Batch Processing:

for scene in scenes/*.json; do
    node cli/cli.js --input "$scene" --format summary >> report.txt
done