0
# VS Code Integration
1

2
VS Code extension commands, views, and integrations that provide the user interface and development workflow features for OCP CAD Viewer. These commands are accessible through the Command Palette, keyboard shortcuts, activity bar, and context menus.
3

4
## Capabilities
5

6
### Core Viewer Commands
7

8
Essential commands for opening and controlling the CAD viewer.
9

10
```typescript { .api }
11
// Primary viewer command - opens the 3D CAD viewer panel
12
"ocpCadViewer.ocpCadViewer"
13

14
// Button-triggered viewer opening (from activity bar)  
15
"ocpCadViewer.openViewer"
16

17
// Toggle visual debugging on/off (status bar button)
18
"ocpCadViewer.toggleWatch"
19

20
// Open viewer preferences/settings
21
"ocpCadViewer.preferences"
22

23
// Toggle output panel visibility
24
"ocpCadViewer.output"
25

26
// Refresh viewer status
27
"ocpCadViewer.refreshStatus"
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
// Open viewer programmatically
34
vscode.commands.executeCommand('ocpCadViewer.ocpCadViewer');
35

36
// Toggle visual debugging
37
vscode.commands.executeCommand('ocpCadViewer.toggleWatch');
38

39
// Open settings
40
vscode.commands.executeCommand('ocpCadViewer.preferences');
41
```
42

43
**Manual Usage:**
44
- **Keyboard**: Ctrl+K V (Cmd+K V on Mac) when editing Python files
45
- **Command Palette**: "OCP CAD Viewer: Open viewer"
46
- **Activity Bar**: Click OCP CAD Viewer icon, then "Open Viewer" button
47

48
### Library Management Commands
49

50
Commands for installing and managing CAD-related Python libraries and dependencies.
51

52
```typescript { .api }
53
// Install specific Python library (cadquery, build123d, etc.)
54
"ocpCadViewer.installLibrary"
55

56
// Install the ocp_vscode Python library specifically
57
"ocpCadViewer.installPythonModule"
58

59
// Quick installation workflow for cadquery or build123d
60
"ocpCadViewer.quickstart"
61

62
// Refresh the library list in Library Manager
63
"ocpCadViewer.refreshLibraries"
64

65
// Install Jupyter extension for notebook support
66
"ocpCadViewer.installJupyterExtension"
67
```
68

69
**Usage Examples:**
70

71
```python
72
# After installation, libraries can be imported:
73
import cadquery as cq
74
import build123d as bd
75
from ocp_vscode import show
76

77
# Create and display objects
78
box = cq.Workplane().box(10, 10, 10)
79
show(box)
80
```
81

82
**Manual Usage:**
83
- **Library Manager Panel**: Click install buttons next to libraries
84
- **Command Palette**: "OCP CAD Viewer: Install library" 
85
- **Quickstart**: "OCP CAD Viewer: Quickstart installation"
86

87
### Development Workflow Commands
88

89
Commands that enhance the development experience with code snippets and examples.
90

91
```typescript { .api }
92
// Install VS Code snippets for CAD libraries
93
"ocpCadViewer.installVscodeSnippets"
94

95
// Paste import code snippet for installed libraries
96
"ocpCadViewer.pasteSnippet"
97

98
// Download example files for specific libraries
99
"ocpCadViewer.downloadExamples"
100
```
101

102
**Usage Examples:**
103

104
After installing snippets, use these prefixes in Python files:
105
- **bd_p**: BuildPart context
106
- **bd_s**: BuildSketch context  
107
- **bd_bp**: Part with alignment
108
- **bd_exsk**: Extrude sketch pattern
109

110
```python
111
# Type 'bd_p' and press Tab to get:
112
with BuildPart() as partname:
113
    # cursor positioned here
114
```
115

116
### Activity Bar Integration
117

118
The extension adds an activity bar container with two integrated panels.
119

