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.

Basic Usage

To create annotations, use the straightforward command:

\nskAnnotate[<key=value list>]

Minimal Example

Here's how to attach a simple annotation to a block:

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

This generates an annotation box positioned neatly to the left of myblock, connected via an arrow, and auto-incremented by default.

Annotation Customization

Annotations offer extensive customization through various keys:

Detailed Example

This example demonstrates advanced annotations featuring different styles and placements:

% 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,
]

Customizing Reference Tags

Annotations are automatically numbered by default, providing convenient referencing. To explicitly define a tag, use ref-tag:

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

Disabling Tags

To omit tags entirely, set disable-tag:

\nskAnnotate[
  disable-tag=true,
  text={Tagless annotation.},
  connect-to=myBlock.south,
]

Advanced Arrow Routing

Annotations support intricate arrow routing, beneficial in dense diagrams:

\nskAnnotate[
  connect-to=myBlock.north,
  connect-opts={
    arrow-style={dotted, thick},
    bend-route={single left},
    corner-radius=5mm
  },
  text={Clearly routed arrows improve readability.},
]

You can pass custom options to the connecting segments through the connect-opts key to define more advanced arrow routing behaviors. For more details, refer to the Routing System documentation.

Text Alignment

Ensure readability with the text-align property, ideal for multi-line annotations:

\nskAnnotate[
  text-align=justify,
  text={Justified alignment enhances readability, especially when the annotation spans multiple lines or includes detailed explanations.}
]

Best Practices

Practical Example

The following illustrates how annotations clarify layers in a neural network:

\begin{nskFigure}
  \nskBlock[id=input, text-center={Input Layer}]
  \nskBlock[last-pos={right=1.5cm}, id=hidden, text-center={Hidden Layer}]
  \nskBlock[last-pos={right=1.5cm}, id=output, text-center={Output Layer}]
 
  % Annotation for hidden layer
  \nskAnnotate[
    pos={above=2cm of hidden},
    connect-to=hidden.north,
    header={Hidden Layer},
    title={Feature Extraction},
    text={This layer transforms inputs into meaningful features through nonlinear activations.},
    rounded-box=true,
    border-color=nskBlue,
  ]
\end{nskFigure}

Reference