Open-source IC layout and schematic database
Binary .room files · Cap'n Proto · C++17 · Python

C++ API docs · Python API docs

---

ROOM — Reusable Open Object Model — is an open-source IC design database and C++ API (room::) aimed at production quality: libraries, cells, layers, shapes, instances, and nets with portable .room serialization. Layout and schematic data share one model; the view kind (layout, schematic, symbol, abstract) lives in CellContent.

See docs/PRODUCTION_ROADMAP.md for the path from the current MVP to v1.

The project is part of the IHP open-source IC design flow. Design data is kept in a format-neutral internal model and serialized to portable binary .room files via Cap'n Proto, so tools can load, edit, and save the same representation without tying the database to a single exchange format.

This repository is maintained with commits/checkins only from the project owner. After clone, run scripts\setup-githooks.cmd (Windows) or ./scripts/setup-githooks.sh (Linux/macOS) once so git hooks strip accidental Cursor co-author trailers from commit messages.

Data model

On disk (.room, format v1.0): geometry lives in CellContent.payload, not in a top-level block field.

Database
 └── Lib
      ├── layers[]              ← LayerSpec table (library-global)
      ├── index                 ← LibIndex (derived hierarchy + bboxes, persisted)
      └── Cell[]                ← name, aliases[], optional PCellInfo
           └── CellContent[]     ← viewType, dbuPerMicron, dbuPerEditorUnit, properties, layers[] (per-view)
                └── payload      ← ViewPayload (Cap'n Proto union)
                     ├── layout | schematic | symbol | abstract
                     │    ├── layers[]   (per-view layer table on disk)
                     │    ├── block      (verbose geometry, opt-in)
                     │    └── compact    (layer-grouped geometry, default on save)
                     ├── emModel        (EM publish: snp/ports/setup snapshot refs)
                     └── opaque         (skip-friendly unknown views)

C++ API: CellContent::block() is the in-memory accessor for topology; CellContent::layers() holds the per-view layer table (LayerSpec + LayerPurpose). Layout coordinates use dbuPerMicron; schematic/symbol coordinates use dbuPerEditorUnit (see Coordinate scale). Cell::aliases() and Cell::pCell() cover PDK cell identity. On save, compact encoding is the default (SaveOptions::compactGeometry); load auto-detects compact vs block. See docs/COMPACT_ENCODING.md and docs/SCHEMA_EVOLUTION.md.

Requirements

Tool	Notes
CMake ≥ 3.16	Configure and build
C++17 compiler	MinGW-w64 (Windows), GCC or Clang (Linux)
Git	Clones Cap'n Proto on first configure (if needed)
Cap'n Proto	Built automatically into third_party/capnp-install/ by CMake

On Windows, the repo’s VS Code tasks assume Qt MinGW 8.1 (C:/Qt/Tools/mingw810_64). Adjust compiler paths if you use another toolchain.

Build

On the first cmake configure, ROOM builds Cap'n Proto into third_party/capnp-install/ automatically if it is not already there (option ROOM_BOOTSTRAP_CAPNP=ON, default). That step can take several minutes; later configures are instant.

To build Cap'n Proto by hand (optional), see third_party/README.md.

Configure and compile

Windows (command line, MinGW Makefiles):

cmake -S . -B build -G "MinGW Makefiles" ^
  -DCMAKE_BUILD_TYPE=Debug ^
  -DCMAKE_C_COMPILER=C:/Qt/Tools/mingw810_64/bin/gcc.exe ^
  -DCMAKE_CXX_COMPILER=C:/Qt/Tools/mingw810_64/bin/g++.exe ^
  -DCMAKE_MAKE_PROGRAM=C:/Qt/Tools/mingw810_64/bin/mingw32-make.exe

cmake --build build -j4

Linux:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

VS Code

Open the folder in VS Code (CMake Tools extension recommended):

1. CMake: Configure Debug — configures ROOM and bootstraps Cap'n Proto if needed
2. Build: Static Libraries (.a) — room, room_utils
3. Build: All Targets — adds gds_to_room, qucs_to_room, make_sample_gds
4. Example: GDS to ROOM / Example: Qucs to ROOM — run demos after a full build

Default build task: Build: Static Libraries (.a) (Ctrl+Shift+B may need to be bound to that task).

Python bindings

ROOM ships a ctypes package (import room) plus CLI (room / python -m room) on top of a small C API shared library (room_c).

Useful defaults in the Python API:

• room.open("path with spaces") — path is trimmed; quotes around the path are stripped
• cell.content() / cell.contents() — with no view name, returns the first available view (not always LAYOUT)

Full reference: Python API docs (same site as the C++ docs).

pip install (from this repo)

pip install ./python
room info path\to\design.room

Editable:

pip install -e ./python[test]
python -m pytest python\tests -q

On Windows use 64-bit MinGW (C:\msys64\mingw64) on PATH so the first install can build room_c. PyPI wheels are not published yet.

Manual CMake build

scripts\run_python_tests.cmd

Or:

cmake -S . -B build-python -G "MinGW Makefiles" ^
  -DCMAKE_BUILD_TYPE=Release ^
  -DCMAKE_CXX_COMPILER=C:/msys64/mingw64/bin/g++.exe ^
  -DCMAKE_MAKE_PROGRAM=C:/msys64/mingw64/bin/mingw32-make.exe ^
  -DROOM_BUILD_PYTHON=ON -DROOM_BUILD_EXAMPLES=OFF -DROOM_BUILD_TESTS=OFF
cmake --build build-python --target room_c -j

import room

db = room.open("design.room")
print(db.cell_names())

with room.create() as db:
    cell = db.get_or_create_cell("INVX1")
    layout = cell.ensure_content("layout")
    layout.add_rect(0, 0, 0, 100, 200)
    db.save("out.room")

See python/README.md. Disable with -DROOM_BUILD_PYTHON=OFF.

Tests and code coverage

Tests are built when ROOM_BUILD_TESTS=ON (default). Run them with CTest:

ctest --test-dir build --output-on-failure

Code coverage (GCC/MinGW + gcovr), same workflow as LibMan:

Windows:

pip install gcovr
scripts\run_tests_coverage.cmd

Linux:

pip install gcovr
./scripts/run_tests_coverage.sh

The script configures build-coverage/ with -DROOM_ENABLE_COVERAGE=ON, runs all CTest suites, and writes coverage.html in the repo root (Windows opens it in the browser). After tests, you can also regenerate the report from an existing coverage build:

cmake --build build-coverage --target coverage-report

CI runs ./scripts/run_tests_coverage.sh in the Coverage (Ubuntu) job (after Tests pass) and uploads coverage.html (+ detail pages) as the room-coverage-html artifact. Windows has no coverage job yet (gcovr targets GCC/MinGW only).

Build outputs

Target	Type	Description
room	static library	Database API + Cap'n Proto serialization
room_utils	static library	GDS / Qucs importers, text dump
room_c	shared library	C API for Python (import room / python -m room)
gds_to_room	executable	GDSII → .room
qucs_to_room	executable	Qucs .sch → .room (round-trip export)
xschem_to_room	executable	Xschem .sch/.sym → .room
room_to_xschem	executable	.room → Xschem files
room_file_sniff	test tool	Import + sniffRoomFile() smoke test
make_sample_gds	executable	Minimal sample GDS for tests

Install headers and libraries into a prefix:

cmake --install build --prefix install

Use find_package(ROOM) from another CMake project via install/lib/cmake/ROOM/.

Examples

GDS layout import

Bundled demo (no arguments — uses examples/gds_to_room/data/sg13g2_stdcell.gds):

build\gds_to_room.exe

Custom paths:

build\gds_to_room.exe input.gds output\layout.room output\layout.txt CELL_NAME

Optional flags: --all-cells (one .room per GDS cell), --dump (write a text dump next to the .room — do not stream huge dumps to the console).

Qucs schematic import

build\qucs_to_room.exe examples\qucs_to_room\data\rc_lowpass.sch examples\qucs_to_room\output\schematic.room

Xschem schematic / symbol import

build\xschem_to_room.exe examples\xschem_to_room\data\test.sch examples\xschem_to_room\output\test.schematic.room

Sniff a .room file (metadata only)

#include "file_summary.h"
room::RoomFileInfo info = room::sniffRoomFile("cell.schematic.room");

See docs/SNIFF.md and docs/ROOM_FILE_NAMING.md. HTML API: File summary / sniff.

Minimal GDS

build\make_sample_gds.exe testdata\sample.gds
build\gds_to_room.exe testdata\sample.gds output\sample.room

KLayout integration

ROOM ships a KLayout streamer plugin (mroom) that opens and saves .room files directly in KLayout — no GDS round-trip for viewing.

Full guide	integrations/klayout/README.md
What it does	Read/write .room in KLayout; maps shapes, instances, cells, lib name, and properties
Build model	CommonDB sources are compiled into db_plugins/mroom.dll inside a KLayout tree (junction + streamers.pro patch)
Quick setup	scripts\setup_klayout_mroom.cmd C:\path\to\KLayout then rebuild KLayout
Smoke tests	klayout -b -r scripts\test_room_load.rb (set COMMONDB_ROOT to repo root)
Bridge (no plugin yet)	scripts\open_room_in_klayout.cmd or macro scripts\klayout_load_room.lym via room_to_gds

Documentation

HTML API reference · sources in docs/html/ (also usable offline after clone).

Design docs: PRODUCTION_ROADMAP.md · DESIGN_CHARTER.md · SCHEMA_EVOLUTION.md · COMPACT_ENCODING.md · SNIFF.md · ROOM_FILE_NAMING.md · KLayout plugin

Project layout

Path	Purpose
src/	Core C++ API (Database, Cell, Shape, …)
schema/	Cap'n Proto schemas (.capnp)
utils/	GdsImporter, QucsImporter, QucsExporter, XschemImporter, XschemExporter, xschem_bridge, TextDumper
examples/gds_to_room/	GDS import example + sample data
examples/qucs_to_room/	Qucs import example + sample .sch
examples/xschem_to_room/	Xschem import example + sample .sch
integrations/klayout/	KLayout mroom streamer plugin (read/write .room)
third_party/capnp-install/	Cap'n Proto compiler and libraries
scripts/mkcapnp.cmd	Build Cap'n Proto on Windows
docs/html/	Documentation and logo.svg
LICENSE	GNU GPL v3.0

License

ROOM is licensed under the GNU General Public License v3.0. See LICENSE for the full text.