5.10 Source

@{...} creates a source object from an external resource (file, icon, or URL), then uses it as a renderable object in the document.

Use Source when content comes from outside the template and must be resolved at generation time.

5.10.1 Syntax

All three forms below are equivalent entry points into the same source resolver pipeline.

Source{source_ref} or S{source_ref} or @{source_ref}

The source_ref can be:

• a path to a local file,
• an iconify reference,
• a web URL,
• or a virtual source (Wikimedia Commons, Pixabay, Openclipart, PnPInk Assets).

5.10.2 Local File Sources

Use local files for stable, reproducible builds where assets are versioned with the project.

@{ relative/or/absolute/path.png }
@{ C:\path\to\image.png }   # Windows
@{ ~/images/token.png }     # Linux/macOS

Equivalent local-source forms accepted in dataset cells:

Source{path/file.ext}
@{path/file.ext}
@{file.ext}
@file.ext
file.ext

Notes:

• file.ext is accepted only for known source extensions (png, jpg, jpeg, gif, bmp, webp, svg, svgz, pdf, tif, tiff).
• file.ext} is not valid syntax. The closing } only exists in braced forms:
• @{file.ext}
• Source{file.ext}

When no path is provided (file.ext), lookup order is:

1. Same folder as the SVG.
2. assets/
3. images/
4. img/
5. imgs/ (compatibility)

Local sources support environment/home expansion:

• Windows: %USERPROFILE%
• Linux/macOS: $HOME, ${HOME}, ~

Inline text tokens

Inline icons can also use local shorthand directly inside text:

:bola.png:

Behavior:

• If the file is found by the same lookup rules above, it is treated as a source token.
• If not found, the token is kept as normal literal text (:bola.png:).

5.10.3 SVG Node Import (Optional)

For SVG sources only, you can target a specific node with #id:

