ConstructCraft

cc_cad API

← API reference · Generated from the source by cargo run -p api_doc; edit the doc comments, not this page.

Reading DWG and DXF drawings into ConstructCraft’s neutral cc_core::cad::CadDrawing (an underlay placed in a 2D view). DXF (ASCII and binary) is read by an in-house reader: group-code pairs, the HEADER (units, version, code page), the LAYER table, BLOCKS and ENTITIES; blocks are inserted (nested, arrayed, cycle-safe) and 2D entities taken from their object coordinate systems to the plan. DWG is read by the acadrust crate, whose document is written to binary DXF in memory and read by the same reader, so both formats share one path. Everything is bounded (file size, primitives, nesting, work) and errors are values.

Modules

Module Items Summary
cc_cad 10 Reading DWG and DXF drawings into ConstructCraft’s neutral cc_core::cad::CadDrawing (an underlay placed in a 2D view).
cc_cad::dwg 2 DWG files, read by the acadrust crate (MPL-2.0, pure Rust).
cc_cad::dxf 3 DXF files: sections, tables, blocks and entities, read into raw entities (their group pairs) that crate::flatten turns into primitives.
cc_cad::flatten 2 Turning raw entities into flat primitives: object coordinate systems, block insertion (nested, arrayed, cycle-safe and bounded), colors and layers by block, and curve tessellation where a primitive cannot stay an arc.
cc_cad::geom 9 Coordinate systems and curve tessellation for flattening drawings.
cc_cad::svg 4 SVG drawings into the neutral CAD drawing: paths (curves flattened to polylines) in their stroke color, single-outline filled shapes as fills, and embedded pictures as images.
cc_cad::text 2 Text strings of drawings: control codes and MTEXT formatting.
cc_cad::tokens 4 DXF group-code pairs, from ASCII or binary files.

cc_cad

crates/cc_cad/src/lib.rs

Items: CadError · MAX_INSERTS · Limits · Format · CadRead · CadBlock · CadInsert · detect · read · read_file

enum CadError

pub enum CadError

Why a drawing could not be read.

Traits: Debug, Clone, PartialEq, Error

Variants

const MAX_INSERTS

pub const MAX_INSERTS: usize

Most block references one read keeps (Limits::keep_blocks).

struct Limits

pub struct Limits

Bounds on what one read may do.

Traits: Debug, Clone, Default

Fields

enum Format

pub enum Format

File formats.

Traits: Debug, Clone, Copy, PartialEq, Eq, Default

Variants

struct CadRead

pub struct CadRead

A drawing read, with what the reader saw.

Traits: Debug, Clone, Default

Fields

Methods

struct CadBlock

pub struct CadBlock

A block kept as its own drawing: primitives in its frame (drawing units, its base point at the origin, on the drawing’s layers) and the kept blocks it inserts.

Traits: Debug, Clone, Default

Fields

struct CadInsert

pub struct CadInsert

An insert of a kept block: its frame scaled by scale, flipped across its X axis first when mirrored, turned rotation radians and moved to position (drawing units, in the frame of what holds it).

Traits: Debug, Clone, PartialEq

Fields

fn detect

pub fn detect(data: &[u8]) -> Option<Format>

The format of a file’s bytes: DWG files start with their version (AC1015…), binary DXF with its sentinel, ASCII DXF with group pairs.

fn read

pub fn read(data: &[u8], limits: &Limits) -> Result<CadRead, CadError>

Read a drawing from its bytes (DXF, DWG or SVG).

fn read_file

pub fn read_file(path: &std::path::Path, limits: &Limits) -> Result<CadRead, CadError>

Read a drawing file.

cc_cad::dwg

crates/cc_cad/src/dwg.rs

DWG files, read by the acadrust crate (MPL-2.0, pure Rust). The decoded document is written to binary DXF in memory and read by our DXF reader, so DWG and DXF drawings take the same path (blocks, object coordinate systems, colors, limits). acadrust is not written to our robustness rules (it may panic on damaged files), so it runs on its own thread with a large stack, inside catch_unwind; a panic becomes an error and the program goes on. Its memory-mapped reading (unsafe) is not used: the file is read from a byte buffer.

Items: panic_message · read

fn panic_message

pub(crate) fn panic_message(payload: &(dyn std::any::Any + Send)) -> String

fn read

pub fn read(data: &[u8], limits: &Limits) -> Result<CadRead, CadError>

cc_cad::dxf

crates/cc_cad/src/dxf.rs

DXF files: sections, tables, blocks and entities, read into raw entities (their group pairs) that crate::flatten turns into primitives. Model space entities are flattened as they are read, so the largest section is never held whole.

Items: Entity · read · rgb

struct Entity

pub struct Entity

An entity as read: its type, its groups in order, and the entities that belong to it (a polyline’s vertices, an insert’s attributes).

Traits: Debug, Clone, Default

Fields

Methods

fn read

pub fn read(data: &[u8], limits: &Limits) -> Result<CadRead, CadError>

Reads a whole DXF file.

fn rgb

pub fn rgb(v: i64) -> [u8; 3]

The color of a 24-bit true color value.

cc_cad::flatten

crates/cc_cad/src/flatten.rs

Turning raw entities into flat primitives: object coordinate systems, block insertion (nested, arrayed, cycle-safe and bounded), colors and layers by block, and curve tessellation where a primitive cannot stay an arc.

