Skip to content
cadkithome

cadkit-wasm

WebAssembly bindings for cadkit plus a static, drag-and-drop viewer. Everything runs in the browser (or Node); parsing and export do not require a conversion service. This interface covers file I/O, inspection, document operations and SVG-based viewing. It reads DWG, DGN V7/V8, DXF and CityGML 2.0 and writes DXF, seed-based DGN V8, CityGML 2.0, SVG and JSON; see the format matrix for limits. The standalone Rust geometry, scene and GPU renderer APIs are not exported by the npm package.

python crates/cadkit-wasm/build.py

The script runs cargo build --release --target wasm32-unknown-unknown through scripts/buildlock.py (do not wrap build.py in the lock again), then runs the wasm-bindgen CLI twice:

  • crates/cadkit-wasm/pkg/ for --target web (ES module, used by the viewer)
  • crates/cadkit-wasm/pkg-node/ for --target nodejs (CommonJS)

The CLI version must equal the wasm-bindgen version in Cargo.lock. build.py looks in crates/cadkit-wasm/.tools/ (git-ignored; unpack the prebuilt release archive from github.com/wasm-bindgen/wasm-bindgen/releases there), then on PATH.

Size: the workspace release profile is shared, so build.py applies size settings through CARGO_PROFILE_RELEASE_* environment variables (opt-level=z, fat LTO, 1 codegen unit, panic=abort). If wasm-opt (binaryen) is on PATH, it additionally runs wasm-opt -Oz. build.py prints the measured size of each generated module; archive size depends on the selected features, toolchain, and optional optimizer.

Data crosses the boundary as JSON text parsed with JSON.parse (via js-sys) rather than serde-wasm-bindgen: the model is already Serialize, the JSON shape is identical to the CLI and Python output, and one fewer dependency keeps the module small.

import init, { detect, inspect, read, readCityGml } from "./pkg/cadkit_wasm.js"; // web target
await init();
// Node: const { detect, read, readCityGml } = require("./pkg-node/cadkit_wasm.js");
detect(bytes) // "dwg" | "dxf" | "dgn_v7" | "dgn_v8" | "city_gml" | undefined
const summary = inspect(bytes); // header-only format/version/units metadata
const doc = read(bytes, { keepRaw: false, codepage: "windows-1254",
maxInputBytes, maxDecompressedBytes, maxObjects, maxDepth }); // all optional
doc.info() // {format, version, application, units, metersPerUnit,
// models: [{index, name, entities, is3d}], layerCount, blockCount, warningCount}
doc.layers() // [{name, color, visible, frozen, locked}]
doc.warnings() // [{code, message, offset}]
doc.toJSON() // full document as an object; toJsonString(pretty) gives text
doc.toSvg({ model: 0, widthPx: 1600, strokePx: 1, background: "#fff", text: true, images: true, expandBlocks: true, includeHiddenLayers: false })
doc.toSvgBounded({ model: 0, maxOutputBytes: 16 * 1024 * 1024, maxWork: 2_000_000, images: false })
doc.toDxf("r2018") // "r12" | "r2000" | "r2004" | "r2007" | "r2010" | "r2013" | "r2018"
doc.toDgn(seedBytes, { clearSeedModel: true }) // Uint8Array
stripDgnSeed(templateBytes, { modelName: "Model", timestampMs: 1.7e12 }) // {seed: Uint8Array, report}
doc.toCityGml("urn:ogc:def:crs:EPSG::4979", 1) // Uint8Array (UTF-8 XML)
doc.toCityGmlWithReport("urn:ogc:def:crs:EPSG::4979", 1, false) // JSON string: {xml, report}
doc.pickEntity(0, 10, 5, 0.5) // closest visible entity summary or null; world XY coordinates
// Optional fifth argument includes hidden/frozen layers; sixth accepts
// {excludedLayers: ["WALLS"], excludedKinds: ["text"]} for viewer display filters.
doc.pickEntityBounded(0, 10, 5, 0.5, { maxOutputBytes: 16 * 1024, maxWork: 2_000_000,
excludedLayers: ["WALLS"] }, false)
doc.convertUnits("meter") // mutates this document; returns the scale factor
doc.explodeInserts() // mutates; returns {truncated, work}
doc.toDxfBytes("r2000", "DOS857") // Uint8Array with optional legacy output encoding
doc.free()