@{ assets/icons.svg#heart_group }
@{ https://example.com/icons.svg#token_1 }

Behavior:

• without #id: the whole SVG is linked as a final image source,
• with #id: that node is imported and embedded (including required defs/references).

5.10.4 Iconify Sources

Use icon sources for semantic symbols (costs, resources, status icons) without managing local files manually.

@{ icon://icon_set/icon_name }

Examples:

@{ icon://noto/heart-suit }
@{ icon://mdi/account }
@{ icon://cat }   # uses default set (noto)

There is a default snippet definition mapping to the noto icon set:

:Ic(icon) -> @{ icon://noto/icon }

Notes:

• Icons are cached as SVG symbols in <defs>.
• If iconify.py is not available, a placeholder is created.
• To force a re-download, remove the symbol from Object > Symbols (Shift+Ctrl+Y).

5.10.5 Web Sources (HTTP/HTTPS)

Use web sources when assets are remote and can be cached at generation time.

@{ https://... }
@{ http://... }

Web sources are downloaded and cached into the assets folder next to the SVG (or project root). If the download fails, a placeholder symbol is created.

5.10.6 Virtual Sources

Virtual sources map high-level search expressions to real downloadable URLs. They are useful for exploratory workflows and rapid prototyping.

PnPInk supports virtual sources that resolve to real URLs:

@{ wkmc://query/size }
@{ pxby://query/size }
@{ oclp://query/size }
@{ pnp://asset_path }

PnPInk also supports dedicated map sources:

@{ osm://[...] }
@{ ofm://[...] }
@{ osm://madrid }
@{ ofm://spain/z4 }

These sources generate maps from simple URLs. See Maps for the map syntax and examples.

Placed sources can also be adjusted afterwards with Transform, for example to reduce opacity or soften edges.

• wkmc:// (Wikimedia Commons) supports:
• search text: wkmc://query/size
• specific file: wkmc://File:Name.ext/size
• category files: wkmc://Category:Name/size
• pxby:// (Pixabay) supports:
• normal search list: pxby://query/size
• direct lookup for no-space query when possible (single hit / id).
• oclp:// (Openclipart) supports:
• normal search list: oclp://query/size
• specific image by id/detail: oclp://id:12345/size (resolved internally via https://openclipart.org/detail/12345/...)
• pnp:// (PnPInk Assets) supports:
• direct asset path: pnp://birds/egg1
• default .png extension when omitted
• friendly numeric fallback: pnp://birds/egg -> first matching numbered asset such as egg1.png
• optional global lookup when the name is unambiguous: pnp://egg

Size accepts:

• presets: tiny, small, medium, large, xlarge, largest
• vector mode: svg (when available from the provider)
• minimum side: N (example: 1000)
• minimum width+height: WxH (example: 1000x1000)

Examples:

@{ wkmc://"The Ancestral Homes of Britain"/large }
@{ wkmc://"File:Complete_Saxonian_deck.jpg"/1000 }
@{ wkmc://"Category:Complete_decks_of_playing_cards_laid_out"/1000x1000 }
@{ pxby://castle/1200 }
@{ oclp://wolf/large }
@{ oclp://id:24829/largest }
@{ pnp://birds/egg }
@{ pnp://IA/icons/crown1 }

Multiple-result virtual sources can be selected outside the source with a 1-based selector:

@{ wkmc://"The Ancestral Homes of Britain"/medium }[2 4..12 15..26]
*@{ pxby://castle/large }[1..20]

Selector notes:

• indices are 1-based,
• out-of-range indices are ignored with warning,
• without selector, if multiple results exist, the first one is used (warning in log).
• for wkmc://, category/search results keep the API order after size filtering; PnPInk does not reorder them by image dimensions.

Wikimedia Commons category catalogs:

• each wkmc://Category:... source found in the dataset creates an internal 0-based catalog variable:
• first category: _wkmcc1
• second category: _wkmcc2
• each item exposes the useful fields returned by Commons:
• title
• url
• thumburl

${_wkmcc1[0].title}
${_wkmcc1[0].url}
${_wkmcc1[0].thumburl}
@{ wkmc://${_wkmcc1[0].title}/1000 }
@{ ${_wkmcc1[0].thumburl} }

pnp:// PnPInk Assets

pnp:// resolves against the public pnpink-assets index generated on push. It is meant for small reusable art pieces that can be placed automatically from a dataset without downloading them into every project.

Resolution rules are intentionally simple:

• if you provide a full asset stem, it is used directly,
• if you omit the extension, .png is assumed,
• if you omit the numeric suffix, PnPInk tries the lowest matching numbered asset,
• if you omit the folder, PnPInk tries a global lookup and warns if the name is ambiguous.

Examples:

@{ pnp://egg }            # may resolve to birds/egg1.png
@{ pnp://birds/egg }      # resolves within the birds collection
@{ pnp://IA/icons/crown1 }

The source behaves like any other image source, so it can be combined with Fit-Anchor and Transform:

@{ pnp://egg }~i7
@{ pnp://birds/egg3 }.T{o=80%}~[110%]8!

5.10.7 Fit and Placement Behavior

After resolution, a source behaves like any other placeable target in Fit/Anchor terms.

A Source is treated as a final placeable object, so you can apply Fit/Anchor operations exactly as with other objects.

5.10.8 Internal Model

This internal model is important for performance and file size on large projects.

Sources are instantiated as clones of symbols (<use>), not inline geometry copies. This keeps the SVG compact and avoids repeating heavy geometry.

5.10.9 Spritesheets (@)

Spritesheets allow one asset to provide many addressable frames. This is useful for token sheets, icon atlases, and catalog-like image packs.

The Layout module can also be applied to composite sources, such as spritesheets.

Example definition inside a comment block (before the dataset):

# @sp1 = @{sheet.png}.Layout{p=3x2^ s=poker g=[4 3]}

This creates a spritesheet from sheet.png with a 3x2 grid of poker-sized cards, spaced 4 mm horizontally and 3 mm vertically.

Then, you can reference any frame in the dataset as:

@sp1[14] -> frame 14 (third page, second row)
@sp1[2][1][3] -> page 2, column 1, row 3
@sp1[1..6] -> range selector
@sp1[1 4 7] -> explicit list selector

(^ in the grid reverses numbering direction: first rows, then columns.)

This spritesheet can be used as a source in any dataset, positioned with Fit parameters (e.g. ~i6) as any other target.

Notes:

• Alias definitions are read from comment lines before dataset rows.
• Frame selectors are 1-based.
• If a frame is out of range, a warning is logged and placement is skipped.