Annotations

Clearly label and reference diagram elements with automatically numbered annotations.

Overview

Annotations in Neural Sketch provide an elegant way to insert clear, auto-numbered labels and explanatory notes directly into your diagrams. This streamlines the creation of professional, self-explanatory visuals, crucial for effectively communicating complex ideas such as neural architectures, algorithmic steps, or intricate system diagrams.

Key Features:

Automatic numbering or customizable reference tags.
Flexible positioning relative to diagram elements.
Rich styling options for annotation boxes and connector arrows.
Seamless integration with the Neural Sketch ecosystem.
Highly extensible reference system that allows overriding default numbering by providing custom reference tags and labels, ensuring complete control and adaptability.
Integrated referencing: Easily incorporate citations, equations, and references directly within figures, seamlessly linking your diagrams to other sections of your $\LaTeX$ paper.

Annotation as Thought Layer

Annotations in Neural Sketch are not decorative. They’re structural. They let you talk about your diagram from within the diagram—weaving explanation directly into the figure itself.

Think of them as embedded margin notes—auto-numbered, positioned with intent, and visually tuned to match your diagram’s geometry and voice.

They transform diagrams into narratives: part geometry, part language. Think of them as in-line commentary for structure, where insight is embedded next to form.

They automatically track, connect, and style themselves—letting you focus on content, not micromanagement.

What sets them apart

They handle their own numbering. - They know how to connect back to what they’re describing. - They keep you out of the weeds of manual spacing and styling.

Minimal Form

The base form is simple:

\nskAnnotate[<key=value list>]

Here’s the smallest working example:

\nskBlock[id=myblock, text-center=My Block]
\nskAnnotate[
  connect-to=myblock.west,
  text=Important,
  pos={left=of myblock},
]

You get a neatly placed label, auto-numbered, connected by a clean line. No glue code. No guesswork.

What You Can Control

Annotations expose a thoughtful set of keys. Here’s a feel for what’s in your toolbox:

Property	Default	Description
`ref-tag`	Auto-numbered	Manual override for the reference label
`header`	(none)	Bold label placed at the top
`title`	(none)	Italic subheading beneath the header
`text`	(required)	The main content—usually your explanation
`text-align`	`left`	Align annotation text (`left`, `center`, `right`, `justify`)
`fill`	`nskLightestGray`	Background of the annotation box
`border-color`	`nskMidGray`	Color of the annotation border
`border-type`	`solid`	Style of the border: `solid`, `dashed`, or `none`
`rounded-box`	`false`	If true, the annotation uses a rounded rectangle
`padding`	`3pt`	Inner padding between box and text
`connect-to`	(none)	Anchor the annotation points to
`anchor-from`	`east`	Which edge of the annotation emits the connector
`width`	`4.5cm`	Sets the maximum width for text wrapping inside the box

Styles in Practice

% Annotation 1: Simple, no border
\nskAnnotate[
  pos={left=2cm of a},
  anchor-from=east, connect-to=a.west,
  header=Explanation,
  title=Key Observations,
  text=This is an important portion.,
  fill=none, border-type=none,
]

Manual Tags, or No Tags

Neural Sketch manages numbering for you, but you can override it:

\nskAnnotate[
  ref-tag={a},
  text=Essential observation.,
  connect-to=myBlock.west,
]

Want no tag at all?

\nskAnnotate[
  disable-tag=true,
  text=This annotation has no label.,
  connect-to=myblock.west,
]

Routed with Precision

Annotations can connect to diagram nodes with custom arrows, bends, and corners:

\nskAnnotate[
  connect-to=myBlock.north,
  % this options has to match \nskConnect opts
  connect-opts={ 
    arrow-style={dotted, thick}, 
    corner-radius=5mm 
  }, 
  text=Routed arrows improve clarity.,
]

This routing is powered by the bridges and decorations systems—so when needed, style your arrows to match your flow.

Text Layout

Control how the content behaves inside the box:

\nskAnnotate[
  text-align=justify, % left | center | right | justify %
  text={Longer annotations benefit from justified alignment.}
]

Text Wrapping

Annotations wrap by default, unless otherwise specified. You can:

Set width=0cm to disable wrapping
Set a fixed width (e.g. width=3cm) for multiline text

\nskAnnotate[width=0cm, ...] % one-liner (no wrap)
\nskAnnotate[width=3cm, ...] % wrapped block

Line breaks (using \\) are only rendered when a fixed width is specified.

Edge Alignment

