# @x-viewer/core

[![npm version](https://img.shields.io/npm/v/@x-viewer/core.svg)](https://www.npmjs.com/package/@x-viewer/core)
[![npm downloads](https://img.shields.io/npm/dm/@x-viewer/core.svg)](https://www.npmjs.com/package/@x-viewer/core)
[![License](https://img.shields.io/badge/license-UNLICENSED-blue.svg)](LICENSE)

WebGL-based **2D/3D viewer engine** built on [Three.js](https://threejs.org/). View **DWG, DXF, glTF, OBJ, FBX, IFC, STL and PDF** files directly in the browser — no server required.

## Built with @x-viewer/core

| Application | Description |
|---|---|
| [cad.thingraph.site](https://cad.thingraph.site/) | CAD viewer — View 2D(DWG, DXF) & 3D CAD models(glTF, GLB, OBJ, FBX, STL) directly in your browser |
| [drive.thingraph.site](https://drive.thingraph.site/) | DWG viewer - View DWG/DXF files directly in Google Drive |
| [dwg.thingraph.site](https://dwg.thingraph.site/) | Live SDK examples and demos |

## Features

- **High-performance 2D rendering**: WebGL-based rendering engine built on Three.js
- **DWG/DXF support**: Parse and render DWG/DXF files entirely in the browser via WebAssembly (libredwg), no backend needed
- **Paper space & layouts**: Renders AutoCAD paper space layouts, viewports, and layer freeze
- **Hatch patterns**: GPU-rendered AutoCAD hatch patterns (ANSI, ISO, AR-* series)
- **3D formats**: glTF/GLB, OBJ, FBX, IFC, STL, DAE, BimTiles
- **PDF viewer**: Render PDF files in the browser
- **CAD comparison**: Diff two DWG/DXF files with color-coded changes
- **Measurements & markup**: Distance, area, angle tools with snapping; freehand and geometric annotations
- **Modular architecture**: Designed for extensibility and seamless integration
- **TypeScript**: Full TypeScript support with comprehensive type definitions

## Installation

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

## Quick Start

### Viewer2d — DWG/DXF Viewer

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

const viewer = new Viewer2d({
    containerId: "myCanvas",
    enableSpinner: true,
    enableLayoutBar: true,
});

await viewer.loadModel({
    modelId: "id_0",
    name: "sample",
    src: "https://example.com/sample.dwg",
});

viewer.goToHomeView();
```

### Viewer3d — 3D Model Viewer

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

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

await viewer.loadModel({
    modelId: "model_1",
    src: "./models/building.gltf",
    fileFormat: "gltf",
});

viewer.cameraManager.flyToViewpoint({
    eye: new THREE.Vector3(100, 50, 100),
    look: new THREE.Vector3(0, 0, 0),
});
```

## Supported File Formats

### 2D Formats
| Format | Description |
|---|---|
| **DWG** | AutoCAD Drawing (all versions, via libredwg/WebAssembly) |
| **DXF** | AutoCAD Drawing Exchange Format (ASCII and Binary) |
| **PDF** | PDF files with vector graphics |

### 3D Formats
| Format | Description |
|---|---|
| **glTF / GLB** | glTF 2.0 |
| **OBJ** | Wavefront OBJ (with MTL materials) |
| **FBX** | Autodesk FBX |
| **STL** | Stereolithography |
| **DAE** | COLLADA |
| **IFC** | Industry Foundation Classes (BIM; load via `@x-viewer/plugins`) |
| **3DM** | Rhinoceros 3DM (OpenNURBS; load via `@x-viewer/plugins`) |

## API Examples

### Loading with Progress

```typescript
await viewer.loadModel(
    { modelId: "m1", src: "./drawing.dwg" },
    (event) => {
        const pct = (event.loaded / event.total) * 100;
        console.log(`${pct.toFixed(0)}%`);
    }
);
```

### Layer Management (Viewer2d)

```typescript
const layers = viewer.getLayers();
viewer.setLayerVisible("Layer1", false);
viewer.setLayerColor("Layer1", new THREE.Color(1, 0, 0));
```

### CAD Comparison

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

const helper = new DxfCompareHelper(viewer);
await helper.compare(
    { modelId: "v1", src: "./rev1.dxf" },
    { modelId: "v2", src: "./rev2.dxf" },
    {
        addedColor: new THREE.Color(0, 1, 0),   // green = added
        removedColor: new THREE.Color(1, 0, 0), // red = removed
    }
);
```

### Camera Control

```typescript
viewer.cameraManager.setProjection(CameraProjection.Perspective);
viewer.cameraManager.flyToViewpoint({ eye, look });
viewer.zoomToBBox(new THREE.Box3(min, max));
```

## Using Three.js

Import Three.js from this package to avoid version conflicts:

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

const vector = new THREE.Vector3(0, 0, 0);
viewer.zoomToBBox(new THREE.Box3(min, max));
```

## Coordinate System & Units

- **Coordinate system**: Right-handed, Y-up (consistent with Three.js and glTF)
  - +X: right | -X: left
  - +Y: up | -Y: down
  - +Z: front (out of screen) | -Z: back (into screen)
- **Length**: Meter | **Area**: m² | **Angle**: Degrees, CCW | **Time**: Milliseconds

## Performance

- Geometry batching to minimize draw calls
- Instanced rendering for repeated elements
- Material caching across entities
- Custom GLSL shaders for GPU-accelerated hatch patterns
- Spatial indexing for fast picking and culling

## Known Limitations

- DWG table entities are not fully supported (LibreDWG limitation)
- External references (XRefs) are not supported
- Some DWG files may fail to open due to LibreDWG limitations

## Links

- [Live Demos](https://dwg.thingraph.site/)
- [Online CAD Viewer](https://cad.thingraph.site/)
- [Examples on GitHub](https://github.com/thingraph/dwg-viewer-example)
- [Issues / Bug Reports](https://github.com/thingraph/dwg-viewer-example/issues)
- Contact: thingraph@outlook.com

## Related Packages

- [`@x-viewer/plugins`](https://www.npmjs.com/package/@x-viewer/plugins) — Measurement, markup, toolbar, layer panel and more
- `@x-viewer/ui` — Reusable UI components

## License

UNLICENSED — contact thingraph@outlook.com for licensing inquiries.
