Architecture
cadkit is a modular CAD engine for building CAD applications. Its file/document stack, standalone geometry, scene data and GPU renderers can be adopted independently. The host supplies the UI, editing workflow and domain semantics.
File I/O and document stack
Section titled “File I/O and document stack” ┌──────────── bindings ────────────┐ cadkit-cli cadkit-py (PyO3) cadkit-wasm cadkit-capi (C ABI + C++ header) └───────────────┬──────────────┴──────────────┘ cadkit facade: detect / read / open / to_json / to_svg / to_dxf / to_dgn / to_citygml ┌───────────┬───┴──────┬────────────┬────────────┐ cadkit-dgn cadkit-dwg cadkit-dxf cadkit-gml format crates: native I/O ↔ Document └───────────┴────┬─────┴────────────┴────────────┘ cadkit-core model, document operations, bounded I/O, JSON, SVGAnalytic geometry
Section titled “Analytic geometry”cadkit-geom is an independent f64 analytic geometry crate, alongside the format
stack above:
cadkit-geom analytic curves, polygons, booleans, calibration, NURBS | no dependencies on any other cadkit crate +-- serde, thiserror, i_overlay, robust, optional schemarsThe facade and format crates do not depend on the scene or GPU crates; reading a format must not pull in a GPU runtime. Geometry coordinates and tolerances belong to the caller; see geometry contracts.
Scene and rendering
Section titled “Scene and rendering”cadkit-scene GPU-free: Plan2d chunked 2D line/arc store with an f32 error | budget and instance encoding; Mesh3d triangle meshes +-- cadkit-geom, thiserror (WASM-compatible) +-- cadkit-core only with the optional document feature
cadkit-gpu wgpu 30: PlanRenderer (analytic lines/arcs), MeshRenderer | (lit meshes, orbit camera), render targets and readback +-- cadkit-scene, wgpu, glam, thiserrorcadkit-gpu takes a wgpu::Device, Queue, target format and RenderPass; it opens no
window and depends on no UI toolkit. cadkit_gpu::wgpu is re-exported, so callers use the
same wgpu; a wgpu major upgrade is a cadkit minor release. Uploads happen in
prepare, paint only records draw calls, so a UI toolkit’s render pass can host it.
GPU errors are captured with error scopes and returned as GpuError.
cadkit-scene knows how to draw, not what the geometry means. Callers map their
objects to ObjectIds, choose colors and stroke widths in pixels, track which objects
changed and call upsert / remove; change tracking and domain rules stay with the
caller. Chunks that would draw imprecisely in f32 at the current zoom, curves the GPU
does not represent and objects without bounds are returned to the caller’s CPU path
for that frame, never dropped. The instance byte layout is documented in
cadkit_scene::layout.
The optional cadkit-scene/document feature provides document::plan_document: one
neutral document model becomes plan items, with blocks/arrays expanded, placement applied,
XY projection, layer groups and resolved colors/lineweights. Non-circular curves are
flattened. DocumentPlanReport records skipped entity kinds, flattened curves, dashes drawn
solid and traversal truncation. The bridge produces plan items, not 3D meshes; a host
constructs its MeshScene separately. PlanItem::force_cpu explicitly requests the host’s
CPU drawing path. See host integration.
The curve and NURBS helpers in cadkit-core overlap with the standalone geometry layer;
they remain separate APIs with their own contracts.
Contracts
Section titled “Contracts”Each format crate exposes at least:
pub fn sniff(bytes: &[u8]) -> bool; // header check onlypub fn read(bytes: &[u8], options: &ReadOptions) -> Result<Document>; // full readcadkit-dxf exposes write(&Document, DxfVersion) -> Result<String>.
cadkit-dgn exposes, with its default write feature, write_v8(&Document, seed, &WriteOptions) and write_v8_with_seed(&Document, &V8Seed, &WriteOptions) (a parsed seed
with prepare_document, palette, level and font table accessors), repack_v8,
seed_has_raster_template and strip_seed_v8(seed, &StripSeedOptions, &ReadOptions) -> StrippedSeed (the seed bytes and a StripSeedReport of what was removed and which names
remain); without that feature, check_structure(bytes, &ReadOptions) -> StructureReport
(compound file directory and pages of a V8 file, stable warning codes) and the
palette::exact_index / nearest_index colour matches. The facade re-exports the crate as
cadkit::dgn and adds to_dgn, to_dgn_with_seed, write_dgn_to and strip_dgn_seed.
cadkit-gml exposes bounded native XML read/write (CityGmlDocument), a neutral
geometry bridge, and optional local structural TKGM preflight (cadkit-gml::tkgm);
the facade offers to_dgn and to_citygml (plus gml::write_document_with_report).
Seed, CRS, and options are explicit inputs.
CityGML semantics live in cadkit-gml::CityGmlDocument. EntityKind::Polygon
is the format-neutral exception: an exterior and interior rings are necessary to
carry holes honestly through CAD operations and SVG/DXF export. Building/room/LoD
semantics are not added to core. Native CityGML, rather than a reverse-engineered
neutral projection, is the authoritative input for preservation roundtrips.
See GML contracts and DGN writer limits.
cadkit::gml::tkgm checks documented public structural subsets on native CityGML
without certifying institutional acceptance; proprietary domain rules and host-application
workflows live outside this repository.
Format crates are layered internally:
- container — file framing (DGN V8: OLE compound file + zlib pages; DWG: file header, sections, page maps, LZ77 / Reed-Solomon; DGN V7: flat record stream; CityGML 2.0: bounded UTF-8 XML token stream).
- records — native, lossless structures (
DgnElement,DwgObject,CityGmlDocument), public so advanced users can inspect or preserve native structure. - mapping — native ↔
cadkit_core::Document.
Model rules (crates/cadkit-core/src/model.rs)
Section titled “Model rules (crates/cadkit-core/src/model.rs)”- Coordinates in drawing units described by
Document::units. DGN: master units =(uor - global_origin) / uor_per_master. - Angles in radians, CCW about the entity normal.
- References by name (layer, block, linetype, style).
- DGN levels →
Layer; shared cell definitions →Block; shared cell instances →Insert; normal cells, complex chains/shapes and text nodes →Groupwith children. - DGN tags / item-type properties and DWG ATTRIBs →
Entity::attributes. A DGN tag element’s own level, display, color and weight →Attribute::layer,display,colorandlineweight(None= the owner’s; the native values stay in the attribute’sdgn.color_index/dgn.weightprops). - DGN palette colors resolve to
Color::Rgb; the index goes toprops["dgn.color_index"]. An element storing the by-level value0xFFFFFFFFreads asColor::ByLayerwith that value kept; hidden V8 graphics (property bit0x0080) read withvisible = false. - Anything decoded without a typed home goes to
propswith a format prefix. Entity::rawis filled only whenReadOptions::keep_rawis set.
Versioned JSON and Rust API migration
Section titled “Versioned JSON and Rust API migration”Document JSON written by 0.5 includes schema_version: 1. JSON without the field still
reads; other schema versions return Error::SchemaVersion. cadkit-core/schemars provides
JSON Schema generation, with the current schema committed in
schema/document-v1.schema.json.
Model and option types marked #[non_exhaustive] are constructed through new(),
Default and with_* setters; non-exhaustive enum matches need a fallback arm.
Error::LimitExceeded has named limit: LimitKind and message fields. These are 0.5
source changes; see the 0.4 migration guide for exact
replacements. Later 0.5.x releases follow the documented additive API policy.
Errors and limits
Section titled “Errors and limits”Error carries absolute offsets. Readers return Err only when no useful document can be
built; recoverable issues become Document::warnings. All file-provided sizes are checked
against Limits before allocation.
For untrusted SVG previews, to_svg_bounded (toSvgBounded in WASM) enforces an
explicit complete-output UTF-8 byte budget, bounds temporary SVG strings before
growth and rejects work-budget exhaustion. It returns LimitExceeded, never a
partial drawing. Existing SVG APIs retain their coarse body cap and truncation
marker. A host still owns parser limits, worker lifetime and any markup added to
the result; the SVG cap is not a total-process-memory cap.
Bindings
Section titled “Bindings”- cadkit-cli:
inspect,info,layers,blocks,dump,convert(JSON, SVG, DXF, seed-based DGN, CityGML),validate-gml,check-dgn(theStructureReportas JSON, exit 1 on warnings),repack-dgn,strip-seed(StripSeedOptionsas flags,--report) andcompletions. - cadkit-py:
cadkit.read(bytes|path) -> Document,cadkit.read_citygml(bytes) -> CityGmlDocument(Python classes and dicts via JSON),doc.to_svg(),doc.to_dxf(),doc.to_dgn(),doc.to_citygml()/doc.to_citygml_with_report(),doc.to_json(),CityGmlDocument.preflight_tkgm(),V8Seed(parsed seed,prepare_document) andcadkit.strip_dgn_seed(seed, **options) -> (bytes, dict); built with maturin, abi3 wheels. - cadkit-wasm:
read(Uint8Array) -> CadDocument,readCityGml(Uint8Array) -> CityGmlDocument,toSvg,toDxf,toDgn,toCityGml/toCityGmlWithReport,preflightTkgm,stripDgnSeed(seed, options?, readOptions?) -> { seed, report }; plus a static drag-and-drop viewer page incrates/cadkit-wasm/www/. - cadkit-capi: opaque
cadkit_document*(live-handle registry: double free returnsCADKIT_INVALID_HANDLE),cadkit_statusreturn codes, thread-local last-error message,cadkit_document_infostruct + JSON/SVG/DXF/DGN/CityGML exporters,cadkit_dgn_strip_seed(seed bytes and report JSON), native CityGML JSON I/O and TKGM preflight,cadkit_status_string,cadkit_version; hand-writteninclude/cadkit.h(a test fails on missing exports) and a header-only C++17 RAII wrapperinclude/cadkit.hpp(cadkit::strip_dgn_seed). No panic crosses the boundary.
check_structure, repack_v8 (CLI: check-dgn, repack-dgn), the V8Seed font table
accessors, the palette matches and the native record layer are Rust-only. The new
Attribute::color / lineweight fields reach Python, WASM and C through document JSON
(omitted when unset, schema_version 1).
Bindings expose header-only inspection and neutral document operations. Python and C/C++ unit conversion/block expansion return new immutable documents; WASM performs the same operations in-place. C additions use separate entry points without enlarging existing ABI structs. The CLI accepts bounded stdin, explicit stdout formats, legacy DXF output code pages, and transform/filter options. SVG hidden-layer inclusion is a separate render/walk entry point. C ABI layouts and the Python/WASM APIs were retained in 0.5; Rust callers follow the constructor and non-exhaustive migration described above.
The bindings expose file I/O and their documented document operations. They do not expose
the standalone cadkit-geom, cadkit-scene or cadkit-gpu APIs; the browser viewer uses
SVG output. Rust rendering integration is a separate path.