0
# Configuration Management
1

2
Functions and utilities for managing viewer settings, runtime configuration, and integration with VS Code settings. The configuration system provides both global defaults and per-call overrides for complete control over the viewing experience.
3

4
## Capabilities
5

6
### Default Settings Management
7

8
Functions for setting and managing global default values that apply to all subsequent display calls.
9

10
```python { .api }
11
def set_defaults(
12
    # UI Settings
13
    glass=None,
14
    tools=None, 
15
    tree_width=None,
16
    # Viewer Settings
17
    axes=None,
18
    axes0=None,
19
    grid=None,
20
    ortho=None,
21
    transparent=None,
22
    default_opacity=None,
23
    black_edges=None,
24
    orbit_control=None,
25
    collapse=None,
26
    ticks=None,
27
    up=None,
28
    explode=None,
29
    # Camera Settings
30
    zoom=None,
31
    reset_camera=None,
32
    pan_speed=None,
33
    rotate_speed=None,
34
    zoom_speed=None,
35
    # Rendering Settings
36
    deviation=None,
37
    angular_tolerance=None,
38
    edge_accuracy=None,
39
    default_color=None,
40
    default_edgecolor=None,
41
    ambient_intensity=None,
42
    direct_intensity=None,
43
    metalness=None,
44
    roughness=None,
45
    render_edges=None,
46
    render_normals=None,
47
    render_mates=None,
48
    render_joints=None,
49
    helper_scale=None,
50
    # Debug Settings
51
    debug=None,
52
    timeit=None,
53
):
54
    """
55
    Set viewer defaults that apply to all subsequent show() calls.
56
    
57
    Parameters accept same values as show() function. Only specified
58
    parameters are updated; others retain their current values.
59
    
60
    UI Settings:
61
        glass (bool): Glass mode overlay (default: False)
62
        tools (bool): Show tools panel (default: True)
63
        tree_width (int): Object tree width (default: 240)
64
    
65
    Viewer Settings:
66
        axes (bool): Show coordinate axes (default: False)
67
        axes0 (bool): Show axes at origin (default: False)
68
        grid (bool): Show grid planes (default: False)
69
        ortho (bool): Orthographic projection (default: True)
70
        transparent (bool): Transparent objects (default: False)
71
        default_opacity (float): Opacity 0-1 (default: 0.5)
72
        black_edges (bool): Black edge color (default: False)
73
        orbit_control (bool): Orbit vs trackball control (default: False)
74
        collapse (Collapse): Tree collapse mode (default: Collapse.LEAVES)
75
        ticks (int): Grid tick density (default: 10)
76
        up (str): Up direction 'Z' or 'Y' (default: "Z")
77
        explode (bool): Explode mode (default: False)
78
    
79
    Camera Settings:
80
        zoom (float): Zoom factor (default: 1.0)
81
        reset_camera (Camera): Camera reset behavior (default: Camera.RESET)
82
        pan_speed (float): Pan sensitivity (default: 1)
83
        rotate_speed (float): Rotation sensitivity (default: 1)
84
        zoom_speed (float): Zoom sensitivity (default: 1)
85
    
86
    Rendering Settings:
87
        deviation (float): Tessellation deviation (default: 0.1)
88
        angular_tolerance (float): Angular tolerance radians (default: 0.2)
89
        edge_accuracy (float): Edge discretization precision
90
        default_color (str): Default mesh color (default: "#e8b024")
91
        default_edgecolor (str): Default edge color (default: "#707070")
92
        ambient_intensity (float): Ambient light (default: 1.0)
93
        direct_intensity (float): Direct light (default: 1.1)
94
        metalness (float): Material metalness (default: 0.3)
95
        roughness (float): Material roughness (default: 0.65)
96
        render_edges (bool): Render edges (default: True)
97
        render_normals (bool): Render normals (default: False)
98
        render_mates (bool): Render assembly mates (default: False)
99
        render_joints (bool): Render build123d joints (default: False)
100
        helper_scale (float): Helper scale factor (default: 1)
101
    
102
    Debug Settings:
103
        debug (bool): Debug info in console (default: False)
104
        timeit (bool): Timing information (default: False)
105
    """
106

107
def get_defaults():
108
    """
109
    Get current default settings dictionary.
110
    
111
    Returns:
112
        dict: All current default settings with their values
113
    """
114

115
def get_default(key):
116
    """
117
    Get a specific default setting value.
118
    
119
    Parameters:
120
        key (str): Setting key name
121
        
122
    Returns:
123
        Any: Current default value for the specified key, or None if not set
124
    """
125

126
def reset_defaults():
127
    """
128
    Reset all defaults to workspace configuration values.
129
    
130
    Clears any programmatically set defaults and reverts to the
131
    values configured in VS Code settings.
132
    """
133
```
134

