circuitjson-bookshelf-converter
Converts Circuit JSON PCB and schematic designs into Bookshelf physical design format (.nodes, .nets, .pl, .scl, .aux) with courtyard keep-out boundary modeling, and back-annotates Cypress placement optimization results back into Circuit JSON. Trigger this skill whenever converting circuit.json files to Bookshelf format or back-annotating .pl / .gp.pl placement outputs into Circuit JSON.
- License 许可
- GPL-2.0
- 最近更新
- 2026-08-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- circuitjson-bookshelf-converter
- description
- Converts Circuit JSON PCB and schematic designs into Bookshelf physical design format (.nodes, .nets, .pl, .scl, .aux) with courtyard keep-out boundary modeling, and back-annotates Cypress placement optimization results back into Circuit JSON. Trigger this skill whenever converting circuit.json files to Bookshelf format or back-annotating .pl / .gp.pl placement outputs into Circuit JSON.
02 资源文件 2
- 参考文档references/transformation_matrices.md7.9 KB
- 脚本tools/matrix_converter.py30.4 KB
03 SKILL.md 正文
Circuit JSON <-> Bookshelf Converter Skill
This skill provides step-by-step guidance, mathematical conversion rules, and deterministic CLI/Python tools for translating Circuit JSON designs into the Bookshelf format (.aux, .nodes, .nets, .pl, .scl) required by the Cypress placement engine, and back-annotating global placement results (.gp.pl) into updated circuit.json files.
1. Operational Knowledge
The core matrix conversion engine is located in tools/matrix_converter.py.
Command Line Interface (CLI) Commands
1. Forward Conversion (Circuit JSON $\longrightarrow$ Bookshelf PCB)
Converts a Circuit JSON file into a set of Bookshelf files using courtyard keep-out boundary extraction and coordinate normalization.
python3 tools/matrix_converter.py to_bookshelf_pcb <circuit_json_path> <output_dir> [design_name]
2. Back-Annotation (Bookshelf Placement $\longrightarrow$ Circuit JSON PCB)
Back-annotates global placement coordinates (.gp.pl or .pl) back into an updated circuit.json file.
python3 tools/matrix_converter.py from_bookshelf_pcb <original_json_path> <pl_file_path> <output_json_path>
3. Schematic Domain Conversions
# Forward Schematic Conversion
python3 tools/matrix_converter.py to_bookshelf_schematic <circuit_json_path> <output_dir> [design_name]
# Reverse Schematic Back-Annotation
python3 tools/matrix_converter.py from_bookshelf_schematic <original_json_path> <pl_file_path> <output_json_path>
4. Board Preview Rendering
Renders a 2D visualization (PNG) of component layout boundaries against board dimensions.
python3 tools/matrix_converter.py render <circuit_json_path> <output_png_path>
Python API Usage
To integrate the converter directly inside Python automation pipelines:
from tools.matrix_converter import CircuitJSONMatrixConverter
# Initialize converter with scale=1000.0 (mm to um)
converter = CircuitJSONMatrixConverter(scale=1000.0)
# 1. Forward Conversion to Bookshelf
aux_file_path = converter.to_bookshelf_pcb(
circuit_json_path="bms_project/power_circuit/circuit.json",
output_dir="/tmp/bookshelf_out",
design_name="power_circuit"
)
# 2. Back-annotate placement output into updated Circuit JSON
converter.from_bookshelf_pcb(
original_json_path="bms_project/power_circuit/circuit.json",
pl_path="/tmp/bookshelf_out/power_circuit.gp.pl",
output_path="/tmp/updated_circuit.json"
)
2. Reasoning Guidance
Deep Transformation & Coordinate Modeling Reference
For mathematical details regarding forward coordinate normalization, un-rotation formulas, courtyard bounding box offset calculations ($\Delta \mathbf{c}$), and inverse matrix back-annotations, refer to references/transformation_matrices.md.
Conversion Rules & Decision Guidance
- Courtyard Keep-out Modeling: Component nodes in
.nodesmust reflect full courtyard keep-out bounding boxes ($\theta = 0^\circ$) rather than nominal package body sizes to prevent physical overlap during placement. - Courtyard Center Offset Recalibration: When component origins differ from courtyard geometric centers, pin offsets in
.netsmust be offset by $\Delta \mathbf{c}$ to maintain exact net topology. - Child Element Shift Propagation: During back-annotation, coordinate displacements $(\Delta x, \Delta y)$ applied to
pcb_componentmust be recursively applied to all child elements (pcb_smtpad,pcb_courtyard_*,pcb_silkscreen_*,pcb_port,cad_component).
3. Workflow Instructions
- Step 1: Execute Forward Conversion
Runpython3 tools/matrix_converter.py to_bookshelf_pcbto create Bookshelf artifacts (.nodes,.nets,.pl,.scl,.aux). - Step 2: External Optimization Engine Run
Pass the generated.auxfile to Cypress / DREAMPlace placement solver. - Step 3: Execute Back-Annotation
Runpython3 tools/matrix_converter.py from_bookshelf_pcbwith the solver output.gp.plfile to update thecircuit.json. - Step 4: Layout Preview & Verification
Generate board render image usingtools/matrix_converter.py renderto inspect spatial layout visually.
4. Verification
Perform this verification checklist to confirm valid conversion and back-annotation:
- Board Outline Existence: Confirm the input
circuit.jsoncontains a validpcb_boardobject with positivewidthandheight. - Bounding Box Dimension Verification: Inspect
<design_name>.nodesto verify multi-pin ICs reflect actual courtyard keep-out boundaries rather than body boundaries. - Non-Negative Coordinate Check: Confirm all initial coordinates in
<design_name>.plare non-negative database units within board bounds $[0, S \cdot W_{\text{board}}]$. - DRC Overlap Verification: Run
python3 tools/analyze_circuit.py <output_json_path>on back-annotated JSON to verify component placement overlap errors are resolved.
04 同仓库更多 Skills
cypress-tuning
Systematically diagnoses, tunes, and executes Cypress GPU-accelerated PCB placement optimization runs. Trigger when running DREAMPlace/Cypress component placement, diagnosing placement divergence or clumping, or tuning wirelength, density, rotation, and net crossing parameters.
circuit-json-analysis
Analyzes Circuit JSON files for structural component relationships, domain mappings (source, schematic, pcb, cad), and geometric layout DRC violations (courtyard overlaps, solder paste misalignments, pad clearances). Trigger this skill whenever analyzing a circuit.json file, inspecting PCB placement, or performing design rule checks on Circuit JSON data.
vhl-concepts
Architectural foundation for Virtual Hardware Laboratory (VHL). Explains the four fundamental VHL concepts (Module vs Assembly, Interface Boundary, Git Worktree Workspace Isolation, and Shared Circuit Understanding Document), why VHL uses them, their core invariants, and when an agent must reason about them. Trigger this skill whenever reasoning about VHL architecture, defining boundaries, identifying module/assembly scope, or referencing SCUD artifacts.
SCUD
暂无简介
Module_Synthesis
暂无简介
Boundary_Reconciliation
暂无简介