XKT Viewer Extension

A Visual Studio Code extension that provides 3D visualization of XKT (xeokit) files directly in the editor.

Features

• 🎯 3D Visualization: View XKT files in an interactive 3D viewer
• 🖱️ Object Selection: Click on objects to view their ID and type information
• 🔄 Auto-rotation: Optional automatic model rotation
• 🎨 Customizable: Configure background color and viewer settings
• 📐 View Controls: Fit to view, reset view, and toggle rotation controls

Installation

From Source

1. Clone the repository:

   git clone <repository-url>
   cd xkt-viewer-extension

2. Install dependencies:

   npm install

3. Compile the extension:

   npm run compile

4. Package to VSIX (optional):

   # Install packaging tool
   npm install --save-dev vsce
   
   # Create VSIX package
   npx vsce package

   This creates a xkt-viewer-0.0.1.vsix file.

5. Install the extension:

   Option A: Install from VSIX:

   • Open VS Code
   • Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
   • Type "Extensions: Install from VSIX..."
   • Select the generated .vsix file

   Option B: Development mode:

   • Press F5 to run the extension in a new Extension Development Host window

Development Setup

1. Open in VS Code:

   code .

2. Run in development mode:

   • Press F5 to launch Extension Development Host
   • Or use Ctrl+Shift+P → "Debug: Start Debugging"

3. Watch mode (for development):

   npm run watch

Usage

Opening XKT Files

1. Right-click method:

   • Right-click on any .xkt file in the Explorer
   • Select "Open with XKT Viewer"

2. Command Palette:

   • Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
   • Type "XKT Viewer: Open Viewer"
   • Select your XKT file

3. From active editor:

   • Open an XKT file in the editor
   • Use the command palette method above

Viewer Controls

• Fit to View: Centers and scales the model to fit the viewport
• Toggle Rotation: Enables/disables automatic model rotation
• Reset View: Returns to the default camera position
• Object Selection: Click on any object to view its ID and type

Configuration

Configure the extension through VS Code settings:

{
  "xktViewer.autoRotate": false,
  "xktViewer.backgroundColor": "#f0f0f0"
}

File Structure

xkt-viewer-extension/
├── src/
│   ├── extension.ts          # Main extension logic
│   └── webview-script.js     # 3D viewer implementation
├── out/                      # Compiled JavaScript output
├── package.json             # Extension manifest
├── tsconfig.json           # TypeScript configuration
└── README.md              # This file

Requirements

• Visual Studio Code 1.74.0 or higher
• Node.js 16.x or higher
• TypeScript 4.9.x or higher

Technologies Used

• xeokit SDK: 3D visualization engine
• VS Code Extension API: Integration with VS Code
• TypeScript: Type-safe development
• WebView API: Embedded 3D viewer

Development

Build Commands

# Compile TypeScript
npm run compile

# Watch mode for development
npm run watch

# Prepare for publishing
npm run vscode:prepublish

# Package extension to VSIX
npx vsce package

Creating a VSIX Package

To create a distributable .vsix file:

1. Install the packaging tool:

   npm install --save-dev vsce

2. Build and package:

   npm run compile
   npx vsce package

3. Result: This creates xkt-viewer-0.0.1.vsix file that can be:

   • Shared with others
   • Installed manually in VS Code
   • Published to the marketplace

Note: You may see warnings about missing repository or license fields - these are optional for local development.

Testing

1. Press F5 to run the extension in debug mode
2. Open a .xkt file in the Extension Development Host
3. Test the viewer functionality

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

[Add your license information here]

Changelog

[Unreleased]

• Added object selection functionality
• Separated webview script from HTML template
• Initial 3D XKT file visualization

Troubleshooting

Common Issues

1. Extension not loading:

   • Ensure VS Code version is 1.74.0 or higher
   • Check that all dependencies are installed

2. XKT file not displaying:

   • Verify the file is a valid XKT format
   • Check browser console for error messages

3. Performance issues:

   • Large XKT files may take time to load
   • Consider the model complexity and size

Getting Help

• Check the Issues page
• Review the VS Code extension development documentation
• Consult the xeokit SDK documentation