135
**Usage Examples:**
136

137
```python
138
from ocp_vscode import set_defaults, get_defaults, show, Camera, Collapse
139

140
# Set commonly used defaults
141
set_defaults(
142
    axes=True,
143
    transparent=True,
144
    default_opacity=0.7,
145
    grid=True,  
146
    collapse=Collapse.LEAVES,
147
    reset_camera=Camera.RESET
148
)
149

150
# All subsequent show() calls will use these defaults
151
show(object1)  # Will show with axes, transparency, grid
152
show(object2)  # Same defaults applied
153

154
# Override defaults for specific calls
155
show(object3, axes=False, transparent=False)  # Overrides for this call only
156

157
# Check current defaults
158
current = get_defaults()
159
print(f"Current transparency: {current.get('transparent')}")
160

161
# Get specific default
162
opacity = get_default('default_opacity')
163

164
# Reset to VS Code settings
165
reset_defaults()
166
```
167

168
### Runtime Configuration Control
169

170
Functions for modifying viewer configuration after objects are displayed.
171

172
```python { .api }
173
def set_viewer_config(
174
    # UI Controls
175
    axes=None,
176
    axes0=None,
177
    grid=None,
178
    ortho=None,
179
    transparent=None,
180
    black_edges=None,
181
    explode=None,
182
    # Camera Controls  
183
    zoom=None,
184
    position=None,
185
    quaternion=None,
186
    target=None,
187
    default_edgecolor=None,
188
    default_opacity=None,
189
    # Lighting and Materials
190
    ambient_intensity=None,
191
    direct_intensity=None,
192
    metalness=None,
193
    roughness=None,
194
    # Interface Controls
195
    zoom_speed=None,
196
    pan_speed=None,
197
    rotate_speed=None,
198
    glass=None,
199
    tools=None,
200
    tree_width=None,
201
    collapse=None,
202
    reset_camera=None,
203
    states=None,
204
):
205
    """
206
    Set viewer configuration at runtime without re-tessellating objects.
207
    
208
    Updates the viewer's current display settings immediately. Useful for
209
    interactive adjustment of visual properties after objects are loaded.
210
    
211
    Parameters accept same values as corresponding show() parameters.
212
    Changes take effect immediately in the current viewer session.
213
    """
214
```
215

216
**Usage Examples:**
217

218
```python
219
from ocp_vscode import show, set_viewer_config, Camera
220

221
# Display objects first
222
show(assembly)
223

224
# Then adjust settings interactively
225
set_viewer_config(transparent=True, default_opacity=0.5)
226
set_viewer_config(axes=True, grid=True)
227
set_viewer_config(explode=True)
228

229
# Adjust camera
230
set_viewer_config(zoom=1.5, reset_camera=Camera.CENTER)
231

232
# Adjust lighting
233
set_viewer_config(
234
    ambient_intensity=1.2,
235
    direct_intensity=0.8,
236
    metalness=0.5,
237
    roughness=0.3
238
)
239
```
240

241
### Configuration Query Functions
242

243
Functions for retrieving current configuration states and viewer status.
244

