cadmpeg-ir

cadmpeg-ir defines the format-neutral document exchanged by cadmpeg codecs. It provides the CadIr data model, codec interfaces, validation, structural diffing, JSON serialization, and explicit representations of source fidelity and decode loss.

Schema detail lives in CAD IR version 7.

Install

cargo add cadmpeg-ir

Model

The topology graph follows body → region → shell → face → loop → coedge → edge → vertex. Faces reference surface carriers, edges reference curve carriers, coedges may reference parameter-space curves, and vertices reference points. IDs are globally unique within a document. Arena order is canonical after CadIr::finalize; every arena is sorted lexicographically by entity ID.

Coordinates and linear quantities use millimeters. Angular quantities use radians. Call validate_neutral after construction or transformation. Constructors leave document invariants unchecked.

Construct and consume a document

Create and validate an empty current-version document:

use cadmpeg_ir::units::Units;
use cadmpeg_ir::{validate_neutral, CadIr};

let mut ir = CadIr::empty(Units::default());
// Populate ir.model arenas and use typed IDs to connect entities.
let arena = cadmpeg_core::decode::DecodeArena::new();
let (ctx, _) = cadmpeg_core::decode::DecodeContext::from_root_bytes(
    &[], &arena, &cadmpeg_core::decode::DecodePolicy::default(),
)?;
ir.finalize(&ctx)?;
let report = validate_neutral(&ir, Vec::new());

assert!(report.is_ok());
assert_eq!(ir.ir_version, cadmpeg_ir::IR_VERSION);

CadIr::to_canonical_json clones and finalizes the document before it emits pretty JSON. CadIr::from_json accepts exactly ir_version: "7". The model.subds arena is required, including when empty. diff compares units, tolerances, annotations, and entity arenas by stable identity.

Format crates implement the object-safe Codec trait. A consumer can select a codec by detection confidence, inspect a container without decoding geometry, then decode the selected source:

use cadmpeg_ir::{Codec, Confidence};

use cadmpeg_core::{CodecError, decode::{DecodeContext, View}};

fn accepts(codec: &dyn Codec, ctx: &DecodeContext<'_>, prefix: View<'_>) -> Result<bool, CodecError> {
    Ok(codec.detect(ctx, prefix)? >= Confidence::Medium)
}

DecodeResult contains the finalized document, a DecodeReport, and a SourceFidelity sidecar for provenance, conversion exactness, and retained native records. CodecError covers wrong format, malformed container, unsupported capability, and I/O failure. LossNote records transferred information that was approximated or omitted. UnknownRecord retains an uninterpreted source record by location, digest, links, and optional bytes.

Entity and field fidelity belongs in sidecar Annotations. Missing exactness entries mean byte-exact. Other entries distinguish deterministic derivation, inference, and unknown origin. Provenance entries identify source streams and byte offsets.

Documentation

• API documentation
• CAD IR version 7
• Architecture and crate map
• Clean-room and legal policy
• Repository

Requires Rust 1.88 or later. Licensed under Apache-2.0.