Skip to content

docs: document SRJ export behavior and trace-width limitations #1023

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rushabhcodes wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document SRJ export behavior and trace-width limitations #1023

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions docs/command-line/tsci-export.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ The following export formats are supported:
|--------|-------------|
| `json` | Circuit JSON format (alias for `circuit-json`) |
| `circuit-json`| Circuit JSON format |
| `srj` | Simple Route JSON for inspecting or sharing PCB routing input |
| `schematic-svg` | Schematic view as SVG |
| `pcb-svg` | PCB layout as SVG |
| `pcb-png` | PCB layout as PNG |
Expand Down Expand Up @@ -101,6 +102,60 @@ Export selected nets across all copper layers (PCB SVG or PNG only):
tsci export board.tsx -f pcb-png --x-ray-net GND --x-ray-net VCC --hidden-layer-opacity 0.2 -o power.png
```

## Exporting Simple Route JSON

Use `srj` to inspect a PCB routing problem or provide input to an external
autorouter. Simple Route JSON contains board bounds, layers, obstacles, and
connections. It can also include fixed copper routes from child subcircuits.

```bash
tsci export circuit.tsx -f srj -o routing-input.simple-route.json
```

You can also convert an existing Circuit JSON file:

```bash
tsci export circuit.circuit.json -f srj -o routing-input.simple-route.json
```

### Trace widths

Exported widths are in millimeters. The [board trace-width settings](../elements/board.mdx#controlling-trace-width)
have different purposes:

| Setting | Meaning |
|---------|---------|
| `minTraceWidth` | Minimum width requested by the board's routing rules |
| `defaultTraceWidth` / `nominalTraceWidth` | Preferred board width when a connection has no more specific width |
| `connections[].nominalTraceWidth` | Preferred width for an individual SRJ connection |

For example, a board with `minTraceWidth="0.1mm"` and
`defaultTraceWidth="0.35mm"` should give an otherwise unspecified connection a
nominal width of `0.35`, while keeping the SRJ minimum at `0.1`. An explicit
`thickness="0.55mm"` on a trace should take precedence over the board default.
Check both `nominalTraceWidth` and `width` on the exported connections.

### Current export limitations

TSX SRJ export currently uses the full circuit build path. A cold export can run
autorouting before writing the file, and a cached build can supply already-routed
data. Completed routing can leave fewer connections in the SRJ than the original
routing problem.

Regenerating SRJ from Circuit JSON can also lose the board's preferred trace
width and fill unspecified connection widths from `minTraceWidth`. The intended
width distinction above is therefore something to verify in the exported file.

Exporting an existing `.circuit.json` file skips TSX evaluation, but uses the
route state and width metadata already stored in that file. It cannot recover a
board default that was not serialized.

When reporting an SRJ export problem in [tscircuit/cli](https://github.com/tscircuit/cli/issues),
include the CLI and core versions, the export command, whether a full build was
already cached, and the expected connection count and widths. A small circuit
with different minimum, default, and explicit trace widths helps isolate width
loss from routing behavior.

## Exporting 3D models

Use the `gltf`, `glb`, or `step` formats when you want a 3D representation of your board for use in CAD tools, AR viewers, or when embedding on the web.
Expand Down
Loading