0
# Visual Display Functions
1

2
Core functions for displaying CAD objects in the VS Code viewer with extensive styling, configuration options, and interactive features. These functions provide the primary interface for visualizing 3D CAD models during development and debugging.
3

4
## Capabilities
5

6
### Primary Display Function
7

8
The main function for displaying CAD objects with comprehensive configuration options.
9

10
```python { .api }
11
def show(
12
    *cad_objs,
13
    names=None,
14
    colors=None, 
15
    alphas=None,
16
    port=None,
17
    progress="-+c",
18
    # UI Configuration
19
    glass=None,
20
    tools=None,
21
    tree_width=None,
22
    # Viewer Configuration  
23
    axes=None,
24
    axes0=None,
25
    grid=None,
26
    ortho=None,
27
    transparent=None,
28
    default_opacity=None,
29
    black_edges=None,
30
    orbit_control=None,
31
    collapse=None,
32
    explode=None,
33
    ticks=None,
34
    up=None,
35
    # Camera Configuration
36
    zoom=None,
37
    position=None,
38
    quaternion=None, 
39
    target=None,
40
    reset_camera=None,
41
    pan_speed=None,
42
    rotate_speed=None,
43
    zoom_speed=None,
44
    # Rendering Configuration
45
    deviation=None,
46
    angular_tolerance=None,
47
    edge_accuracy=None,
48
    default_color=None,
49
    default_edgecolor=None,
50
    default_facecolor=None,
51
    default_thickedgecolor=None,
52
    default_vertexcolor=None,
53
    ambient_intensity=None,
54
    direct_intensity=None,
55
    metalness=None,
56
    roughness=None,
57
    render_edges=None,
58
    render_normals=None,
59
    render_mates=None,
60
    render_joints=None,
61
    parallel=None,
62
    show_parent=None,
63
    helper_scale=None,
64
    # Debug Configuration
65
    debug=None,
66
    timeit=None,
67
    _force_in_debug=False,
68
):
69
    """
70
    Show CAD objects in Visual Studio Code viewer.
71
    
72
    Parameters:
73
        *cad_objs: All CAD objects to be shown as positional parameters.
74
                   Supports CadQuery objects, build123d objects, OpenCASCADE shapes,
75
                   assemblies, sketches, and lists/tuples of objects.
76
        
77
        names (list, optional): List of names for the cad_objs.
78
                               Must have same length as cad_objs.
79
                               
80
        colors (list or ColorMap, optional): List of colors for the cad_objs.
81
                                           Colors can be RGB tuples (0-1), RGBA tuples, 
82
                                           web color names, or hex strings.
83
                                           Can also be ColorMap instance for automatic colors.
84
                                           
85
        alphas (list, optional): List of alpha (transparency) values for the cad_objs.
86
                                Must have same length as cad_objs. Values 0-1.
87
                                
88
        port (int, optional): The port the viewer listens to.
89
                             Typically use set_port() instead.
90
                             
91
        progress (str, optional): Progress indicator characters (default: "-+c").
92
                                 "-": reference, "+": tessellated, "c": from cache.
93
                                 Use None or "" to disable progress indication.
94
    
95
    UI Configuration:
96
        glass (bool): Use glass mode where tree is overlay over CAD object (default: False)
97
        tools (bool): Show tools panel (default: True)  
98
        tree_width (int): Width of the object tree panel (default: 240)
99
    
100
    Viewer Configuration:
101
        axes (bool): Show coordinate axes (default: False)
102
        axes0 (bool): Show axes at origin (0,0,0) (default: False)
103
        grid (bool): Show grid planes (default: False)
104
        ortho (bool): Use orthographic projection (default: True)
105
        transparent (bool): Show objects as transparent (default: False)
106
        default_opacity (float): Opacity for transparent objects 0-1 (default: 0.5)
107
        black_edges (bool): Show edges in black color (default: False)
108
        orbit_control (bool): Use orbit control instead of trackball (default: False)
109
        collapse (Collapse): Tree collapse mode (default: Collapse.LEAVES)
110
        explode (bool): Turn on explode mode (default: False)
111
        ticks (int): Grid tick density hint (default: 10)
112
        up (str): Up direction 'Z' or 'Y' for camera (default: "Z")
113
    
114
    Camera Configuration:
115
        zoom (float): Zoom factor (default: 1.0)
116
        position (tuple): Camera position (x, y, z)
117
        quaternion (tuple): Camera orientation quaternion (x, y, z, w)
118
        target (tuple): Camera look-at target (x, y, z)
119
        reset_camera (Camera): Camera reset behavior (default: Camera.RESET)
120
        pan_speed (float): Mouse pan sensitivity (default: 1)
121
        rotate_speed (float): Mouse rotation sensitivity (default: 1)  
122
        zoom_speed (float): Mouse zoom sensitivity (default: 1)
123
    
124
    Rendering Configuration:
125
        deviation (float): Tessellation linear deflection (default: 0.1)
126
        angular_tolerance (float): Tessellation angular tolerance in radians (default: 0.2)
127
        edge_accuracy (float): Edge discretization precision
128
        default_color (str): Default mesh color (default: "#e8b024")
129
        default_edgecolor (str): Default edge color (default: "#707070")
130
        default_facecolor (str): Default face color (default: "Violet")
131
        default_thickedgecolor (str): Default thick edge color (default: "MediumOrchid")
132
        default_vertexcolor (str): Default vertex color (default: "MediumOrchid")
133
        ambient_intensity (float): Ambient light intensity (default: 1.0)
134
        direct_intensity (float): Direct light intensity (default: 1.1)
135
        metalness (float): Material metalness property (default: 0.3)
136
        roughness (float): Material roughness property (default: 0.65)
137
        render_edges (bool): Render object edges (default: True)
138
        render_normals (bool): Render surface normals (default: False)
139
        render_mates (bool): Render assembly mates (default: False)
140
        render_joints (bool): Render build123d joints (default: False)
141
        parallel (bool): Use parallel tessellation (default: False)
142
        show_parent (bool): Render parent wireframe for sub-objects (default: False)
143
        helper_scale (float): Scale factor for helpers/annotations (default: 1)
144
    
145
    Debug Configuration:
146
        debug (bool): Show debug info in browser console (default: False)
147
        timeit (bool): Show timing information levels 0-3 (default: False)
148
    
149
    Returns:
150
        Communication result from viewer
151
    """
152
```
153