Items: Block · Flattener

struct Block

pub struct Block

A block definition: its base point and entities.

Traits: Debug, Clone, Default

Fields

struct Flattener

pub struct Flattener

Some fields are private.

Methods

cc_cad::geom

crates/cc_cad/src/geom.rs

Coordinate systems and curve tessellation for flattening drawings.

Items: MAX_CURVE_SEGMENTS · ocs_axes · ocs · Affine2 · arc_segments · arc_points · bulge_arc · ellipse_points · spline_points

const MAX_CURVE_SEGMENTS

pub const MAX_CURVE_SEGMENTS: usize

Most segments one curve (ellipse, spline) is tessellated into.

fn ocs_axes

pub fn ocs_axes(normal: DVec3) -> (DVec3, DVec3, DVec3)

The object coordinate system of an extrusion direction (the DXF “arbitrary axis algorithm”): its X and Y axes in world coordinates.

fn ocs

pub fn ocs(normal: DVec3) -> DAffine3

The transform from an OCS (of normal) to world coordinates.

struct Affine2

pub struct Affine2

A 2D affine map p ↦ m·p + t (the plan projection of a 3D transform of a plane).

Traits: Debug, Clone, Copy, PartialEq

Fields

Methods

fn arc_segments

pub fn arc_segments(sweep: f64) -> usize

Number of segments for sweep radians, about 5° each, within bounds.

fn arc_points

pub fn arc_points(center: DVec2, radius: f64, start: f64, sweep: f64) -> Vec<DVec2>

Points of a circular arc.

fn bulge_arc

pub fn bulge_arc(a: DVec2, b: DVec2, bulge: f64) -> Option<(DVec2, f64, f64, f64)>

The arc of a polyline segment from a to b with bulge: center, radius, start angle and sweep; None for a straight segment.

fn ellipse_points

pub fn ellipse_points(center: DVec3, major: DVec3, ratio: f64, normal: DVec3, t0: f64, t1: f64) -> Vec<DVec3>

Points of an elliptical arc (world coordinates) from parameter t0 to t1, counter-clockwise about normal.

fn spline_points

pub fn spline_points(degree: usize, knots: &[f64], control: &[DVec3], weights: &[f64]) -> Option<Vec<DVec3>>

Points along a NURBS curve of degree with knots and control points (weights optional), by de Boor’s algorithm; None when the data is inconsistent.

cc_cad::svg

crates/cc_cad/src/svg.rs

SVG drawings into the neutral CAD drawing: paths (curves flattened to polylines) in their stroke color, single-outline filled shapes as fills, and embedded pictures as images. Units are millimeters at the CSS 96 pixels per inch, y up, the page’s bottom-left corner at the origin. Texts are not read (they need fonts): SVGs from CAD programs usually carry them as outlines already.

Items: MAX_SVG_BYTES · is_svg · options · read

const MAX_SVG_BYTES

pub const MAX_SVG_BYTES: usize

Largest SVG file read, bytes.

fn is_svg

pub fn is_svg(data: &[u8]) -> bool

Whether data looks like SVG (an <svg element near the start).

fn options

pub fn options() -> usvg::Options<'static>

Parsing options that read nothing but the file itself: an <image> whose href is not a data: URL (a path on this machine, say) comes in empty.

fn read

pub fn read(data: &[u8], limits: &Limits) -> Result<CadRead, CadError>

Read an SVG file’s bytes. usvg parses and converts nested elements recursively (it allows over a thousand levels), which can overflow a small stack, and a stack overflow aborts the process; so the file is read on a thread of its own with a large stack, inside catch_unwind, like DWG files.

cc_cad::text

crates/cc_cad/src/text.rs

Text strings of drawings: control codes and MTEXT formatting.

Items: plain · mtext_lines

fn plain

pub fn plain(s: &str) -> String

Replace \U+XXXX escapes and the %% control codes of single-line text (%%c diameter, %%d degree, %%p plus-minus, %%nnn a character code; %%u/%%o underline and overline toggles dropped).

fn mtext_lines

pub fn mtext_lines(s: &str) -> Vec<String>

The lines of an MTEXT string without its formatting: \P breaks lines, \~ is a space, \\ \{ \} are literal, stacked fractions \Sa^b; become a/b, other codes (\A1;, \H2x;, \fArial|b0;, \C1;, \L…) and grouping braces are removed.

cc_cad::tokens

crates/cc_cad/src/tokens.rs

DXF group-code pairs, from ASCII or binary files. A DXF file is a sequence of (group code, value) pairs; the code decides the value’s type. ASCII files put each on its own line; binary files (after the sentinel AutoCAD Binary DXF\r\n\x1a\0) store the code as a little-endian 16-bit integer and the value in its binary form.

Items: BINARY_SENTINEL · Val · Decoder · Pairs

const BINARY_SENTINEL

pub const BINARY_SENTINEL: &[u8]

The sentinel that starts a binary DXF file.

enum Val

pub enum Val

A group value.

Traits: Debug, Clone, PartialEq

Variants

Methods

struct Decoder

pub struct Decoder

Decodes strings: UTF-8 when valid, else the drawing’s code page.

Traits: Default

Some fields are private.

Methods

struct Pairs

pub struct Pairs<'a>

Reads pairs one at a time, with one pair of look-ahead.

Fields

Some fields are private.

Methods