gridquill 0.1.1__tar.gz

gridquill-0.1.1/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 — 2026-10-26
+
+Initial extraction of the Gridquill diagram library, examples and regression tests.

gridquill-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rpeschke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gridquill-0.1.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md CHANGELOG.md LICENSE
+recursive-include examples *.py
+recursive-include tests *.py

gridquill-0.1.1/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: gridquill
+Version: 0.1.1
+Summary: Reactive grid-based diagrams with nested canvases and editable Excalidraw output
+License-Expression: MIT
+Keywords: diagrams,excalidraw,reactive,grid,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: setuptools>=77.0.3; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# Gridquill
+
+Build editable diagrams in Python using reactive coordinates, nested canvases,
+elements, signals, captions and connectors. Export to `.excalidraw` for Excalidraw
+or `.excalidraw.md` for Obsidian. Python 3.10+; no runtime dependencies.
+
+## Install from this checkout
+
+```console
+python -m pip install -e .
+```
+
+The package is prepared for PyPI but has not been published.
+
+## Draw a diagram
+
+```python
+import gridquill as gq
+
+gq.set_color_scheme(
+    element_color=0x1971C2, element_fill=0xA5D8FF,
+    signal_color=0xF08C00, signal_fill=0xFFEC99,
+)
+
+with gq.canvas("Example") as diagram:
+    with gq.canvas("Acquisition", column=2, row=1,
+                   background=0xEDF2FF, margin_left=20, margin_right=20,
+                   margin_top=20, margin_bottom=20):
+        adc = gq.element("ADC", column=0, top=0, length=4)
+        fpga = gq.element("FPGA", column=4, top=0, length=4)
+        samples = gq.signal("Samples", row=adc.port(2), components=[adc])
+        samples.components.append(fpga)
+        gq.connector(fpga, samples, inout="in")
+        gq.caption("Acquisition", row=-1, column=0)
+
+diagram.save("example.excalidraw.md")
+```
+
+## Coordinates and ownership
+
+Literal coordinates are local to their canvas. On save, coordinate references
+resolve to positions in the drawing, including all parent offsets. A captured
+reference such as `fpga.column` follows later moves and assignments. Sizes and
+lengths are distances; coordinate formulas return drawing coordinates.
+
+```python
+fpga.column = lambda: adc.column + 5
+diagram.resolve()  # resolve without writing a file
+```
+
+Geometry fields and span entries accept numbers, reactive arithmetic or
+zero-argument functions. Each save evaluates them in passes. Pending dependencies
+read as NaN; stalled resolution raises `ReactiveResolutionError` naming the
+unresolved fields. Functions must be pure. `float(value)` reads a snapshot of the
+last resolved value. Failed resolution leaves an existing output file untouched.
+
+Creating a canvas opens it. Subsequent objects attach automatically; `pop()`
+returns to the previous canvas. `with canvas(...)` restores the previous scope
+on exit. Use `canvas(activate=False)` for explicit ownership and `append()`.
+
+## Objects
+
+- `element(label, column=..., top=..., bottom=... / length=...)`: vertical box.
+  Alternatively use `span=[top, bottom]`. `element.port(index)` returns a reactive
+  row, with 0.5 grid-unit spacing; negative indices count from the bottom.
+- `signal(label, row=..., left=..., right=... / length=...)`: horizontal box.
+  Alternatively use `span=[left, right]` or a mutable `components` list whose
+  outermost columns are connected. Endpoint formulas are prepared at save time.
+- `caption(label, row=..., column=..., fill=..., length=...)`: automatically sized
+  label box; omit `length` to fit the text on each save.
+- `connector(element_or_column, signal_or_row, position="auto", inout="out")`:
+  chevron marker. With a signal, the default chooses `left` or `right` when its
+  span lies entirely on that side of the element's column, including a signal
+  ending at the element. The side and arrow direction follow layout changes on
+  every save. A signal crossing both sides, or a numeric row, defaults to `left`.
+  Set `position="left"` or `"right"` to override. Flow is `in`, `out` or `inout`.
+- `chevron(...)`: individual direction stencil.
+- `canvas(...)`: group with an optional background, border style and per-side
+  margins in pixels. Bounds follow its members automatically.
+
+Default grid size is 80 pixels. `set_color_scheme()` changes global defaults;
+explicit object colors take precedence. Assign `None` to inherit again.
+`get_color_scheme()` returns a copy; `reset_color_scheme()` restores defaults.
+
+`draw_diagram()` provides the lower-level renderer. To normalize existing
+drawings, run `gridquill-normalize drawing.excalidraw.md` (edits the input file).
+
+## Drawing order
+
+Set `z_index` to control overlaps. Higher values appear in front, and each box
+and its label stay together:
+
+```python
+with gq.canvas() as diagram:
+    block = gq.element("FPGA", column=2, span=[0, 4])
+    bus = gq.signal("Bus", row=2, span=[0, 4], z_index=1)
+
+bus.z_index = 2  # editable after creation; applied on the next save
+diagram.save("layers.excalidraw")
+```
+
+Signals, elements, chevrons, captions, connectors and canvases accept `z_index`
+(default `0`). Negative and fractional values are allowed, as are reactive
+formulas. A canvas adds its `z_index` to its descendants' values, so a connector
+or a nested canvas can shift all its members together. Layers compare across
+canvas boundaries. Canvas backgrounds remain behind all drawing objects.
+
+Equal values preserve the existing order: signals (including captions), then
+elements, then chevrons, in traversal order within each kind. Existing diagrams
+therefore keep their drawing order. For `draw_diagram()`, set `z_index` in each
+horizontal or vertical item dictionary; connection arrows remain behind boxes.
+
+## Examples and development
+
+```console
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests
+python examples/canvas_scope_example.py
+python examples/recreate_udt_overview.py --output overview.excalidraw.md
+python -m build
+python -m twine check dist/*
+```
+
+Source lives in `src/gridquill`; tests and runnable examples live in `tests` and
+`examples`. The firmware-specific CSV layout exporter remains in the firmware
+repository because it depends on the separate `fmake` toolchain.
+
+## Publishing
+
+Add author details and actual project URLs to `pyproject.toml`.
+Set `__version__` in `src/gridquill/__init__.py` for a release.
+Build and validate the distributions using the commands above. When ready,
+upload explicitly with `python -m twine upload dist/*` using your PyPI account.
+No publishing credentials or upload automation are included.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

