nsk@Annotate

Overview

The \nskAnnotate command elegantly provides precise textual annotations in diagrams generated with Neural Sketch, enabling authors to directly associate descriptive notes, remarks, or explanatory details with specific diagram elements.

This mechanism enhances visual storytelling and technical clarity, proving invaluable for producing clear, informative, and aesthetically pleasing publication-quality diagrams.

Basic Usage

The simplest invocation of \nskAnnotate inserts a basic annotation:

\nskAnnotate[text={Simple annotation}]

Comprehensive Example

Below is an advanced example illustrating how annotations connect to existing blocks, and are visually customized with headers, titles, and detailed content:

\begin{nskFigure}
  \nskBlock[id=myBlock, text-center={Target Block}]
 
  \nskAnnotate[
    header={Important},
    title={Annotation Example},
    text={This block represents a critical step in the algorithm.},
    connect-to=myBlock.east,
    pos={right=2cm of myBlock},
    rounded-box=true,
    border-color=nskBlue,
    fill=nskLightGray,
    text-color=nskDarkGray
  ]
\end{nskFigure}

Available Options

Textual Content

• header (string, default={}): Header text prominently displayed.
• title (string, default={}): Subheading or title for annotation.
• text (string, default={}): Main explanatory content.

\nskAnnotate[
  header={Note},
  title={Data Processing},
  text={This step filters out redundant data points.}
]

Positioning & Connections

• pos (coordinate, default={}): Relative positioning of the annotation.
• x, y (numbers, default=0): Absolute positioning fallback when pos is unspecified.
• connect-to (node.anchor, default={}): Specifies the diagram element to connect the annotation to.
• anchor-from (anchor, default=east): Anchor point from which the annotation connects.

\nskAnnotate[
  connect-to=myBlock.north,
  pos={above=1cm of myBlock}
]

Styling Options

• rounded-box (boolean, default=false): Enables rounded corners for the annotation box.
• fill (color, default=nskLightestGray): Background color of the annotation.
• border-color (color, default=nskMidGray): Border color of annotation.
• border-type (string, default=solid): Border style (solid, dashed, or none).
• border-size (dimension, default=0.4mm): Thickness of the annotation's border.
• border-radius (dimension, default=1mm): Curvature radius for corners.

\nskAnnotate[
  rounded-box=true,
  border-type=dashed,
  border-radius=2mm,
  border-color=nskMainAccent
]

Typography and Alignment

• text-align (choice, default=left): Text alignment (left, center, right, justify).
• header-style, title-style, text-style (string): Styling for individual textual components.
• text-color (color, default=c__nsk_principal): Color of annotation text.

\nskAnnotate[
  text-align=center,
  header-style={\bfseries},
  title-style={\itshape},
  text-style={\small},
  text-color=nskDarkGray
]

Advanced Customizations

• connect-opts (string): Custom connection styles passed directly to underlying TikZ connector.
• tikz-opts (string): Additional TikZ options applied directly.

\nskAnnotate[
  connect-opts={arrow-style={dotted,thick},color=nskBlue},
  tikz-opts={drop shadow}
]

Autoincrementing Reference Tags

Annotations automatically maintain an incremental numbering system unless explicitly provided through ref-tag. This helps maintain clear referencing across complex diagrams.

• ref-tag (string, default=auto-increment): Explicit custom reference tag.
• disable-tag (boolean, default=false): Disables automatic numbering tag.

\nskAnnotate[ref-tag=A1, disable-tag=false]

Internal Behavior

\nskAnnotate performs several internal actions to simplify your annotation tasks:

• Text Composition: Automatically formats annotation text combining header, title, and content, optionally preceded by an autoincremented reference number.
• Positioning Logic: Seamlessly determines placement either via relative positions (pos) or absolute (x, y) coordinates.
• Connector Generation: Draws annotated arrows to target nodes with customizable styling.

Common Use Cases

The versatility of \nskAnnotate supports a wide range of diagrammatic contexts:

• Algorithmic explanations: Clarify specific steps or elements.
• Neural network architectures: Detail individual layers or interactions.
• Flowcharts: Describe complex branching conditions.

Practical Tips

• Use consistent styling for annotations across diagrams to preserve uniformity.
• Utilize precise anchor points (east, west, north, south) for visual clarity.
• Leverage rich content formatting to enhance readability and professional aesthetics.

Reference Table