3D Viewer for VS Code

A read-only 3D model preview built with TypeScript and Three.js. Open a model directly in an editor tab, or use 3D Viewer: Open Model from the Command Palette or Explorer context menu.

Get started

Requires VS Code 1.100 or newer, including VS Code Insiders.

1. Install 3D Viewer (extension ID: logicossoftware.logicos-3d-viewer). For a local package, run Extensions: Install from VSIX… and select logicos-3d-viewer-0.9.0.vsix.
2. Open an OBJ, GLB, glTF, STL, or PLY file, or run 3D Viewer: Open Model from the Command Palette.
3. Drag to orbit, right-drag to pan, and scroll to zoom. Animated models show clip selection and playback controls.

If another extension owns the format, right-click the editor tab and choose Reopen Editor With… → 3D Viewer. The same menu lets you return to the text editor.

Screenshots

Select an animation clip, scrub to a pose, and control playback speed and looping.

Inspect triangle edges with the wireframe toggle and use the grid and axes for orientation.

The viewer follows your VS Code color theme.

Supported formats

The viewer provides orbit, pan, zoom, fit, wireframe, grid, coordinate axes, auto-rotation, model statistics, and original model dimensions. Geometry is centered and scaled for display; source files are never changed. Dimensions use the file's coordinates, with no assumed physical unit.

• The compact toolbar uses Microsoft Codicons and follows your VS Code theme, including light and high-contrast themes. Hover or focus an action for its tooltip and shortcut.
• Tab enters the toolbar; Left/Right move between actions; Home/End jump to the first/last action. Enter/Space activates the focused action.
• Drag to orbit; right-drag to pan; scroll to zoom.
• F fits the model, W toggles wireframe, and G toggles the grid when the viewport has focus.
• Use the view selector for front, back, left, right, top, bottom, or three-quarter views. These use a perspective camera.
• Animated GLB/glTF files show a clip selector and timeline. Scrubbing pauses at the selected pose; the toolbar play/pause button controls playback. Choose 0.25×–2× speed and toggle looping.
• Try cube-animated.glb to switch between Turntable and Pulse animations; cube-draco.glb and cube-meshopt.glb include the same animations with compressed geometry.
• Reload refreshes the model and all companion files. Saving the model file also refreshes its preview.
• Camera position, display toggles, selected animation, playback position, speed, and loop settings survive reloads and webview recreation. Rendering pauses while hidden and runs on demand while idle.

Keep companion files in the model's folder or its subfolders, preserving their relative paths:

model/
  scene.obj
  materials/
    scene.mtl
    textures/
      albedo.png

MTL texture references resolve relative to the MTL file. glTF references resolve relative to the glTF file. Parent folders, absolute filesystem paths, and remote URLs are blocked. All viewer code is bundled locally; no CDN, backend, or runtime internet connection is required.

Development

Requires Node.js 22 or newer. Run npm install, open this repository in VS Code or Insiders, then press F5 and select Run 3D Viewer. The build task opens an Extension Development Host with the sample models. Try cube.obj, cube-animated.glb, cube-draco.glb, or cube-meshopt.glb from the sample folder.

npm run build       # Bundle extension and webview
npm run watch       # Rebuild source changes
npm run check       # TypeScript, unit tests, and build
npm run benchmark   # Compare CPU work on a synthetic 10,000-mesh scene
npm run samples     # Regenerate sample assets, including animation and compression
npm run preview     # Local browser harness at http://127.0.0.1:4173
npm run package     # Produce logicos-3d-viewer-0.9.0.vsix

Install a generated VSIX with VS Code's Extensions: Install from VSIX… command. Packaging does not publish to the Marketplace.

Browser tests use Playwright:

npx playwright install chromium
npm run test:browser
npm run test:browser:production  # Also verify minified decoder workers

Alternatively set PLAYWRIGHT_CHANNEL=chrome or msedge to use an installed browser. Tests cover actual WebGL rendering, textures, animations, error handling, reloads, local resource restrictions, and narrow panels. Screenshots are written to .test-output/.

On Windows, npm run test:extension uses the installed code executable; npm run test:insiders uses code-insiders. Both use isolated test profiles to verify activation, command registration, and custom editor opening for all five formats plus animated and compressed samples. They do not use your normal VS Code profile.

For manual testing in Insiders, open this repository with code-insiders . and press F5. Open cube-animated.glb in the development window to try the playback controls.

The benchmark compares the previous and current bounds/normalization work and wireframe updates, using 10,000 meshes sharing 32 materials. It reports warmed-up median CPU times; it excludes file parsing, texture loading, and GPU rendering, so it is not an overall load-time or FPS benchmark. Bounds are reused after validation, and display settings use a cached list of unique materials.

Architecture

• src/extension.ts: VS Code read-only custom editor, file selection, resource permissions, and reload notifications.
• src/panelHtml.ts: webview markup with a nonce-based content security policy.
• src/webview/loadModel.ts: Three.js format loaders and companion materials.
• src/webview/main.ts: viewport, lighting, controls, state, and lifecycle.
• src/webview/animationPlayer.ts: clip selection, timeline, playback, and pose restoration.
• src/webview/cameraViews.ts: standard camera directions.
• src/webview/decoders.ts: bundled Draco/Meshopt decoders and permitted decoder resources.
• src/webview/modelUtils.ts: bounds, camera fitting, statistics, and GPU cleanup.
• src/webview/assetUrls.ts: local resource resolution and restrictions.

TypeScript is the initial choice because VS Code's extension host and webview already run JavaScript, and Three.js supplies loaders for these formats. Go or Rust would add a second toolchain and per-platform binaries without helping this first viewer. A Rust/WASM geometry worker would be worth considering for measured parsing bottlenecks; a native converter could later add CAD formats. There is no need for a separate service yet.

The implementation follows the VS Code custom editor API, webview guidance, and Three.js loaders.

Current limits

• This is a viewer; model editing, export, measurements, and material editing are not implemented.
• KTX2/Basis textures are not supported yet; use PNG or JPEG textures. The bundled upstream Basis decoder currently requires broader script execution permissions than this webview allows (upstream issue).
• FBX, 3MF, USD, STEP, and IGES are not supported yet.
• Only the default glTF scene is exposed. Animation clips play individually; blending, skeleton inspection, and morph-target controls are not implemented.
• WebGL 2 is required. Draco decoding runs in workers, but most parsing still runs on the webview thread. Very large models can temporarily stall the UI; streaming is not implemented.
• Remote/virtual workspace URIs use VS Code's resource API, but only local Windows operation has been tested so far.