Viewer API

Autodesk APS Viewer & Edit2D Development

CRITICAL: The Case Study viewer is the primary user experience (85% of interaction time). Quality is non-negotiable. This skill documents proven patterns for the Autodesk Viewer JavaScript API.

MANDATORY: Query Context7 FIRST

BEFORE writing any Viewer or Edit2D code, ALWAYS query Context7:

Library ID: /websites/aps_autodesk_en_viewer_v7

How to Query

// Step 1: Resolve library (if needed)
mcp__context7__resolve-library-id({
  libraryName: "Autodesk Viewer",
  query: "your specific question"
})

// Step 2: Query docs
mcp__context7__query-docs({
  libraryId: "/websites/aps_autodesk_en_viewer_v7",
  query: "Edit2D PolygonPath setEllipseArc circle shape"  // Be specific!
})

Why This is Mandatory

Autodesk's documentation is scattered across:

• Official docs (incomplete for Edit2D)
• Stack Overflow answers
• GitHub issues
• Kean Walmsley's blog posts
• Autodesk forums

Context7 has aggregated this knowledge. We wasted hours trying Shape.fromSVG() with arc commands when PolygonPath.setEllipseArc() was documented in Context7 all along.

Case Study Viewer Architecture

Edit2D Shape Classes

Native Classes (USE THESE)

Edit2D provides native classes for programmatic shape creation. Always prefer these over string-based methods.

Creating True Circles

IMPORTANT: Edit2D has NO Circle class. Circles are PolygonPath with arc segments:

const Edit2D = window.Autodesk?.Edit2D

// 1. Create path with 2 diametrically opposite points
const polygonPath = new Edit2D.PolygonPath([
  { x: cx - radius, y: cy },  // Left point
  { x: cx + radius, y: cy }   // Right point
])

// 2. Define arc parameters
const params = new Edit2D.EllipseArcParams()
params.rx = radius
params.ry = radius
params.rotation = 0
params.largeArcFlag = false  // Semicircle is not "large"
params.sweepFlag = true      // Clockwise

// 3. Apply to both segments (top + bottom semicircles)
polygonPath.setEllipseArc(0, params)  // Top arc
polygonPath.setEllipseArc(1, params)  // Bottom arc

// 4. Style and add
polygonPath.style.lineColor = '#000000'
ctx.addShape(polygonPath)

Creating Rectangles

const polygon = new Edit2D.Polygon([
  { x: x, y: y },           // Top-left
  { x: x + w, y: y },       // Top-right
  { x: x + w, y: y + h },   // Bottom-right
  { x: x, y: y + h }        // Bottom-left
])

Creating Lines

const polyline = new Edit2D.Polyline([
  { x: x1, y: y1 },
  { x: x2, y: y2 }
])

KNOWN PITFALLS

Shape.fromSVG() Does NOT Support Arcs

// ❌ WRONG - produces "Inf or NaN" errors
const shape = Edit2D.Shape.fromSVG(`<path d="M 0 50 A 50 50 0 1 0 100 50..." />`)

// ✅ CORRECT - use native PolygonPath.setEllipseArc()
const shape = new Edit2D.PolygonPath([...])
shape.setEllipseArc(0, params)

Polygon Circle Approximation is Ugly

// ❌ WRONG - 16-sided polygon looks jagged
const sides = 16
const points = []
for (let i = 0; i < sides; i++) {
  const angle = (i / sides) * Math.PI * 2
  points.push({ x: cx + Math.cos(angle) * r, y: cy + Math.sin(angle) * r })
}
const polygon = new Edit2D.Polygon(points)

// ✅ CORRECT - use PolygonPath.setEllipseArc() for smooth circles

Coordinate System

Edit2D uses "page coordinates" which are the same as MarkupsCore:

• Origin (0,0) is typically at drawing center
• Conversion to/from DWG model coords requires getPageToModelTransform()

// Page coords → DWG model coords
const transform = viewer.model.getPageToModelTransform(0)
const modelPoint = new THREE.Vector3(pageX, pageY, 0).applyMatrix4(transform)

// DWG model coords → Page coords
const inverse = transform.clone().invert()
const pagePoint = new THREE.Vector3(dwgX, dwgY, 0).applyMatrix4(inverse)

Unit Scaling for Symbols

Product symbols are defined in mm. Convert to page units:

const MM_TO_METERS = 0.001
const mmToPageUnits = MM_TO_METERS / (modelUnitScale * pageToModelScale)
const radiusInPageUnits = radiusMm * mmToPageUnits

Viewer Extensions

Edit2D Extension

// Load extension
await viewer.loadExtension('Autodesk.Edit2D')
const edit2d = viewer.getExtension('Autodesk.Edit2D')

// Initialize context
edit2d.registerDefaultTools()
const ctx = edit2d.defaultContext

// Add shapes to layer
ctx.addShape(shape)
ctx.removeShape(shape)
ctx.clearLayer()

Selection Events

const selectionEvents = window.Autodesk?.Edit2D?.Selection?.Events
ctx.selection.addEventListener(
  selectionEvents.SELECTION_CHANGED,
  () => {
    const selected = ctx.selection.getSelectedShapes()
    // Handle selection...
  }
)

Quick Reference: Context7 Queries

Implementation Checklist

Before implementing any Viewer/Edit2D feature:

• Query Context7 with specific terms
• Check if native Edit2D class exists (Polygon, Polyline, PolygonPath)
• Avoid string-based parsing (fromSVG) for complex shapes
• Handle coordinate system transformations
• Test with actual marker placement
• Verify no console errors (especially "Inf or NaN")

See Also

• Case Study feature: docs/features/case-study.md
• Edit2D Context7 docs: /websites/aps_autodesk_en_viewer_v7
• Component: src/components/case-study-viewer/