Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
61 commits
Select commit Hold shift + click to select a range
4ba0539
Start scene viewer visualisation initiative
tomvanmele Nov 7, 2026
ac5d555
Accept scene viewer visualisation ADRs
tomvanmele Nov 7, 2026
b0b76f1
Revisit scene state architecture
tomvanmele Nov 7, 2026
79f4081
Decouple scene architecture from ModelViewer draft
tomvanmele Nov 7, 2026
1e25f10
Drop legacy scene loader proposal
tomvanmele Nov 7, 2026
441609e
Separate scene descriptions from session data
tomvanmele Nov 7, 2026
5c95c1a
Accept scene data reference boundary
tomvanmele Nov 7, 2026
ee8c4d8
Record scene phase zero checkpoint
tomvanmele Nov 7, 2026
666e98b
Record scene phase zero draft PRs
tomvanmele Nov 7, 2026
8c7b4a1
Add scene candidate integration gate
tomvanmele Nov 7, 2026
c8ba171
Install scene candidates without dependency re-resolution
tomvanmele Nov 7, 2026
245aab9
Resolve scene candidate dependencies in stages
tomvanmele Nov 7, 2026
e0e9891
Provision graphics runtime for scene integration
tomvanmele Nov 7, 2026
dbeabbe
Refresh scene candidate checkpoint
tomvanmele Nov 7, 2026
a3cf910
Gate indexed Viewer candidate
tomvanmele Nov 7, 2026
d9c72ff
Propose node-first scene architecture
tomvanmele Nov 7, 2026
d50d7b6
Propose stable scene objects and operation plugins
tomvanmele Nov 7, 2026
0093010
Accept stable scene architecture
tomvanmele Nov 7, 2026
0fe8f4a
Refresh stable scene integration gate
tomvanmele Nov 7, 2026
f2976d1
Record stable scene integration evidence
tomvanmele Nov 7, 2026
84b1a95
Record core patch coverage recovery
tomvanmele Nov 7, 2026
9d05138
Propose contextual scene form contributions
tomvanmele Nov 7, 2026
919964d
Accept contextual scene form ADRs
tomvanmele Nov 8, 2026
ed2527e
Amend contextual form architecture
tomvanmele Nov 8, 2026
c6c8352
Unify editable and durable scene state
tomvanmele Nov 8, 2026
fa47dbf
Verify contextual forms and propose viewer extensions
tomvanmele Nov 8, 2026
f67452e
Record contextual form verification
tomvanmele Nov 8, 2026
8bdb6d6
Accept viewer tables and configuration ADRs
tomvanmele Nov 8, 2026
33952e8
Verify viewer configuration and attribute tables
tomvanmele Nov 8, 2026
d3b0702
Refresh final viewer candidate
tomvanmele Nov 8, 2026
0e0de91
Pin documented scene candidates
tomvanmele Nov 8, 2026
667a281
Record final scene viewer verification
tomvanmele Nov 8, 2026
b29dc21
Pin refreshed viewer examples candidate
tomvanmele Nov 8, 2026
1196daa
Record refreshed viewer example verification
tomvanmele Nov 8, 2026
84d9102
Record exploratory viewer UI sketch
tomvanmele Nov 8, 2026
ef10a8c
Verify unified viewer selection
tomvanmele Nov 8, 2026
89cfcd6
Record selection integration evidence
tomvanmele Nov 8, 2026
16d017d
Verify reversible viewer transformations
tomvanmele Nov 8, 2026
f4370a4
Record transform integration evidence
tomvanmele Nov 8, 2026
2d817a2
Refine annotation and measurement architecture
tomvanmele Nov 8, 2026
ed1afc7
Accept annotation ownership and dimension units
tomvanmele Nov 8, 2026
0392dc2
Accept viewer measurement settings
tomvanmele Nov 8, 2026
d689448
Accept viewer overlay contracts
tomvanmele Nov 8, 2026
0347364
Accept measurement snapping contract
tomvanmele Nov 8, 2026
8b45ab5
Verify Phase 3 scene candidates
tomvanmele Nov 9, 2026
c4ae08f
Record Phase 3 scene verification
tomvanmele Nov 9, 2026
f849c26
Refresh measurement integration candidate
tomvanmele Nov 9, 2026
541b5a3
Record green scene integration gate
tomvanmele Nov 9, 2026
8fa3d05
Refine measurement snap contract
tomvanmele Nov 9, 2026
e8d02d0
Record green snap refinement gates
tomvanmele Nov 9, 2026
de3cb19
Refresh scene initiative measurement contracts
tomvanmele Nov 9, 2026
bd3062b
Record refreshed scene integration evidence
tomvanmele Nov 9, 2026
871a568
Integrate scene annotation collection candidates
tomvanmele Nov 9, 2026
3d2c9d1
Integrate viewer sidebar redesign
tomvanmele Nov 9, 2026
270e1d6
Record sidebar candidate revision
tomvanmele Nov 9, 2026
6648a94
Record verified sidebar redesign
tomvanmele Nov 9, 2026
21ff563
Pin viewer crash fixes
tomvanmele Nov 9, 2026
e09fd7e
Record and integrate viewer follow-up decisions
tomvanmele Nov 9, 2026
81c4b7d
Repin verified Viewer follow-up
tomvanmele Nov 9, 2026
f7ac4ce
Repin portable Viewer candidate
tomvanmele Nov 9, 2026
84846ea
Record verified viewer follow-ups
tomvanmele Nov 9, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/scene-candidates/core-requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
compas @ git+https://github.com/compas-dev/compas.git@70aeb1e408772f0a84213c280658d4d594bf12ea
721 changes: 721 additions & 0 deletions .github/scene-candidates/test_scene_integration.py

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions .github/scene-candidates/viewer-requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
compas_viewer @ git+https://github.com/compas-dev/compas_viewer.git@efbb7991c9f60aef2e8225813c5050190b5cfb0b
62 changes: 62 additions & 0 deletions .github/workflows/scene-candidate-integration.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
name: scene-candidate-integration

