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.pyThe 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.
JS API
Section titled “JS API”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 targetawait init();// Node: const { detect, read, readCityGml } = require("./pkg-node/cadkit_wasm.js");
detect(bytes) // "dwg" | "dxf" | "dgn_v7" | "dgn_v8" | "city_gml" | undefinedconst summary = inspect(bytes); // header-only format/version/units metadataconst 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 textdoc.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 }) // Uint8ArraystripDgnSeed(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 factordoc.explodeInserts() // mutates; returns {truncated, work}doc.toDxfBytes("r2000", "DOS857") // Uint8Array with optional legacy output encodingdoc.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.mjspython scripts/buildlock.py cargo clippy --no-deps -p cadkit-wasm --target wasm32-unknown-unknown -- -D warningsnode --check crates/cadkit-wasm/www/viewer.jsThe 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.
Viewer
Section titled “Viewer”cd crates/cadkit-wasmpython -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.
DGN V8 and CityGML
Section titled “DGN V8 and CityGML”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.