Skip to main content

cadkit_dxf/
lib.rs

1//! DXF reader and writer (ASCII and binary) for the cadkit model.
2//!
3//! Contract used by the `cadkit` facade: [`sniff()`], [`read()`], [`write()`].
4//!
5//! * [`read`] accepts ASCII and binary DXF from R12 (AC1009) to 2018 (AC1032) and maps it to
6//!   a [`cadkit_core::Document`]. Geometry of planar entities is converted to world
7//!   coordinates; see `docs/dxf/NOTES.md` for every mapping decision.
8//! * [`write()`] produces ASCII DXF in one of the [`DxfVersion`]s.
9//! * [`native`] exposes the group-code tokenizer for scanners and oracles.
10
11pub mod native;
12mod ocs;
13mod reader;
14mod writer;
15
16use cadkit_core::{Document, ReadOptions, Result, Summary, Warning};
17
18/// DXF output version.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
20#[non_exhaustive]
21pub enum DxfVersion {
22    /// AutoCAD R12 (AC1009).
23    R12,
24    /// AutoCAD 2000 (AC1015).
25    R2000,
26    /// AutoCAD 2004 (AC1018).
27    R2004,
28    /// AutoCAD 2007 (AC1021).
29    R2007,
30    /// AutoCAD 2010 (AC1024).
31    R2010,
32    /// AutoCAD 2013 (AC1027).
33    R2013,
34    /// AutoCAD 2018 (AC1032).
35    #[default]
36    R2018,
37}
38
39impl DxfVersion {
40    /// The `$ACADVER` string of this version (for example `"AC1015"`).
41    pub fn acadver(self) -> &'static str {
42        match self {
43            DxfVersion::R12 => "AC1009",
44            DxfVersion::R2000 => "AC1015",
45            DxfVersion::R2004 => "AC1018",
46            DxfVersion::R2007 => "AC1021",
47            DxfVersion::R2010 => "AC1024",
48            DxfVersion::R2013 => "AC1027",
49            DxfVersion::R2018 => "AC1032",
50        }
51    }
52}
53
54/// Returns true when `bytes` look like DXF (ASCII or binary).
55///
56/// Only the first few groups are inspected: binary files by their sentinel, ASCII files by
57/// `0` / `SECTION` (after optional `999` comments).
58pub fn sniff(bytes: &[u8]) -> bool {
59    native::sniff(bytes)
60}
61
62/// Inspects the DXF `HEADER` section without decoding tables, blocks, or entities.
63pub fn inspect(bytes: &[u8], options: &ReadOptions) -> Result<Summary> {
64    reader::inspect(bytes, options)
65}
66
67/// Reads a DXF file into the format-neutral model.
68///
69/// Fails only when no useful document can be produced (not DXF, limits exceeded, or no
70/// section could be read); damaged or truncated files yield a partial document with
71/// `dxf.truncated` warnings.
72pub fn read(bytes: &[u8], options: &ReadOptions) -> Result<Document> {
73    reader::read(bytes, options)
74}
75
76/// Options for DXF output.
77#[derive(Debug, Clone, PartialEq, Eq, Default)]
78#[non_exhaustive]
79pub struct WriteOptions {
80    /// Target DXF release (`R2018` by default).
81    pub version: DxfVersion,
82    /// Optional legacy `$DWGCODEPAGE`, WHATWG, or OEM encoding label (for example
83    /// `"ANSI_1254"`, `"windows-1254"`, `"DOS857"`, or `"cp857"`) for pre-R2007 output.
84    /// Characters representable in that 8-bit encoding are emitted directly as raw bytes;
85    /// unrepresentable characters remain `\U+XXXX` escapes.
86    pub codepage: Option<String>,
87}
88
89impl WriteOptions {
90    /// Creates DXF output options for `version`.
91    #[must_use]
92    pub fn new(version: DxfVersion) -> Self {
93        Self {
94            version,
95            codepage: None,
96        }
97    }
98
99    /// Sets the target DXF release.
100    #[must_use]
101    pub fn with_version(mut self, version: DxfVersion) -> Self {
102        self.version = version;
103        self
104    }
105
106    /// Sets an explicit legacy `$DWGCODEPAGE` / WHATWG / OEM output encoding for pre-R2007 DXF.
107    #[must_use]
108    pub fn with_codepage(mut self, codepage: Option<String>) -> Self {
109        self.codepage = codepage;
110        self
111    }
112}
113
114/// Writes `doc` as ASCII/UTF-8 DXF text.
115pub fn write(doc: &Document, version: DxfVersion) -> Result<String> {
116    writer::write(doc, version).map(|(text, _)| text)
117}
118
119/// Like [`write()`], but also returns the warnings for everything that could not be
120/// represented (skipped unknown entities, undefined block references, ...).
121pub fn write_with_report(doc: &Document, version: DxfVersion) -> Result<(String, Vec<Warning>)> {
122    writer::write(doc, version)
123}
124
125/// Writes `doc` as DXF bytes using `options` (honoring legacy 8-bit `codepage` on pre-R2007 versions).
126pub fn write_bytes(doc: &Document, options: &WriteOptions) -> Result<Vec<u8>> {
127    writer::write_bytes(doc, options).map(|(bytes, _)| bytes)
128}
129
130/// Like [`write_bytes()`], returning both the encoded DXF bytes and conversion warnings.
131pub fn write_bytes_with_report(
132    doc: &Document,
133    options: &WriteOptions,
134) -> Result<(Vec<u8>, Vec<Warning>)> {
135    writer::write_bytes(doc, options)
136}