@2112-lab/pathfinder/README.md

Pure JavaScript 3D pathfinding algorithm library for industrial plant pipe routing

# 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
```javascript
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
```bash
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:

```json
{
  "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:

```json
{
  "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
```bash
cd cli/
./install.sh
```

For global CLI installation:
```bash
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:
```bash
cd cli/
node cli.js --input test-scene.json --verbose
```

### CLI Tool
Run the comprehensive test suite:
```bash
cd cli/
node test.js
```

## Integration

The pathfinder can be used both programmatically and via CLI:

**Programmatic Use:**
```javascript
import { Pathfinder } from './src/index.js';
// Use in your application
```

**CLI Use:**
```bash
node cli/cli.js --input scene.json --output results.json
```

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