2bc41aeb8602
lib.rs
//! CAD interchange: a DXF writer (versions R12 to 2018) on `craft_dxf::drawing` and a reader on
//! `craft_dxf::model`, and an HP-GL/2 plot file reader and writer.
//!
//! [`export`] writes the visible art of a document into one DXF drawing: each layer becomes a DXF
//! layer (hidden ones switched off, locked ones locked, non-printing ones not plotted), paths
//! become polylines (straight segments) or cubic splines (curves), fills their outlines and solid
//! hatches, type text entities or glyph outlines, and placed images image entities linked to PNG
//! or JPEG files the caller writes next to the drawing. Coordinates are y-up, in drawing units: `scale` units per
//! `unit` of the art, with the origin at the bottom-left corner of [`DxfOptions::region`].
//! [`export_drawings`] writes one such drawing for each of several regions, applying the live
//! effects once for all of them.
//!
//! What DXF can't hold (blending modes, opacity masks, raster effects, gradients, patterns,
//! clipping) is approximated or left out, and each such loss comes back as a warning.
//!
//! [`import()`] reads a DXF drawing (ASCII or binary, any version) into a document: see [`import`].
//! [`hpgl::import`] reads an HP-GL plotter file, and [`hpgl::export`] writes one: see [`hpgl`].
//!
//! - `aci`: the 256-colour index palette and the nearest index of a colour.
//! - The ASCII file around those entities is written by `craft_dxf::drawing`.
//! - `scene`: the document walk that turns objects into entities.
//! - `import`: the reader, entities to art, blocks to symbols.
//! - `hpgl`: the HP-GL reader, the pen's moves to paths, and the writer, paths to pen moves.
mod aci;
pub mod hpgl;
pub mod import;
mod scene;
use vectorcraft_doc::{Document, Unit};
use vectorcraft_geom::Rect;
pub use aci::{aci_rgb, nearest_aci};
pub use import::{DxfInfo, ImportOptions, Imported, import, info, is_dxf};
/// How deep symbols, blocks and brush art may nest in one another (deeper art is left out).
const MAX_NEST: u32 = 8;
/// Cap height as a fraction of the type size: the height of CAD text is that of its capitals.
const CAP_HEIGHT: f64 = 0.7;
/// The `$INSUNITS` codes of the units documents use (feet and inches write feet).
const INSUNITS: [(u8, Unit); 7] =
[(1, Unit::Inches), (2, Unit::Feet), (2, Unit::FeetInches), (4, Unit::Millimeters), (5, Unit::Centimeters), (6, Unit::Meters), (10, Unit::Yards)];
/// The `$INSUNITS` code of `unit` (none for points, picas and pixels).
fn insunits_code(unit: Unit) -> Option<u8> {
INSUNITS.iter().find(|(_, u)| *u == unit).map(|(c, _)| *c)
}
/// The DXF version a file is written for (the `$ACADVER` it declares).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
pub enum DxfVersion {
R12,
R13,
R14,
R2000,
R2004,
R2007,
R2010,
R2013,
#[default]
R2018,
}
impl DxfVersion {
/// Newest first, as version menus list them.
pub const ALL: [Self; 9] = [Self::R2018, Self::R2013, Self::R2010, Self::R2007, Self::R2004, Self::R2000, Self::R14, Self::R13, Self::R12];
/// The `version` param value.
pub fn id(self) -> &'static str {
match self {
Self::R12 => "R12",
Self::R13 => "R13",
Self::R14 => "R14",
Self::R2000 => "2000",
Self::R2004 => "2004",
Self::R2007 => "2007",
Self::R2010 => "2010",
Self::R2013 => "2013",
Self::R2018 => "2018",
}
}
/// The releases that write this version (menus).
pub fn label(self) -> &'static str {
match self {
Self::R12 => "R12",
Self::R13 => "R13",
Self::R14 => "R14",
Self::R2000 => "2000โ2002",
Self::R2004 => "2004โ2006",
Self::R2007 => "2007โ2009",
Self::R2010 => "2010โ2012",
Self::R2013 => "2013โ2017",
Self::R2018 => "2018",
}
}
/// The `$ACADVER` header value.
pub fn acadver(self) -> &'static str {
match self {
Self::R12 => "AC1009",
Self::R13 => "AC1012",
Self::R14 => "AC1014",
Self::R2000 => "AC1015",
Self::R2004 => "AC1018",
Self::R2007 => "AC1021",
Self::R2010 => "AC1024",
Self::R2013 => "AC1027",
Self::R2018 => "AC1032",
}
}
/// A version by id (`2018`, `R2018`, `r12`) or `$ACADVER` (`AC1032`), any case.
pub fn from_id(s: &str) -> Option<Self> {
let s = s.trim();
Self::ALL.into_iter().find(|v| {
let id = v.id();
s.eq_ignore_ascii_case(id) || s.eq_ignore_ascii_case(v.acadver()) || s.strip_prefix(['R', 'r']).is_some_and(|y| y == id)
})
}
/// Objects carry handles and subclass markers; splines, hatches and images exist.
fn handles(self) -> bool {
self >= Self::R13
}
/// Lightweight polylines.
fn lwpolyline(self) -> bool {
self >= Self::R14
}
/// Lineweights, layouts, plot styles and long symbol names.
fn r2000(self) -> bool {
self >= Self::R2000
}
/// True colour and transparency.
fn true_color(self) -> bool {
self >= Self::R2004
}
/// Text is UTF-8 (earlier versions escape what isn't ASCII as `\U+XXXX`).
pub fn utf8(self) -> bool {
self >= Self::R2007
}
}
impl From<DxfVersion> for craft_dxf::drawing::Format {
fn from(v: DxfVersion) -> Self {
match v {
DxfVersion::R12 => Self::R12,
DxfVersion::R13 => Self::R13,
DxfVersion::R14 => Self::R14,
DxfVersion::R2000 => Self::R2000,
DxfVersion::R2004 => Self::R2004,
DxfVersion::R2007 => Self::R2007,
DxfVersion::R2010 => Self::R2010,
DxfVersion::R2013 => Self::R2013,
DxfVersion::R2018 => Self::R2018,
}
}
}
/// How many colours entities may use: indexed colours of the 256-colour palette, or true colour
/// (with the nearest index for apps that read only the index).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum ColorDepth {
/// Indices 1โ8: the seven standard colours and dark grey.
Aci8,
/// Indices 1โ9, orange (30) and the six greys (250โ255).
Aci16,
/// Every index 1โ255.
Aci256,
/// 24-bit colour (DXF 2004 and later).
#[default]
True,
}
impl ColorDepth {
pub const ALL: [Self; 4] = [Self::Aci8, Self::Aci16, Self::Aci256, Self::True];
/// The `colors` param value.
pub fn id(self) -> &'static str {
match self {
Self::Aci8 => "8",
Self::Aci16 => "16",
Self::Aci256 => "256",
Self::True => "true",
}
}
pub fn label(self) -> &'static str {
match self {
Self::Aci8 => "8 Colors",
Self::Aci16 => "16 Colors",
Self::Aci256 => "256 Colors",
Self::True => "True Colors",
}
}
/// A depth by id (`8`, `16`, `256`, `true`; `truecolor` and `24` also read).
pub fn from_id(s: &str) -> Option<Self> {
let s = s.trim().to_ascii_lowercase();
match s.as_str() {
"truecolor" | "truecolors" | "true colors" | "24" => Some(Self::True),
_ => Self::ALL.into_iter().find(|d| d.id() == s),
}
}
}
/// The file format placed images are written in.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum RasterFormat {
#[default]
Png,
/// No transparency: transparent pixels show white.
Jpeg,
}
impl RasterFormat {
pub const ALL: [Self; 2] = [Self::Png, Self::Jpeg];
/// The `rasterFormat` param value.
pub fn id(self) -> &'static str {
match self {
Self::Png => "png",
Self::Jpeg => "jpeg",
}
}
pub fn label(self) -> &'static str {
match self {
Self::Png => "PNG",
Self::Jpeg => "JPEG",
}
}
/// The extension the image files get.
pub fn extension(self) -> &'static str {
match self {
Self::Png => "png",
Self::Jpeg => "jpg",
}
}
/// A format by id (`png`, `jpeg`, `jpg`), any case.
pub fn from_id(s: &str) -> Option<Self> {
let s = s.trim();
if s.eq_ignore_ascii_case("jpg") {
return Some(Self::Jpeg);
}
Self::ALL.into_iter().find(|f| s.eq_ignore_ascii_case(f.id()))
}
}
/// What the export favours when DXF can't hold an object's look as it is.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Preserve {
/// Type becomes glyph outlines; strokes a plain CAD line can't draw (aligned inside or
/// outside, width profiles, arrowheads, fitted dashes, dashes offset into their pattern)
/// become their filled outlines; brush
/// strokes become their brush art.
#[default]
Appearance,
/// Type stays text; every stroke is a line with its weight and dashes.
Editability,
}
impl Preserve {
pub const ALL: [Self; 2] = [Self::Appearance, Self::Editability];
/// The `preserve` param value.
pub fn id(self) -> &'static str {
match self {
Self::Appearance => "appearance",
Self::Editability => "editability",
}
}
pub fn label(self) -> &'static str {
match self {
Self::Appearance => "Preserve Appearance",
Self::Editability => "Maximize Editability",
}
}
pub fn from_id(s: &str) -> Option<Self> {
Self::ALL.into_iter().find(|p| s.trim().eq_ignore_ascii_case(p.id()))
}
}
/// The DXF export settings.
#[derive(Clone, Debug)]
pub struct DxfOptions {
pub version: DxfVersion,
/// The unit of the art that `scale` drawing units stand for.
pub unit: Unit,
/// Drawing units per `unit` (1 mm = `scale` units).
pub scale: f64,
/// Lineweights grow with `scale` (else they keep their printed width).
pub scale_lineweights: bool,
pub colors: ColorDepth,
pub raster: RasterFormat,
/// Placed images are written as IMAGE entities with their files (else left out, undecoded).
pub include_images: bool,
/// Filled areas get a solid HATCH after their outlines (else the outlines alone).
pub include_hatches: bool,
pub preserve: Preserve,
/// Alter Paths for Appearance: a stroke a CAD line can't draw (one [`Preserve::Appearance`]
/// outlines, one wider than the widest lineweight, or any stroke in R13 and R14, which have
/// no lineweights) is written as the filled area it paints.
pub alter_paths: bool,
/// Type is written as glyph outlines (always with [`Preserve::Appearance`]).
pub outline_text: bool,
/// The drawing's origin is this region's bottom-left corner (document space).
pub region: Rect,
/// Leave out objects entirely outside `region` (one drawing per artboard).
pub crop: bool,
}
impl Default for DxfOptions {
fn default() -> Self {
Self {
version: DxfVersion::default(),
unit: Unit::Millimeters,
scale: 1.0,
scale_lineweights: false,
colors: ColorDepth::default(),
raster: RasterFormat::default(),
include_images: true,
include_hatches: true,
preserve: Preserve::default(),
alter_paths: false,
outline_text: false,
region: Rect::ZERO,
crop: false,
}
}
}
/// A named set of DXF options (the `dxfPreset` param): the options it sets, and the ones a set of
/// options matches.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum DxfPreset {
/// The options as chosen (the export's defaults for those left out).
#[default]
Custom,
/// For CNC and CAM cutting software: version 2000 (the oldest version that has both lightweight
/// polylines and lineweights), 1 mm = 1 unit, 256 indexed colors (all version 2000 holds), Maximize
/// Editability with Alter Paths off (every stroke a center line), Outline Text (type as paths),
/// and placed images and fill hatches left out (fills are their outlines), with PNG as the
/// format images take when they are put back in.
Cnc,
}
impl DxfPreset {
pub const ALL: [Self; 2] = [Self::Custom, Self::Cnc];
/// The `dxfPreset` param value.
pub fn id(self) -> &'static str {
match self {
Self::Custom => "custom",
Self::Cnc => "cnc",
}
}
pub fn label(self) -> &'static str {
match self {
Self::Custom => "Custom",
Self::Cnc => "CNC / CAM",
}
}
/// A preset by id (`custom`, `cnc`), any case.
pub fn from_id(s: &str) -> Option<Self> {
Self::ALL.into_iter().find(|p| s.trim().eq_ignore_ascii_case(p.id()))
}
/// The options the preset sets (Custom: the defaults); the region and crop are the defaults.
pub fn options(self) -> DxfOptions {
match self {
Self::Custom => DxfOptions::default(),
Self::Cnc => DxfOptions {
version: DxfVersion::R2000,
unit: Unit::Millimeters,
scale: 1.0,
scale_lineweights: false,
colors: ColorDepth::Aci256,
raster: RasterFormat::Png,
include_images: false,
include_hatches: false,
preserve: Preserve::Editability,
alter_paths: false,
outline_text: true,
..DxfOptions::default()
},
}
}
/// The preset `o` matches: CNC / CAM when every option it sets is as it sets it, else Custom.
pub fn of(o: &DxfOptions) -> Self {
let c = Self::Cnc.options();
let same = o.version == c.version
&& o.unit == c.unit
&& o.scale == c.scale
&& o.scale_lineweights == c.scale_lineweights
&& o.colors == c.colors
&& o.raster == c.raster
&& o.include_images == c.include_images
&& o.include_hatches == c.include_hatches
&& o.preserve == c.preserve
&& o.alter_paths == c.alter_paths
&& o.outline_text == c.outline_text;
if same { Self::Cnc } else { Self::Custom }
}
}
/// An image file a drawing links to, to be written next to it under `name`.
#[derive(Clone, Debug)]
pub struct DxfImage {
pub name: String,
pub bytes: Vec<u8>,
}
/// A written drawing.
#[derive(Clone, Debug, Default)]
pub struct DxfOutput {
pub bytes: Vec<u8>,
/// The image files the drawing links to (by name, next to it).
pub images: Vec<DxfImage>,
/// What was approximated or left out.
pub warnings: Vec<String>,
/// What was left out because an option turns it off (Include Placed Images or Include Fill
/// Hatches off).
pub setting_notes: Vec<String>,
}
/// The smallest and largest `scale` (drawing units per unit).
pub const SCALE_RANGE: std::ops::RangeInclusive<f64> = 1e-6..=1e6;
/// Write `doc` as a DXF drawing with `opts`. Live geometry effects are applied first; template
/// layers, guides and hidden objects are left out.
pub fn export(doc: &Document, opts: &DxfOptions) -> Result<DxfOutput, String> {
Ok(export_drawings(doc, opts, &[(opts.region, opts.crop)])?.pop().unwrap_or_default())
}
/// Write `doc` as one DXF drawing for each `(region, crop)` of `drawings`, in order, each as
/// [`export`] writes it with `opts` and that region and crop. Live geometry effects are applied
/// once for all the drawings.
pub fn export_drawings(doc: &Document, opts: &DxfOptions, drawings: &[(Rect, bool)]) -> Result<Vec<DxfOutput>, String> {
export_drawings_with(doc, opts, drawings, bake_for_drawings)
}
/// `doc` with its live geometry effects applied and its symbols' art placed, or `None` when
/// nothing changes.
fn bake_for_drawings(doc: &Document) -> Option<Document> {
// Symbols' art is placed without clipping, as the scene places it.
let layers = vectorcraft_effects::WrittenLayers { hidden: true, non_printing: true, hidden_objects: false };
vectorcraft_effects::bake_document_placing_symbols(doc, false, layers)
}
/// [`export_drawings`] with `bake` applying the live effects.
fn export_drawings_with(
doc: &Document,
opts: &DxfOptions,
drawings: &[(Rect, bool)],
bake: impl Fn(&Document) -> Option<Document>,
) -> Result<Vec<DxfOutput>, String> {
if !(opts.scale.is_finite() && SCALE_RANGE.contains(&opts.scale)) {
return Err(format!("scale must be a number from {} to {}, not {}", SCALE_RANGE.start(), SCALE_RANGE.end(), opts.scale));
}
if drawings.iter().any(|(r, _)| ![r.x0, r.y0, r.x1, r.y1].iter().all(|v| v.is_finite())) {
return Err("the export region is not finite".into());
}
if drawings.is_empty() {
return Ok(vec![]);
}
let baked = bake(doc);
let doc = baked.as_ref().unwrap_or(doc);
Ok(drawings.iter().map(|&(region, crop)| scene::Scene::new(doc, &DxfOptions { region, crop, ..opts.clone() }).run()).collect())
}
#[cfg(test)]
mod tests;
No file is open. Choose one in the tree, or press Ctrl+O (โO on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.