# @tscircuit/capacity-autorouter

An MIT-licensed full-pipeline PCB autorouter for node.js and TypeScript projects. Part of [tscircuit](https://github.com/tscircuit/tscircuit)

[View Online Playground](https://autorouter.tscircuit.com) · [tscircuit docs](https://docs.tscircuit.com) · [discord](https://tscircuit.com/join) · [twitter](https://x.com/seveibar) · [try tscircuit online](https://tscircuit.com) · [Report/Debug Autorouter Bugs](https://docs.tscircuit.com/contributing/report-autorouter-bugs)

Want to understand how the autorouter works? Read this [blog post](https://blog.autorouting.com/p/hypergraph-autorouting)

## How to file a bug report

1. You should have [created a bug report via the tscircuit errors tab](https://docs.tscircuit.com/contributing/report-autorouter-bugs)
2. Run `bun run bug-report <bug-report-url>` to download the report and create a debugging fixture file in the `examples/bug-reports` directory, you can then find the bug report in the server (via `bun run start`)
3. Or run `bun run bug-report-with-test <bug-report-url>` to download the report, create the fixture, and scaffold a matching snapshot test under `tests/bugs`

Or [run the Create Bug Report workflow](https://github.com/tscircuit/capacity-autorouter/actions/workflows/create-bug-report.yml) to automatically create a PR with the bug report (maintainers only)

## Installation

```bash
bun add @tscircuit/capacity-autorouter
```

## Usage as a Library

### Basic Usage

```typescript
import { AutoroutingPipelineSolver } from "@tscircuit/capacity-autorouter"

// Create a solver with SimpleRouteJson input
const solver = new AutoroutingPipelineSolver(simpleRouteJson)

// Run the solver until completion
while (!solver.solved && !solver.failed) {
  solver.step()
}

// Check if solving was successful
if (solver.failed) {
  console.error("Routing failed:", solver.error)
} else {
  // Get the routing results as SimpleRouteJson with traces
  const resultWithRoutes = solver.getOutputSimpleRouteJson()

  // Use the resulting routes in your application
  console.log(
    `Successfully routed ${resultWithRoutes.traces?.length} connections`
  )
}
```

### Input Format: SimpleRouteJson

The input to the autorouter is a `SimpleRouteJson` object with the following structure:

```typescript
interface SimpleRouteJson {
  layerCount: number
  minTraceWidth: number
  obstacles: Obstacle[]
  connections: Array<SimpleRouteConnection>
  bounds: { minX: number; maxX: number; minY: number; maxY: number }
  traces?: SimplifiedPcbTraces // Optional for input
}

interface Obstacle {
  type: "rect"
  layers: string[]
  center: { x: number; y: number }
  width: number
  height: number
  ccwRotationDegrees?: number
  connectedTo: string[] // TraceIds
  isCopperPour?: boolean
  offBoardConnectsTo?: string[] // TraceIds connected off-board
}

interface SimpleRouteConnection {
  name: string
  pointsToConnect: Array<{ x: number; y: number; layer: string }>
}
```

### Output Format

The `getOutputSimpleRouteJson()` method returns the original `SimpleRouteJson` with a populated `traces` property. The traces are represented as `SimplifiedPcbTraces`:

```typescript
type SimplifiedPcbTraces = Array<{
  type: "pcb_trace"
  pcb_trace_id: string // TraceId
  route: Array<
    | {
        route_type: "wire"
        x: number
        y: number
        width: number
        layer: string
      }
    | {
        route_type: "via"
        x: number
        y: number
        to_layer: string
        from_layer: string
      }
  >
}>
```

### Advanced Configuration

You can provide optional configuration parameters to the solver:

```typescript
const solver = new CapacityMeshSolver(simpleRouteJson, {
  // Optional: Manually set capacity planning depth (otherwise automatically calculated)
  capacityDepth: 7,

  // Optional: Set the target minimum capacity for automatic depth calculation
  // Lower values result in finer subdivisions (higher depth)
  targetMinCapacity: 0.5,
})
```

By default, the solver will automatically calculate the optimal `capacityDepth` to achieve a target minimum capacity of 0.5 based on the board dimensions. This automatic calculation ensures that the smallest subdivision cells have an appropriate capacity for routing.

### Visualization Support

For debugging or interactive applications, you can use the `visualize()` method to get a visualization of the current routing state:

```typescript
// Get visualization data that can be rendered with graphics-debug
const visualization = solver.visualize()
```

## Development

To work on this library:

```bash
# Install dependencies
bun install

# Start the interactive development environment
bun run start

# Run tests
bun test

# Build the library
bun run build
```