Alice Virtual Assembly

A buildable starter repository for a commercial virtual assembly platform.

This delivery is intentionally honest about scope:

• It is not a full Siemens Process Simulate / DELMIA replacement.
• It is a production-oriented foundation that cleanly separates domain model, validation, planning, execution, export/reporting, optional desktop UI, and future geometry/collision adapters.
• It compiles, runs, tests, and packages in its current form.

Current capabilities

• Assembly domain model: parts, occurrences, mate constraints, resources, zones, scenario expectations, and process steps
• Physical/process metadata: part mass, resource payload capacity, resource nominal linear speed, resource nominal angular speed, and resource selection priority
• Occurrence collision groups for process-aware collision filtering
• Step-level collision filtering with explicit ignored occurrences and ignored collision groups
• Scenario loading from a simple text-based format (.vaasm)
• Validation pipeline for broken references, dependency issues, resource mismatches, invalid sample counts, and invalid collision-ignore references
• Planning pipeline that resolves target transforms and propagates sequential step state
• Execution pipeline separated from planning
• Static feasibility analysis for resource work-envelope checks and zone checks before execution
• Broad-phase / narrow-phase simplified collision checking using a replaceable collision backend boundary with a current yaw-aware AABB implementation
• Straight-line and yaw-interpolated motion simulation with configurable interpolation samples
• Absolute target moves (step_move), mate-based moves (step), two-stage guided inserts (step_insert), authored path moves (step_path), and screw-style mate moves (step_screw)
• Deterministic CLI execution for batch verification
• Simulation replay trace capture
• JSON trace export
• Markdown report export
• Suite execution with expected success/failure classification
• Optional Qt desktop shell with linked tree, viewport, properties, timeline, and log panes
• Dual-view desktop shell with a productive OpenGL viewport and a parallel OCCT backend seat
• Toolbar and menu commands for OpenGL/OCCT backend switching and step preview scrubbing
• Runtime geometry catalog with analytic box geometry and cached OBJ wireframe import
• Scene-model layer for visual occurrences and step-target preview
• Unit tests
• CMake presets
• Linux and Windows build/package scripts
• CPack packaging
• vcpkg manifest for future optional dependencies

Repository layout

