Skip to content

Commit 23c7d0a

Browse files
LiciniLicini
committed
readme
1 parent 70a41ac commit 23c7d0a

File tree

1 file changed

+132
-19
lines changed

1 file changed

+132
-19
lines changed

‎README.md‎

Lines changed: 132 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,155 @@
11
# COMPAS VIEWER
22

3-
Standalone viewer for COMPAS 2.0
3+
A standalone, high-performance 3D viewer for COMPAS 2.0, built with PySide6 and OpenGL.
4+
5+
[![Version](https://img.shields.io/badge/version-1.6.0-blue.svg)](https://github.com/compas-dev/compas_viewer)
6+
[![Documentation](https://img.shields.io/badge/docs-compas.dev-green.svg)](https://compas.dev/compas_viewer/)
7+
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
48

59
More information is available in the docs: <https://compas.dev/compas_viewer/>
610

711
## Features
812

9-
- Performative and easy-to-use new architecture based on [compas_v1](https://compas.dev/compas/1.17.9/)'s [compas_view2](https://compas.dev/compas_view2/).
10-
- Complete configurable settings and flexible customization.
11-
- Full support for all COMPAS objects (primitives, shapes, graph, mesh, volmesh) based on [compas.scene](https://compas.dev/compas/latest/api/generated/compas.scene.Scene.html#scene) architecture.
12-
- Up-to-date [PySide6](https://pypi.org/project/PySide6/) and [PyOpenGL](https://pypi.org/project/PyOpenGL/) compatibility.
13-
- Action-based user interaction: drag, select, zoom, pan, rotate, etc.
14-
- Data-driven visualization with simple decorators: facecolor, edgecolor, vertexcolor, linewidth, pointsize, etc.
15-
- Text tags and grids.
16-
- Customizable UI and UI Controller
17-
- Transformations in object space
18-
- ...
13+
### Core Functionality
14+
- **High-Performance Rendering**: Modern OpenGL 3.3 Core Profile with optimized buffer management and instanced rendering
15+
- **Complete COMPAS Integration**: Full support for all COMPAS objects based on the [compas.scene](https://compas.dev/compas/latest/api/generated/compas.scene.Scene.html#scene) architecture
16+
- **Multiple Rendering Modes**: Shaded, ghosted, lighted, and wireframe rendering with configurable opacity
17+
- **Interactive Navigation**: Smooth camera controls with perspective, orthographic, and preset views (top, front, right)
18+
- **Advanced Selection**: Object selection with window/box selection, multi-selection, and selection highlighting
19+
20+
### User Interface
21+
- **Customizable UI**: Fully configurable interface with dockable panels, toolbars, and sidebars
22+
- **Scene Management**: Hierarchical scene tree with show/hide controls and object settings
23+
- **Real-time Controls**: Dynamic sliders, buttons, and form controls for interactive parameter adjustment
24+
- **Property Editing**: Built-in object property dialogs for colors, line widths, point sizes, and transformations
25+
26+
### Supported Geometry Types
27+
- **Primitives**: Point, Line, Vector, Plane, Frame
28+
- **Curves**: Polyline, Circle, Ellipse, NurbsCurve
29+
- **Surfaces**: Polygon, NurbsSurface, BRep (via compas_occ)
30+
- **Solids**: Box, Sphere, Cylinder, Cone, Torus, Capsule, Polyhedron
31+
- **Data Structures**: Mesh, Graph, Pointcloud, Collection
32+
- **Special**: Text tags, Grid, Custom buffer objects
33+
34+
### Advanced Features
35+
- **Dynamic Animations**: Built-in animation system with `@viewer.on()` decorator for time-based updates
36+
- **Multi-Unit Support**: Automatic scaling for meters, centimeters, and millimeters
37+
- **Command System**: Extensive keyboard and mouse shortcuts with customizable bindings
38+
- **File I/O**: Load/save scenes in JSON format, drag and drop COMPAS scene, geometries and data structures
39+
- **Command Line Interface**: Direct launching with `python -m compas_viewer -f filename.json`
40+
- **Extensible Architecture**: Plugin system for custom scene objects and UI components
1941

2042
## Installation
2143

22-
See the [Getting Started](https://compas.dev/compas_viewer/latest/installation.html) instructions in the docs.
44+
### Requirements
45+
- Python >= 3.9
46+
- COMPAS >= 2.2.0
47+
48+
### Quick Install
49+
```bash
50+
pip install compas_viewer
51+
```
52+
53+
### Development Install
54+
```bash
55+
git clone https://github.com/compas-dev/compas_viewer.git
56+
cd compas_viewer
57+
pip install -e .
58+
```
59+
60+
See the [Getting Started](https://compas.dev/compas_viewer/latest/installation.html) instructions in the docs for detailed installation guidelines.
61+
62+
## Quick Start
63+
64+
### Basic Usage
65+
```python
66+
from compas_viewer import Viewer
67+
from compas.geometry import Box, Sphere
68+
69+
# Create viewer
70+
viewer = Viewer()
71+
72+
# Add geometry
73+
box = Box(1, 2, 3)
74+
sphere = Sphere(0.5)
75+
76+
viewer.scene.add(box, name="My Box")
77+
viewer.scene.add(sphere, name="My Sphere")
78+
79+
# Show viewer
80+
viewer.show()
81+
```
82+
83+
### Command Line Usage
84+
```bash
85+
# Launch with a empty scene
86+
python -m compas_viewer
2387

24-
## Tutorials
88+
# Launch with a specific file
89+
python -m compas_viewer -f path/to/geometry.json
2590

26-
This [tutorial page](https://compas.dev/compas_viewer/latest/tutorial.html) contains basic lead-through, configuration setting, and software concepts.
91+
# Launch with multiple files from a directory
92+
python -m compas_viewer --files path/to/directory/
93+
```
2794

28-
## Examples
95+
### Dynamic Animations
96+
```python
97+
from compas_viewer import Viewer
98+
from compas.geometry import Box, Translation
2999

30-
Examples can be found in our [example page](https://compas.dev/compas_viewer/latest/examples.html).
100+
viewer = Viewer()
101+
box = viewer.scene.add(Box(1, 1, 1))
102+
103+
@viewer.on(interval=50) # Update every 50ms
104+
def animate(frame):
105+
T = Translation.from_vector([0.01 * frame, 0, 0])
106+
box.transformation = T
107+
108+
viewer.show()
109+
```
110+
111+
## Key Controls
112+
113+
| Action | Shortcut |
114+
|--------|----------|
115+
| Rotate | Right-click + drag |
116+
| Pan | Right-click + shift + drag |
117+
| Zoom | Mouse wheel |
118+
| Select object | Left-click |
119+
| Select multiple | Left-click + shift + drag |
120+
| Delete selected | Delete key |
121+
| Zoom to selected | F key (with selection) |
122+
| Zoom to All | F key (without selection) |
123+
124+
## Documentation
125+
126+
- **[Tutorial](https://compas.dev/compas_viewer/latest/tutorial.html)**: Basic concepts, configuration, and software architecture
127+
- **[Examples](https://compas.dev/compas_viewer/latest/examples.html)**: Comprehensive examples covering all features
128+
- **[API Reference](https://compas.dev/compas_viewer/latest/api.html)**: Complete API documentation
31129

32130
## Contributing
33131

34-
[Contributing page](CONTRIBUTING.md) provides the guidelines for contributing to this project. We very much welcome any contributions to this project (Bug Fix, Action class contribution, etc.)
132+
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for:
133+
- Bug reports and feature requests
134+
- Code contributions and pull requests
135+
- Documentation improvements
136+
- Community guidelines
137+
138+
## Dependencies
139+
140+
- **[PySide6](https://pypi.org/project/PySide6/)**: Qt6 bindings for Python
141+
- **[PyOpenGL](https://pypi.org/project/PyOpenGL/)**: OpenGL bindings for Python
142+
- **[freetype-py](https://pypi.org/project/freetype-py/)**: Font rendering
143+
- **[COMPAS](https://compas.dev/)**: COMPAS framework (>= 2.2.0)
35144

36145
## License
37146

38-
The code in this repo is licensed under the [MIT License](LICENCSE).
147+
The code in this repo is licensed under the [MIT License](LICENSE).
39148

40149
## Known Issues
41150

42-
Please check the [Issue Tracker](https://github.com/compas-dev/compas_viewer/issues) of the repo for known issues and their solutions.
151+
Please check the [Issue Tracker](https://github.com/compas-dev/compas_viewer/issues) for known issues and their solutions.
152+
153+
## Changelog
154+
155+
See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.

0 commit comments

Comments
 (0)