Errors are thrown as Error objects with a kind property: unknown_format, unsupported, invalid, truncated, limit_exceeded (from the readers), plus io and bad_argument (bad model index or DXF version). toSvg({background: null}) gives a transparent SVG.

Use toSvgBounded for previews of untrusted drawings. maxOutputBytes is required (positive integer, at most 2^32 - 1) and counts the entire UTF-8 SVG, including XML, layer names and definitions. Temporary paths, escaped text, accumulated layer bodies and final assembly are checked before they grow past the cap. Derived geometry/text scratch has a conservative size check, so a too-large temporary can fail even when the final SVG would be smaller. The cap is not a bound on total process memory or on the parsed document: parsing still needs the read limits and worker isolation. maxWork optionally overrides the normal traversal work budget (positive safe integer). Budget exhaustion throws Error.kind === "limit_exceeded"; no partial SVG is returned. Free the document and terminate/recreate its worker after this error to release the WASM memory instance. A caller adding CSS or other markup must also budget that output. The existing toSvg API keeps its coarse body limit and truncation-marker behavior.

Limits: wasm32 aborts on allocation failure, so read uses conservative defaults instead of the desktop ones: input 512 MiB, decompressed 1 GiB, 5,000,000 objects, depth 64. Override with the max* options. If a call still traps (WebAssembly.RuntimeError) the module instance is unusable and must be re-instantiated; the viewer does this automatically.

build.py writes a private development package.json into pkg/ and pkg-node/ and then assembles the npm package cadkit-wasm in crates/cadkit-wasm/npm/ (git-ignored):

Import Folder Build
cadkit-wasm web/ --target web, ES module; call await init() first
cadkit-wasm/node node/ --target nodejs, CommonJS, ready on load
cadkit-wasm/cadkit_wasm_bg.wasm web/ the module bytes, for init({ module_or_path }) in Node

The package README is crates/cadkit-wasm/README.md. npm pack in npm/ produces the tarball that the release workflow publishes; tests/package_smoke.mjs installs it and exercises both entry points.

python scripts/buildlock.py node --test crates/cadkit-wasm/tests/node_test.mjs
python scripts/buildlock.py cargo clippy --no-deps -p cadkit-wasm --target wasm32-unknown-unknown -- -D warnings
node --check crates/cadkit-wasm/www/viewer.js

The Node test needs pkg-node/ (run build.py first). It covers garbage input, a synthetic DXF, SVG well-formedness and every file under corpus/public/; reader-dependent checks skip when a reader reports unsupported or unknown_format.

cd crates/cadkit-wasm
python -m http.server 8000 # then open http://localhost:8000/www/

Serve the crate folder (not www/ alone) because the viewer imports ../pkg/. Opening index.html from file:// does not work (browsers block module and wasm loading).

Features: drop zone and file picker (.dwg, .dgn, .dxf); pan by dragging, zoom with the wheel, pinch or +/- buttons, all through the SVG viewBox; fit-to-view (button, 0/F, double click); keyboard pan with arrow keys; layer panel with per-layer visibility from the data-layer groups (layers that render nothing are shown disabled; Include hidden layers renders hidden/frozen layers too); model selector, text/image toggles and fallback code-page selection; world-coordinate HUD and click selection; information panel with format, version, units, counts and warnings; SVG, DXF, GML and JSON export; light/dark theme from prefers-color-scheme; responsive layout with a collapsible panel on phones. The sheet background can be switched between light and dark. GML export requires the user to enter the CRS identifier of existing coordinates. Unsupported geometry is rejected unless the user explicitly checks the metadata option; a diagnostic message reports metadata-only exports.