gridquill-0.1.1/README.md

@@ -0,0 +1,138 @@
+# Gridquill
+
+Build editable diagrams in Python using reactive coordinates, nested canvases,
+elements, signals, captions and connectors. Export to `.excalidraw` for Excalidraw
+or `.excalidraw.md` for Obsidian. Python 3.10+; no runtime dependencies.
+
+## Install from this checkout
+
+```console
+python -m pip install -e .
+```
+
+The package is prepared for PyPI but has not been published.
+
+## Draw a diagram
+
+```python
+import gridquill as gq
+
+gq.set_color_scheme(
+    element_color=0x1971C2, element_fill=0xA5D8FF,
+    signal_color=0xF08C00, signal_fill=0xFFEC99,
+)
+
+with gq.canvas("Example") as diagram:
+    with gq.canvas("Acquisition", column=2, row=1,
+                   background=0xEDF2FF, margin_left=20, margin_right=20,
+                   margin_top=20, margin_bottom=20):
+        adc = gq.element("ADC", column=0, top=0, length=4)
+        fpga = gq.element("FPGA", column=4, top=0, length=4)
+        samples = gq.signal("Samples", row=adc.port(2), components=[adc])
+        samples.components.append(fpga)
+        gq.connector(fpga, samples, inout="in")
+        gq.caption("Acquisition", row=-1, column=0)
+
+diagram.save("example.excalidraw.md")
+```
+
+## Coordinates and ownership
+
+Literal coordinates are local to their canvas. On save, coordinate references
+resolve to positions in the drawing, including all parent offsets. A captured
+reference such as `fpga.column` follows later moves and assignments. Sizes and
+lengths are distances; coordinate formulas return drawing coordinates.
+
+```python
+fpga.column = lambda: adc.column + 5
+diagram.resolve()  # resolve without writing a file
+```
+
+Geometry fields and span entries accept numbers, reactive arithmetic or
+zero-argument functions. Each save evaluates them in passes. Pending dependencies
+read as NaN; stalled resolution raises `ReactiveResolutionError` naming the
+unresolved fields. Functions must be pure. `float(value)` reads a snapshot of the
+last resolved value. Failed resolution leaves an existing output file untouched.
+
+Creating a canvas opens it. Subsequent objects attach automatically; `pop()`
+returns to the previous canvas. `with canvas(...)` restores the previous scope
+on exit. Use `canvas(activate=False)` for explicit ownership and `append()`.
+
+## Objects
+
+- `element(label, column=..., top=..., bottom=... / length=...)`: vertical box.
+  Alternatively use `span=[top, bottom]`. `element.port(index)` returns a reactive
+  row, with 0.5 grid-unit spacing; negative indices count from the bottom.
+- `signal(label, row=..., left=..., right=... / length=...)`: horizontal box.
+  Alternatively use `span=[left, right]` or a mutable `components` list whose
+  outermost columns are connected. Endpoint formulas are prepared at save time.
+- `caption(label, row=..., column=..., fill=..., length=...)`: automatically sized
+  label box; omit `length` to fit the text on each save.
+- `connector(element_or_column, signal_or_row, position="auto", inout="out")`:
+  chevron marker. With a signal, the default chooses `left` or `right` when its
+  span lies entirely on that side of the element's column, including a signal
+  ending at the element. The side and arrow direction follow layout changes on
+  every save. A signal crossing both sides, or a numeric row, defaults to `left`.
+  Set `position="left"` or `"right"` to override. Flow is `in`, `out` or `inout`.
+- `chevron(...)`: individual direction stencil.
+- `canvas(...)`: group with an optional background, border style and per-side
+  margins in pixels. Bounds follow its members automatically.
+
+Default grid size is 80 pixels. `set_color_scheme()` changes global defaults;
+explicit object colors take precedence. Assign `None` to inherit again.
+`get_color_scheme()` returns a copy; `reset_color_scheme()` restores defaults.
+
+`draw_diagram()` provides the lower-level renderer. To normalize existing
+drawings, run `gridquill-normalize drawing.excalidraw.md` (edits the input file).
+
+## Drawing order
+
+Set `z_index` to control overlaps. Higher values appear in front, and each box
+and its label stay together:
+
+```python
+with gq.canvas() as diagram:
+    block = gq.element("FPGA", column=2, span=[0, 4])
+    bus = gq.signal("Bus", row=2, span=[0, 4], z_index=1)
+
+bus.z_index = 2  # editable after creation; applied on the next save
+diagram.save("layers.excalidraw")
+```
+
+Signals, elements, chevrons, captions, connectors and canvases accept `z_index`
+(default `0`). Negative and fractional values are allowed, as are reactive
+formulas. A canvas adds its `z_index` to its descendants' values, so a connector
+or a nested canvas can shift all its members together. Layers compare across
+canvas boundaries. Canvas backgrounds remain behind all drawing objects.
+
+Equal values preserve the existing order: signals (including captions), then
+elements, then chevrons, in traversal order within each kind. Existing diagrams
+therefore keep their drawing order. For `draw_diagram()`, set `z_index` in each
+horizontal or vertical item dictionary; connection arrows remain behind boxes.
+
+## Examples and development
+
+```console
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests
+python examples/canvas_scope_example.py
+python examples/recreate_udt_overview.py --output overview.excalidraw.md
+python -m build
+python -m twine check dist/*
+```
+
+Source lives in `src/gridquill`; tests and runnable examples live in `tests` and
+`examples`. The firmware-specific CSV layout exporter remains in the firmware
+repository because it depends on the separate `fmake` toolchain.
+
+## Publishing
+
+Add author details and actual project URLs to `pyproject.toml`.
+Set `__version__` in `src/gridquill/__init__.py` for a release.
+Build and validate the distributions using the commands above. When ready,
+upload explicitly with `python -m twine upload dist/*` using your PyPI account.
+No publishing credentials or upload automation are included.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

