toon

Usage

acr toon board.PrjPcb --theme white
acr toon board.PrjPcb --assembly --side top
acr toon board.PrjPcb --variant "production" --side top
acr toon board.PrjPcb --all-variants
acr toon board.PrjPcb --workers 8
acr toon --write-config toon.jsonc

Input and project context

Accepts a PrjPcb or PcbDoc. Without an input, searches the current directory for projects first, otherwise boards. Loads project metadata and selected boards without parsing schematics; project parameters, variants and PCB special strings remain available. PcbDoc inputs discover a referencing sibling project when available, including projects with unavailable schematic files. Standalone boards retain synthesized project context. Schematic sheet parameters are not used by Toon. --doc/--pcbdoc selects a board by filename, stem, or relative path.

Editable configuration

The PCB SVG/Toon config contract is authored in TypeSpec and generates its JSON Schema, Python and TypeScript types, browser validator and field help. See the authoring and consumer guide and generated field reference. The authored-config codecs retain unset fields for inheritance; they do not materialize resolved settings when saving an override.

Creates toon.config beside the input if missing, then renders with it. Subsequent runs load the existing file without rewriting edits. --config PATH selects another file, creating the illustration template there if missing. The schema is the existing pcb.svg.config.a0; no separate illustration schema. The initial template contains both sides and records the first invocation's theme and assembly settings. --side filters only the invocation. --write-config PATH writes the resolved configuration and exits without rendering or requiring an input.

Preset defaults are overlaid by config objects recursively; arrays, including views, replace the preset arrays. Explicit CLI choices apply last. Every enabled view must contain exactly one of ILLUSTRATION_TOP or ILLUSTRATION_BOTTOM. Layer outputs are disabled; use pcb-svg for arbitrary non-illustration compositions. Configured view names and output_svg paths are respected.

All style groups, including illustration and assembly_designators, inherit global fields and merge partial view overrides. Per-designator suppression uses components.J1.show_designator=false. Export a reusable config to customize substrate color, mask opacity, silk, holes, outlines, cutouts and projected labels. Presets place BOARD_SUBSTRATE beneath copper and film; global.styles.board_substrate.color defaults to muted tan #B6A26B. Mask text and logos over bare board reveal this color. Existing saved configs can enable it by adding BOARD_SUBSTRATE first in each view's layer list. Set global.styles.assembly_designators.stroke_color and stroke_width_mm for an outline behind the label fill. A width of 0 disables it; the review uses white at 0.1 mm.

Options and defaults

SVG retains vector artwork, component metadata, transparency and physical canvas dimensions. Raster conversion is outside this command; use a separate tool when needed. Older experimental configs must remove global.png. The removed --format, --dpi, --width and --background flags are no longer accepted.

Variants

No variant flags means the base saved board, with no DNP filtering and an empty VariantName special string. A named variant removes DNP component bodies and projected assembly labels while retaining fabricated copper/pads/silkscreen. Variant project and component parameter overrides are applied to the render context without modifying source files. Named outputs receive a data-variant root attribute in SVG.

Explicit variant output goes into a sanitized variant-name directory; all-variant output also includes base/. Relative SVG output patterns resolve inside each variant directory. Unknown variant names, colliding directory names, and alternate-part model substitutions are reported as errors before rendering. Alternate-part 3D model resolution is not implemented; existing models are never silently presented as replacements.

Output and progress

Geometer returns usable model faces with warnings when individual faces cannot be tessellated. These partial meshes are illustrated and cached normally; progress warnings identify the component and model. Models with no usable geometry follow the omission behavior below.

Default output is {board}__top.svg and {board}__bottom.svg. The command replaces its selected output files. Configurations remain editable across runs. Normal output reports config selection/creation, project loading, board/variant/view rendering, STEP model completions with filenames and component designators, component progress and saved files. The final message confirms success and the output directory after cleanup and any requested timing report are written. Unsupported model warnings identify the affected component/body, model filename and format/extension; rendering continues with that body omitted. Missing or unreadable STEP data is reported separately from unsupported formats. Root --quiet suppresses informational progress but keeps warnings and errors. Use acr --verbose toon for internal context, worker scheduling, cache statistics and per-layer/view/variant timings. These diagnostics precede the final success message. --timings PATH writes structured timings independently of console verbosity.

SVG reuse and timings

