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 board.PrjPcb --gallery
acr toon board.PrjPcb --open
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 current additive schema is pcb.svg.config.a1; pcb.svg.config.a0 remains accepted and there is 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 A1 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, film, silk, holes, outlines, cutouts and projected labels. Presets place BOARD_SUBSTRATE beneath regional surface copper and film. SURFACE_COPPER_TOP/BOTTOM select and region-clip each substack's actual outer copper row, so rigid TOP and flex MID2 can coexist without exposing internal rigid copper. Substrate color=auto resolves authored region material colors when present, the saved rigid board-core display color, and separate rigid/flex palette fallbacks; flex substrate defaults to amber #D18B28. Film is emitted only in regions whose resolved substack authors solder mask or coverlay. A non-auto substrate or film color remains a global compatibility override. New Toon presets use silkscreen_surface.clip_mode=film, clipping top/bottom physical silk to that same film domain and its openings; set it to none for authored-overlay compatibility or board to allow ink on bare substrate while still removing board voids. Their physical silkscreen colors default to auto: each side selects black or near-white from its resolved film colors to maximize worst-case contrast, so saved white mask uses black silk. Explicit category colors remain unchanged, including colors stored in older editable configs. 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 diagnostics when individual faces cannot be tessellated. These partial meshes are illustrated and cached normally; the queued diagnostic retains the component, body, model and exact upstream message. Models with no usable geometry follow the omission behavior below.

Through-board component bodies are resolved against Cruncher's region-aware rigid-board thickness. When every board-material region intersected by the body's conservative XY bounds has an equivalent stack envelope, Toon submits a world-space top or bottom half-space to Geometer B0 after the complete authored model transform. The returned surface fragment alone supplies its bounds, HLR, outlines and shading. Toon composes that fragment inside the board-material domain with an uncut projection restricted to true mechanical open space: routed cutouts, eligible untented through bores, and the area beyond the board edge. Film openings and pad graphics do not create mechanical visibility. Expected empty fragments are omitted without warning. Bodies spanning unlike stack envelopes use the conservative authored-side surface fallback and omit unsafe opposite-side material rather than guessing. Flex regions remain flat; bend lines are documentation graphics rather than component deformation. See the rendering algorithm and limitations.

When every rendered body in one component or free-board instance has the same authored partial opacity, Toon computes geometry, clipping, HLR, shading and occlusion as opaque, then applies that opacity once to the final component-instance SVG group. This avoids cumulative darkening from overlapping projected polygons. It is not transparent-aware HLR: partially transparent bodies still occlude as opaque and produce the nonfatal partial-opacity-opaque-occlusion diagnostic. A zero-opacity body is omitted before geometry processing. Mixed per-body opacity remains material-local because one final instance value cannot represent it.

Default output is {board}__top.svg and {board}__bottom.svg. The command replaces its selected output files. --gallery adds a self-contained index.html using relative, cache-busted links to exactly the SVGs emitted by the current run; stale output files are not included. The responsive gallery centers transparent or fixed-canvas SVGs inside each preview instead of displaying them at the browser viewport's upper-left. Selecting a preview opens the original SVG markup in a full-screen inspector with drag panning, wheel and toolbar zoom, fit, next/previous navigation, and a raw-SVG link. The inspector uses the vendored svg-pan-zoom library and requires no network access; it never rasterizes the review SVG. --open implies the gallery and opens its local file URI through the default browser. 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. Recoverable model and geometry conditions do not stream during this work. After rendering, cleanup and requested reports complete, Toon presents the selected warning summary or detail and then confirms success. Unsupported-model diagnostics identify the affected component/body, model filename and format/extension; rendering continues with that body omitted. Missing or unreadable STEP data is separate from unsupported formats. A fitted component with no authored model is omitted and contributes one side-independent missing-renderable-model diagnostic; DNP components in the active population do not. Root --quiet suppresses informational progress but keeps the selected warning presentation and errors. Use acr --verbose toon for internal context, worker scheduling, cache statistics and per-layer/view/variant timings. --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. Exact direct-model projections are also single-flighted within the command by native source, model bytes, view, style and clipping plane; occurrence placement, region decisions, masks and metadata remain independent. Trusted bounds omit a fully hidden opposite-side projection only when a conservative board/open-space query also proves that it cannot appear beyond an edge or through a physical opening. Ambiguous and surface-crossing cases retain the exact clipped/unclipped composition. 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 and both authored body sides when region-aware clipping is available. Final composition removes expected empty fragments and DNP illustrations/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 preserves the authored physical silkscreen by default and adds projected labels as an overlay. Set assembly.hide_silkscreen_designators=true when an assembly-only presentation should suppress the saved designators.

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, render settings, and the physical board/open-space domain that controls omission. Changed recipes, board topology, bores, or tenting rebuild the affected bundle while retaining safe ordinary model-cache reuse. The namespace is tied to the consumed native binaries, dependency versions and all internal illustration/cache-policy sources. 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 once when the render job completes, including failure exits; this command-scoped maintenance avoids repeatedly scanning a populated cache during cold rendering. Individual uncompressed entries above 256 MiB are skipped. Recently reused entries survive trimming. --cache-dir and --no-cache are invocation controls, not an SVG config field. 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.

--warning-report output/toon-warnings.json writes the warning report contract. Diagnostics and summary groups use deterministic structured ordering, independent of worker completion. Repeated views, retries and cache replay merge by stable occurrence identity. An explicitly requested report is written even when empty. The command creates parent directories and replaces an existing report file; an unwritable path is a fatal output error. Console mode does not change report contents.

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.