gridquill-0.1.1/examples/__init__.py

@@ -0,0 +1 @@
+"""Runnable Gridquill examples; install the package before running them."""

gridquill-0.1.1/examples/canvas_background_example.py

@@ -0,0 +1,32 @@
+"""Run python canvas_background_example.py to generate an editable example."""
+
+from pathlib import Path
+
+import gridquill
+
+
+if __name__ == "__main__":
+    # The root stays invisible. Each nested canvas opts into its own style.
+    diagram = gridquill.canvas(activate=False)
+    acquisition = diagram.append(gridquill.canvas(
+        "acquisition", column=1, row=1,
+        background=0xEDF2FF, border_color=0x1971C2, border_style="dashed",
+        margin_left=30, margin_right=40, margin_top=20, margin_bottom=25,
+        activate=False,
+    ))
+    acquisition.append(gridquill.element("ADC", column=0, span=[0, 4]))
+    acquisition.append(gridquill.signal("Samples", row=2, span=[0, 4]))
+    acquisition.append(gridquill.element("Processing", column=4, span=[0, 4]))
+
+    group = acquisition.append(gridquill.canvas(
+        "control", column=0, row=6,
+        background=0xFFF9DB, border_color=0xE67700, border_style="dotted",
+        margin_left=15, margin_right=15, margin_top=15, margin_bottom=15,
+        activate=False,
+    ))
+    group.append(gridquill.signal("Configuration", row=0, span=[0, 4]))
+
+    # Resizing, moving or removing members changes the bounds on the next save.
+    output = Path(__file__).parent / "build" / "canvas_background_example.excalidraw"
+    output.parent.mkdir(exist_ok=True)
+    print(diagram.save(output))