on:
pull_request:
branches: [c3-upgrade]
paths:
- .github/scene-candidates/**
- .github/workflows/scene-candidate-integration.yml
workflow_dispatch:

permissions:
contents: read

concurrency:
group: scene-candidate-integration-${{ github.ref }}
cancel-in-progress: true

jobs:
source-installed-candidates:
runs-on: ubuntu-24.04
env:
PYTHONDONTWRITEBYTECODE: "1"
QT_QPA_PLATFORM: offscreen
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install Linux EGL/OpenGL runtime
run: |
sudo apt-get update
sudo apt-get install --yes libegl1 python3-opengl
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: "3.12"
- uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
with:
version: "0.12.7"
- name: Install test tools and exact source candidates
run: |
uv venv
uv pip install --python .venv/bin/python pytest==9.0.2 pyright==1.1.414
uv pip install --python .venv/bin/python compas_viewer==2.0.2
uv pip install \
--python .venv/bin/python \
--reinstall \
--requirements .github/scene-candidates/core-requirements.txt
uv pip install \
--python .venv/bin/python \
--no-deps \
--reinstall \
--requirements .github/scene-candidates/viewer-requirements.txt
- name: Check installed scene typing boundary
run: >-
uv run --no-sync pyright
--pythonversion 3.12
.github/scene-candidates/test_scene_integration.py
- name: Exercise installed scene and Viewer behavior
run: >-
uv run --no-sync pytest
--basetemp "${RUNNER_TEMP}/scene-candidate-pytest"
-o cache_dir="${RUNNER_TEMP}/scene-candidate-cache"
.github/scene-candidates/test_scene_integration.py
59 changes: 59 additions & 0 deletions initiatives/scene-viewer-visualisation/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Scene, Viewer, and Visualisation

This initiative aligns backend-neutral scene infrastructure with Viewer
rendering, interaction, state, and UI composition.

Current phase: **Phase 3 ADRs 036 and 040–042 implemented and verified**.

- [Objective](objective.md)
- [Inventory](inventory.md)
- [Proposal](proposal.md)
- [Architecture decisions](decisions/README.md)
- [Implementation plan](implementation-plan.md)
- [Current handoff](handoff.md)

The stable scene architecture correction in Accepted ADRs 013–014 is
implemented and verified: nodes are hierarchy-only, durable scene objects are
stable, and backend operations are context-keyed. Amended Accepted ADRs
015–016 now govern `SceneStateField`-backed editability, narrowly declared
non-state editable attributes, and Viewer-owned contextual forms. Scene
remains reference-only, and optional aggregation is reserved for a separate
future Session design.

Accepted ADRs 017–020 govern lazy Mesh/Graph element-attribute tables, their
editing semantics, configured Viewer identity, and configuration lifecycle.
They are implemented, locally verified, and independently approved. Hosted
Viewer and framework checks passed. ADR 003 object selection and ADR 004
transformations, categorized refresh, and Viewer-level transform history are
also implemented and fully verified. Accepted ADRs 021–028 and 030 are
implemented for durable Core annotations, Viewer rendering and overlays,
measurement snapping and interaction, unit/precision presentation,
discrete-only point acquisition, and an always-visible persistent-dimension
pass. The latest measurement follow-up is verified in Viewer package CI and the
framework exact source-installed gate. Accepted ADRs 029 and 031 now authorize
the separate annotation collection and UI, narrow durable dimension style, and
discoverable spatial-object deletion. Their Core and Viewer implementations
and refreshed package and exact source-installed framework integration pass.
Direct-use evidence exposed an unstable and ambiguous stacked sidebar, so ADR
032 accepts a three-domain Scene, Annotations, and System replacement. Its
implementation, documentation, local verification, independent review,
hosted package CI, and the exact source-installed framework gate pass. Two
direct-use regressions in annotation visibility refresh and numeric field
editing are fixed and verified in hosted Viewer and framework CI. Further
direct use has produced ADRs 033–039 for a resizable Scene inspector,
hidden-glyph vertex snapping, spatial dimension layout, viewport text,
annotation label backgrounds, contextual deletion, and moving the existing
geometry Add hierarchy under Scene. ADR 036 accepts the programmatic-first
screen-text overlay. Accepted ADRs 040–042 add synchronized toolbar selectors,
a coherent Grid and Units System section with consistent field alignment, and
transient selected-object area and volume inspection. The remaining ADRs are
Proposed. ADRs 036 and 040–042 are implemented on the Viewer initiative branch
and pass the complete local and hosted Viewer gates plus the exact
source-installed framework gate. Exact candidate-artifact compatibility has
not been run and is not implied by the existing results.

The refined initial package scope is `compas`, `compas_viewer`, and
`compas_framework`. The current `compas_model.ModelViewer` is draft evidence
and a later redesign consumer, not a behavior contract. Session persistence,
notebook visualisation, and CAD-host adapters are compatibility-review
consumers until an approved decision admits them to implementation scope.
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# ADR 001: Ownership and State Boundaries

## Status

Accepted.

## Context

Core scene objects currently combine durable content with context-adapter
state, while Viewer selection, GPU identity, configuration, tool state, and UI
refresh paths are distributed across objects, renderer, commands, and widgets.
Moving everything into core would make Qt/rendering concerns framework
dependencies; leaving ownership implicit perpetuates coupling.

## Options

1. Keep core responsible for durable scene content and place renderer and
interaction state in Viewer.
2. Add rendering, selection, and reactive application state to core Scene.
3. Keep all current ownership and coordinate behavior through conventions.
4. Move durable scene content into Viewer and reduce core Scene to adapters.

## Recommendation

Choose option 1.

- Core owns scene items, hierarchy, scene-object GUIDs, local transformations,
visibility, durable appearance, and serialization.
- Viewer configuration owns persistent application preferences.
- Viewer session state owns selection, hover, tools, gestures, and transient
results.
- Viewer rendering owns indexed buffers, pick IDs, GPU resources, and refresh.
- Domain packages own authoritative domain hierarchies and caches and project
them into core scenes through public Viewer operations.

GUIDs connect durable scene objects to Viewer state. Pick IDs and transient
state are never serialized. Do not add Qt signals or GPU contracts to core.

## Consequences

- Core remains usable by notebook and host adapters without Viewer.
- Selection and tools stop leaking into serialized scene-object settings.
- Viewer must provide explicit public state and synchronization operations.
- Domain packages retain their own data authority rather than duplicating it
in a generic application store.
- Existing Viewer code that reaches its singleton, renderer, or widgets must
migrate gradually after the public boundary exists.

## Compatibility

ADR 008 proposes replacing the current incomplete scene serialization without
a compatibility loader. Removing transient Viewer fields and introducing the
new scene-node schema therefore form a deliberate C3 serialization break.

## Verification

- Round-trip core scenes without Viewer installed.
- Prove Viewer selection, hover, tools, and pick IDs are absent from scene
serialization.
- Verify domain objects resolve through stable scene-object GUIDs after UI
rebuilds.

## Affected packages

Initial implementation: `compas`, `compas_viewer`, and `compas_framework`.

Later redesign/regression consumer: `compas_model`.

## Dependencies

- Geometry-tessellation ADRs 022 and 024
- Plugin-implementations ADR 002

## Pending amendments

Verified round-trip failures showed that this decision did not distinguish the
durable scene node/state from the context-specific runtime `SceneObject`
adapter precisely enough. Accepted [ADR 008](008-scene-nodes-and-runtime-adapters.md)
and [ADR 009](009-scene-state-fields.md) amend that boundary. Accepted
[ADR 010](010-scene-description-and-item-bundling.md) defines item ownership
and the later Session aggregation boundary.

The generic principle that domain packages retain their own data authority
does not preserve the current draft `ModelViewer` controller, projections,
selection behavior, or cache shape. Explicit user correction moves that draft
to a later redesign phase.
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# ADR 002: Indexed Viewer Buffer Geometry

## Status

Accepted.

## Context

Viewer can batch geometry efficiently but its general `BufferGeometry`
requires expanded line and triangle vertices. This duplicates arrays and makes
callers manually expand vertices plus edges or triangles. Core numerical APIs
already accept structural Python and NumPy buffers, and Viewer-specific GPU
layout should not become a compulsory core geometry representation.

## Options

1. Add one Viewer-owned shared-vertex indexed `BufferGeometry` contract and
convenience constructors.
2. Put a GPU-oriented buffer type in core.
3. Require `Tessellation`, `PolygonalSurface`, or `Mesh` for every input.
4. Preserve expanded arrays and add only helper functions that duplicate them.

## Recommendation

Choose option 1. Use shared `vertices` plus optional point, edge, and triangle
index channels. Provide:

```python
BufferGeometry.from_points(vertices)
BufferGeometry.from_vertices_and_edges(vertices, edges)
BufferGeometry.from_vertices_and_triangles(vertices, triangles)
```

Accept structural Python sequences and NumPy arrays. Normalize once to Viewer
dtypes and check rank, column count, and index bounds. Preserve indices through
the buffer manager and do not create one scene object per primitive.

Keep styling on scene objects. Do not add a universal render geometry to core
or make this contract an input to geometry algorithms.

## Consequences

- Large edge and triangle datasets avoid Python-object and vertex-expansion
overhead.
- Viewer adapters gain one common path for indexed geometry.
- Geometry with independent point/line/triangle vertex pools must combine
them into one vertex table with offset indices at the Viewer boundary.
- Per-channel or per-primitive color arrays beyond current behavior require
evidence and a separate refinement rather than speculative fields.

## Compatibility

The existing expanded `points`, `lines`, and `faces` constructor is replaced
in a coordinated Viewer change. Examples and adapters migrate together; no
parallel deprecated constructor is proposed.

## Verification

- Test list and NumPy inputs, exact shapes/dtypes, bounds, empty channels, and
input non-mutation.
- Assert indices remain indexed in CPU/GPU assembly.
- Exercise large input without per-edge or per-triangle scene objects.
- Compare rendering semantics with current points, lines, and faces.

## Affected packages

Initial implementation: `compas_viewer` and `compas_framework`.

Later redesign consumer: `compas_model`; its current render-cache shape is not
preserved by this decision.

## Dependencies

- [ADR 001](001-ownership-boundaries.md)
- Accepted structural numerical-input decisions from typing alignment
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# ADR 003: Viewer State and Object Selection

## Status

Accepted.

## Context

Selection currently lives in mutable `ViewerSceneObject.is_selected` flags.
Viewport commands, tree widgets, shaders, and programmatic consumers mutate or
poll those flags and then trigger imperative refreshes. `ViewerState` observes
persistent configuration but not selection or tool state.

## Options

1. Add one Viewer-owned observable object-selection model and separate
persistent configuration from transient state.
2. Keep scene-object flags and add selection-change signals around them.
3. Put selection into core Scene and serialize it.
4. Adopt a generic third-party reactive state store for all Viewer data.

## Recommendation

Choose option 1.

`Viewer.state.selection` stores ordered scene-object GUIDs and provides
replace, add, remove, toggle, clear, membership, and ordered-resolution
operations. It emits one batched change notification per operation. Viewport,
rectangle selection, scene tree, commands, shaders, and programmatic consumers use
this model exclusively.

Keep `Viewer.config` for persistent preferences. Keep hover, active tool,
gesture, and temporary tool values in small explicit Viewer state fields. Use a
Qt-neutral Python model with a Qt bridge. Remove `is_selected` rather than
retaining a second writable authority.

Initial selection is scene-object-level only. Do not invent a generic vertex,
edge, face, or domain-component token until an approved editing workflow
requires it.

## Consequences

- Tree, viewport, code, and renderer observe one mutation
path.
- Selection no longer participates in scene serialization.
- Batch changes avoid repeated renderer/UI updates.
- Existing selection APIs and tests require a coordinated breaking migration.
- Sub-object selection remains explicitly unsupported in the initial wave.

## Compatibility

Remove Viewer `is_selected` constructor/settings behavior. Later integrations
may consume the selection model but do not define its contract.

## Verification

- Exercise replace/add/remove/toggle/clear from viewport, rectangle, tree, and
programmatic paths.
- Assert one notification and one render/UI synchronization per batch.
- Verify stable ordering, removed-object cleanup, and serialization exclusion.

## Affected packages

`compas_viewer` and `compas_framework`. `compas_model` is a later redesign
consumer.

## Dependencies

- [ADR 001](001-ownership-boundaries.md)

## Refinement after acceptance

The current `compas_model.ModelViewer` is a draft and does not promise a
model-order selection contract that this ADR must preserve. The accepted
decision remains one Viewer-owned selection model; model-specific preservation
language has been removed by explicit user correction.
Loading