120
```typescript { .api }
121
// Activity Bar Container
122
interface ActivityBarContainer {
123
    id: "ocpCadHome";
124
    title: "OCP CAD Viewer";
125
    icon: "resources/ocp-icon.svg";
126
}
127

128
// Main panels in the activity bar
129
interface ViewerPanels {
130
    // Shows viewer status, installed libraries, open/paste buttons
131
    "ocpCadStatus": "Viewer Manager";
132
    
133
    // Shows available libraries with install buttons  
134
    "ocpCadSetup": "Library Manager";
135
}
136
```
137

138
**Panel Features:**
139

140
**Viewer Manager Panel:**
141
- Current viewer status (running/stopped)
142
- Port information
143
- Quick action buttons (Open, Paste, Settings)
144
- Visual debugging toggle
145
- Installed library status
146

147
**Library Manager Panel:**
148
- Available CAD libraries (CadQuery, build123d, etc.)
149
- Installation status indicators
150
- Install/reinstall buttons
151
- Example download options
152
- Refresh button
153

154
### Keyboard Shortcuts
155

156
Default keyboard bindings provided by the extension.
157

158
```typescript { .api }
159
interface KeyBindings {
160
    // Open OCP CAD Viewer (when Python file is active)
161
    "ctrl+k v": "ocpCadViewer.ocpCadViewer";    // Windows/Linux
162
    "cmd+k v": "ocpCadViewer.ocpCadViewer";     // macOS
163
    
164
    // Context: only active when editing Python files
165
    when: "editorTextFocus && editorLangId=='python'";
166
}
167
```
168

169
### Configuration Settings
170

171
VS Code settings that control extension behavior and viewer appearance.
172

173
```typescript { .api }
174
interface ExtensionSettings {
175
    // View settings (OcpCadViewer.view.*)
176
    "OcpCadViewer.view.tree_width": number;        // Tree panel width (240)
177
    "OcpCadViewer.view.glass": boolean;            // Glass mode (true)
178
    "OcpCadViewer.view.tools": boolean;            // Show toolbar (true)
179
    "OcpCadViewer.view.dark": boolean;             // Dark theme (false)
180
    "OcpCadViewer.view.orbit_control": boolean;    // Orbit control (false)
181
    "OcpCadViewer.view.up": "Z" | "Y" | "L";      // Up direction ("Z")
182
    "OcpCadViewer.view.rotate_speed": number;      // Rotation speed (1)
183
    "OcpCadViewer.view.zoom_speed": number;        // Zoom speed (1)
184
    "OcpCadViewer.view.pan_speed": number;         // Pan speed (1)
185
    "OcpCadViewer.view.axes": boolean;             // Show axes (false)
186
    "OcpCadViewer.view.axes0": boolean;            // Show origin axes (true)
187
    "OcpCadViewer.view.black_edges": boolean;      // Black edges (false)
188
    "OcpCadViewer.view.grid_XY": boolean;          // XY grid (false)
189
    "OcpCadViewer.view.grid_YZ": boolean;          // YZ grid (false)
190
    "OcpCadViewer.view.grid_XZ": boolean;          // XZ grid (false)
191
    "OcpCadViewer.view.collapse": string;          // Tree collapse ("leaves")
192
    "OcpCadViewer.view.ortho": boolean;            // Orthographic (true)
193
    "OcpCadViewer.view.ticks": number;             // Grid ticks (10)
194
    "OcpCadViewer.view.transparent": boolean;      // Transparency (false)
195
    "OcpCadViewer.view.default_opacity": number;   // Default opacity (0.5)
196
    "OcpCadViewer.view.explode": boolean;          // Explode mode (false)
197
    
198
    // Render settings (OcpCadViewer.render.*)
199
    "OcpCadViewer.render.angular_tolerance": number;    // Angular tolerance (0.2)
200
    "OcpCadViewer.render.deviation": number;            // Deviation (0.1)
201
    "OcpCadViewer.render.default_color": string;        // Default color ("#e8b024")
202
    "OcpCadViewer.render.default_edgecolor": string;    // Edge color ("#707070")
203
    "OcpCadViewer.render.default_thickedgecolor": string; // Thick edge ("MediumOrchid")
204
    "OcpCadViewer.render.default_facecolor": string;    // Face color ("Violet")
205
    "OcpCadViewer.render.default_vertexcolor": string;  // Vertex color ("MediumOrchid")
206
    "OcpCadViewer.render.ambient_intensity": number;    // Ambient light (1)
207
    "OcpCadViewer.render.direct_intensity": number;     // Direct light (1.1)
208
    "OcpCadViewer.render.metalness": number;            // Metalness (0.3)
209
    "OcpCadViewer.render.roughness": number;            // Roughness (0.65)
210
    
211
    // Advanced settings (OcpCadViewer.advanced.*)
212
    "OcpCadViewer.advanced.watchCommands": string;      // Debug watch command
213
    "OcpCadViewer.advanced.watchByDefault": boolean;    // Default debug state (true)
214
    "OcpCadViewer.advanced.quickstartCommands": object; // Install command templates
215
    "OcpCadViewer.advanced.installCommands": object;    // Library install commands
216
    "OcpCadViewer.advanced.codeSnippets": object;       // Import code snippets
217
    "OcpCadViewer.advanced.exampleDownloads": object;   // Example download URLs
218

219
    // Snippet settings (OcpCadViewer.snippets.*)
220
    "OcpCadViewer.snippets.dotVscodeSnippets": object;  // VS Code snippet definitions
221
}
222
```
223

