Direct library integration
cadkit supplies modules for building CAD viewers, editors, geometry tools and file import/export workflows. Downstream host applications can call the file/document stack through its Rust, Python, WASM, or C/C++ bindings. Format parsing, DGN record encoding, CityGML XML writing and format validation belong in cadkit. The host application supplies its drawing data, export settings, and file destination; no separate conversion service is required.
Choosing modules
Section titled “Choosing modules”Use cadkit for DWG, DGN V7/V8, DXF and CityGML 2.0 input and the supported output paths:
DXF, seed-based DGN V8, CityGML 2.0, SVG and JSON. There is no DWG or DGN V7 writer.
cadkit-core supplies the neutral document and operations such as transforms, unit
conversion, block expansion and layer filtering. Use the
format matrix and each interface’s API guide for coverage.
In Rust, add cadkit-geom independently for analytic geometry with explicit tolerances.
Add cadkit-scene and cadkit-gpu when the application needs scene preparation and GPU
rendering. File I/O does not require them. Python, WASM and C/C++ expose the documented
file/document APIs; the standalone geometry, scene and GPU APIs are Rust modules.
Scene and GPU integration
Section titled “Scene and GPU integration”A Rust host can read or build a Document, enable the document feature on cadkit-scene,
and call document::plan_document with DocumentPlanOptions. This turns one model into
plan items with blocks/arrays expanded, XY projection, layer groups, resolved colors and
lineweight widths. Curves that do not stay circular are flattened to polylines.
Inspect DocumentPlanReport for skipped entity kinds, flattened curves, dashes drawn solid
and traversal truncation. Text, hatches/fills, points, images and viewports are not drawn
by this bridge.
Insert the returned items into Plan2d and feed its frames to cadkit-gpu::PlanRenderer.
Plan2d needs no GPU. PlanRenderer takes the host’s wgpu device, queue, target format
and render pass; it opens no window. The host must draw CPU handoffs, selection/preview
cut-outs and items marked PlanItem::force_cpu. Domain object IDs, change tracking,
interaction and UI remain host responsibilities.
The existing crates/cadkit-gpu/examples/render_png.rs demonstrates the document-to-plan
path and offscreen PNG output. It reports CPU handoffs but has no CPU renderer for them.
For 3D rendering, supply a MeshScene to MeshRenderer;
the document bridge does not automatically create meshes from drawing entities. The
WASM viewer uses SVG and does not expose these Rust renderers.
DGN export
Section titled “DGN export”The host application supplies a neutral Document, a compatible DGN V8 seed, and
dgn::WriteOptions to cadkit::to_dgn. Bindings expose the same operation; the
JSON options accept preserve_seed_rasters without a separate C ABI function.
Units, dimension, palette, and font tables must match the seed
(V8Seed::prepare_document converts units, promotes a 2D document to a 3D seed and maps
symbology when asked). A production seed
should be an approved blank template rather than an arbitrary client drawing.
Obtaining a seed
Section titled “Obtaining a seed”cadkit ships no seed: the file header and model header streams every seed needs hold
undecoded fields whose values differ between the writers of the public samples, so a
built-in seed would have to copy a vendor template’s values or guess them
(format notes). Make one from a drawing whose tables you are allowed to hand on (your
organisation’s own template, a drawing you produced): dgn::strip_seed_v8
(cadkit::strip_dgn_seed, cadkit strip-seed in.dgn seed.dgn --report, Python
strip_dgn_seed, WASM stripDgnSeed, C cadkit_dgn_strip_seed) removes the model’s
graphic records, by default its control records and raster attachments, and every property
set (author, last author, company, manager, title, comments, thumbnail and user-defined
sets), writes minimal property sets and normalised times, and rebuilds the container so no
removed byte survives in free space. It keeps what a seed is for byte for byte: levels,
fonts, colour table, tag sets, text styles, views and settings records, cell definitions
(unless keep_cell_definitions is false), units, and streams cadkit does not decode.
The result is not anonymous. Level names and descriptions, tag set and tag names, cell
names, font and style names, the model name (unless model_name replaces it) and
description, kept control records, kept raster file paths and undecoded streams remain.
StripSeedReport counts them (named_levels, tag_sets, cell_definitions,
model_name_from_seed, model_description, kept_control_records,
raster_file_references, unknown_streams); review them before handing the seed to anyone:
cadkit layers and cadkit blocks list level and cell names, and cadkit dump --json shows
the rest (tag sets and tag names in the document’s dgn.tag_sets, the model description in
the model’s dgn.description, raster file names and paths in the image entities’
dgn.raster_file / dgn.raster_path). A seed made from a client drawing
carries that client’s level and tag names. Stripping is deterministic for equal input and
options (timestamp_ms fixes the stored times) and idempotent. The stripped seed is checked
locally (check_structure, V8Seed::parse, write_v8); it has not been opened in another
application, so confirm acceptance in the target software before relying on it.
When opening and rewriting an existing DGN, passing its original bytes as the
seed preserves unchanged raster attachments (preserve_seed_rasters, enabled by
default). New raster attachments (Image entities without an id, with path
and size_px) are written by cloning a complete attachment group from the seed
(dgn::seed_has_raster_template), or falling back to cadkit’s built-in attachment
template when the seed has none. Editing existing seed attachments in place or
mixing preserved and newly added attachments in a single write is not supported;
rewrite all attachments as new Image entities or keep the seed’s attachments
unchanged. Callers must retain external image files alongside or at the referenced
paths, as DGN raster attachments reference external files rather than embedding pixel data.
A host needs no compound-file or page code of its own to check or prepare a write:
dgn::check_structure(bytes, &ReadOptions)returns aStructureReportof any V8 file (Rust andcadkit check-dgn file.dgn; the Python, WASM and C bindings do not expose it): sibling tree order and shape, unused directory slots, the writer’s slot order, page headers, record times, split dictionary pages and the model header’s page count, with stable warning codes. The writer does not run it on its output; tests check that writes and repacks of the public samples and of synthetic seeds, and writes into 274 private plan seeds, report no warning when the write has a time (WriteOptions::timestamp_msor the seed’s own). A slot order or a page number/population other than the writer’s is not a defect: observed files differ.dgn::V8Seedgives the seed’s palette, levels (reader names), font table (font_entriesin stored order;font_numberresolves a name exactly, then trimmed and ASCII case-insensitive, and tells an absent name from an ambiguous one) and file header time.dgn::palette::exact_indexis the writer’s color match,nearest_indexthe mappingprepare_documentuses.dgn::native::v8::readandnative::decode_v8::decodeexpose pages, page headers, raw records (type, id, complex flags) and decoded tables (ColorTable,Font,Level).
Policies stay with the host: loose or locale-aware matching of level, tag and font names
(pass the resolved dgn.font_number / exact names on), resolving ByBlock from a parent,
how far an RGB may move to a palette entry, and which time to give new records. The writer
keeps unchanged seed pages byte for byte and writes level-sentinel symbology
(dgn.color_index / dgn.weight 0xFFFFFFFF) back as read. Layers read from 240-byte
level entries (the only layout of the private corpus; the three public V8 samples use
104-byte entries, which give no color) carry the level color (Layer.color, dgn.color_index);
a ByLayer entity without its own index is written with the layer’s dgn.color_index.
Center/right text requires measured dgn.text_length in drawing units. The
application must update that value when text or its font metrics change. A read
text’s length is stored in the file, derived from its range
(dgn.text_length_source = "range") or estimated (dgn.text_length_estimated).
Identifier attributes should use the receiving profile’s declared data type;
numeric identifiers must not be routed through an inexact floating-point type.
CityGML export
Section titled “CityGML export”The two public paths have different data contracts:
cadkit::to_citygml(Document, ExportOptions)creates generic geometry objects with an explicit CRS and LoD. It does not infer buildings or independent units.cadkit::gml::write(CityGmlDocument, ValidationOptions)writes an explicit native CityGML model, including object IDs, building/room/surface relationships, shared references and typed attributes. Native JSON and the existing object/polygon builders are available to applications without implementing an XML writer.
The application supplies the meaning of its own objects and the receiving institution’s field mappings. A drawing of a rectangle alone cannot determine whether it represents a room, floor, roof or parcel. Imported CityGML should keep its native model as the source of identity and relationships; the neutral drawing view is a geometric projection, not a replacement for that model.
A host-application adapter should marshal application objects into either the
format-neutral Document or native CityGmlDocument, select the appropriate
export path, surface validation and conversion diagnostics to the user, and write
the returned bytes to the destination.
Conversion diagnostics and TKGM preflight
Section titled “Conversion diagnostics and TKGM preflight”gml::write_document_with_report accepts UnsupportedGeometry::Reject (the
existing default) or the explicit MetadataOnly option. The latter retains the
original neutral entity JSON in cadkit.entity, leaves unsupported GML geometry
absent and returns model/child-index diagnostics. Nested groups keep supported
child geometry and report the missing parts. External raster pixels and block
definitions are not embedded. This generic conversion is not a TKGM delivery.
Closed polylines remain closed curves; callers must create explicit Polygon
entities for surfaces. Circles use exact three-point GML Circle segments.
The same report path is available through Python to_citygml_with_report, WASM
toCityGmlWithReport, C cadkit_document_to_citygml_with_report, the matching C++
method and CLI convert --gml-metadata-only. Python returns (bytes, report);
C/C++ and WASM return JSON with xml and report fields. Metadata-only mode is
opt-in in every interface. Display the report to the application user.
For the public TKGM 3D city-model tender workflow, the production guide
uses CityGML 2.0; its latest listed revision is v2.50 (6 May 2025).
The separate Digital Building registration guide is TKGMCityGML 3.0.3.
Buildings are Building,
storeys are CityObjectGroup and independent sections are GenericCityObject
with the required class, typed attributes and links. Supplying only generic
geometry does not populate that model. See TKGM profile notes.
gml::tkgm::preflight(doc, Profile::CityModelTender, limits) checks a documented
architectural subset on the native model. The distinct
Profile::DigitalBuildingRegistration applies registration-specific rules.
Python exposes CityGmlDocument.preflight_tkgm, WASM preflightTkgm, and C
cadkit_citygml_preflight_tkgm accepts native JSON. Each requires the profile
string city-model-tender or digital-building-registration; there is no default.
CLI uses validate-gml --tkgm-profile city-model-tender.
The report always states acceptance_verified: false and names unchecked rules.
Tender-year-dependent MAKS rules and sustainability extensions are explicitly
unchecked in the common tender subset; select the contract’s rules at acceptance.
The app should run this before export in addition to native geometry and official
XSD checks; the receiving TKGM system remains the final acceptance authority.
Acceptance
Section titled “Acceptance”Local write/read comparisons, independent CFB opening and official XSD checks are necessary checks. They do not establish recipient acceptance. Release gates also need files created by the consuming application, inspection in the target CAD application, save/reopen checks, and validation by the receiving system. For DGN, dgn/ACCEPTANCE.md is the protocol for such a pass with a generated kit of synthetic files; none has been recorded yet. See implementation status and the DGN / CityGML contracts for current coverage and unresolved cases.