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.
| 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_cadcrates/cc_cad/src/lib.rs
Items: CadError · MAX_INSERTS · Limits · Format · CadRead · CadBlock · CadInsert · detect · read · read_file
CadErrorpub enum CadError
Why a drawing could not be read.
Traits: Debug, Clone, PartialEq, Error
Variants
TooLarge(usize)UnknownFormatFormat(String)TooComplex(String)Dwg(String)Io(String)MAX_INSERTSpub const MAX_INSERTS: usize
Most block references one read keeps (Limits::keep_blocks).
Limitspub struct Limits
Bounds on what one read may do.
Traits: Debug, Clone, Default
Fields
max_dxf_bytes: usize
Largest DXF file, bytes.
max_dwg_bytes: usize
Largest DWG file, bytes.
max_prims: usize
Most primitives produced (blocks inserted).
max_work: usize
Most entity visits while inserting blocks (arrays of nested blocks).
max_points: usize
Most points and text characters handled in all: those of every entity read (each time a block inserts it) and of every primitive produced, so one large entity in an arrayed block cannot ask for more memory or time than this.
max_depth: usize
Deepest block nesting followed.
max_block_entities: usize
Most entities kept in block definitions.
keep_blocks: bool
Keep block inserts as references (CadRead::inserts) and the
blocks they use as their own drawings (CadRead::kept) instead of
flattening them into the drawing, wherever an insert places its
block by a similarity of the plan (move, turn, uniform scale,
mirror); other inserts, anonymous blocks and dimensions are still
flattened. DXF and DWG only.
Formatpub enum Format
File formats.
Traits: Debug, Clone, Copy, PartialEq, Eq, Default
Variants
DxfDwgSvgCadReadpub struct CadRead
A drawing read, with what the reader saw.
Traits: Debug, Clone, Default
Fields
drawing: CadDrawingformat: Formatversion: String
$ACADVER (e.g. AC1032).
binary: bool
A binary DXF file (or a DWG, read through binary DXF).
entities: usize
Model space entities read.
blocks: usize
Block definitions read.
skipped: BTreeMap<String, usize>
Entities not drawn, by type.
truncated: bool
A limit stopped the reader; the drawing is incomplete.
kept: Vec<CadBlock>
Blocks kept (with Limits::keep_blocks): those the drawing uses.
inserts: Vec<CadInsert>
Where the drawing inserts kept blocks.
Methods
pub fn skipped_total(&self) -> usizeCadBlockpub 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
name: String
The block’s name, upper case (as DXF compares them).
prims: Vec<cc_core::cad::CadPrim>inserts: Vec<CadInsert>CadInsertpub 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
block: Stringposition: glam::DVec2rotation: f64scale: f64mirrored: boollayer: u32
The insert’s own layer and color.
color: Option<[u8; 3]>detectpub 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.
readpub fn read(data: &[u8], limits: &Limits) -> Result<CadRead, CadError>
Read a drawing from its bytes (DXF, DWG or SVG).
read_filepub fn read_file(path: &std::path::Path, limits: &Limits) -> Result<CadRead, CadError>
Read a drawing file.
cc_cad::dwgcrates/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
panic_messagepub(crate) fn panic_message(payload: &(dyn std::any::Any + Send)) -> String
readpub fn read(data: &[u8], limits: &Limits) -> Result<CadRead, CadError>
cc_cad::dxfcrates/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.
Entitypub 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
name: Stringgroups: Vec<(i32, Val)>children: Vec<Entity>Methods
pub fn get(&self, code: i32) -> Option<&Val>pub fn real(&self, code: i32, default: f64) -> f64pub fn int(&self, code: i32, default: i64) -> i64pub fn str(&self, code: i32) -> &strpub fn has(&self, code: i32) -> boolpub fn point(&self, code: i32) -> DVec3
The point of groups code, code + 10, code + 20 (first occurrence).
pub fn normal(&self) -> DVec3
The extrusion direction (210/220/230), +Z by default.
pub fn points(&self, code: i32) -> Vec<DVec3>
Every point of groups code/code + 10/code + 20, in order.
pub fn reals(&self, code: i32) -> Vec<f64>
Every value of code, in order.
readpub fn read(data: &[u8], limits: &Limits) -> Result<CadRead, CadError>
Reads a whole DXF file.
rgbpub fn rgb(v: i64) -> [u8; 3]
The color of a 24-bit true color value.
cc_cad::flattencrates/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.
Blockpub struct Block
A block definition: its base point and entities.
Traits: Debug, Clone, Default
Fields
base: DVec3entities: Vec<Entity>Flattenerpub struct Flattener
Some fields are private.
Methods
pub fn new(limits: &Limits) -> Selfpub fn take_inserts(&mut self) -> Vec<CadInsert>
The block references of the drawing’s entities (blocks kept).
pub fn kept_blocks(&mut self, blocks: &HashMap<String, Block>) -> Vec<CadBlock>
The blocks the drawing references, each read on its own (base point
at the origin, layer 0 and BYBLOCK left as they are), with the
references they make to others; a reference that would close a
cycle is dropped. Call after the entities and Self::take_inserts.
pub fn set_layers(&mut self, layers: &[CadLayer])
Register the layers of the LAYER table (kept in file order).
pub fn finish(mut self) -> (Vec<CadPrim>, Vec<CadLayer>, bool)
The primitives, the layers and whether a limit cut the drawing short.
pub fn top_level(&mut self, e: &Entity, blocks: &HashMap<String, Block>)
Flatten a model space entity.
cc_cad::geomcrates/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
MAX_CURVE_SEGMENTSpub const MAX_CURVE_SEGMENTS: usize
Most segments one curve (ellipse, spline) is tessellated into.
ocs_axespub 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.
ocspub fn ocs(normal: DVec3) -> DAffine3
The transform from an OCS (of normal) to world coordinates.
Affine2pub 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
m: DMat2t: DVec2Methods
pub fn of_plane(t: &DAffine3, elevation: f64) -> Self
Points (x, y) of the plane z = elevation of the frame t, projected on the world XY plane.
pub fn apply(&self, p: DVec2) -> DVec2pub fn vector(&self, v: DVec2) -> DVec2pub fn det(&self) -> f64pub fn similarity(&self) -> Option<f64>
The uniform scale when the map is a similarity (rotation, uniform
scale, maybe a mirror), else None.
arc_segmentspub fn arc_segments(sweep: f64) -> usize
Number of segments for sweep radians, about 5° each, within bounds.
arc_pointspub fn arc_points(center: DVec2, radius: f64, start: f64, sweep: f64) -> Vec<DVec2>
Points of a circular arc.
bulge_arcpub 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.
ellipse_pointspub 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.
spline_pointspub 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::svgcrates/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
MAX_SVG_BYTESpub const MAX_SVG_BYTES: usize
Largest SVG file read, bytes.
is_svgpub fn is_svg(data: &[u8]) -> bool
Whether data looks like SVG (an <svg element near the start).
optionspub 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.
readpub 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::textcrates/cc_cad/src/text.rs
Text strings of drawings: control codes and MTEXT formatting.
Items: plain · mtext_lines
plainpub 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).
mtext_linespub 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::tokenscrates/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
BINARY_SENTINELpub const BINARY_SENTINEL: &[u8]
The sentinel that starts a binary DXF file.
Valpub enum Val
A group value.
Traits: Debug, Clone, PartialEq
Variants
Str(String)Real(f64)Int(i64)Bin
Binary chunks (thumbnails, proxy data): ignored.
Methods
pub fn real(&self) -> f64pub fn int(&self) -> i64pub fn str(&self) -> &strDecoderpub struct Decoder
Decodes strings: UTF-8 when valid, else the drawing’s code page.
Traits: Default
Some fields are private.
Methods
pub fn set_code_page(&mut self, name: &str)
Use the code page named by $DWGCODEPAGE (e.g. ANSI_1252).
pub fn decode(&self, bytes: &[u8]) -> String
Pairspub struct Pairs<'a>
Reads pairs one at a time, with one pair of look-ahead.
Fields
decoder: DecoderSome fields are private.
Methods
pub fn new(data: &'a [u8]) -> Selfpub fn is_binary(&self) -> boolpub fn next_pair(&mut self) -> Result<Option<(i32, Val)>, CadError>
The next pair, or None at the end of the data.
pub fn peek(&mut self) -> Result<Option<&(i32, Val)>, CadError>
Look at the next pair without consuming it.