245
```python { .api }
246
def workspace_config(port=None):
247
    """
248
    Get workspace configuration from VS Code settings.
249
    
250
    Parameters:
251
        port (int, optional): Viewer port. Uses get_port() if None.
252
        
253
    Returns:
254
        dict: Current VS Code workspace configuration settings
255
        
256
    Raises:
257
        RuntimeError: If viewer is not running or unreachable
258
    """
259

260
def status(port=None, debug=False):
261
    """
262
    Get current viewer status and UI state.
263
    
264
    Parameters:
265
        port (int, optional): Viewer port. Uses get_port() if None.
266
        debug (bool): Return debug state instead of UI status (default: False)
267
        
268
    Returns:
269
        dict: Current viewer status including UI state, last interactions, etc.
270
        bool: Debug state if debug=True
271
        
272
    Raises:
273
        RuntimeError: If viewer is not running or unreachable
274
    """
275

276
def combined_config(port=None, use_status=True):
277
    """
278
    Get combined configuration merging defaults, workspace settings, and current status.
279
    
280
    Parameters:
281
        port (int, optional): Viewer port. Uses get_port() if None.
282
        use_status (bool): Include current viewer status (default: True)
283
        
284
    Returns:
285
        dict: Complete configuration combining all sources
286
        
287
    Raises:
288
        RuntimeError: If viewer is not running or unreachable
289
    """
290
```
291

292
**Usage Examples:**
293

294
```python
295
from ocp_vscode import workspace_config, status, combined_config
296

297
# Get VS Code settings
298
workspace = workspace_config()
299
print(f"Tree width: {workspace['tree_width']}")
300
print(f"Glass mode: {workspace['glass']}")
301

302
# Get current viewer status  
303
current_status = status()
304
print(f"Last picked object: {current_status.get('lastPick')}")
305

306
# Check if debug mode is active
307
debug_active = status(debug=True)
308

309
# Get complete configuration
310
full_config = combined_config()
311
print(f"Effective transparency: {full_config['transparent']}")
312
print(f"Current collapse mode: {full_config['collapse']}")
313
```
314

315
### Configuration Priority and Merging
316

317
The configuration system follows a priority order for determining effective settings:
318

319
1. **Function call parameters** (highest priority) - Arguments passed to show(), show_object()
320
2. **Python defaults** - Values set via set_defaults()  
321
3. **Viewer status** - Current UI state (if use_status=True)
322
4. **VS Code workspace settings** - Settings configured in VS Code
323
5. **Built-in defaults** (lowest priority) - Hard-coded fallback values
324

325
```python
326
from ocp_vscode import set_defaults, show, workspace_config
327

328
# VS Code setting: transparent=False
329
# Python default: Not set
330
# Function call: transparent=True
331

332
set_defaults(axes=True)  # Set Python default
333

334
# This call will use:
335
# - transparent=True (function parameter - highest priority)
336
# - axes=True (Python default)  
337
# - other settings from VS Code workspace config
338
show(object, transparent=True)
339
```
340

341
### Configuration Validation and Error Handling
342

343
The system validates configuration values and provides helpful error messages:
344

345
```python
346
from ocp_vscode import set_defaults, Camera, Collapse
347

348
# Valid configurations
349
set_defaults(
350
    reset_camera=Camera.RESET,  # Use enum values
351
    collapse=Collapse.LEAVES,
352
    default_opacity=0.5,        # 0-1 range
353
    zoom_speed=1.0             # Positive numbers
354
)
355

356
# The system handles deprecated values with warnings:
357
set_defaults(reset_camera=True)   # Warns: use Camera.RESET instead
358
set_defaults(collapse="1")        # Warns: use Collapse.LEAVES instead
359

360
# Invalid configurations raise errors or print warnings:
361
set_defaults(unknown_setting=True)  # Prints: "'unknown_setting' is unknown config, ignored!"
362
```
363

364
### Environment-Specific Configurations
365

366
Settings can be adapted for different development environments:
367

368
```python
369
from ocp_vscode import set_defaults, Camera, Collapse
370
import os
371

372
# Development environment
373
if os.getenv('DEBUG_MODE'):
374
    set_defaults(
375
        debug=True,
376
        timeit=True,
377
        axes=True,
378
        render_normals=True
379
    )
380

381
# Production/demo environment  
382
elif os.getenv('DEMO_MODE'):
383
    set_defaults(
384
        glass=True,
385
        transparent=True,
386
        default_opacity=0.8,
387
        reset_camera=Camera.RESET,
388
        collapse=Collapse.LEAVES
389
    )
390

391
# Performance testing
392
elif os.getenv('PERF_TEST'):
393
    set_defaults(
394
        parallel=True,
395
        deviation=0.2,        # Lower quality for speed
396
        render_edges=False,   # Faster rendering
397
        timeit=True
398
    )
399
```