154
**Usage Examples:**
155

156
```python
157
import cadquery as cq
158
from ocp_vscode import show, ColorMap, Camera, Collapse
159

160
# Basic display
161
box = cq.Workplane().box(10, 10, 10)
162
show(box)
163

164
# Multiple objects with names and colors
165
box = cq.Workplane().box(10, 10, 10)
166
cylinder = cq.Workplane().cylinder(5, 20).translate((15, 0, 0))
167
show(box, cylinder, names=["Box", "Cylinder"], colors=["red", "blue"])
168

169
# Using colormap for automatic colors  
170
objects = [cq.Workplane().box(i, i, i).translate((i*12, 0, 0)) for i in range(1, 6)]
171
show(*objects, colors=ColorMap.tab10(), axes=True)
172

173
# Advanced configuration
174
show(
175
    assembly,
176
    transparent=True,
177
    default_opacity=0.7,
178
    axes=True,
179
    grid=True,
180
    reset_camera=Camera.RESET,
181
    collapse=Collapse.LEAVES,
182
    render_mates=True,
183
    deviation=0.05,  # Higher quality tessellation
184
    ambient_intensity=1.2
185
)
186
```
187

188
### Incremental Display Function
189

190
Function for building up visualizations incrementally, useful for interactive development and step-by-step construction.
191

