From bdfce09db9e44cc9a937fd56112e1f8c16060e46 Mon Sep 17 00:00:00 2001
From: Twinkle-3000 <hui.zhou.a@icloud.com>
Date: Wed, 11 Nov 2026 23:08:28 +0100
Subject: [PATCH] docs: rewrite README quickstart

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 README.md | 189 ++++++++++++++++++------------------------------------
 1 file changed, 62 insertions(+), 127 deletions(-)

diff --git a/README.md b/README.md
index 9669c9c..11f5a9b 100644
--- a/README.md
+++ b/README.md
@@ -1,127 +1,62 @@
-# edb-layout-viewer
-
-**Explore Ansys EDB layouts in an interactive Qt viewer.**
-
-Open an existing design to inspect its traces, polygons, padstacks, and
-components.
-
-## Install
-
-Requires Python 3.13 or newer. Install the package and its runtime dependencies
-from this repository:
-
-```bash
-python -m pip install "git+https://github.com/OpenEngiTools/edb-layout-viewer.git"
-```
-
-Opening a design also requires a usable Ansys EDB runtime.
-
-## Use
-
-Open an `.aedb` design from the command line:
-
-```bash
-edb-layout-viewer path/to/my_design.aedb
-```
-
-You can also select the design's `edb.def` file in a dialog by omitting the
-path:
-
-```bash
-edb-layout-viewer
-```
-
-Use `--help` to see all options. For example, filter the displayed layout by
-layer and net, specify an EDB version, or enable automatic refresh after
-supported geometry edits:
-
-```bash
-edb-layout-viewer path/to/my_design.aedb --edbversion 2025.1 --layers TOP BOTTOM --nets VCC GND --live
-```
-
-Automatic refresh is disabled by default. Rendering backend can be selected
-with `--backend auto`, `--backend vulkan`, `--backend d3d11`, or
-`--backend metal`.
-
-The viewer can also be launched from Python when you already have a PyEDB
-session:
-
-```python
-from pyedb import Edb
-from edb_layout_viewer import launch_viewer
-
-edb = Edb("my_design.aedb", edbversion="2025.1")
-launch_viewer(edb)
-```
-
-The adapter converts EDB layout data into the viewer's detached `LayoutScene`
-model and can apply incremental updates from PyEDB's layout-change stream.
-
-## Architecture
-
-```text
-PyEDB
-  EDB layout data and change events
-          │
-          ▼
-edb-layout-viewer
-  capture, filtering, and geometry conversion
-          │
-          ▼
-LayoutScene
-  detached scene-data boundary
-          │
-          ▼
-layout-viewer-core
-  Qt/RHI viewer
-```
-
-The adapter owns scene capture and conversion; `layout-viewer-core` owns
-rendering. The scene is detached from the EDB session, whose lifetime remains
-the caller's responsibility. Importing `edb_layout_viewer` does not load Qt;
-Qt is loaded when the viewer is launched.
-
-## Development setup
-
-The project requires Python 3.13 or newer and `uv`. For local development,
-check out `layout_viewer_core` beside this repository:
-
-```text
-OpenEngiTools/
-├── edb-layout-viewer/
-└── layout_viewer_core/
-```
-
-From the repository root, synchronize the project and its development
-dependencies:
-
-```bash
-uv sync --extra dev
-```
-
-## Development checks
-
-Run the test suite, lint and formatting checks, and package build with:
-
-```bash
-uv run --extra dev pytest
-uv run --extra dev ruff check
-uv run --extra dev ruff format --check
-uv run --extra dev python -m build
-```
-
-The EDB integration test uses the bundled fixture and is skipped when an AEDT
-runtime is unavailable. Interactive rendering should also be smoke-tested with
-a usable Qt/RHI runtime.
-
-## Further documentation
-
-- [Implementation](IMPLEMENTATION.md) — package structure, data flows, and
-  design boundaries.
-- [Contributing](CONTRIBUTING.md) — supported environments, checks, and
-  release guidance.
-- [Changelog](CHANGELOG.md) — project changes.
-
-## License
-
-Apache-2.0. See [LICENSE](LICENSE).
+# EDB Layout Viewer
+
+EDB Layout Viewer is a Python application for interactively viewing Ansys EDB
+printed-circuit-board designs. It displays layout geometry such as traces,
+polygons, padstacks, and components.
+
+## Quickstart
+
+Requires Python 3.13 or newer. Opening a design also requires a usable Ansys
+EDB runtime and a desktop environment supported by Qt.
+
+### Install
+
+Install the viewer and its dependencies from this repository:
+
+```bash
+python -m pip install "git+https://github.com/OpenEngiTools/edb-layout-viewer.git"
+```
+
+### Run from the command line
+
+Pass the path to an `.aedb` design directory:
+
+```bash
+edb-layout-viewer path/to/my_design.aedb
+```
+
+You can also run the viewer without a path and select the design's `edb.def`
+file in the dialog:
+
+```bash
+edb-layout-viewer
+```
+
+Use `edb-layout-viewer --help` to see options, including filters for layers
+and nets.
+
+### Run from a Python IDE
+
+Install the package into the Python interpreter configured in your IDE. Create
+a Python file, update the design path, and run it:
+
+```python
+from pyedb import Edb
+from edb_layout_viewer import launch_viewer
+
+edb = Edb("path/to/my_design.aedb")
+launch_viewer(edb, block=True)
+```
+
+The `Edb` session remains under your script's control while the viewer is
+open.
+
+## More information
+
+- [Contributing](CONTRIBUTING.md)
+- [Implementation](IMPLEMENTATION.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).