gridquill-0.1.1/examples/canvas_scope_example.py

@@ -0,0 +1,42 @@
+"""Run py canvas_scope_example.py for automatic canvas ownership examples."""
+
+from pathlib import Path
+
+import gridquill
+
+
+def build_diagram():
+    with gridquill.canvas("diagram") as diagram:
+        # A constructor opens a child canvas; pop returns to diagram.
+        acquisition = gridquill.canvas(
+            "acquisition", column=1, row=1, background=0xEDF2FF,
+            border_color=0x1971C2, margin_left=20, margin_right=20,
+            margin_top=20, margin_bottom=20,
+        )
+        gridquill.element("ADC", column=0, span=[0, 4])
+        gridquill.signal("Samples", row=2, span=[0, 4])
+        gridquill.connector(column=4, row=2, position="left", inout="in")
+        gridquill.element("Processing", column=4, span=[0, 4])
+        gridquill.pop()
+
+        # A with block automatically pops, including on an exception.
+        with gridquill.canvas(
+            "control", column=1, row=7, background=0xFFF9DB,
+            border_color=0xE67700, border_style="dashed",
+            margin_left=20, margin_right=20, margin_top=20, margin_bottom=20,
+        ) as control:
+            gridquill.signal("Configuration", row=0, span=[0, 4])
+
+        assert gridquill.current_canvas() is diagram
+        assert acquisition.parent is diagram and control.parent is diagram
+
+    # No active canvas now: this object remains unassigned and is not exported.
+    unassigned = gridquill.element("not in the diagram")
+    assert unassigned.parent is None
+    return diagram
+
+
+if __name__ == "__main__":
+    output = Path(__file__).parent / "build" / "canvas_scope_example.excalidraw"
+    output.parent.mkdir(exist_ok=True)
+    print(build_diagram().save(output))

gridquill-0.1.1/examples/draw_chevrons_example.py

@@ -0,0 +1,15 @@
+"""Run py draw_chevrons_example.py to preview the UDT chevron stencil."""
+
+from pathlib import Path
+
+import gridquill
+
+
+if __name__ == "__main__":
+    diagram = gridquill.canvas(activate=False)
+    section = diagram.append(gridquill.canvas("chevron examples", column=1, row=1, activate=False))
+    for row, direction in enumerate(("right", "left", "up", "down")):
+        section.append(gridquill.signal(direction, row=row, span=[0, 3]))
+        section.append(gridquill.chevron(
+            direction, column=3.25, row=row, direction=direction))
+    print(diagram.save(Path(__file__).with_name("chevrons_example.excalidraw.md")))

gridquill-0.1.1/examples/draw_connectors_example.py

@@ -0,0 +1,17 @@
+"""Run py draw_connectors_example.py to preview left/right in/out/inout ports."""
+
+from pathlib import Path
+
+import gridquill
+
+
+if __name__ == "__main__":
+    diagram = gridquill.canvas(activate=False)
+    diagram.append(gridquill.element("element at column 4", column=4, span=[0, 4]))
+    for row, flow in enumerate(("in", "out", "inout"), start=1):
+        diagram.append(gridquill.signal("left: " + flow, row=row, span=[0, 4]))
+        diagram.append(gridquill.signal("right: " + flow, row=row, span=[4, 8]))
+        for side in ("left", "right"):
+            diagram.append(gridquill.connector(column=4, row=row,
+                                               position=side, inout=flow))
+    print(diagram.save(Path(__file__).with_name("connectors_example.excalidraw.md")))

