COMPAS VIEWER

A standalone, high-performance 3D viewer for COMPAS 2.0, built with PySide6 and OpenGL.

More information is available in the docs: https://compas.dev/compas_viewer/

Features

Core Functionality

• High-Performance Rendering: Modern OpenGL 3.3 Core Profile with optimized buffer management and instanced rendering
• Complete COMPAS Integration: Full support for all COMPAS objects based on the compas.scene architecture
• Multiple Rendering Modes: Shaded, ghosted, lighted, and wireframe rendering with configurable opacity
• Interactive Navigation: Smooth camera controls with perspective, orthographic, and preset views (top, front, right)
• Advanced Selection: Object selection with window/box selection, multi-selection, and selection highlighting

User Interface

• Customizable UI: Fully configurable interface with dockable panels, toolbars, and sidebars
• Scene Management: Hierarchical scene tree with show/hide controls and object settings
• Real-time Controls: Dynamic sliders, buttons, and form controls for interactive parameter adjustment
• Property Editing: Built-in object property dialogs for colors, line widths, point sizes, and transformations

Supported Geometry Types

• Primitives: Point, Line, Vector, Plane, Frame
• Curves: Polyline, Circle, Ellipse, NurbsCurve
• Surfaces: Polygon, NurbsSurface, BRep (via compas_occ)
• Solids: Box, Sphere, Cylinder, Cone, Torus, Capsule, Polyhedron
• Data Structures: Mesh, Graph, Pointcloud, Collection
• Special: Text tags, Grid, Custom buffer objects

Advanced Features

• Dynamic Animations: Built-in animation system with @viewer.on() decorator for time-based updates
• Multi-Unit Support: Automatic scaling for meters, centimeters, and millimeters
• Command System: Extensive keyboard and mouse shortcuts with customizable bindings
• File I/O: Load/save scenes in JSON format, drag and drop COMPAS scene, geometries and data structures
• Command Line Interface: Direct launching with python -m compas_viewer -f filename.json
• Extensible Architecture: Plugin system for custom scene objects and UI components

Installation

Requirements

• Python >= 3.9
• COMPAS >= 2.2.0

Quick Install

pip install compas_viewer

Development Install

git clone https://github.com/compas-dev/compas_viewer.git
cd compas_viewer
pip install -e .

See the Getting Started instructions in the docs for detailed installation guidelines.

Quick Start

Basic Usage

from compas_viewer import Viewer
from compas.geometry import Box, Sphere

# Create viewer
viewer = Viewer()

# Add geometry
box = Box(1, 2, 3)
sphere = Sphere(0.5)

viewer.scene.add(box, name="My Box")
viewer.scene.add(sphere, name="My Sphere")

# Show viewer
viewer.show()

Command Line Usage

# Launch with a empty scene
python -m compas_viewer

# Launch with a specific file
python -m compas_viewer -f path/to/geometry.json

# Launch with multiple files from a directory
python -m compas_viewer --files path/to/directory/

Dynamic Animations

from compas_viewer import Viewer
from compas.geometry import Box, Translation

viewer = Viewer()
box = viewer.scene.add(Box(1, 1, 1))

@viewer.on(interval=50)  # Update every 50ms
def animate(frame):
    T = Translation.from_vector([0.01 * frame, 0, 0])
    box.transformation = T

viewer.show()

Key Controls

Documentation

• Tutorial: Basic concepts, configuration, and software architecture
• Examples: Comprehensive examples covering all features
• API Reference: Complete API documentation

Contributing

We welcome contributions! Please see our Contributing Guidelines for:

• Bug reports and feature requests
• Code contributions and pull requests
• Documentation improvements
• Community guidelines

Dependencies

• PySide6: Qt6 bindings for Python
• PyOpenGL: OpenGL bindings for Python
• freetype-py: Font rendering
• COMPAS: COMPAS framework (>= 2.2.0)

License

The code in this repo is licensed under the MIT License.

Known Issues

Please check the Issue Tracker for known issues and their solutions.

Changelog

See CHANGELOG.md for version history and release notes.