Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

9.4 KB
Raw Blame

ai_engine

A from-scratch Illustrator (.ai) engine: it reads Illustrator's PDF-based files (and any PDF), turns their pages into an editable model of artboards, layers, groups, paths, text, and images, draws any part of the canvas at any scale, applies edits with undo, shares edits between people editing together, and saves files Illustrator and every PDF reader open. The same Rust code runs natively (tests, the ai_render CLI, the AI tools, search indexing) and as WebAssembly in the web app's Illustrator editor workers (apps/web/src/lib/core/ai-engine).

Third-party code is limited to small libraries: tiny-skia (rasterizing), miniz_oxide (deflate), png and zune-jpeg (images), skrifa (TrueType, CFF, and Type 1 outlines through its PostScript reader), and serde. The PDF reader and writer, content interpreter, fonts, color spaces, functions, shadings, images, model, editing, saving, and collaboration are implemented here; text the editor lays out uses the font registry fig_engine shares.

The format

Since Illustrator CS, an .ai file is a PDF. Its pages are the artboards (one page per artboard when the file was saved with "Create PDF Compatible File"), Illustrator's top-level layers are optional content groups (each layer's content is marked /OC /MCn BDC … EMC, listed in panel order in the catalog's OCProperties), clipping masks are clipping paths around what they clip, groups with opacity are transparency group forms, and text is text objects in embedded (often subset) fonts. Illustrator also keeps its own native copy of the artwork as private data (PieceInfo → AIPrivateData, compressed PostScript-like streams); it reads that copy rather than the PDF when it opens the file. Files from Illustrator 8 and earlier are PostScript and are not read.

Design

pdf          objects, cross-reference tables and streams, object streams,
             repair of damaged files, filters, content streams, writing
             (pdf/lexer, parse, xref, repair, pages, filter, content, write)
font         PDF fonts: Type 1, CFF, TrueType, OpenType, Type 3, CMaps,
             encodings, the glyph list, standard-14 metrics, stand-ins
color        color spaces to sRGB (device, calibrated, Lab, ICC by
             component count, indexed, separation, DeviceN)
function     sampled, exponential, stitching, and PostScript functions
shading      the seven shading types, drawn into pixels
image        image XObjects and inline images: every depth, decode arrays,
             masks, JPEG (CMYK too), CCITT fax
interp       the content interpreter: graphics state, clipping, text
             positioning, forms, Type 3 glyphs, reported to a sink
build        a file into the model (the sink that builds it)
model        artboards, layers, groups (clip groups), paths, text, images,
             raw content; each object remembers the operators that drew it
render       the model drawn with tiny-skia; raw content through the
             interpreter (render/content: patterns, soft masks, groups)
