Demo Drawings

Demo site that showcases pre-rendered CAD drawings exported from cad-viewer / @mlightcad/cad-html-plugin as multi-file ACEX packages, then hosted as static files on GitHub Pages.

You can:

• View drawings instantly in the browser (no DWG parsing on the client)
• Download the original DWG while browsing the gallery

Drawing source: original DWG files were downloaded from DWG Models.

Live site: https://mlightcad.github.io/demo-drawings/

Related docs:

• ACEX web hosting guide — how the pre-render + static hosting model works
• cad-viewer — open-source CAD viewer used to export these packages

---

Why this approach?

There are two common ways to view DWG/DXF on the web:

Architecture	Flow	Trade-off
A. Parse in the browser	Download DWG → parse entities → tessellate → WebGL	Flexible, but large files mean slow first paint and heavy devices
B. Pre-render + static host (this demo)	Convert once on the server/build → ship display data + viewer	Fast open, great for publish/share/archive; re-export when the drawing changes

This repo is a small gallery for architecture B. Each drawing folder is a multi-file ACEX package produced by cad-html-plugin:

<drawing-folder>/
  drawing.acex.json     # Package manifest (metadata + chunk index)
  chunks/
    L0-000.acex.gz      # Gzipped geometry chunks (progressive load)
    L0-osnap-000.osnap.gz
    ...
  preview.jpg           # Gallery thumbnail
  drawing.dwg           # Original file for download (optional for viewing)

A shared drawings/viewer.html loads any package via:

drawings/viewer.html?manifest=<absolute-url-to>/drawing.acex.json

At runtime the viewer:

1. Fetches and validates the manifest
2. Streams the current layout’s geometry chunks → gunzip → decode → paint progressively
3. Lazily loads osnap / other layouts as needed

No backend runtime is required—any static host (GitHub Pages, nginx, S3/CDN) works. Chunks must be served as opaque bytes (do not set Content-Encoding: gzip on .acex.gz / .osnap.gz; the viewer gunzips in JavaScript). See the hosting guide for nginx/Apache notes.

---

Features

• Gallery grid (3 columns) driven by drawings/catalog.json
• Click a preview → open the shared ACEX viewer with that package’s manifest URL
• Hover Download on a preview → save the original DWG
• DWG file size shown next to each title
• Local preview script + GitHub Actions → GitHub Pages deploy

---

Requirements

• Node.js 18+ (catalog generation / local preview)

To export new packages from DWG/DXF yourself, use cad-viewer / cad-html-plugin / @mlightcad/cad-simple-viewer-cli as described in the hosting guide.

---

Local preview

pnpm preview
# or: npm run preview

Regenerates drawings/catalog.json and serves the site at http://127.0.0.1:4173/
If port 4173 is busy, the script tries the next free port.

Catalog only:

pnpm catalog
# or: npm run catalog

On Windows you can also run scripts/preview.cmd.

Packages must be opened over http(s). Opening viewer.html via file:// will not load manifests/chunks correctly.

---

Project layout

.
├── index.html                 # Gallery (browse + download DWG)
├── drawings/
│   ├── catalog.json           # Generated index for the gallery
│   ├── viewer.html            # Shared offline ACEX viewer shell
│   └── <drawing-folder>/
│       ├── preview.jpg        # Thumbnail (required)
│       ├── drawing.acex.json  # ACEX manifest (required)
│       ├── chunks/            # Geometry / osnap chunks (required)
│       └── drawing.dwg        # Original DWG for download (required for catalog)
├── scripts/
│   ├── generate-catalog.mjs
│   ├── preview.mjs
│   └── preview.cmd
└── .github/workflows/
    └── deploy-pages.yml

viewer.html is a generic shell—one copy serves every package via ?manifest=…. Per-folder duplicate viewers are not needed for hosting.

---

Adding a drawing

1. Export a multi-file (ZIP) package from cad-viewer (chtml / -chtml, format Multi), or via the headless CLI — see the hosting guide.
2. Unzip into drawings/<folder-name>/ so you have drawing.acex.json + chunks/.
3. Add preview.jpg and drawing.dwg (original source for the download button).
4. Run pnpm catalog (or pnpm preview).

Display titles replace underscores with spaces (parking_area → parking area).

Catalog fields

Field	Description
folder	Directory name under drawings/
title	Display title (underscores removed)
preview	Path to preview.jpg
manifest	Path to drawing.acex.json
dwg	Path to the DWG file
dwgFile	DWG file name
dwgSize	DWG size in bytes

---

How viewing + download work together

Action	What happens
View	Gallery links to drawings/viewer.html?manifest={site}/drawings/{folder}/drawing.acex.json. The viewer loads only display data (chunks), so browsing is fast and does not require parsing the DWG in the browser.
Download	The Download control fetches drawing.dwg so users who need the editable source can take it with them.

This matches a common “publish for viewing, offer DWG for power users” workflow: pre-rendered packages for share/CDN, originals available on demand.

---

GitHub Pages

Pushing to main or master runs .github/workflows/deploy-pages.yml: regenerate catalog → publish index.html + drawings/ (including DWGs and chunks).

First-time setup:

1. Repo Settings → Pages
2. Source = GitHub Actions
3. Wait for the workflow to finish

The gallery builds absolute manifest URLs from the current origin (including the /demo-drawings/ project-Pages base path).

---

Exporting packages (upstream)

Typical ways to produce the multi packages used here (details in the hosting guide):

1. cad-viewer UI — open a drawing, run chtml, choose Multi
2. Headless CLI — @mlightcad/cad-simple-viewer-cli with an export .scr (good for CI/batch)
3. In-app API — AcApHtmlConvertor / buildAcExPackage inside your own web app

Useful export defaults for demos: exportFormat: 'multi', viewerMode: 'measure', exportLayouts: true, initialView: 'fit'.

---

License

Site code in this repository. Drawing DWG files were downloaded from DWG Models; refer to that site for terms that apply to those assets. ACEX packages were produced with cad-viewer tooling.