@x-viewer/core

Core package providing the foundational 2d and 3D viewer engine for x-viewer. Includes DXF/DWG parsing and rendering, 3D rendering, BIM support, and essential utilities for building visualization applications.

Features

• High-performance rendering: WebGL-based rendering engine built on Three.js with advanced optimization techniques
• DXF/DWG support: Parse and render DXF/DWG files entirely in the browser without backend server
• Multiple viewers: Support for 2D and 3D viewers
• Model formats: Support for glTF, GLB, OBJ, STL, and other 3D model formats
• Modular architecture: Designed for extensibility and seamless integration
• TypeScript: Full TypeScript support with comprehensive type definitions

Installation

npm install @x-viewer/core
# or
pnpm add @x-viewer/core
# or
yarn add @x-viewer/core

Quick Start

Viewer2d - DXF/DWG Viewer

import { Viewer2d } from "@x-viewer/core";

// Create a 2D viewer
const viewerCfg = {
    containerId: "myCanvas",
    enableSpinner: true,
    enableLayoutBar: true,
};

const modelCfg = {
    modelId: "id_0",
    name: "sample",
    src: "http://www.example.com/sample.dwg",
};

const viewer = new Viewer2d(viewerCfg);
await viewer.loadModel(modelCfg);

Viewer3d - 3D Model Viewer

import { Viewer3d, THREE } from "@x-viewer/core";

// Create a 3D viewer
const viewerCfg = {
    containerId: "myCanvas",
};

const modelCfg = {
    modelId: "model_1",
    src: "./models/rac_basic_sample_project.gltf",
    fileFormat: "gltf",
};

const viewer = new Viewer3d(viewerCfg);
await viewer.loadModel(modelCfg);

// Set camera viewpoint
const viewpoint = {
    eye: new THREE.Vector3(100, 50, 100),
    look: new THREE.Vector3(0, 0, 0),
};
viewer.cameraManager.flyToViewpoint(viewpoint);

Supported File Formats

2D Formats

• DXF: AutoCAD Drawing Exchange Format (ASCII and Binary)
• DWG: AutoCAD Drawing Format
• PDF: PDF files with vector graphics

3D Formats

• glTF/GLB: glTF 2.0 format
• OBJ: Wavefront OBJ format
• STL: Stereolithography format
• IFC: Industry Foundation Classes (BIM)

Coordinate System

x-viewer uses a right-handed, y-up coordinate system, consistent with Three.js and glTF:

• +X: right
• -X: left
• +Y: up
• -Y: down
• +Z: front (out of screen)
• -Z: back (into screen)

Units

• Length: Meter
• Area: Square Meter
• Angle: Degree (0-360), Counter-clockwise (CCW)
• Time: Millisecond

Using Three.js

Since Three.js is included in @x-viewer/core, you should import it from this package:

import { THREE, THREEAddons } from "@x-viewer/core";

// Use THREE.js directly
const vector = new THREE.Vector3(0, 0, 0);
const box = new THREE.Box3(min, max);
viewer.zoomToBBox(box);

API Examples

Loading Models with Progress

const viewer = new Viewer3d({ containerId: "myCanvas" });

await viewer.loadModel(
    {
        modelId: "model_1",
        src: "./model.gltf",
    },
    (event) => {
        const progress = (event.loaded / event.total) * 100;
        console.log(`Loading: ${progress.toFixed(1)}%`);
    }
);

Camera Control

// Set camera projection
viewer.cameraManager.setProjection(CameraProjection.Perspective);

// Fly to a viewpoint
const viewpoint = {
    eye: new THREE.Vector3(100, 50, 100),
    look: new THREE.Vector3(0, 0, 0),
};
viewer.cameraManager.flyToViewpoint(viewpoint);

// Zoom to bounding box
const bbox = new THREE.Box3(
    new THREE.Vector3(-10, -10, -10),
    new THREE.Vector3(10, 10, 10)
);
viewer.zoomToBBox(bbox);

Layer Management (Viewer2d)

// Get all layers
const layers = viewer.getLayers();

// Set layer visibility
viewer.setLayerVisible("Layer1", false);

// Set layer color
viewer.setLayerColor("Layer1", new THREE.Color(1, 0, 0));

DXF Comparison

import { DxfCompareHelper } from "@x-viewer/core";

const compareHelper = new DxfCompareHelper(viewer);

await compareHelper.compare(
    { modelId: "model1", src: "./file1.dxf" },
    { modelId: "model2", src: "./file2.dxf" },
    {
        addedColor: new THREE.Color(0, 1, 0), // green
        removedColor: new THREE.Color(1, 0, 0), // red
    }
);

// Zoom to a specific change
compareHelper.zoomToChange(1);

Performance

x-viewer is optimized for high performance with large files:

• Geometry Batching: Merges geometries to reduce draw calls
• Instanced Rendering: Optimizes repeated geometries
• Material Caching: Reuses materials across similar entities
• Spatial Indexing: Efficient object picking and culling
• Custom Shaders: GPU-accelerated rendering for complex patterns

Known Limitations

• DWG Tables: Table entities in DWG files are not fully supported (LibreDWG limitation)
• XRefs: External references (XRefs) are not supported
• DWG Compatibility: Some DWG files may fail to open due to LibreDWG library limitations

Documentation

• Examples
• Online Demos

License

UNLICENSED

Related Packages

• @x-viewer/plugins - Extensible functionality modules
• @x-viewer/editor - 2D/3D editing capabilities
• @x-viewer/builder - Parametric and static model creation
• @x-viewer/ui - Reusable UI components