• include/va/* - public platform headers
• src/* - core implementation
• apps/virtual_assembly_cli - batch and regression-friendly command line front end
• apps/virtual_assembly_desktop - optional Qt desktop shell
• samples/*.vaasm - sample assembly scenarios
• samples/meshes/* - sample external mesh assets
• docs/*.md - architecture and delivery documentation
• scripts/* - Linux and Windows build/package automation

Build on Linux

cmake --preset linux-debug
cmake --build --preset linux-debug
ctest --preset linux-debug
./out/build/linux-debug/virtual_assembly_cli samples/ignored_fixture_transfer.vaasm --plan --replay --export-trace out/reports/ignored_fixture_transfer_trace_v8.json --export-report out/reports/ignored_fixture_transfer_report_v8.md
./out/build/linux-debug/virtual_assembly_cli --suite-dir samples --export-suite-report out/reports/sample_suite_report_v12.md
cpack --config out/build/linux-debug/CPackConfig.cmake -B out/package/linux-debug

Or use:

./scripts/linux/build.sh
./scripts/linux/package.sh

Build on Windows (Visual Studio 2022 Developer Prompt)

scripts\windows\build_vs2022.bat
scripts\windows\package_vs2022.bat

Build on Windows (Visual Studio 2022)

The Windows scripts now switch to the repository root before invoking cmake --preset ..., so they can be launched directly from scripts\windows without failing on CMakePresets.json path resolution.

Build the optional Qt desktop shell

The desktop shell now includes a productive OpenGL scene viewport, a parallel OCCT backend seat, linked tree/properties/timeline panes, and toolbar/menu buttons for backend switching. Load samples/mesh_transfer_demo.vaasm after building to verify external OBJ geometry preview and linked step-target visualization.

cmake -S . -B out/build/linux-qt -G Ninja -DVA_BUILD_QT_DESKTOP=ON -DVA_ENABLE_OCCT_VIEWER=ON
cmake --build out/build/linux-qt

If OpenCASCADE is not available, the OpenGL backend still builds and runs while the OCCT page remains present as an isolated backend seat with explicit status messaging rather than a fake fallback renderer.

CLI usage

virtual_assembly_cli <scenario.vaasm> [options]
virtual_assembly_cli --suite-dir <directory> [options]

Options:
  --list-model
  --validate
  --plan
  --replay
  --export-trace <file.json>
  --export-report <file.md>
  --export-suite-report <file.md>

Scenario format highlights

expect failure codes=step.workspace.out_of_bounds
occurrence gripper_inst gripper 0 0 0 fixed groups=fixture,gripper
step_move carry_part part_inst 2 0 0 0.0 8 resource=robot_01 ignore_occurrences=gripper_inst
step_move carry_part_2 part_inst 2 0 0 0.0 8 resource=robot_01 ignore_groups=fixture

See docs/ScenarioFormat.md for the full grammar.

Why the current release still uses AABB-only collision

This repository optimizes for:

1. clean architecture,
2. zero-friction compilation,
3. deterministic testing,
4. CI-friendly trace and report generation.

The collision backend is isolated behind ICollisionBackend / CollisionEngine, so it can be replaced by OCCT+BRep, FCL, Bullet, or GPU distance-field backends without rewriting the process layer.

v0.9.0

• Added step contact policy (strict, allow_touch_at_target)
• Added candidate resource selection and planner auto-assignment
• Added reusable step profiles in .vaasm scenarios
• Added profiled touch-fit sample and tests

v1.0.0

• Added part mass metadata (part ... mass=)
• Added resource payload / speed / priority metadata (resource ... payload= speed= priority=)
• Added step payload margin semantics (payload_margin=)
• Planner now performs payload-aware resource selection and computes estimated duration
• Reports and suite summaries now expose payload margins and estimated cycle-time KPIs
• Added payload-ranked transfer sample and tests

v1.2.0

• Added yaw-aware transforms for occurrences, mate targets, absolute targets, and path waypoints
• Added resource ... angular_speed= and duration estimation from both linear and angular travel
• Added mate ... yaw_offset= and occurrence ... yaw=
• Added step_screw with extra revolutions along a mate-constrained motion
• Upgraded the collision broad phase to use yaw-aware world AABBs for rotated box-like parts
• Added threaded fastener sample and new orientation / screw-step tests

v1.7.0

• Added va_geometry runtime geometry catalog
• Added OBJ wireframe import and cache
• Added va_scene visual occurrence model with step target preview
• Rebuilt the Qt desktop shell into a linked workstation layout with tree, properties, timeline, log, and viewport
• Added geom / color scenario directives and a mesh-backed demo scenario

v1.8.0

• Kept the OpenGL viewport as the productive scene renderer
• Added a parallel OCCT backend seat and explicit backend availability messaging
• Added menu and toolbar actions for OpenGL/OCCT switching
• Added previous-step / next-step / clear-preview navigation in the desktop timeline workflow
• Upgraded the desktop shell CMake path to use Qt6::OpenGLWidgets and optional VA_ENABLE_OCCT_VIEWER discovery

Desktop build policy (rewritten in v1.9)

The Qt desktop build now treats the OpenGL viewport as the default production path. The OCCT backend is opt-in only and is never auto-discovered from arbitrary machine-global CMake package locations.

Windows

Build the Qt desktop with OpenGL only:

scripts\windows�uild_qt_vs2022.bat

Build the Qt desktop with an explicit OCCT package directory:

scripts\windows�uild_qt_vs2022.bat --with-occt D:\ThirdParty\occt\cmake

Linux

Build the Qt desktop with OpenGL only:

./scripts/linux/build_qt_with_vcpkg.sh

Build the Qt desktop with an explicit OCCT package directory:

./scripts/linux/build_qt_with_vcpkg.sh --with-occt /opt/occt/lib/cmake/opencascade

This policy prevents accidental pickup of stale or incomplete OpenCASCADEConfig.cmake files from unrelated machines or projects.

v20 build note

The Windows build scripts now remove stale build caches before configuring. This package also ships without embedded out/build artifacts.

Windows Qt desktop deployment

The desktop target should not be launched as a raw Debug executable unless the Qt debug plugin tree is available. Use these scripts instead:

• scripts\windows\run_qt_debug_vs2022.bat for an in-tree debug run
• scripts\windows\package_qt_vs2022.bat for a deployable Release app-local package

The packaged application is generated under:

out\package\windows-qt-vs2022\AliceVirtualAssemblyDesktop