Metadata-Version: 2.4
Name: kwasm
Version: 0.2.5
Summary: Standalone web-based layout viewer using KLayout
License-Expression: GPL-3.0
Requires-Python: ~=3.12.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Dynamic: license-file

# kwasm

Standalone wasm-based client-only layout viewer for semiconductor designs, powered by
[KLayout](https://www.klayout.org).

kwasm compiles KLayout's layout rendering engine to WebAssembly via Emscripten, wrapped
in a Rust FFI layer. The result is an interactive GDS2/OASIS viewer that runs entirely
in the browser — no install required.

## Features

- View GDS2 and OASIS layout files in the browser
- Pan, zoom, select, measure, and draw annotations
- Layer panel with per-layer visibility toggling and color display
- Toolbar with switchable interaction modes
- Dark and light theme
- Load layouts via drag & drop or `?url=` query parameter
- Configurable toolbar via `?tools=` query parameter
- Python package with embeddable Jupyter viewer
- CLI for bundling layouts into self-contained HTML files

## Quick Start

```bash
# Build all WASM artifacts
just build

# Build docs site and serve at http://localhost:8080
just serve
```

## Available Commands

| Command                    | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `just build [mode]`        | Build WASM artifacts (`all` by default)                |
| `just dev [mode]`          | Copy bundled HTML from `dist/` into the Python package |
| `just wheel`               | Build Python wheel                                     |
| `just dist`                | Build everything (WASM + wheel)                        |
| `just check [mode]`        | Check WASM compilation (no link)                       |
| `just docs [mode]`         | Build versioned documentation pages in `site/`         |
| `just serve [mode] [port]` | Build docs and serve                                   |
| `just clean`               | Clean build artifacts                                  |

## Query Parameters

| Parameter  | Description                                                                    |
| ---------- | ------------------------------------------------------------------------------ |
| `?url=`    | Load a layout file from a URL (e.g. `?url=https://example.com/chip.gds`)       |
| `?tools=`  | Comma-separated list of toolbar tools to show. All tools are shown by default. |
| `?lyp=`    | Load a .lyp layer properties file from a URL (e.g. `?lyp=layers.lyp`)          |
| `?drop=`   | Enable/disable drag & drop (`true`/`false`). Default: `true`.                  |
| `?layers=` | Show/hide the layer panel (`true`/`false`). Default: `true`.                   |

Available tool names for `?tools=`:

| Name             | Description                   |
| ---------------- | ----------------------------- |
| `select`         | Pointer/select mode           |
| `move`           | Pan mode                      |
| `ruler`          | Ruler/measure mode            |
| `draw-polyline`  | Draw polyline annotations     |
| `draw-manhattan` | Draw manhattan route          |
| `draw-freehand`  | Draw freehand annotations     |
| `clear-all`      | Erase all annotations         |
| `fit-all`        | Zoom to fit layout            |
| `reload`         | Reload layout                 |
| `top-ports`      | Toggle top-level port markers |
| `instance-ports` | Toggle instance port markers  |
| `dangling-ports` | Toggle dangling port markers  |
| `text`           | Toggle text labels            |
| `theme`          | Light/dark mode toggle        |

Example: `?tools=ruler,top-ports,instance-ports` shows only the ruler, top-level ports, and instance ports buttons.

## Python Package

kwasm is available as a Python package that bundles the WASM viewer:

```bash
pip install kwasm
```

### Jupyter Notebook

```python
import kwasm

kwasm.show("my_chip.gds")
kwasm.show("my_chip.gds", lyp="layers.lyp", tools=("ruler", "fit-all"))
```

When used with [gdsfactory](https://github.com/gdsfactory/gdsfactory), you can pass components directly:

```python
import gdsfactory as gf
import kwasm

c = gf.components.mzi()
kwasm.show(c)
```

### CLI

```bash
# Bundle a GDS into a self-contained HTML file
kwasm bundle my_chip.gds --output viewer.html --lyp layers.lyp

# Bundle and open in the default browser
kwasm view my_chip.gds
```

## License

[GPL-3.0](LICENSE)
