An integrated OCP CAD viewer for CadQuery and build123d with visual debugging capabilities
pkg:vscode-extension/ocp-cad-viewer@1.2.x
npx @tessl/cli install tessl/vscode-extension-ocp-cad-viewer@1.2.00
# OCP CAD Viewer
1
2
OCP CAD Viewer is an integrated 3D CAD viewer extension for Visual Studio Code that provides seamless visualization and debugging capabilities for OpenCASCADE (OCP) based projects. It specifically supports CadQuery and build123d libraries, enabling developers to visualize 3D CAD models directly within their development environment with interactive debugging features and comprehensive library management.
3
4
## Package Information
5
6
- **Package Name**: ocp-cad-viewer
7
- **Package Type**: VS Code Extension
8
- **Language**: TypeScript + Python
9
- **Installation**: Install from VS Code Marketplace or `code --install-extension bernhard-42.ocp-cad-viewer`
10
- **Python Library**: `pip install ocp_vscode`
11
12
## Core Imports
13
14
**Python Library (ocp_vscode):**
15
16
```python
17
from ocp_vscode import show, show_object, reset_show, set_port, set_defaults
18
```
19
20
Common display functions:
21
22
```python
23
from ocp_vscode import show, show_object, show_all, show_clear
24
```
25
26
Configuration and debugging:
27
28
```python
29
from ocp_vscode import set_defaults, get_defaults, Camera, Collapse
30
```
31
32
Color management:
33
34
```python
35
from ocp_vscode import ColorMap, set_colormap, get_colormap
36
```
37
38
## Basic Usage
39
40
**VS Code Extension Commands:**
41
42
- **Ctrl+K V** (Cmd+K V on Mac): Open OCP CAD Viewer
43
- Command Palette: "OCP CAD Viewer: Open viewer"
44
- Activity Bar: Click OCP CAD Viewer icon
45
46
**Python Display:**
47
48
```python
49
import cadquery as cq
50
from ocp_vscode import show
51
52
# Create a simple CAD object
53
box = cq.Workplane().box(10, 10, 10)
54
55
# Display in VS Code viewer
56
show(box)
57
```
58
59
**Multiple Objects with Styling:**
60
61
```python
62
from ocp_vscode import show, ColorMap
63
import cadquery as cq
64
65
# Create multiple objects
66
box = cq.Workplane().box(10, 10, 10)
67
cylinder = cq.Workplane().cylinder(5, 20).translate((15, 0, 0))
68
sphere = cq.Workplane().sphere(8).translate((0, 15, 0))
69
70
# Display with custom colors and names
71
show(
72
box, cylinder, sphere,
73
names=["Box", "Cylinder", "Sphere"],
74
colors=ColorMap.tab10(),
75
axes=True,
76
transparent=True
77
)
78
```
79
80
**Interactive Development:**
81
82
```python
83
from ocp_vscode import show_object, reset_show
84
85
# Clear previous objects and add incrementally
86
reset_show()
87
show_object(part1, name="Base", clear=True)
88
show_object(part2, name="Feature", options={"color": (255, 0, 0), "alpha": 0.7})
89
```
90
91
## Architecture
92
93
The OCP CAD Viewer consists of two integrated components:
94
95
- **VS Code Extension (TypeScript)**: Provides the user interface, webview panel, library management, debugging integration, and command palette integration within VS Code
96
- **Python Library (ocp_vscode)**: Handles CAD object tessellation, WebSocket communication, configuration management, and provides the Python API for displaying objects
97
- **Communication Layer**: WebSocket-based communication between the Python library and VS Code extension for real-time visualization updates
98
- **3D Viewer Engine**: three-cad-viewer component provides interactive 3D rendering with orbit/trackball controls, lighting, materials, and object tree navigation
99
- **Library Manager**: Integrated package manager for installing and managing CAD-related Python dependencies (CadQuery, build123d, etc.)
100
101
## Capabilities
102
103
### Visual Display Functions
104
105
Core functions for displaying CAD objects in the VS Code viewer with extensive styling and configuration options.
106
107
```python { .api }
108
def show(*cad_objs, names=None, colors=None, alphas=None, **kwargs): ...
109
def show_object(obj, name=None, options=None, parent=None, clear=False, **kwargs): ...
110
def reset_show(): ...
111
def show_clear(): ...
112
def show_all(variables=None, exclude=None, **kwargs): ...
113
```
114
115
[Visual Display](./visual-display.md)
116
117
### VS Code Extension Commands
118
119
Commands and integrations provided by the VS Code extension for managing the viewer, libraries, and development workflow.
120
121
```typescript { .api }
122
// Command IDs accessible via vscode.commands.executeCommand()
123
"ocpCadViewer.ocpCadViewer" // Open viewer
124
"ocpCadViewer.toggleWatch" // Toggle visual debugging
125
"ocpCadViewer.installLibrary" // Install CAD library
126
"ocpCadViewer.quickstart" // Quick installation
127
"ocpCadViewer.preferences" // Open settings
128
```
129
130
[VS Code Integration](./vscode-integration.md)
131
132
### Configuration Management
133
134
Functions for managing viewer settings, defaults, and runtime configuration with VS Code settings integration.
135
136
```python { .api }
137
def set_defaults(**kwargs): ...
138
def get_defaults(): ...
139
def get_default(key): ...
140
def reset_defaults(): ...
141
def set_viewer_config(**kwargs): ...
142
def workspace_config(port=None): ...
143
def combined_config(port=None, use_status=True): ...
144
def status(port=None, debug=False): ...
145
```
146
147
[Configuration](./configuration.md)
148
149
### Color and Styling
150
151
Color management system with built-in colormaps, custom color generation, and styling utilities for enhanced visualization.
152
153
```python { .api }
154
class ColorMap:
155
@staticmethod
156
def tab10(alpha=1.0, reverse=False): ...
157
@staticmethod
158
def set1(alpha=1.0, reverse=False): ...
159
@staticmethod
160
def golden_ratio(colormap="hsv", alpha=1.0, reverse=False): ...
161
162
def set_colormap(colormap): ...
163
def get_colormap(): ...
164
def unset_colormap(): ...
165
def web_to_rgb(name): ...
166
```
167
168
[Color Management](./color-management.md)
169
170
### Communication and Networking
171
172
WebSocket-based communication functions for connecting the Python library to the VS Code extension viewer.
173
174
```python { .api }
175
def set_port(port): ...
176
def get_port(): ...
177
def send_data(data, port=None, timeit=False): ...
178
def send_command(data, port=None, timeit=False): ...
179
def listener(callback): ...
180
```
181
182
[Communication](./communication.md)
183
184
### Animation System
185
186
Animation framework for creating animated sequences of CAD objects with timeline-based keyframe animation.
187
188
```python { .api }
189
class Animation:
190
def __init__(self, assembly): ...
191
def add_track(self, path, action, times, values): ...
192
def animate(self, speed): ...
193
```
194
195
[Animation](./animation.md)
196
197
198
## Types
199
200
### Core Enums
201
202
```python { .api }
203
class Camera(Enum):
204
RESET = "reset" # Reset camera position, rotation, zoom and target
205
CENTER = "center" # Keep camera settings, look at center
206
KEEP = "keep" # Keep all camera settings
207
208
class Collapse(Enum):
209
NONE = 0 # Expand all nodes
210
LEAVES = 1 # Collapse leaf nodes
211
ALL = 2 # Collapse all nodes
212
ROOT = 3 # Expand root only
213
214
class MessageType(IntEnum):
215
data = 1 # Data message
216
command = 2 # Command message
217
updates = 3 # Update message
218
listen = 4 # Listen message
219
```
220
221
### Configuration Types
222
223
```python { .api }
224
# Display configuration parameters (used in show(), show_object(), set_defaults())
225
DisplayConfig = {
226
# UI Settings
227
"glass": bool, # Glass mode overlay (default: False)
228
"tools": bool, # Show tools (default: True)
229
"tree_width": int, # Object tree width (default: 240)
230
231
# Viewer Settings
232
"axes": bool, # Show axes (default: False)
233
"axes0": bool, # Show axes at origin (default: False)
234
"grid": bool, # Show grid (default: False)
235
"ortho": bool, # Orthographic projection (default: True)
236
"transparent": bool, # Transparent objects (default: False)
237
"default_opacity": float, # Opacity for transparent objects (default: 0.5)
238
"black_edges": bool, # Black edge color (default: False)
239
"orbit_control": bool, # Orbit vs trackball control (default: False)
240
"collapse": Collapse, # Tree collapse mode
241
"explode": bool, # Explode mode (default: False)
242
"ticks": int, # Grid ticks hint (default: 10)
243
"up": str, # Up direction 'Z' or 'Y' (default: "Z")
244
245
# Camera Settings
246
"zoom": float, # Zoom factor (default: 1.0)
247
"position": tuple, # Camera position (x, y, z)
248
"quaternion": tuple, # Camera orientation quaternion (x, y, z, w)
249
"target": tuple, # Camera look-at target (x, y, z)
250
"reset_camera": Camera, # Camera reset mode
251
"pan_speed": float, # Pan speed (default: 1)
252
"rotate_speed": float, # Rotation speed (default: 1)
253
"zoom_speed": float, # Zoom speed (default: 1)
254
255
# Rendering Settings
256
"deviation": float, # Tessellation deviation (default: 0.1)
257
"angular_tolerance": float, # Angular tolerance (default: 0.2)
258
"edge_accuracy": float, # Edge discretization precision
259
"default_color": str, # Default mesh color
260
"default_edgecolor": str, # Default edge color
261
"default_facecolor": str, # Default face color
262
"default_thickedgecolor": str, # Default thick edge color
263
"default_vertexcolor": str, # Default vertex color
264
"ambient_intensity": float, # Ambient light intensity (default: 1.0)
265
"direct_intensity": float, # Direct light intensity (default: 1.1)
266
"metalness": float, # Material metalness (default: 0.3)
267
"roughness": float, # Material roughness (default: 0.65)
268
"render_edges": bool, # Render edges (default: True)
269
"render_normals": bool, # Render normals (default: False)
270
"render_mates": bool, # Render mates for assemblies (default: False)
271
"render_joints": bool, # Render build123d joints (default: False)
272
"parallel": bool, # Parallel tessellation (default: False)
273
"show_parent": bool, # Show parent wireframe (default: False)
274
"helper_scale": float, # Helper scale factor (default: 1)
275
276
# Debug Settings
277
"debug": bool, # Show debug info (default: False)
278
"timeit": bool, # Show timing info (default: False)
279
}
280
```
281
282
### Animation Types
283
284
```python { .api }
285
# Animation action types for add_track()
286
AnimationAction = Literal[
287
"t", # Position vector (3-dim array)
288
"tx", # Translation along x-axis
289
"ty", # Translation along y-axis
290
"tz", # Translation along z-axis
291
"q", # Quaternion rotation (x,y,z,w)
292
"rx", # Rotation around x-axis (degrees)
293
"ry", # Rotation around y-axis (degrees)
294
"rz", # Rotation around z-axis (degrees)
295
]
296
```