Module @mlightcad/cad-viewer - v1.4.13

CAD Viewer Component

CAD Viewer is a high-performance Vue 3 component for viewing and editing CAD files (DXF, DWG) entirely in the browser without requiring any backend server. It provides a modern user interface, state management, and seamless integration with optimized rendering engines for smooth browser-based CAD workflows with exceptional performance.

Key Features

High-performance CAD editing and viewing with smooth 60+ FPS rendering
No backend required - Files are parsed and processed entirely in the browser
Enhanced data security - Files never leave your device, ensuring complete privacy
Local file support - Load DWG/DXF files directly from your computer via file dialog or drag & drop
Remote file support - Load CAD files from URLs automatically
Easy integration - No server setup or backend infrastructure needed for third-party integration
Customizable UI - Control visibility of toolbars, command line, coordinates, and performance stats
Customizable Resources - Set custom base URLs for fonts, templates, and example files
Modern UI optimized for large CAD file handling
State management for layers, entities, and settings
Integration with optimized SVG and THREE.js renderers
Dialogs, toolbars, and command line interface
Vue 3 component for embedding high-performance CAD viewers in your own apps

When Should You Choose cad-viewer?

Use cad-viewer if you want a ready-to-use Vue 3 component for viewing and editing CAD files with a modern UI, dialogs, toolbars, and state management. This package is ideal if:

You want to quickly embed a high-performance CAD viewer/editor into your Vue application with minimal setup.
You need support for both local file loading (from user's computer) and remote file loading (from URLs).
You need a solution that handles file loading, rendering, layer/entity management, and user interactions out of the box.
You want seamless integration with optimized SVG and THREE.js renderers, internationalization, and theming.
You do not want to build your own UI from scratch.

Recommended for: Most web applications, dashboards, or platforms that need to display CAD files with a polished user interface.

Browser-Only Architecture

This Vue 3 component operates entirely in the browser with no backend dependencies. DWG/DXF files are parsed and processed locally using WebAssembly and JavaScript, providing:

Zero server requirements - Deploy the component anywhere with just static file hosting
Complete data privacy - CAD files never leave the user's device, whether loaded locally or from URLs
Local file support - Users can load files directly from their computer using the built-in file dialog
Remote file support - Automatically load files from URLs when provided
Instant integration - No complex backend setup or API configuration needed
Offline capability - Works without internet connectivity once loaded
Third-party friendly - Easy to embed in any Vue 3 application without server-side concerns

File Loading Methods

The MlCadViewer component supports multiple ways to load CAD files:

1. Local File Loading

Users can load files directly from their computer:

File Dialog: Click the main menu (☰) and select "Open" to browse and select local DWG/DXF files
Drag & Drop: Drag and drop CAD files directly onto the viewer (if implemented in your application)
File Input: Use the built-in file reader component for programmatic file selection
Component Prop: Pass a File object directly to the localFile prop for automatic loading

Example: Using localFile prop with file input

2. Remote File Loading

Automatically load files from URLs:

URL Prop: Provide a url prop to automatically load a file when the component mounts
Dynamic Loading: Change the url prop to load different files without remounting the component

3. Supported File Formats

DWG files: Binary AutoCAD drawing format (read as ArrayBuffer)
DXF files: ASCII/binary AutoCAD drawing exchange format (read as text)

Directory Structure (partial)

src/app/ – Application entry, store, and main logic
src/component/ – UI components (dialogs, toolbars, status bar, etc.)
src/composable/ – Vue composables for state and logic
src/locale/ – Internationalization files
src/style/ – Stylesheets
src/svg/ – SVG assets

Installation

npm install @mlightcad/cad-viewer

Usage

Please refer to sub-package cad-viewer-example as one example.

Basic Usage

Firstly, add the following dependencies into your package.json.

@element-plus/icons-vue
@mlightcad/cad-simple-viewer
@mlightcad/cad-viewer
@mlightcad/data-model
@vueuse/core
element-plus
vue
vue-i18n

Then create one vue component as follows.

MlCadViewer Component

The MlCadViewer is the main Vue 3 component that provides a complete CAD viewing and editing interface. It includes toolbars, layer management, command line, status bar, and various dialogs for a full-featured CAD experience.

Component Properties

The MlCadViewer component accepts the following props:

Property	Type	Default	Description
`locale`	`'en' \| 'zh' \| 'default'`	`'default'`	Sets the language for the component interface. Use `'en'` for English, `'zh'` for Chinese, or `'default'` to use the browser's default language.
`url`	`string`	`undefined`	Optional URL to automatically load a CAD file when the component mounts. The file will be fetched and opened automatically. Note: If not provided, users can still load local files using the main menu "Open" option.
`localFile`	`File`	`undefined`	Optional local File object to automatically load a CAD file when the component mounts. The file will be read and opened automatically. Note: This takes precedence over the `url` prop if both are provided.
`background`	`number`	`undefined`	Background color as 24-bit hexadecimal RGB (e.g., `0x000000` for black, `0x808080` for gray).
`baseUrl`	`string`	`undefined`	Base URL for loading fonts, templates, and example files. This URL is used by the CAD viewer to load resources like fonts and drawing templates. Note: If not provided, uses the default URL.
`useMainThreadDraw`	`boolean`	`false`	Optional flag whether to use main thread or webwork to render drawing. The true value means using main thread to render drawing. This approach take less memory and take longer time to show rendering results. The false value means using web worker to render drawing. This approach take more memory and take shorter time to show rendering results.
`theme`	`'light' \| 'dark'`	`'dark'`	Initial UI theme of the CAD viewer. On mount, this prop initializes the `COLORTHEME` system variable in the active database (`0 = dark`, `1 = light`). After that, the viewer theme is driven by `COLORTHEME`, so runtime changes from the status bar theme button or direct system-variable updates stay synchronized across `cad-viewer` and `cad-simple-viewer`.
`mode`	`AcEdOpenMode`	`'AcEdOpenMode.Write'`	Access mode for opening CAD files. `'AcEdOpenMode.Read'` means read-only access. `'AcEdOpenMode.Review'` means review access, compatible with read. `'AcEdOpenMode.Write'` means full read/write access, compatible with review and read.

UI Settings

The MlCadViewer reads its UI visibility from the global AcApSettingManager (provided by @mlightcad/cad-simple-viewer). Configure these flags anywhere before rendering the viewer to customize the UI.

Setting	Type	Default	Description
`isShowToolbar`	`boolean`	`true`	Controls toolbar visibility
`isShowCommandLine`	`boolean`	`true`	Controls command line visibility
`isShowCoordinate`	`boolean`	`true`	Controls coordinate display visibility
`isShowEntityInfo`	`boolean`	`false`	Controls entity info card visibility
`isShowLanguageSelector`	`boolean`	`true`	Controls language selector visibility
`isShowMainMenu`	`boolean`	`true`	Controls main menu visibility
`isShowStats`	`boolean`	`false`	Controls performance statistics display

Example (recommended)

Notes

Settings are global and immediately reflected by MlCadViewer.
You can change them at runtime using the same AcApSettingManager.instance reference.

Base URL Configuration

The baseUrl property allows you to customize where the CAD viewer loads fonts, templates, and example files from. This is particularly useful for:

Self-hosted resources: Host your own fonts and templates on your CDN or server
Corporate environments: Use internal servers for CAD resources
Offline deployments: Serve resources from local file systems
Custom branding: Use your own templates and fonts

Default Behavior

If no baseUrl is provided, the viewer uses the default URL: https://mlightcad.gitlab.io/cad-data/

Resource Structure

When using a custom baseUrl, ensure your server has the following structure:

your-base-url/
├── fonts/           # Font files for text rendering
├── templates/       # Drawing templates (e.g., acadiso.dxf)
└── examples/        # Example CAD files

Example: Custom Base URL

This configuration will:

Load fonts from https://my-company.com/cad-resources/fonts/
Load templates from https://my-company.com/cad-resources/templates/
Use the custom base URL for any "Quick New" operations

Component Features

The MlCadViewer component includes:

Main Menu - File operations (including local file opening), view controls, and settings
Toolbars - Drawing tools, zoom controls, and selection tools
Layer Manager - Layer visibility and property management
Command Line - AutoCAD-style command input
Status Bar - Current position, zoom level, and system status
Dialog Manager - Modal dialogs for various operations
File Reader - Local file loading via file dialog and drag-and-drop support
Entity Info - Detailed information about selected entities
Language Selector - UI language switching
Theme Support - Dark/light mode driven by the COLORTHEME system variable

Event Handling

The component automatically handles various events:

File Loading - Supports local file loading (via file dialog), drag-and-drop, and URL-based file loading
Error Messages - Displays user-friendly error messages for failed operations
Font Loading - Handles missing fonts with appropriate notifications
System Messages - Shows status updates and operation feedback

Advanced Usage

Please refer to readme of cad-simple-viewer to learn the following advanced usage.

Register DWG converter to display drawings in DWG format
Define your own font loader to load fonts from your own server
Create drawing or modify drawing

Available Exports

Main Component

MlCADViewer - The main CAD viewer component

Commands

AcApLayerStateCmd - Layer state command
AcApLogCmd - Log command
AcApMissedDataCmd - Missed data command
AcApPointStyleCmd - Point style command

Components

MlPointStyleDlg - Point style dialog
MlReplacementDlg - Replacement dialog
Various layout and UI components

Composables

useCommands - Command management
useCurrentPos - Current position tracking
useDark - Reactive dark-mode state backed by the COLORTHEME system variable
useDialogManager - Dialog management
useFileTypes - File type utilities
useLayers - Layer management
useLayouts - Layout management
useMissedData - Missed data handling
useSettings - Settings management
useSystemVars - System variables

Theme Synchronization

The viewer UI theme is synchronized through the COLORTHEME system variable managed by AcDbSysVarManager.

COLORTHEME = 0 means dark theme.
COLORTHEME = 1 means light theme.
The theme prop provides the initial value when MlCadViewer mounts.
Clicking the status bar theme button updates COLORTHEME.
Any runtime change to COLORTHEME is reflected automatically in viewer UI and MTEXT-related UI.
The exported useDark composable is still available, but it now wraps COLORTHEME instead of maintaining an isolated local dark-mode state.

Locale

i18n - Internationalization instance
Language files for English and Chinese

Styles

CSS and SCSS files for styling
Dark mode support
Element Plus integration

Development

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build the library
pnpm build

# Preview the build
pnpm preview

License

MIT

Classes

AcApLayerStateCmd
AcApMissedDataCmd
AcApPointStyleCmd
AcApPropertiesCmd
AcApQSelectCmd

Interfaces

CommandInfo
Dialog
ImageMappingData
LayerInfo
LayerStateSnapshot
LayoutInfo
MlQuickSelectCriteria
MlQuickSelectResult
Notification
NotificationAction
SystemVariables
ViewerRect

Type Aliases

LayerStateToggleKey
LocaleProp
MlQuickSelectApplyTo
MlQuickSelectOperator
MlQuickSelectProperty
MlQuickSelectSelectionMode

Variables

COLOR_THEME_SYSVAR_NAME
DYNAMIC_MODE_SYSVAR_NAME
i18n
isDark
LINEWIDTH_DISPLAY_SYSVAR_NAME
LOCALE_OPTIONS
MlCadViewer

Functions

References

MlBaseDialog → MlCadViewer
MlBaseDrawStyleToolbar → MlCadViewer
MlBaseInputNumber → MlCadViewer
MlColorDropdown → MlCadViewer
MlColorIndexPicker → MlCadViewer
MlColorPickerDlg → MlCadViewer
MlColorPickerDropdown → MlCadViewer
MlColorPickerTabs → MlCadViewer
MlDialogManager → MlCadViewer
MlEntityDrawStyleToolbar → MlCadViewer
MlEntityInfo → MlCadViewer
MlFileReader → MlCadViewer
MlLanguageSelector → MlCadViewer
MlLayerDrawStyleToolbar → MlCadViewer
MlLayerSelect → MlCadViewer
MlLineTypeSelect → MlCadViewer
MlLineWeightSelect → MlCadViewer
MlMainMenu → MlCadViewer
MlNotificationCenter → MlCadViewer
MlNotificationItem → MlCadViewer
MlPaletteManager → MlCadViewer
MlPointStyleDlg → MlCadViewer
MlQuickSelectDlg → MlCadViewer
MlReplacementDlg → MlCadViewer
MlRibbonCommands → MlCadViewer
MlRibbonLanguageSelector → MlCadViewer
MlRibbonPropertyColorDropdown → MlCadViewer
MlRibbonPropertyField → MlCadViewer
MlRibbonPropertyLineTypeSelect → MlCadViewer
MlRibbonPropertyLineWeightSelect → MlCadViewer
MlStatusBar → MlCadViewer
MlSysVarToggleButton → MlCadViewer
MlToggleButton → MlCadViewer
MlToolBars → MlCadViewer