If you want all annotations to align along a shared visual edge (e.g., same left edge), use \nskMeasure to dynamically compute the required offset:

% (0) first annotation block
\nskAnnotate[
  connect-to=dy, pos={right=3cm of dy}, anchor-from=west,
  header=Leaf Nodes, title=AccumulateGrad, text=Leaf nodes,
]
% (1) measure
\nskMeasure[from=gb.east, to=\nskID{1}.west]
 
% (2) align
\nskAnnotate[
  connect-to=gb, pos={right=\nskDistance of gb}, anchor-from=west,
  header=Dependencies, title=Decrement \& Dispatch,
  text={Dec. deps, queue if ready.},
]

In practice

examples/bgrad.tex

\begin{nskFigure}[]
	\foreach \v[count=\i] in {r, s, t} {
			\nskBlock[
				type=circle, width=1cm, id=d\v,
				text-center={\large$\frac{\partial{z}}{\partial{\v}}$},
				text-north=\i, last-pos-s={right=.5cm}, text-north-style={xshift=-3mm}
			]
		}
	\nskBlock[id=gc, text-center={grad\_fn \textbf{C}}, pos={below=of \nskID!{2}}, fill=nskOrange]
	\nskBlock[id=ga, text-center={grad\_fn \textbf{A}}, last-pos={above left=3cm and 0cm}, fill=nskMainAccent]
	\nskBlock[id=gb, text-center={grad\_fn \textbf{B}}, last-pos={right=2.5cm}, fill=nskSecondaryAccent]
 
	\nskBlock[
		type=circle, width=1cm, id=dx,
		text-center={\large$\frac{\partial{z}}{\partial{x}}$},
		pos={above=of ga}, fill=nskMainAccent,
	]
	\nskBlock[
		type=circle, width=1cm, id=dy,
		text-center={\large$\frac{\partial{z}}{\partial{y}}$},
		pos={above=of gb},  fill=nskSecondaryAccent,
	]
 
	\foreach \v in {r, s, t} {\nskConnect[from=gc, to=d\v, bend-type=double]}
	\nskConnect[from=dr, to=ga, bend-type=double]
	\foreach \v in {s, t} {\nskConnect[from=d\v, to=gb, bend-type=double]}
	\foreach \f/\t in {a/x, b/y} {\nskConnect[from=g\f, to=d\t]}
 
	% annotations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ <<<
	\nskAnnotate[
		connect-to=dy, pos={right=2.7cm of dy}, anchor-from=west,
		header={Leaf Nodes}, title={AccumulateGrad},
		text=Leaf nodes,
		fill=none, border-type=none,
	]
	\nskMeasure[from=gb.east, to=\nskID{1}.west]
	\nskAnnotate[
		connect-to=gb, pos={right=\nskDistance of gb}, anchor-from=west,
		header={Dependencies}, title={Decrement \& Dispatch},
		text={Dec. deps, queue if ready.},
		fill=none, border-type=none,
	]
	\nskMeasure[from=gc.east, to=\nskID{1}.west]
	\nskAnnotate[
		connect-to=gc, pos={right=\nskDistance of gc}, anchor-from=west,
		header=Outputs, title=Grad Mapping, text=One grad per input.,
		fill=none, border-type=none,
	]
 
\end{nskFigure}
]

Reference Table

This table summarizes all available keys for \nskAnnotate. Defaults are inherited from global styles unless explicitly overridden.

Prop	Type	Default
anchor-from?	`token list`	`east`
width?	`dim`	`4.5cm`
border-color?	`token list`	`nskMidGray`
border-radius?	`dimension`	`1mm`
border-size?	`dimension`	`{}`
border-type?	`token list`	`solid`
connect-opts?	`token list`	`arrow-style = {dotted, thick`
connect-to?	`token list`	`{}`
disable-tag?	`boolean`	`false`
fill?	`token list`	`nskLightestGray`
header?	`token list`	`{}`
header-style?	`token list`	`\bfseries`
padding?	`dimension`	`3pt`
pos?	`token list`	`{}`
ref-tag?	`token list`	`{}`
rounded-box?	`boolean`	`false`
text?	`token list`	`{}`
text-align?	`choice`	`left`
text-color?	`token list`	`c__nsk_principal`
text-style?	`token list`	`{}`
tikz-opts?	`token list`	`{}`
title?	`token list`	`{}`
title-style?	`token list`	`\itshape`
width?	`dimension`	`0cm`
x?	`number`	`0`
y?	`number`	`0`

Annotations

On this page