text         layout of text the editor changed (fig_engine's fonts)
edit         operations and undo/redo (edit/nodes, edit/tree, edit/shapes)
save         writing the document as a PDF-based `.ai` (save/emit, text,
             paint, resources, objects)
marks        marked content the engine writes so saved files read back
             (groups, edited text, masked paths, hidden objects)
collab       editing together: node states as CRDT map entries
inspect      layers panel rows, node properties, hit tests, marquees, fonts
describe     documents summarized for AI agents and search
wasm         the web app's API (`AiFile`)

Reading

build::open interprets every page and builds the model. Pages become artboards placed side by side on one canvas (artboard = TrimBox, else CropBox, else MediaBox; page rotation shown). Optional content groups become layers in the file's panel order (empty and hidden layers too). Clipping paths become clip groups: clips are told apart by which W set them (interp::ClipPath::serial), so objects drawn under one clip share one group however q/Q nest; clips of the page's own box are dropped (they clip nothing on the artboard; content past the artboard shows on the pasteboard as in Illustrator). Forms become groups: a transparency group keeps its opacity, blend mode, isolation, and knockout; its bounding box clip is dropped when it clips nothing; a form that only wraps one object is replaced by it.

Each painted path becomes a path object in its own user space (the object's transform maps it to the canvas, so moves change one matrix and points stay exact) with its fill and stroke: colors keep their space (gray, RGB, CMYK, spot), axial and radial shading patterns become gradients. Text blocks become text objects: the glyphs as the file placed them (font, codes, positions, paints, grouped in runs) plus the characters, font family and style, size, line height, and tracking, so the text is editable and shows exactly as the file drew it until it is edited. Images become image objects. What the model has no equivalent for (soft-masked painting, tiling patterns, mesh shadings, sh, stencil masks, Type 3 text) becomes raw content, drawn by running its operators and moved as a whole.

Every object keeps its source: the operators that drew it, the CTM, the operators that set the rest of its graphics state (each with the resource dictionary it names things in, since state set in a page applies inside the forms it draws), and its resources.

Drawing

render::Renderer draws a view of the canvas: artboards, then layers. Paths fill and stroke with tiny-skia (gradients as shaders, non-extended ends clipped); groups clip and composite through layers when they have opacity or a blend mode; text from files draws the file's glyph outlines; edited text is laid out and drawn; images decode once and are kept, with halved copies for drawing small. Raw content runs through the interpreter into a canvas with a clip stack, transparency groups, soft masks (luminosity and alpha, with transfer functions), shading and tiling patterns (cells drawn at device resolution), shadings, images, and glyph outlines.

Fidelity, measured with ai_render compare against poppler at 72 dpi on sample Illustrator files: mean channel difference under 0.4 for vector artwork and under 2 for files with photos and text (text antialiasing and CMYK conversion account for the rest).

Editing

Operations (edit::Op, JSON from the editor) name nodes by id and run as undoable steps; a batch that fails leaves the document as it was. Edit flags record what changed. Transforms change node transforms (groups pass them to their contents and clips); fills, strokes, paths, and text change the model; there are creation (paths, rectangles, ellipses, polygons and stars, text), deletion, duplication, moves in the tree, grouping, clipping masks, layers, text to outlines, boolean operations (fig_engine's), artboards, and placed images.

Saving

An unedited document saves byte for byte. Otherwise the file is written again as a PDF: one page per artboard (the original page boxes and rotation when the artboard kept its size), layers as optional content groups (hidden and locked ones listed off and locked), groups as marked content (/MacroGroup with the name; transparency groups as forms), and each object either as the file drew it — its operators, renamed into the page's resources, with any move written in front as a cm — or, when it was redrawn, from the model. Edited text is written as outlines (so every application shows it as laid out here) with an invisible copy of its characters (search and copy work) inside /MacroText marked content that reads back as editable text. Hidden objects go in an optional content group that is off. A gradient with transparent stops is painted under a soft mask of its stops' opacities, as Illustrator writes it, inside /MacroPath marked content that reads back as the path. Illustrator's private data is left out, so Illustrator reads the edited PDF instead of its stale copy. Saving every sample file after moving everything away and back draws identically in poppler.

Collaboration

Everyone opens the stored file (node ids are given in reading order, so they agree) and applies shared entries: node states (properties, transform, parent and fractional position, and the node's content when it differs from the stored file), the artboards, and images placed during the session. New nodes get ids in the creator's session (session << 20). See collab.rs.

The CLI

cargo run -p ai_engine --features cli --release --bin ai_render -- <command>:

  • info <files…> [--tree]: artboards, layers, object counts, warnings, open time.
  • render <file> [--out dir] [--scale s]: each artboard as PNG.
  • roundtrip <files…> [--out dir]: moves everything away and back, saves, reopens, and compares renders.
  • compare <file> <refs-dir> [--scale s] [--out dir]: renders against reference PNGs (pdftoppm -cropbox -r 72 -png file.ai refs/name).

Known gaps

  • Illustrator 8 and earlier (PostScript) files are not read.
  • Artboard positions come from page order (side by side), not from Illustrator's private data; an object spanning two artboards is drawn on each page and reads back twice.
  • Edited text is saved as outlines with invisible text; Illustrator opens it as outlines, the engine as text.
  • Knockout groups draw as plain transparency groups.
  • Live effects, symbols, and other Illustrator-only constructs show as they were drawn in the PDF.