192
```python { .api }
193
def show_object(
194
    obj,
195
    name=None,
196
    options=None,
197
    parent=None,
198
    clear=False,
199
    port=None,
200
    progress="-+c",
201
    **kwargs  # All configuration parameters from show()
202
):
203
    """
204
    Incrementally show CAD objects in Visual Studio Code viewer.
205
    
206
    Parameters:
207
        obj: The CAD object to be shown. Supports same object types as show().
208
        
209
        name (str, optional): Name for the CAD object in the viewer tree.
210
        
211
        options (dict, optional): Styling options for the object.
212
                                 Format: {"alpha": 0.5, "color": (64, 164, 223)}
213
                                 alpha: 0-1, color: RGB tuple (0-255) or (0-1)
214
                                 
215
        parent (object, optional): Parent object to show with alpha=0.25.
216
                                  Useful for showing context (e.g., parent solid 
217
                                  when displaying faces/edges).
218
                                  
219
        clear (bool): Clear the object stack before adding this object.
220
                     Typically used for the first object in a sequence.
221
                     
222
        port (int, optional): Viewer port. Use set_port() instead.
223
        
224
        progress (str, optional): Progress indicator (default: "-+c").
225
        
226
        **kwargs: All configuration parameters from show() function.
227
    
228
    Returns:
229
        Communication result from viewer
230
    """
231
```
232

233
**Usage Examples:**
234

235
```python
236
from ocp_vscode import show_object, reset_show
237

238
# Start fresh and add objects incrementally
239
reset_show()
240
show_object(base_part, name="Base", clear=True)
241
show_object(feature1, name="Feature 1", options={"color": (255, 0, 0), "alpha": 0.8})
242
show_object(feature2, name="Feature 2", options={"color": (0, 255, 0)})
243

244
# Show sub-objects with parent context
245
edge = part.edges().filter_by(GeomType.CIRCLE)[0] 
246
show_object(edge, name="Selected Edge", parent=part, clear=True)
247

248
# Interactive workflow
249
for i, face in enumerate(part.faces()):
250
    show_object(
251
        face, 
252
        name=f"Face {i}",
253
        clear=(i == 0),  # Clear on first iteration
254
        options={"alpha": 0.6}
255
    )
256
    input(f"Press Enter to show face {i+1}...")
257
```
258

259
### Display Management Functions
260

261
Functions for controlling and clearing the display state.
262

263
```python { .api }
264
def reset_show():
265
    """
266
    Reset the incremental show object stack.
267
    
268
    Clears all objects that have been added via show_object() calls,
269
    preparing for a fresh set of incremental additions.
270
    """
271

272
def show_clear():
273
    """
274
    Clear the viewer display completely.
275
    
276
    Removes all objects from the viewer and resets the display state.
277
    """
278

279
def show_all(variables=None, exclude=None, **kwargs):
280
    """
281
    Show all CAD objects from local variables (used in debugging).
282
    
283
    Automatically detects and displays CAD objects from the current scope.
284
    Typically called during debugging sessions via VS Code's visual debugging feature.
285
    
286
    Parameters:
287
        variables (dict, optional): Variable dictionary to search.
288
                                   Defaults to caller's locals().
289
                                   
290
        exclude (list, optional): List of variable names to exclude from display.
291
        
292
        **kwargs: All configuration parameters from show() function.
293
    
294
    Returns:
295
        Communication result from viewer
296
    """
297
```
298

299
**Usage Examples:**
300

301
```python
302
from ocp_vscode import show_all, reset_show, show_clear
303

304
# Clear everything
305
show_clear()
306

307
# Reset incremental stack
308
reset_show()
309

310
# Debug mode - show all CAD objects in current scope
311
box = cq.Workplane().box(10, 10, 10)  
312
cylinder = cq.Workplane().cylinder(5, 20)
313
sphere = cq.Workplane().sphere(8)
314

315
# This will automatically find and display box, cylinder, sphere
316
show_all(exclude=["temp_var"])
317

318
# Or show all with configuration
319
show_all(axes=True, transparent=True, collapse=Collapse.ROOT)
320
```
321

322
### Display Progress Indication
323

324
The progress parameter in display functions provides visual feedback during tessellation:
325

326
- **"-"**: Object is referenced (already tessellated)
327
- **"+"**: Object is being tessellated
328
- **"c"**: Object loaded from tessellation cache
329

330
```python
331
# Show detailed progress
332
show(complex_assembly, progress="-+c")
333

334
# Disable progress indication
335
show(objects, progress="")
336

337
# Custom progress characters
338
show(objects, progress="123")  # Use 1, 2, 3 as progress indicators
339
```