Document installation and CLI usage

README.md

@@ -1,24 +1,50 @@
 # edb-layout-viewer
 
-EDB → layout-viewer-core scene adapter.
+**Explore Ansys EDB layouts in an interactive Qt viewer.**
 
-This package bridges PyEDB gRPC layout data and the
-Qt/RHI `layout-viewer-core` frontend. It converts EDB geometry (traces, polygons, padstacks,
-components) into the detached `layout_viewer_core.scene.LayoutScene` representation, and
-subscribes to PyEDB's layout-change event stream (`pyedb.grpc.database.layout_changes`)
-to support live, incremental viewer updates.
+Open an existing design to inspect its traces, polygons, padstacks, and
+components.
 
-Importing `edb_layout_viewer` does not load Qt; only `launch_viewer()` does, and it raises
-an actionable `ImportError` if `layout-viewer-core` is not installed.
+## Install
 
-## Installation
+Requires Python 3.13 or newer. Install the package and its runtime dependencies
+from this repository:
 
 ```bash
-python -m pip install -e ../layout_viewer_core
-python -m pip install -e ".[dev]"
+python -m pip install "git+https://github.com/OpenEngiTools/edb-layout-viewer.git"
 ```
 
-## Usage
+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
@@ -28,36 +54,74 @@ edb = Edb("my_design.aedb", edbversion="2025.1")
 launch_viewer(edb)
 ```
 
-### Command line
+The adapter converts EDB layout data into the viewer's detached `LayoutScene`
+model and can apply incremental updates from PyEDB's layout-change stream.
 
-After installation, open a design directly from the shell:
+## Architecture
 
-```bash
-edb-layout-viewer my_design.aedb --edbversion 2025.1 --layers TOP BOTTOM --nets VCC GND
-python -m edb_layout_viewer my_design.aedb
+```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
 ```
 
-Omit the design path to open a file dialog and select the design's `edb.def` file:
+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
-edb-layout-viewer
-python -m edb_layout_viewer
+uv sync --extra dev
 ```
 
-The viewer opens the selected file's containing directory. Cancelling the dialog
-exits without opening an EDB session.
+## Development checks
 
-Run `edb-layout-viewer --help` for all options (`--backend`, `--debug`, `--live [true|false]`, default false).
+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
+```
 
-## Implementation
+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.
 
-See [IMPLEMENTATION.md](IMPLEMENTATION.md) for the package structure, capture
-and update flows, error behavior, and development checks.
+## Further documentation
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, supported
-environments, checks, and release guidance. Changes are recorded in
-[CHANGELOG.md](CHANGELOG.md).
+- [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`.
+Apache-2.0. See [LICENSE](LICENSE).