Icons

Why an Icon System?

In complex, publication‑grade diagrams, a lone arrow or block label is rarely enough. We often need semantic glyphs – check‑marks for valid, exclamation triangles for warning, tiny CPUs for compute node – to compress entire phrases into a few visual atomic components.

Yet: manually hunting SVGs, juggling \includegraphics, tweaking dimensions, and recoloring for dark‑mode is drudgery. Neural‑Sketch treats icons as first‑class primitives, governed by the same declarative key–value philosophy that powers blocks, annotations, and containers.

Quick Start

% Load an icon by name – fuss‑free
\nskIcon[name=compute]

On first compilation Neural Sketch will:

1. Fetch the raw SVG from the Lucide repo (via pyfetch).
2. Recolor its stroke to match your theme (icon-color, defaults to your block border color).
3. Cache the processed file in ./icons/ for future compilations.
4. Inline it with the correct width/height so it sits snugly beside text.
5. Collect unused icons and purge them from the disk—keeping your repo lean.

No extra packages, no manual downloads, no brittle path juggling.

Anatomy of \nskIcon

% General form – every key other than `name` is optional
\nskIcon[
  name        = check,   % SVG Provider name (slug)
  type        = lucide,  % future‑proof; SVG Provider
  color       = nskRed,  % any color expr or xcolor name
  border-size = 2.5,     % stroke-width / floating point or int
  size        = .5cm,    % overall icon size (dim)
]

Parameter Cheatsheet

Icons as regular text

Icons read like letters—seamless in the line. \nskIcon is a real node, so place it anywhere $\LaTeX$ accepts text—mid‑sentence, in captions, or via a `\nskBlock` text-* keys.

Spin it with style={rotate=…} or nudge the baseline with shift-y. Below, a compass‑rose demo shows the idea.

You can use and insert an \nskIcon wherever text is accepeted. The most common way is to embed it in a text-* within an \nskBlock.

\nskBlock[
  text-center = {\nskIcon[name=aperture]},
  text-north  = {\nskIcon[name=redo, style={rotate=0}]},
  text-east   = {\nskIcon[name=redo, style={rotate=-90}]},
  text-west   = {\nskIcon[name=redo, style={rotate=90}]},
  text-south  = {\nskIcon[name=redo, style={rotate=180}]},
  % ...
]
 
\nskBlock[
  width=3cm, last-pos={right=},
  text-center={\nskIcon[name=memory-stick]\; Memory},
  % ...
]

Providers

You can easily use an icon from one of the supported providers by just specifying their icon name (slug).

Search icons on Lucide

  \nskBlock[
    text-center = {\nskIcon[name=check, type=lucide]},
  ]

Supported

Alignment

Icons ship baseline‑centred, so they slip into prose without tilting the line. Add breathing room with the usual TeX spacers (\,, \;, \quad, …).

By default icons are vertically aligned, with their baseline aligned with the center of the icon. This allows natural insertion within text. You can easily adjust the horizontal spacing using the usual $\LaTeX$ spacing macros.

\foreach \cmd/\name [count=\i from 1] in {
    \! / Neg. thin space,
    \, / Thin space,
    \: / Medium space,
    \; / Thick space,
    \quad / Quad,
    \qquad / Double quad
  }{
    \nskBlock[
      last-pos={right=5mm}, width=0cm,
      text-center={\nskIcon[name=arrow-right-to-line]{\cmd}Text},
      text-south={\name},
      fill={nskRed!\pct!nskBg},
    ]
  }

Customization

To ensure pixel-perfect rendering and broad compatibility across icon libraries, we rely on SVG vector graphics. However, $\LaTeX$ does not support vector graphics directly, so a preprocessing conversion must take place before you can use them.

This means that you cannot directly change icon properties on-the-fly. Neural Sketch allows you to modify both the color and border-size of the icon by altering the SVG properties before the icon is converted to a format accepted by $\LaTeX$.

Icon Color

You can specify the icon color through the color= key:

\nskIcon[name=circle, color=nskRed]

  \foreach \i/\c[count=\x] in {
    brain/Red,cpu/Orange,memory-stick/MainAccent,
    brick-wall/Pink,bot/Blue,
    bug/SecondaryAccent,layers-2/Yellow
  } {
      \nskBlock*[
        last-pos-s={right=5mm},
        text-center={\nskIcon[name=\i, color=nsk\c]},
        % ...
      ]
		}

Icon Border size

You can specify the border-size as:

\nskIcon[name=circle, border-size=2.5]

\foreach \i[count=\x] in {
  brain, cpu, memory-stick, brick-wall,
  bot, bug, layers-2
} {
  \nskBlock*[
    last-pos-s={right=5mm},
    text-center={\nskIcon[name=\i, border-size=\w]},
    text-south={\w},
    % ...
  ]
}

Behind the Curtain – the pyfetch CLI

The TeX layer delegates all I/O to the Python helper pyfetch.py, invoked under \write18 (so remember to enable --shell-escape).
Four micro‑services form the backbone:

Global Style Hooks

Neural‑Sketch exposes a quartet of package‑level keys so you can shape icon behaviour across all icons:

icon-type        = lucide       % future: fontawesome, tabler, …
icon-color       = nskFg        % default stroke colour
icon-width       = .5cm         % css‑like unit, any dimexpr
icon-height      = .5cm         % usually =width for square glyphs
icon-border-size = 2.0          % default stroke width applied pre‑conversion
icon-shift-y     = 0pt          % default vertical baseline offset
icon-outdir      = icons        % where processed SVGs live
icon-intdir      = out          % sub‑folder for pyfetch scratch files

Tweak them once in the preamble, watch every figure adapt automatically.

Garbage Collection – \nskCleanUnusedIcons

Unused icons are automatically purged and deleted. You can modify this behavior by specifying the icon-clean global options:

\usepackage[
  icon-clean=true,
]{neural-sketch}

If you want to manually clean the unused icons, At the end of each run, issue:

% Usually in \AtEndDocument
\nskCleanUnusedIcons

The macro walks the internal property list g__nsk_used_icons_prop, computes the set difference against files on disk, and delegates removal to pyfetch clean-lucide ….

Reference Table