224
**Settings Usage:**
225

226
```json
227
// In VS Code settings.json
228
{
229
    "OcpCadViewer.view.glass": true,
230
    "OcpCadViewer.view.axes": true,  
231
    "OcpCadViewer.view.transparent": true,
232
    "OcpCadViewer.render.deviation": 0.05,
233
    "OcpCadViewer.advanced.watchByDefault": false
234
}
235
```
236

237
### Debug Integration
238

239
The extension integrates with VS Code's debugging system to provide visual debugging capabilities.
240

241
```typescript { .api }
242
interface DebugIntegration {
243
    // Automatic execution during debug sessions
244
    debugAdapter: {
245
        // Triggers when debugger stops at breakpoint  
246
        onStopped: () => {
247
            // Executes watchCommands setting (default: "from ocp_vscode import show_all; show_all(locals())")
248
            executeWatchCommand();
249
        };
250
        
251
        // Visual debugging state management
252
        watchingState: boolean; // Controlled by toggleWatch command
253
    };
254
}
255
```
256

257
**Debug Workflow:**
258

259
1. Set breakpoints in Python CAD code
260
2. Start debugging (F5)
261
3. When debugger stops, viewer automatically shows all CAD objects in current scope
262
4. Continue debugging to see objects at each breakpoint
263
5. Toggle visual debugging on/off with status bar button
264

265
### Status Bar Integration
266

267
The extension adds a status bar item showing the current visual debugging state.
268

269
```typescript { .api }
270
interface StatusBarItem {
271
    text: "OCP:on" | "OCP:off";  // Current visual debugging state
272
    tooltip: string;              // Descriptive tooltip
273
    command: "ocpCadViewer.toggleWatch"; // Click action
274
    alignment: "Left";            // Status bar position
275
}
276
```
277

278
**Status Indication:**
279
- **"OCP:on"**: Visual debugging enabled (shows objects at breakpoints)
280
- **"OCP:off"**: Visual debugging disabled (no automatic object display)
281

282
### File Association and Context
283

284
The extension activates and provides features based on file context.
285

286
```typescript { .api }
287
interface FileContext {
288
    // Extension activates when these commands are executed
289
    activationEvents: [
290
        "onCommand:ocpCadViewer.ocpCadViewer"
291
    ];
292
    
293
    // Keyboard shortcuts only work in Python files
294
    pythonFileContext: "editorTextFocus && editorLangId=='python'";
295
    
296
    // Supported file types for CAD development
297
    supportedFiles: [
298
        "*.py",     // Python files
299
        "*.ipynb"   // Jupyter notebooks
300
    ];
301
}
302
```