A job starts native model workers lazily, only for unique requests missing from its memory and disk caches. Each worker owns a separate Geometer process, reused across sides and variants until the command finishes. Results, warnings and instance metadata are committed in source order, so worker count does not change SVG paint order or deduplication. Embedded STEP cache misses are processed in a bounded batch before source-order body collection; failed operations are reported at their original body position. The batch finishes before serial extrusion work starts. Cached-only work starts no native workers. The configured limit does not include the separate serial model-collection client. Larger counts can increase memory and may be slower on some machines. Cancellation cancels queued work, drains already-running requests with their ordinary native timeouts, then closes the clients.

Within one invocation, selected variants share immutable board/layer data and prepared component artwork. Preparation includes the union of selected populations. Final composition removes DNP illustrations and projected labels, prunes unused symbols, and updates instance metadata and bounds. Physical board layers remain present. Parameter-only variants reuse physical/film layers when their text dependencies agree; variant-dependent strings are resolved before cache lookup. Cached XML is stored as immutable fragments, and each output retains its own metadata and group IDs. Board contexts share stable facts while binding each view's options and variant parameters independently. Native single-layer primitives share an ordered index of resolved layer identities across physical and film renderers; pads, vias and custom renderers retain their existing selection rules.

Silkscreen graphics and saved designators are cached separately. To retain saved designators while hiding graphics, set both global.styles.silkscreen_component_graphics.enabled and global.styles.silkscreen_board_graphics.enabled to false, and global.styles.silkscreen_designators.enabled to true. Graphic categories include their non-designator text. Assembly presets hide saved designators by default.

Across invocations, disk caching is enabled for completed tessellations and relative illustration SVGs/outlines. A successful component-artwork bundle can also supply placements, bounds and shared SVGs before loading or transforming meshes. Its conservative side-level key includes exact authored body recipes, model content, pose, materials, diagnostic identities and render settings. Changed recipes rebuild that side's bundle while retaining ordinary model-cache reuse. The namespace is tied to the consumed native binaries, dependency versions and illustration/cache policy. It uses checksummed compressed JSON and atomic writes. Corrupt or unavailable cache entries warn and rebuild. Geometry warnings replay in their original body order; native illustration warnings retain their original first-use ownership. Failed bodies and components are not saved as successful placements and retry on later runs. Final board layers, parameter resolution and editable configs are rebuilt or loaded normally.

The default directory is %LOCALAPPDATA%/altium-cruncher/svg-models on Windows, ~/Library/Caches/altium-cruncher/svg-models on macOS, or $XDG_CACHE_HOME/altium-cruncher/svg-models (default ~/.cache) on Linux. The internal versioned layout is disposable, not an interchange contract. Generated entries are trimmed to 1 GiB after writes and on job completion (including failures); individual uncompressed entries above 256 MiB are skipped. Recently reused entries survive trimming. --cache-dir and --no-cache are invocation controls, not SVG config fields. Timings include disk-cache counts and read/write durations; silk_chunk rows identify the reused silk category in part.

Assembly variants retain the exact projected labels from the prepared artwork. The existing fitter uses quantized geometry cache keys; a separately prepared population can differ by a small font-search step near a boundary. Population selection does not refit or reposition a prepared label.

--timings output/svg-timings.json writes the timing contract. Layer durations include materialization, including native illustration or HLR calls, or the measured cost of a cache lookup/population assembly. Side is top, bottom, both for mixed views, or board for side-independent layers. Parent durations include their children; do not sum them together. exclusive_seconds subtracts measured children. View totals describe SVG construction; variant/job totals also include SVG file writing. Times include native IPC waits and are not CPU profiles. Completed/failed spans are recorded on errors; a failed job report can be partial.

Unavailable or unsupported attached models (including Parasolid .x_t) and native model-conversion failures produce warnings identifying the component, body and model. The affected body is omitted; other bodies and board layers continue. Native HLR/illustration operation failures omit that component illustration with a warning. Failed requests are remembered within the renderer job so repeated geometry is not retried for every instance. Omitted attached models do not receive invented illustrations or pad-based assembly labels. These warnings do not make the command fail. Invalid inputs/settings, native service/process/protocol failures and output failures still return a nonzero exit code.

SVG Editors

Views and PCB layers are emitted as named Inkscape layers while retaining stable IDs and web-facing metadata. Component illustration and designator groups appear by designator in editor object panels and include matching ARIA labels.

Tests

CLI/config/progress tests live in tests/test_toon_cli.py. Rack L3 illustration workflows exercise native STEP, extruded and cylinder bodies, top/bottom placement, composable layers and metadata. Shared contract vectors and serializer tests validate TypeSpec projections in Python and browser consumers.