gridquill-0.1.1/examples/draw_diagram_example.py

@@ -0,0 +1,21 @@
+"""Run `python draw_diagram_example.py`, then open the generated drawing."""
+
+from gridquill.render import draw_diagram
+
+
+if __name__ == "__main__":
+    output = draw_diagram(
+        "udt_example.excalidraw.md",
+        horizontal=[
+            {"text": "Lemo", "x": 20, "y": 60, "length": 240},
+            {"text": "RF waveform", "x": 300, "y": 60, "length": 240},
+            {"text": "HV Pulse", "x": 300, "y": 200, "length": 240},
+        ],
+        vertical=[
+            {"text": "Ultrasound Probe", "x": 0, "y": 0, "length": 300},
+            {"text": "IO decoupler", "x": 280, "y": 0, "length": 300},
+            {"text": "ADC", "x": 560, "y": 0, "length": 140},
+            {"text": "HV pulse generator", "x": 560, "y": 160, "length": 280},
+        ],
+    )
+    print(output)

gridquill-0.1.1/examples/draw_objects_example.py

@@ -0,0 +1,24 @@
+"""Run python draw_objects_example.py to generate an editable nested diagram."""
+
+import gridquill
+
+
+if __name__ == "__main__":
+    canvas = gridquill.canvas(activate=False)
+    canvas.signal_gap = 4
+    signal = gridquill.signal()
+    signal.row = 5
+    signal.span = [2, 4]
+    signal.label = "signal 1"
+    canvas.append(signal)
+
+
+    channel = gridquill.canvas("channel", activate=False)
+    channel.append(gridquill.element("ADC", column=0, span=[0, 4]))
+    channel.append(gridquill.signal("RF waveform", row=1, span=[0, 3]))
+    channel.row = 5
+    channel.column = 2
+    canvas.append(channel)
+
+    # Children stay relative to channel.column and channel.row.
+    print(canvas.save("objects_example.excalidraw.md"))

gridquill-0.1.1/examples/recreate_udt_overview.py

