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, Google Drive).

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} or Source{file.ext} is accepted as the standard Source module form.
• .webp inputs are converted to cached .png files before SVG placement, because not every Inkscape/export pipeline handles WebP reliably.

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

1. Same folder as the SVG template.
2. Asset folders beside it: assets/, images/, img/, imgs/.
3. Template-named asset folders beside it: template_name*assets/, template_name*images/, template_name*img/, template_name*imgs/.
4. Parent asset folders: ../assets/, ../images/, ../img/, ../imgs/.
5. Runtime Python asset folders: python_dir/assets/, python_dir/images/, python_dir/img/, python_dir/imgs/.

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 }
@{ gdrive://file/file_id }
@{ gdrive://folder/folder_id/*.png }

PnPInk also supports dedicated map sources:

@{ osm://[...] }
@{ ofm://[...] }
@{ osm://madrid }
@{ ofm://spain/z4 }
@{ ofm://shikoku/t1 }
@{ ofm://shikoku/z8/t1 view=all-labels+water_name[bay lake] }
@{ ofm://asturias view=mountains smooth=3 }

These sources generate maps from simple URLs. Map sources support /zN to force zoom and /tN to limit the automatic tile grid per axis. Use view= to choose rendered layers/features and smooth=/s= to control configured line smoothing. See Maps for details.

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
• gdrive:// (Google Drive) supports public shared files/folders:
• file by id: gdrive://file/file_id
• folder listing by id: gdrive://folder/folder_id/*.png
• folder paths: gdrive://folder/folder_id/Artworks/used/card.png
• real Drive URLs: https://drive.google.com/file/d/file_id/... and https://drive.google.com/drive/folders/folder_id
• folder listing requires gdrive_api_key in preferences.ini

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 }
@{ gdrive://file/1AbCdEf... }
@{ gdrive://folder/1AbCdEf.../*.png }
@{ gdrive://folder/1AbCdEf.../Artworks/used/card.png }

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]
*@{ gdrive://folder/1AbCdEf.../*.png }[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.

Google Drive notes:

• Only public/shared resources are supported. Private folders require OAuth and are not handled here.
• gdrive://file/... downloads a single file and caches it locally.
• gdrive://folder/... lists the public folder, filters by name/glob, then downloads selected files.
• Folder path segments are resolved as real Drive folders, not as slash characters in the file name.
• Cached downloads are stored in the same assets cache used by other web sources.
• Folder listings are cached per run, and file downloads are prefetched in parallel using network_workers_gdrive from preferences.ini (default: 8).

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[B3] -> column B, row 3
@sp1[B3:C5] -> rectangular range
@sp1[B4..C6] -> linear walk following the spritesheet layout order
@sp1[A4 B2 A1] -> explicit unordered 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.