Core API — CadViewer

// the main viewer class that orchestrates parsing, rendering, and interaction

The CadViewer class is the central entry point. It manages the full lifecycle: canvas setup, file loading, rendering, user interaction, and resource cleanup.

Constructor

import { CadViewer } from '@cadview/core';

const viewer = new CadViewer(canvas: HTMLCanvasElement, options?: CadViewerOptions);

CadViewerOptions

Loading Files

Multiple methods for loading CAD data, from high-level to low-level:

loadFile

await viewer.loadFile(file: File): Promise<void>

Load from a browser File object. Automatically detects format via registered formatConverters (checks magic bytes, not file extension). Falls back to DXF parsing. Uses Web Worker if worker: true.

loadBuffer

await viewer.loadBuffer(buffer: ArrayBuffer): Promise<void>

Load from an ArrayBuffer. Same format detection and worker support as loadFile.

loadString

viewer.loadString(dxf: string): void

Load a DXF string directly. Synchronous. No format conversion, no worker support.

loadArrayBuffer

viewer.loadArrayBuffer(buffer: ArrayBuffer): void

Load a DXF file from an ArrayBuffer. Synchronous. No format conversion.

loadDocument

viewer.loadDocument(doc: DxfDocument): void

Load a pre-parsed DxfDocument directly. Useful if you parse the DXF yourself or receive it from another source.

clearDocument

viewer.clearDocument(): void

Clear the current document and reset all viewer state (selection, measurement, spatial index) without destroying the viewer instance.

Camera Controls

fitToView

viewer.fitToView(): void

Fit the camera to the document extents with 5% padding. Call after loading a file to show the full drawing.

zoomTo

viewer.zoomTo(scale: number): void

Zoom to an absolute scale level, centered on the canvas.

panTo

viewer.panTo(worldX: number, worldY: number): void

Pan so that the given world coordinate is at the center of the canvas.

getViewTransform

viewer.getViewTransform(): ViewTransform

Get a copy of the current view transform. Returns { scale, offsetX, offsetY }.

Layer Management

getLayers

viewer.getLayers(): DxfLayer[]

Get all layers from the loaded document.

setLayerVisible

viewer.setLayerVisible(name: string, visible: boolean): void

Show or hide a layer by name. Triggers a re-render.

setLayerColor

viewer.setLayerColor(name: string, color: string): void

Override the display color of a layer. Pass a hex color string (e.g., '#ff0000').

Theme

setTheme / getTheme

viewer.setTheme(theme: 'dark' | 'light'): void
viewer.getTheme(): Theme

Switch between dark and light themes. See Theming for details.

setBackgroundColor

viewer.setBackgroundColor(color: string): void

Override the theme background color with a custom hex color.

Tools

setTool / getTool

viewer.setTool(tool: 'pan' | 'select' | 'measure'): void
viewer.getTool(): Tool

Switch the active interaction tool:

• pan — Click and drag to pan. Scroll to zoom. This is the default.
• select — Click an entity to select it. Fires the select event with entity data.
• measure — Click two points to measure distance. Snaps to entity endpoints, midpoints, and centers. Fires the measure event.

Tip: Middle-click always pans, regardless of the active tool.

Events

viewer.on('select', (event: SelectEvent) => { ... });
viewer.on('measure', (event: MeasureEvent) => { ... });
viewer.on('viewchange', (transform: ViewTransform) => { ... });

viewer.off('select', callback);

See Events for full event reference.

Document Access

getDocument

viewer.getDocument(): DxfDocument | null

Get the currently loaded document, or null if no document is loaded.

getEntities

viewer.getEntities(): DxfEntity[]

Get all entities from the loaded document. Returns an empty array if no document is loaded.

Debug

setDebug

viewer.setDebug(debug: boolean | DebugOptions): void

Enable or disable the debug overlay. Pass true for defaults, false to disable, or a DebugOptions object for granular control:

viewer.setDebug({
	showFps: true,
	showRenderStats: true,
	showDocumentInfo: true,
	showTimings: true,
	showCamera: true,
	position: 'top-left'
});

getDebugStats

viewer.getDebugStats(): DebugStats | null

Get the latest debug stats snapshot. Returns null if debug mode is off.

Lifecycle

resize

viewer.resize(): void

Update the canvas size. Called automatically by an internal ResizeObserver, but you can call it manually if needed.

destroy

viewer.destroy(): void

Destroy the viewer and release all resources (canvas context, event listeners, resize observer, spatial index, Web Worker). Always call this when the viewer is no longer needed.