2bc41aeb8602
lib.rs
//! VectorCraft SVG import and export.
//!
//! * [`export`] / [`export_full`] write a [`Document`] as SVG 1.1 with our own writer, as set by
//! [`ExportOptions`] (presentation attributes, inline styles, style entities or internal CSS
//! classes; gradients in `<defs>` with `userSpaceOnUse`; clip groups as `<clipPath>`; images
//! embedded as `data:` URIs or linked; text as `<text>`/`<tspan>` or outlines; symbols as one
//! `<symbol>` each with a `<use>` per instance; hidden layers left out, or kept not displayed),
//! in UTF-8, UTF-16 or ISO 8859-1 ([`Output::bytes`]), as SVG 1.1 or a simplified SVG Tiny 1.2
//! ([`Profile`]), optionally with the fonts type uses embedded as `@font-face` subsets.
//! * [`import`] / [`import_with_report`] parse SVG with `usvg` and convert its normalized tree into
//! document nodes with all transforms baked into the geometry.
//! * What other software keeps on an object survives the round trip: its `data-*` attributes and
//! its attributes in other applications' XML namespaces (`plotter:pen="2"`) are kept with the
//! object ([`vectorcraft_doc::ObjectAttributes`]), so they are copied, saved and deleted with it,
//! and export writes them back.
//! * [`css_rules`] writes the CSS web pages style objects with (the CSS Properties panel): shapes'
//! paints as backgrounds and borders, type as fonts, shadows as `box-shadow`, each property
//! written as SVG export writes it in its style sheets.
//!
//! ## Export approximations
//!
//! * **Stroke alignment** is not expressible in SVG 1.1. An *inside* stroke of a closed path is
//! written as a stroke of double width clipped to the path's own shape (`<clipPath>`); an
//! *outside* stroke as a stroke of double width masked by a `<mask>` that hides the path's
//! interior. Both are visually exact but re-import as a group (clip group / masked stroke)
//! rather than an aligned stroke. Open paths have no inside: their strokes are written centred,
//! as the canvas draws them.
//! * **Arrowheads, width profiles, dashes fitted to corners and dotted dashes** are written as the
//! filled outlines the canvas paints (the line and each arrowhead, grouped under the stroke's
//! opacity); **brushed strokes** as their brush art. Both re-import as filled paths.
//! * **Multiple fills/strokes** (or per-fill/stroke blend modes) are written as a `<g>` holding one
//! `<path>` per appearance item, in paint order.
//! * Live geometry effects are written as their result and raster effects (shadows, glows, blurs)
//! as SVG filters.
//! * **Freeform gradients**, which SVG can't express, fill or stroke objects as an `<image>` of
//! their colour field (sampled as the canvas samples it) clipped to the shape or the stroke's
//! outline; on characters they are written as linear gradients. Gradients along or across
//! strokes are written as slices of linear gradients clipped to the stroke.
//! * **Dithered gradient fills** are written as an `<image>` of the gradient with its noise, at
//! the document's raster effects resolution, clipped to the shape: Illustrator's documentation
//! describes dither as the gradient converted to pixels with subtle noise
//! (<https://helpx.adobe.com/illustrator/desktop/paint-and-fill/create-and-edit-gradients/control-dither-in-gradients.html>).
//! On characters the gradient stays a vector gradient, without dither (with a warning).
//! * **Perceptual gradients** fill or stroke objects as an `<image>` of the gradient, at the
//! document's raster effects resolution, clipped to the shape or the stroke's outline: SVG
//! gradients mix linearly, and Illustrator's documentation says perceptual gradients are
//! rasterised in SVG
//! (<https://helpx.adobe.com/illustrator/desktop/paint-and-fill/create-and-edit-gradients/control-perceptual-interpolation-in-gradients.html>).
//! On characters they are written as linear gradients through stops on the perceptual curve.
//! * **Gradients mixed around the hue wheel** (Hue Clockwise and Hue Counterclockwise,
//! VectorCraft's own methods) fill or stroke objects as an `<image>` of the gradient too, at the
//! document's raster effects resolution. On characters they are written as gradients through
//! stops on their way around the wheel.
//! * **Symbol instances** the shared `<symbol>` would paint differently from the canvas (stained,
//! scaled with strokes, turned or scaled with effects, brushes or live objects, or holding
//! pattern paints or unlinked masks, which stay on the page) are written as their own art.
//!
//! ## Import approximations
//!
//! * One CSS pixel (user unit) is one point, as on export, and absolute lengths (`in`, `cm`, `mm`,
//! `pt`, `pc`) keep their physical size (72 pt per inch): `font-size="12pt"` is 12 pt. A root
//! `width`/`height` in absolute units keeps its physical size, so a 210 mm SVG opens on a 210 mm
//! artboard, its user units being CSS pixels of it (96 per inch), the other side's too when only
//! one is absolute. The document's units follow the unit of the root `width` (pixels when it has
//! none).
//! * `<mask>` imports as a luminance opacity mask; a mask we exported keeps its options and art
//! (its `data-vectorcraft-mask="noclip invert"` lists the options that differ from clipping and
//! not inverted). Nested clip paths (`<clipPath clip-path>`) are clip groups in clip groups.
//! * Filters that are a Gaussian blur, a drop shadow (`feDropShadow` or the usual chains of offset,
//! blur, flood or colour matrix, composite and merge), a glow or a feather (as we export them)
//! become those live effects; other filters are ignored (reported as warnings).
//! * `<pattern>` becomes a pattern swatch (its content clipped to the tile) painted with the
//! pattern's placement.
//! * `<symbol>` with `<use>` becomes a symbol and its instances. A `<use>` that shows the symbol
//! differently (inherited paint, a viewport that cuts it) or that the canvas would paint
//! differently (see the export's symbol rules) becomes plain art, as do `<use>`s of other
//! elements.
//! * A `<g id>` layer (top-level, or inside one) that isn't displayed (`display: none`) comes back
//! as a hidden layer; other undisplayed objects as hidden objects, unless a `<use>` refers to
//! them.
//! * `spreadMethod` reflect and repeat become the gradient's spread, Reflect or Repeat, its stops
//! running once along the vector.
//! * `<image>` files are read through [`ImportOptions`]: rasters stay linked, SVG files (and SVG
//! `data:` URLs) become art (without their text), missing ones a placeholder keeping the link.
//! * Text lines after the first start at the first line's x; absolute positions inside type on a
//! path are ignored; vertical text sets every glyph sideways.
//! * A `<text>` in a `<clipPath>`, or a `<use>` there that shows one, clips by its glyph outlines.
//! When a clip path holds only one text, and that text has no clip path of its own and no
//! even-odd clip rule, the clip group's clipping path is the text as live type that paints nothing.
//!
//! ## Import text
//!
//! usvg only keeps `<text>` when fonts are loaded; we don't load a font database (too expensive and
//! unavailable on wasm), so `<text>` elements are read from the XML as live [`TextObject`]s. Each
//! one is swapped for a placeholder before usvg runs, so the text keeps its z-order, parent group,
//! clip, mask, opacity, link, `<use>` instances and gradient or pattern paints. The style cascade
//! supports type, `#id`, `.class` (several), attribute, descendant and child selectors.
//! `<textPath>` becomes type on a path (`startOffset`, `side`), vertical `writing-mode` type on a
//! vertical path; per-character `x`/`y`/`dx`/`dy`/`rotate`, `baseline-shift`, numeric weights,
//! letter and word spacing become character attributes (line breaks, kerning, baseline shift,
//! rotation and style names).
#![forbid(unsafe_code)]
use craft_svg::tree::usvg;
mod css;
mod entities;
mod export;
mod glyph;
mod import;
pub use css::{CssOptions, CssRule, CssSheet, CssUnits, css_rules};
use serde::{Deserialize, Serialize};
pub use vectorcraft_doc::Document;
pub use vectorcraft_doc::TextObject;
/// How style properties are written (SVG Options โ Styling).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum Styling {
/// `fill="#ff0000"` attributes.
#[default]
#[serde(rename = "presentation")]
PresentationAttributes,
/// `style="fill:#ff0000"`.
#[serde(rename = "style")]
InlineStyle,
/// `style="&st1;"`, each distinct declaration block an XML entity declared in the DOCTYPE.
#[serde(rename = "entities")]
StyleEntities,
/// `class="cls-1"` with a `<style>` element in `<defs>`.
#[serde(rename = "css")]
InternalCss,
}
/// Which `id` attributes objects get (SVG Options โ Object IDs). Definitions other elements
/// reference (gradients, clip paths, masks, patterns, filters) always have ids.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum ObjectIds {
/// Readable ids from layer and object names.
#[default]
LayerNames,
/// Only the ids that are referenced.
Minimal,
/// Every id carries a prefix derived from the content, so SVGs inlined in one page never
/// share an id.
Unique,
}
/// How raster images are written (SVG Options โ Images).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum ImageMode {
/// `data:` URIs inside the SVG.
#[default]
Embed,
/// `href` to an image file: a linked image's own file, an embedded one written next to the
/// SVG (see [`Output::linked`]).
Link,
}
/// The character encoding of an exported file (SVG Options โ Encoding).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum Encoding {
#[default]
#[serde(rename = "utf8", alias = "utf-8")]
Utf8,
/// UTF-16, big-endian, after a byte order mark.
#[serde(rename = "utf16", alias = "utf-16")]
Utf16,
/// ISO 8859-1 (Latin-1): other characters are written as character references (`中`).
#[serde(rename = "latin1", alias = "iso-8859-1")]
Latin1,
}
impl Encoding {
/// The name the XML declaration gives it.
pub fn xml_name(self) -> &'static str {
match self {
Self::Utf8 => "UTF-8",
Self::Utf16 => "UTF-16",
Self::Latin1 => "ISO-8859-1",
}
}
}
/// The SVG profile written (SVG Options โ SVG Profile).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum Profile {
/// SVG 1.1 (full).
#[default]
#[serde(rename = "svg11", alias = "1.1")]
Svg11,
/// SVG Tiny 1.2, simplified: `version="1.2" baseProfile="tiny"`, presentation attributes only
/// (no style sheets, style attributes, blend modes or CSS-only properties), no filters, masks
/// or `<symbol>`s and no embedded fonts. Raster effects and opacity masks are left out,
/// knockout groups written as plain groups, symbol instances as their own art and strokes
/// aligned outside clipped by the area outside the shape. Clip paths, patterns and type on a
/// path are written as in SVG 1.1.
#[serde(rename = "tiny12", alias = "tiny1.2")]
Tiny12,
}
/// SVG export options (SVG Options). Deserializes from camelCase JSON with every field optional;
/// unknown fields are rejected.
///
/// These defaults are the library's and the engine's (`document.export` without options):
/// presentation attributes and a fixed size, the most portable output. The SVG Options dialog
/// starts from Internal CSS and Responsive instead, like the reference app's Export As.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase", deny_unknown_fields)]
pub struct ExportOptions {
/// Artboard index to export (sets the viewBox); `None` = the bounds of all art. Callers pick
/// it (the engine's `artboard`/`range`/`useArtboards` params), so it is not deserialized.
#[serde(skip)]
pub artboard: Option<usize>,
/// The file is the one artboard `artboard` names, exported on its own (Export As with Use
/// Artboards, Export for Screens, Asset Export, an `artboard`/`range` param): its `<title>` is
/// the artboard's name, else (unnamed) the document's title (#3544). Off, the file stands for
/// the document (Save, Save As) and has the document's title. Callers set it with `artboard`,
/// so it is not deserialized either.
#[serde(skip)]
pub artboard_title: bool,
pub styling: Styling,
/// Decimal places for coordinates (1โ7 in the dialog; default 3).
pub decimals: u8,
pub object_ids: ObjectIds,
pub images: ImageMode,
/// No indentation or newlines, no XML declaration.
pub minify: bool,
/// Omit `width`/`height` so the SVG scales to its container.
pub responsive: bool,
/// Fonts โ Convert to Outlines: text becomes paths (portable, no font needed to view it).
pub outline_text: bool,
/// Embed the native document (passed to [`export_full`]) in `<metadata>` so VectorCraft
/// reopens the SVG with nothing lost (see [`editing`]).
pub preserve_editing: bool,
/// Write `<metadata>` with the document's title, format and File Info (Dublin Core).
pub metadata: bool,
/// One positioned `<tspan>` per line of type instead of one per style run, tab stop and
/// justified word (smaller; viewers then space the line with their own font metrics).
pub fewer_tspans: bool,
/// Keep hidden layers and objects, written hidden (`display="none"`), as Save does; exports
/// leave them out unless asked.
pub hidden_layers: bool,
/// The file's character encoding (see [`Output::bytes`]).
pub encoding: Encoding,
pub profile: Profile,
/// Embed the fonts type uses as `@font-face` rules, each subset to the characters used where
/// its licence allows (whole where it forbids subsetting, left out where it forbids
/// embedding). Not with outlined text or the Tiny profile.
pub embed_fonts: bool,
/// Include Variable Data: write the document's text variables, its data sets and the object
/// each text variable is bound to as a `variableSets` element, in the layout Load Variable
/// Library reads. Opening the SVG reads them back.
pub variable_data: bool,
}
impl Default for ExportOptions {
fn default() -> Self {
Self {
artboard: Some(0),
artboard_title: false,
styling: Styling::PresentationAttributes,
decimals: 3,
object_ids: ObjectIds::LayerNames,
images: ImageMode::Embed,
minify: false,
responsive: false,
outline_text: false,
preserve_editing: false,
metadata: false,
fewer_tspans: false,
hidden_layers: false,
encoding: Encoding::Utf8,
profile: Profile::Svg11,
embed_fonts: false,
variable_data: false,
}
}
}
/// Decimal places the options accept.
pub const DECIMALS: std::ops::RangeInclusive<u8> = 1..=7;
impl ExportOptions {
/// Values outside what the options allow (the decimals range).
pub fn check(&self) -> Result<(), String> {
if DECIMALS.contains(&self.decimals) {
Ok(())
} else {
Err(format!("decimals must be {}โ{} (got {})", DECIMALS.start(), DECIMALS.end(), self.decimals))
}
}
}
/// An export: the SVG text and the image files it links to.
#[derive(Clone, Debug, Default)]
pub struct Output {
pub svg: String,
/// [`ImageMode::Link`]: embedded images written as files next to the SVG, named after their
/// content (`imgโฆ.png`), so exports of different documents into one folder never clash.
pub linked: Vec<LinkedImage>,
/// Features the export approximates.
pub warnings: Vec<String>,
/// Notes on the options: one the export didn't apply or applied another way (an encoding, a
/// font embedded whole).
pub setting_notes: Vec<String>,
/// The encoding [`Self::bytes`] writes.
pub encoding: Encoding,
}
impl Output {
/// The file: the SVG in its encoding (UTF-16 after a byte order mark).
pub fn bytes(&self) -> Vec<u8> {
match self.encoding {
Encoding::Utf8 => self.svg.as_bytes().to_vec(),
e => e.encode_str(&self.svg),
}
}
/// [`Self::bytes`], taking the SVG text (UTF-8 files are the text itself, not a copy).
pub fn take_bytes(&mut self) -> Vec<u8> {
let svg = std::mem::take(&mut self.svg);
match self.encoding {
Encoding::Utf8 => svg.into_bytes(),
e => e.encode_str(&svg),
}
}
}
impl Encoding {
/// `svg` written in this encoding.
fn encode_str(self, svg: &str) -> Vec<u8> {
match self {
Encoding::Utf8 => svg.as_bytes().to_vec(),
Encoding::Utf16 => [0xfe, 0xff].into_iter().chain(svg.encode_utf16().flat_map(u16::to_be_bytes)).collect(),
// The writer left only Latin-1 characters (the others are character references).
Encoding::Latin1 => svg.chars().map(|c| u8::try_from(c).unwrap_or(b'?')).collect(),
}
}
}
/// An image file an exported SVG links to by `name`.
#[derive(Clone, Debug)]
pub struct LinkedImage {
pub name: String,
pub bytes: std::sync::Arc<Vec<u8>>,
}
#[derive(Clone, Debug, thiserror::Error)]
pub enum SvgError {
#[error("SVG parse error: {0}")]
Parse(String),
/// Its elements nest (references followed) deeper than the reader goes.
#[error("the SVG's elements are nested more than {0} deep")]
TooDeep(usize),
/// SVGZ data unpacks to more than the reader takes (a guard against decompression bombs).
#[error("SVG parse error: {0}")]
TooBig(String),
/// The SVG expands to more objects than the reader takes (a guard against `<use>` and
/// nested-image expansion bombs, #3564).
#[error("the SVG expands to more than {0} objects")]
TooLarge(usize),
/// The SVG expands to more nested SVG images than the reader takes (a guard against
/// nested-image expansion bombs, #3564).
#[error("the SVG expands to more than {0} nested SVG images")]
TooManyImages(usize),
/// The style values the reader would copy into the elements the SVG expands to, `<use>`
/// copies and SVG images included, add up to more than this many megabytes.
#[error("the SVG's styles expand to more than {0} MB")]
StylesTooLarge(usize),
/// Matching the style sheets' selectors against the elements the SVG expands to, `<use>`
/// copies and SVG images included, takes more tests than the reader allows.
#[error("the SVG's style sheets take too long to match")]
StylesTooComplex,
}
/// Export a document as an SVG string (linked images are not returned: see [`export_full`]).
pub fn export(doc: &Document, opts: &ExportOptions) -> String {
export_full(doc, opts, None).svg
}
/// Export a document as an SVG string, also returning warnings about approximated features,
/// then the notes on the options ([`Output::setting_notes`]).
pub fn export_with_report(doc: &Document, opts: &ExportOptions) -> (String, Vec<String>) {
let o = export_full(doc, opts, None);
(o.svg, o.warnings.into_iter().chain(o.setting_notes).collect())
}
/// Export a document as SVG plus the image files it links to. `native`: the document in the
/// native format, embedded when [`ExportOptions::preserve_editing`] is on.
pub fn export_full(doc: &Document, opts: &ExportOptions, native: Option<&[u8]>) -> Output {
// Type in the document's composite fonts is drawn in them, whether or not an app has the document open.
let _lent = vectorcraft_text::FontDb::global().lend_composite_fonts(&doc.composite_fonts);
export::export(doc, opts, native)
}
/// The XML namespace of the editing data [`ExportOptions::preserve_editing`] embeds.
pub const EDITING_NS: &str = "urn:vectorcraft:editing";
/// The native document an SVG carries ([`ExportOptions::preserve_editing`]).
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Editing {
/// The native document, base64.
pub data: String,
/// The SVG around it is still the one written with it: the hash it keeps of the markup
/// outside its `<metadata>` matches (whitespace between tags and line endings aside). False
/// once another app edited the SVG; true for editing data written without a hash.
pub intact: bool,
}
/// The native document an SVG carries, if any, and whether the SVG was edited since.
pub fn editing(svg: &str) -> Option<Editing> {
// (An SVG nested too deep for the XML reader carries none: it isn't one of ours.)
if !svg.contains(EDITING_NS) || import::xml_too_deep(svg) || entities::expansion_too_large(svg) {
return None;
}
let opts = usvg::roxmltree::ParsingOptions { allow_dtd: true, ..Default::default() };
let xml = usvg::roxmltree::Document::parse_with_options(svg, opts).ok()?;
let el = xml.descendants().find(|n| n.tag_name().namespace() == Some(EDITING_NS) && n.tag_name().name() == "document")?;
let data: String = el.children().filter_map(|c| c.text()).flat_map(|t| t.chars().filter(|c| !c.is_whitespace())).collect();
if data.is_empty() {
return None;
}
// The hash covers everything but the `<metadata>` element holding the data.
let intact = match (el.attribute("hash"), el.parent_element()) {
(None, _) => true,
(Some(h), Some(meta)) => {
let r = meta.range();
let (head, tail) = (svg.get(..r.start).unwrap_or(""), svg.get(r.end..).unwrap_or(""));
body_hash(&[head, tail]) == h
}
(Some(_), None) => false,
};
Some(Editing { data, intact })
}
/// The native document an SVG carries (base64), if any, edited since or not (see [`editing`]).
pub fn editing_data(svg: &str) -> Option<String> {
editing(svg).map(|e| e.data)
}
/// The hash [`ExportOptions::preserve_editing`] keeps of an SVG's markup outside its
/// `<metadata>` (`parts`, in order): FNV-1a of the text with whitespace between tags dropped and
/// other whitespace runs read as one space, so re-indenting or other line endings don't count as
/// edits.
pub(crate) fn body_hash(parts: &[&str]) -> String {
let mut h = FNV_SEED;
// The last byte hashed and whether whitespace came after it.
let (mut last, mut gap) = (None, false);
for b in parts.iter().flat_map(|p| p.bytes()) {
if b.is_ascii_whitespace() {
gap = true;
continue;
}
if gap && last.is_some_and(|l| l != b'>') && b != b'<' {
h = fnv1a_from(h, b" ");
}
gap = false;
last = Some(b);
h = fnv1a_from(h, &[b]);
}
format!("{h:016x}")
}
/// Does `bytes` start like gzip data (an SVGZ file)?
pub fn is_svgz(bytes: &[u8]) -> bool {
craft_svg::sniff::is_svgz(bytes)
}
/// Compress SVG text as SVGZ (gzip).
pub fn compress(svg: &str) -> Vec<u8> {
craft_svg::svgz::compress(svg.as_bytes())
}
/// Compress an SVG file (in any encoding, see [`Output::bytes`]) as SVGZ (gzip).
pub fn compress_bytes(svg: &[u8]) -> Vec<u8> {
craft_svg::svgz::compress(svg)
}
/// Most bytes an SVGZ file may unpack to (a guard against decompression bombs).
pub(crate) const MAX_SVGZ: u64 = 512 << 20;
/// SVG text from SVG or SVGZ bytes: UTF-8, UTF-16 (after a byte order mark) or, when the XML
/// declaration says so, ISO 8859-1.
pub fn text_of(bytes: &[u8]) -> Result<std::borrow::Cow<'_, str>, SvgError> {
text_within(bytes, &std::sync::atomic::AtomicU64::new(0))
}
/// [`text_of`], SVGZ bytes unpacking within what `unpacked`, the bytes SVGZ data unpacked to so
/// far, leaves of [`MAX_SVGZ`]. What they unpack to is added to it, whether or not it decodes.
pub(crate) fn text_within<'a>(bytes: &'a [u8], unpacked: &std::sync::atomic::AtomicU64) -> Result<std::borrow::Cow<'a, str>, SvgError> {
use std::sync::atomic::Ordering;
if !is_svgz(bytes) {
return craft_svg::svgz::decode(bytes).map_err(|_| not_utf8());
}
let most = usize::try_from(MAX_SVGZ.saturating_sub(unpacked.load(Ordering::Relaxed))).unwrap_or(usize::MAX);
match craft_svg::svgz::inflate(bytes, most) {
Ok(raw) => {
unpacked.fetch_add(raw.len() as u64, Ordering::Relaxed);
craft_svg::svgz::decode(&raw).map(|t| std::borrow::Cow::Owned(t.into_owned())).map_err(|_| not_utf8())
}
Err(craft_svg::svgz::Error::TooLarge(_)) => Err(SvgError::TooBig(format!("the SVGZ file unpacks to more than {} MB", most >> 20))),
Err(craft_svg::svgz::Error::Corrupt(e)) => Err(SvgError::Parse(format!("not a valid SVGZ file: {e}"))),
Err(craft_svg::svgz::Error::Encoding) => Err(not_utf8()),
Err(e) => Err(SvgError::Parse(e.to_string())),
}
}
fn not_utf8() -> SvgError {
SvgError::Parse("SVG is not UTF-8, UTF-16 or ISO 8859-1".into())
}
/// Import an SVG document.
pub fn import(svg: &str) -> Result<Document, SvgError> {
import_with_report(svg).map(|(d, _)| d)
}
/// Import an SVG document, also returning warnings about unsupported or approximated features.
/// Linked files (`<image href="photo.png">`) aren't read: see [`import_with`].
pub fn import_with_report(svg: &str) -> Result<(Document, Vec<String>), SvgError> {
import_with(svg, &ImportOptions::default())
}
/// Effect โบ SVG Filters โบ Import SVG Filter: the `<filter>` elements of SVG text `svg` that an SVG
/// filter effect takes, as (name, XML) in document order, up to `room` of them and leaving out the
/// names `taken` says, and how many it doesn't take. Filters past `room` or named as `taken` says
/// are not checked. The text is read with the limits on depth and entities that [`import`] reads
/// documents with.
pub fn svg_filters(svg: &str, room: usize, taken: impl Fn(&str) -> bool) -> Result<(Vec<(String, String)>, usize), SvgError> {
import::svg_filters(svg, room, taken)
}
pub use glyph::glyph_art;
pub use import::{
MAX_DATA_URL_BYTES, MAX_ELEMENT_DEPTH, MAX_FOREIGN, MAX_FOREIGN_VALUE, MAX_NESTED_SVG_IMAGES, MAX_NESTED_SVG_READS, MAX_NESTED_SVG_TEXT,
MAX_NODES,
};
/// Import an SVG document reading the files it links to as `opts` says, also returning warnings.
pub fn import_with(svg: &str, opts: &ImportOptions) -> Result<(Document, Vec<String>), SvgError> {
import_within(svg, opts, MAX_NODES)
}
/// [`import_with`], capping the objects the document may expand to at `max_nodes`.
pub fn import_within(svg: &str, opts: &ImportOptions, max_nodes: usize) -> Result<(Document, Vec<String>), SvgError> {
// usvg converts the tree by recursion, in large stack frames: the nesting it is given is
// capped (`import::depth`), and it gets room for that cap whatever thread asks.
vectorcraft_doc::depth::with_deep_stack(|| import::import(svg, opts, max_nodes))
}
/// [`import_with`], also returning the object made of each element whose id `ids` lists (the
/// first object named after it), by element id. Ids with no object are left out.
pub fn import_finding(svg: &str, opts: &ImportOptions, ids: &std::collections::HashSet<String>) -> Result<(Document, Vec<String>, Found), SvgError> {
vectorcraft_doc::depth::with_deep_stack(|| import::import_finding(svg, opts, MAX_NODES, ids))
}
/// The object made of each element [`import_finding`] looked for, by element id.
pub type Found = std::collections::HashMap<String, vectorcraft_doc::NodeId>;
/// Reads a linked file: its bytes and the link to it (absolute path, size, time and hash), or
/// `None` when there is no readable file at the (absolute) path.
pub type ReadFile<'a> = &'a (dyn Fn(&str) -> Option<(Vec<u8>, vectorcraft_doc::LinkInfo)> + Sync);
/// How [`import_with`] reads the files an SVG's `<image>` elements link to.
///
/// A raster file stays linked ([`vectorcraft_doc::ImageObject::link`]); an SVG file imports as
/// vector art. A file that can't be read imports as a placeholder that keeps the link (and a
/// warning), so it can be relinked.
#[derive(Clone, Copy, Default)]
pub struct ImportOptions<'a> {
/// The folder relative links are found in: the SVG file's own (taken from the working
/// directory when it isn't absolute). Without it they can't be read.
pub folder: Option<&'a str>,
/// Reads a linked file. Without it no file is read.
pub read: Option<ReadFile<'a>>,
}
/// FNV-1a: a stable content hash (image keys, unique id prefixes).
pub(crate) fn fnv1a(bytes: &[u8]) -> u64 {
fnv1a_from(FNV_SEED, bytes)
}
const FNV_SEED: u64 = 0xcbf29ce484222325;
/// FNV-1a of `bytes` continued from hash `h`.
fn fnv1a_from(h: u64, bytes: &[u8]) -> u64 {
bytes.iter().fold(h, |h, b| (h ^ *b as u64).wrapping_mul(0x100000001b3))
}
/// Standard base64 (RFC 4648, with padding).
pub fn base64_encode(data: &[u8]) -> String {
// SVG data URLs need one unwrapped line, not MIME's folded base64_lines variant.
craft_mime::transfer::base64(data)
}
/// Escape text for XML content and attribute values.
pub fn xml_escape(s: &str) -> String {
let mut o = String::with_capacity(s.len());
for c in s.chars() {
match c {
'&' => o.push_str("&"),
'<' => o.push_str("<"),
'>' => o.push_str(">"),
'"' => o.push_str("""),
'\'' => o.push_str("'"),
_ => o.push(c),
}
}
o
}
/// [`push_num`] through integer arithmetic, for the values it writes the same as the decimal
/// formatter: `decimals` of at most 9, and `v` scaled by 10^`decimals` below 2^53 and further from
/// halfway between two integers than the scaling's rounding error. Returns false, writing nothing,
/// for any other value.
fn push_num_scaled(out: &mut String, v: f64, decimals: u8) -> bool {
const SCALE: [f64; 10] = [1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9];
let Some(&scale) = SCALE.get(usize::from(decimals)) else { return false };
// Each power of ten here is exact, so `x` is within half an ulp (`x * EPSILON / 2`) of |v| ร 10^decimals.
let x = v.abs() * scale;
if x.is_nan() || x >= 9.0e15 {
return false;
}
let whole = x.floor();
let frac = x - whole;
if (frac - 0.5).abs() <= x * f64::EPSILON {
return false;
}
let mut n = whole as u64 + u64::from(frac > 0.5);
let places = usize::from(decimals);
// The digits of `n` from the last one, at least one more than `places` of them.
let mut digits = [0u8; 24];
let mut len = 0;
for d in digits.iter_mut() {
if n == 0 && len > places {
break;
}
*d = b'0' + (n % 10) as u8;
n /= 10;
len += 1;
}
let Some((fraction, int)) = digits.get(..len).and_then(|d| d.split_at_checked(places)) else { return false };
let zeros = fraction.iter().take_while(|&&d| d == b'0').count();
if v < 0.0 && (zeros < places || int.iter().any(|&d| d != b'0')) {
out.push('-');
}
out.extend(int.iter().rev().map(|&d| char::from(d)));
if zeros < places {
out.push('.');
out.extend(fraction.iter().skip(zeros).rev().map(|&d| char::from(d)));
}
true
}
/// Format a number with at most `decimals` places, trimming trailing zeros.
pub fn fmt_num(v: f64, decimals: u8) -> String {
let mut s = String::new();
push_num(&mut s, v, decimals);
s
}
/// [`fmt_num`] appended to `out`, without allocating.
pub fn push_num(out: &mut String, v: f64, decimals: u8) {
use std::fmt::Write as _;
let v = if v.is_finite() { v } else { 0.0 };
if push_num_scaled(out, v, decimals) {
return;
}
let start = out.len();
let _ = write!(out, "{:.*}", decimals as usize, v); // writing to a String can't fail
let s = out.get(start..).unwrap_or_default();
if s.contains('.') {
let keep = s.trim_end_matches('0').trim_end_matches('.').len();
out.truncate(start + keep);
}
if matches!(out.get(start..), Some("-0" | "")) {
out.truncate(start);
out.push('0');
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn base64_vectors() {
assert_eq!(base64_encode(b""), "");
assert_eq!(base64_encode(b"f"), "Zg==");
assert_eq!(base64_encode(b"fo"), "Zm8=");
assert_eq!(base64_encode(b"foo"), "Zm9v");
assert_eq!(base64_encode(b"foobar"), "Zm9vYmFy");
}
#[test]
fn base64_binary_payload_stays_standard_padded_and_unwrapped() {
let data: Vec<u8> = (0..=255).collect();
assert_eq!(
base64_encode(&data),
"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w=="
);
assert_eq!(base64_encode(&[0xfb, 0xff, 0xff]), "+///");
assert_eq!(base64_encode(&[0xfb]), "+w==");
assert_eq!(base64_encode(&[0xfb, 0xff]), "+/8=");
assert_eq!(base64_encode(&[0; 60]), "A".repeat(80));
}
#[test]
fn numbers() {
assert_eq!(fmt_num(1.0, 3), "1");
assert_eq!(fmt_num(1.23456, 3), "1.235");
assert_eq!(fmt_num(-0.0001, 3), "0");
assert_eq!(fmt_num(10.5, 1), "10.5");
assert_eq!(fmt_num(100.0, 0), "100");
}
#[test]
fn escaping() {
assert_eq!(xml_escape("a<b>&\"'"), "a<b>&"'");
}
/// `v` at `decimals` places by the decimal formatter, trailing zeros trimmed.
fn formatted(v: f64, decimals: u8) -> String {
let s = format!("{:.*}", usize::from(decimals), if v.is_finite() { v } else { 0.0 });
let s = if s.contains('.') { s.trim_end_matches('0').trim_end_matches('.') } else { &s };
if matches!(s, "-0" | "") { "0".into() } else { s.into() }
}
#[test]
fn numbers_match_the_decimal_formatter() {
let mut values =
vec![0.0, -0.0, 0.5, -0.5, 2.5, 0.0005, -0.0005, 1.0005, 0.125, 1e-12, 9.0e15, 4503599627370495.5, 1e20, f64::NAN, f64::INFINITY];
// Coordinates of every size, and values on and just off the halfway points between written numbers.
let mut seed = 0x2545_f491_4f6c_dd1d_u64;
for _ in 0..20_000 {
seed ^= seed << 13;
seed ^= seed >> 7;
seed ^= seed << 17;
let unit = (seed >> 11) as f64 / (1u64 << 53) as f64;
let v = (unit - 0.5) * 10f64.powi((seed % 13) as i32 - 3);
let tie = ((v * 1000.0).trunc() + 0.5) / 1000.0;
values.extend([v, tie, f64::from_bits(tie.to_bits() + 1), f64::from_bits(tie.to_bits() - 1)]);
}
for v in values {
for d in 0..=12 {
assert_eq!(fmt_num(v, d), formatted(v, d), "{v:e} at {d} decimals");
}
}
}
#[test]
fn coordinates_are_written_through_integers() {
for (v, d, want) in [(123.4567, 3, "123.457"), (-0.25, 3, "-0.25"), (-0.0004, 3, "0"), (1600.0, 3, "1600"), (7.0, 0, "7")] {
let mut s = String::new();
assert!(push_num_scaled(&mut s, v, d), "{v} at {d} decimals");
assert_eq!(s, want);
}
// Halfway as stored, too large, or too many places: the decimal formatter writes them.
for (v, d) in [(0.5, 0), (0.125, 2), (1e16, 0), (1.0, 10)] {
let mut s = String::new();
assert!(!push_num_scaled(&mut s, v, d), "{v} at {d} decimals");
assert!(s.is_empty());
}
}
}
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.