@@ -0,0 +1,139 @@
+"""Recreate UDT_overview using only the public Gridquill library objects.
+
+Run: py recreate_udt_overview.py
+The original drawing is not read or modified by this generator. The layout
+preserves its labels (including original spelling), two staggered planes,
+probe banks, shared PC/backplane and signal directions. Standalone captions
+become signal boxes because the library currently has no text-only object.
+
+Canvas ownership uses with blocks and automatic attachment; helpers do not
+need a parent parameter or append calls. Each scope restores its parent.
+All positions/spans are grid units. Background margins are pixels.
+"""
+
+import argparse
+from pathlib import Path
+import gridquill
+
+
+COLOR_SCHEME = dict(
+    element_color=0x1971C2,
+    element_fill=0xA5D8FF,
+    signal_color=0xF08C00,
+    signal_fill=0xFFEC99,
+    chevron_color=0x1971C2,
+    chevron_fill=0xA5D8FF,
+    text_color=0x1E1E1E,
+)
+PANEL_BORDER = 0x228BE6
+PINK = 0xFFC9C9
+GREEN = 0xB2F2BB
+
+
+def probe_bank(label, column, row, decoupler_column):
+    """Four staggered symbols represent the original bank labelled 8 Probes."""
+    with gridquill.canvas(label, column=column, row=row) as bank:
+        gridquill.caption("8 Probes", row=-1.55, column=-10.7, fill=0xFFFFFF)
+        for i in range(4):
+            slope = 0.35
+            x = gridquill.element("Ultra sound Probe", column=-10 + i*slope,
+                                  top=-1.10 + i*slope, length=4)
+            gridquill.signal("Lemo", left=  x.column, right= decoupler_column,  row=0.27 + i*slope)
+    return bank
+
+
+
+def plane(label, column, row, fill, fpga = None) -> gridquill.canvas:
+    margins=(50, 50, 20, 20)
+    fpga = [0, 0] if fpga is None else fpga
+    with gridquill.canvas(
+        label, column=column, row=row, background=fill,
+        border_color=PANEL_BORDER, border_style="solid",
+        margin_left=margins[0], margin_right=margins[1],
+        margin_top=margins[2], margin_bottom=margins[3],
+    ) as result:
+        gridquill.caption(label, row=-1.5, column=-5., fill=fill)
+        IO_decopler = gridquill.element("IO decopler", column=-4.5, top=-1.0, bottom=2)
+        gain = gridquill.element("Gain", column=-1.5, top=-1.5, bottom=0)
+        ADC = gridquill.element("ADC", column=2, top=-.5, bottom=1.5)
+        HV = gridquill.element("HV pusle generator", column=1, top=0.5, length=3)
+        temp = gridquill.element("Temp. sensor", column=0., top=2.5, bottom=4.5)
+        fpga = gridquill.element("FPGA", column=5, top=gain.span[0]+fpga[0],
+                                 bottom=temp.span[1]+fpga[1])
+
+        gridquill.signal( "Gain Control",  row=gain.port(0), components=[gain ,  fpga] )
+        gridquill.signal( "RF waveform",  row=IO_decopler.port(0), components=[ IO_decopler , gain])
+        gridquill.signal( "RF waveform",  row=gain.port(2), components=[ gain , ADC])
+        gridquill.signal( "RF waveform",  row=ADC.port(-1), components=[ ADC , fpga ])
+        
+        gridquill.signal( "HV Pulse",  row=HV.port(-4), components=[ IO_decopler , HV ])
+        gridquill.signal( "Pulse",  row=HV.port(-1), components=[ HV , fpga ])
+        gridquill.signal( "Temperatur",  row=temp.port(-1), components=[ temp , fpga ])
+           
+        
+    return result
+
+def build_overview():
+    # A standalone root keeps the caller's active canvas and drawing separate.
+    # The with block opens it; all nested helpers attach to the active scope.
+    with gridquill.canvas(
+        "UDT overview", grid_size=80, height=40, font_size=20,
+        signal_gap=2, activate=False,
+    ) as diagram:
+        pl0 = plane(
+            "Top Plane", 
+            column=0, 
+            row=0, 
+            fill=PINK,
+            fpga= [ 0, 4]
+        )
+
+        pl1 = plane(
+            "Bottom Plane", 
+            column=-2, 
+            row=7.8, 
+            fill=GREEN,
+            fpga= [-1, 0]
+        )
+
+        
+        probe_bank("Top probe bank", column=0, row=-0.5, decoupler_column=pl0["IO decopler"].column)
+        probe_bank("Bottom probe bank", column=-2, row=7.5, decoupler_column=pl1["IO decopler"].column)
+
+        # Shared components remain outside the plane canvases, as in the reference.
+        pc = gridquill.element("Embedded PC", column=10, top=2, bottom=5.8)
+        Backplane = gridquill.element("Backplane", column=8, top=6.5, bottom=12.30)
+        gridquill.signal("DMA", row=pl1["FPGA"].port(0), components=[pc,pl1["FPGA"] , pl0["FPGA"]])
+
+        eth = gridquill.signal("Ethernet", left= lambda:pc.column, right= 15.0, row= 2.25)
+        gridquill.connector(15.65, eth, "left", "inout")
+
+        # PIN has one direction marker at each FPGA, preserving both directions.
+        PIN = gridquill.signal("PIN", row=pl0["FPGA"].port(-1), components= [pl1["FPGA"] , pl0["FPGA"] ] )
+        gridquill.connector(pl1["FPGA"], PIN, "right", "in")
+        gridquill.connector(pl0["FPGA"] , PIN, "left", "in")
+
+        gridquill.signal("Trigger IO", row=Backplane.port(0), components= [Backplane ,pl0["FPGA"]  ] )
+        gridquill.signal("Position Encoder", row=Backplane.port(1.5), components= [Backplane ,pl0["FPGA"]  ] )
+        
+        
+        gridquill.signal("Trigger IO", row=Backplane.port(5.7), components= [Backplane ,pl1["FPGA"]  ] )
+        
+        gridquill.signal("Position Encoder", row=Backplane.port(7.2), components= [Backplane ,pl1["FPGA"]  ] )
+
+        
+        gridquill.signal("UDT_OptEingang", row=Backplane.port(-3), left= Backplane.column,  right= 15.15 )
+        
+        gridquill.signal("UDT_Output", row=Backplane.port(-1), left=  Backplane.column,  right= 15.15 )
+
+    return diagram
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path,
+                        default=Path("UDT_overview_recreated.excalidraw.md"))
+    args = parser.parse_args()
+    gridquill.set_color_scheme(**COLOR_SCHEME)
+    print(build_overview().save(args.output))
+