@whdigitalbuild/forge-viewer-core

Framework-agnostic Autodesk Forge Viewer library with advanced features

A comprehensive TypeScript library for working with Autodesk Forge Viewer, providing high-level abstractions for common tasks like model loading, coloring, data exchange, and GraphQL queries.

🚀 Features

• ViewerCore - Complete viewer lifecycle management
• ColoringEngine - Advanced element coloring with batching and performance optimization
• DataExchangeClient - GraphQL client for Autodesk AEC Data Model & Data Exchange APIs
• URN Handling - Utilities for URN encoding, decoding, and validation
• ACC URL Parsing - Extract project IDs and file URNs from ACC URLs
• Type-safe - Full TypeScript support with comprehensive type definitions
• Framework-agnostic - Use with any JavaScript framework or vanilla JS

📦 Installation

npm install @whdigitalbuild/forge-viewer-core

🔧 Usage

Initialize Viewer

import { ViewerCore } from '@whdigitalbuild/forge-viewer-core';

const container = document.getElementById('viewer');
const viewerCore = new ViewerCore(container, {
  accessToken: 'your-3-legged-token',
  extensions: ['Autodesk.DocumentBrowser']
});

await viewerCore.initialize();

Load Model

// Load by URN
await viewerCore.loadModel({
  urn: 'dXJuOmFkc2sud2lwcHJvZDpmcy5maWxlOnZmLnlvdXItZmlsZS1pZD92ZXJzaW9uPTE',
  urnType: 'derivative'
});

// Load from ACC URL
await viewerCore.loadModel({
  accUrl: 'https://acc.autodesk.com/docs/files/projects/...'
});

// Load from Data Exchange
await viewerCore.loadModel({
  dataExchangeConfig: {
    projectId: 'b.project-id',
    lineageUrn: 'urn:adsk.wipprod:dm.lineage:...'
  }
});

Element Coloring

import { ColoringEngine } from '@whdigitalbuild/forge-viewer-core';

const viewer = viewerCore.getViewer();
const coloringEngine = new ColoringEngine(viewer);

// Apply colors to elements
coloringEngine.applyColors({
  123: { r: 1, g: 0, b: 0 }, // Red
  456: { r: 0, g: 1, b: 0 }, // Green
  789: { r: 0, g: 0, b: 1 }  // Blue
});

// Clear all colors
coloringEngine.clearColors();

GraphQL Data Exchange

import { DataExchangeClient } from '@whdigitalbuild/forge-viewer-core';

const client = new DataExchangeClient(() => Promise.resolve('your-token'));

// Query elements from Lineage URN (AEC Data Model)
const elements = await client.queryElements(
  'urn:adsk.wipprod:dm.lineage:...',
  `elements {
    results {
      id
      name
      properties {
        name
        value
      }
    }
  }`,
  { projectId: 'b.project-id' }
);

// Get all elements
const allElements = await client.getAllElements('urn:adsk.wipprod:dm.lineage:...');

URN Utilities

import { URNHelper } from '@whdigitalbuild/forge-viewer-core';

// Encode URN
const encoded = URNHelper.encodeBase64Unpadded('urn:adsk.wipprod:fs.file:...');

// Decode URN
const decoded = URNHelper.decodeURN(encoded);

// Validate URN
const isValid = URNHelper.isValidUrn('urn:adsk.wipprod:dm.lineage:...');

// Get URN type
const type = URNHelper.getUrnType('urn:adsk.wipprod:dm.lineage:...'); // 'lineage'

ACC URL Parsing

import { ACCUrlParser } from '@whdigitalbuild/forge-viewer-core';

const urlInfo = ACCUrlParser.parseACCUrl(
  'https://acc.autodesk.com/docs/files/projects/a1b2c3d4...?fileUrn=urn:...'
);

console.log(urlInfo.projectId); // 'a1b2c3d4...'
console.log(urlInfo.fileUrn); // 'urn:...'

📚 API Documentation

ViewerCore

| Method | Description | |--------|-------------| | initialize() | Initialize the viewer | | loadModel(options) | Load a model | | unloadModel(model) | Unload a model | | getViewer() | Get the underlying viewer instance | | setViewMode('3d' \| '2d') | Set view mode | | destroy() | Destroy viewer and cleanup |

ColoringEngine

| Method | Description | |--------|-------------| | applyColors(colorMap) | Apply colors to elements | | applyColor(dbId, color) | Apply color to single element | | clearColors() | Clear all theming colors | | applyGradient(config) | Apply gradient/heatmap coloring |

DataExchangeClient

| Method | Description | |--------|-------------| | queryElements(id, query, vars) | Execute GraphQL query | | getAllElements(id) | Get all elements with properties | | getElementProperties(id, elementIds) | Get properties for specific elements | | getDerivativeUrn(lineageUrn) | Convert Lineage URN to Derivative URN |

🔑 Authentication

All methods require a valid 3-legged OAuth token with data:read scope:

const getToken = async () => {
  // Your token refresh logic
  return 'eyJhbGciOiJIUzI1...';
};

const viewerCore = new ViewerCore(container, {
  accessToken: getToken // Function or string
});

📝 License

MIT © Woh Hup Digital

🤝 Contributing

Issues and pull requests are welcome!

📧 Support

For support, contact Woh Hup Digital team.