CadDocument.fromJsonString(text) constructs a neutral model. toDgn(seed, optionsJson?) returns Uint8Array; toCityGml(srsName, lod) returns UTF-8 XML bytes as Uint8Array; toCityGmlWithReport(srsName, lod, metadataOnly) returns a JSON string {"xml": ..., "report": ...} (metadataOnly: false rejects unsupported geometry; true retains unsupported entities as JSON metadata). DGN options use Rust dgn::WriteOptions JSON, including clear_seed_model.

stripDgnSeed(seed, options?, readOptions?) copies a DGN V8 seed without its model’s drawing content and without the document properties that name people or organisations and returns { seed: Uint8Array, report }. options follows Rust dgn::StripSeedOptions (object or JSON string, camelCase accepted: keepControls, keepRasterTemplate, keepCellDefinitions, modelName, timestampMs, application; any other key throws a bad_argument error); readOptions sets the read limits as for read. The report (dgn::StripSeedReport) counts what was removed and what remains; names in the kept tables remain, so the result is not anonymous. See obtaining a seed.

readCityGml(bytes, optionsJson?) returns a native CityGmlDocument with toGml(optionsJson?), toJsonString(), static fromJsonString(text), toDocument(lod?), validate(optionsJson?), and preflightTkgm(profile). preflightTkgm(profile) requires an explicit profile ("city-model-tender" or "digital-building-registration") and returns a local structural preflight report object (acceptance_verified is always false). Call free() on both document classes when done. Native read options use Rust ReadOptions; native write and validation options use gml::ValidationOptions.

New native APIs cap input at 512 MiB, decompressed data at 1 GiB, objects at five million and depth at 64 even if larger JSON limits are supplied. Runtime schema fetching and implicit CRS transformation are not performed. The Node test suite includes native GML preservation, new generic output and public-seed DGN writing.

The wasm-bindgen output includes TypeScript option/result interfaces. Read options and DGN write options accept JS objects; native CityGML/DGN options also accept their existing Rust JSON strings. CadDocument.fromCityGml(bytes, lod?, options?) converts native GML geometry directly into a neutral document. All returned document objects need free().

Picking uses exact XY distance for lines and circular arcs, bounded curve sampling for other curves, and bounding-box approximations for annotations and hatches. It follows nested block transforms and layer visibility; it is a viewer selection aid, not a CAD snapping or geometric intersection API. Browser appearance and pointer interactions need separate interactive QA; Node tests exercise the WASM contract only.

For untrusted inspection metadata, use pickEntityBounded (added after 0.5.2). Its fifth argument requires maxOutputBytes (positive integer, at most 65,536) for the entire UTF-8 JSON result, including keys, escaping and punctuation. Optional maxWork is a positive integer up to 5,000,000; it defaults to that ceiling. The optional sixth argument includes hidden/frozen layers. Filters accept at most 20,000 names per array, 2,048 UTF-16 units per name and 65,536 UTF-8 bytes per filter array. Invalid options throw bad_argument.

Selection retains references to candidate entities instead of cloning their metadata. Only the final hit is summarized. The result includes index, id, layer, kind, color, bbox, distance, optional text/block, string-valued attributes and truncated; raw props are omitted. Previews cap layer/block at 200 Unicode scalars, text at 500, attribute tags at 100 and values at 200. At most 20 attributes and 8 KiB of preview text are copied. List previews visit at most three levels, 16 entries per list and 64 value nodes per attribute. Limits are applied while reading the borrowed values, before allocation proportional to their full size. truncated: true identifies shortened or unsupported metadata; the underlying document is never modified.

The JSON writer rejects overflow before extending its output. Exhausted output or traversal work throws limit_exceeded, including when an earlier candidate was found; it never returns a partial search result as success. null means no hit in a completed search. Legacy pickEntity keeps its full metadata shape. Neither API bounds the already parsed document or total process memory; retain parser limits and worker isolation. Hosts must wait for a package containing the new method before switching from legacy picking.