nsk@Group

Overview

The \nskGroup macro provides a powerful and intuitive way to logically group diagram components within Neural Sketch, facilitating advanced transformations such as rotation, scaling, and precise relative positioning. By wrapping elements in a cohesive group, users can effortlessly control collective styling and spatial arrangement, ensuring visual coherence in complex diagrams.

Basic Usage

The minimal syntax for grouping elements is:

\nskGroup[]{
  % diagram components here
}

Advanced Example

Below is a practical example demonstrating multiple grouped blocks with transformations:

\begin{nskFigure}
  \nskGroup[
    bounds-name=myGroup,
    pos={below right=2cm and 1cm of refBlock},
    rotate=15,
    scale=0.8,
  ]{
    \nskBlock[id=A, text-center={A}]
    \nskBlock[last-pos={right=1cm}, text-center={B}]
  }
\end{nskFigure}

Available Options

Positioning

• pos (coordinate, default={}): Specifies the group position relative to another element.

\nskGroup[pos={below right=1cm and 2cm of referenceNode}]{...}

• last-pos (coordinate, default={}): Sets the position relative to the previous block or group, simplifying chained positioning.

\nskGroup[last-pos={right=1.5cm}]{...}

Transformations

• rotate (number, default=0): Rotates the entire group around its center.

\nskGroup[rotate=45]{...}

• scale (number, default=1): Scales the group uniformly.

\nskGroup[scale=1.5]{...}

• shift-x, shift-y (number, default=0): Shifts the group horizontally or vertically.

\nskGroup[shift-x=2, shift-y=-1]{...}

Anchoring and Alignment

• pos-align (string, default={}): Explicitly defines the anchor alignment, overriding automatic detection.

\nskGroup[pos-align={north west}]{...}

Boundaries

• bounds-name (string, default=__nsk_container_bounds): Internally defines a local bounding box name for advanced referencing or later transformations.

\nskGroup[bounds-name=myCustomBounds]{...}

Internal Mechanics

Internally, \nskGroup:

• Generates a local bounding box, allowing precise relative positioning.
• Supports comprehensive alignment logic, automatically adjusting anchor positions based on provided directions.
• Allows forward compatibility with TikZ options by passing unrecognized keys directly to TikZ scopes.
• Automatically manages phantom reference nodes to ensure seamless positioning without visual artifacts.

Positioning Logic

Smart Anchor Detection

Neural Sketch analyzes your positioning directives and automatically determines suitable anchors:

• Example:

\nskGroup[pos={above right=0.5cm and 1cm of nodeA}]{...}

This automatically aligns the group's anchor appropriately (south-west by default in the above example) to facilitate precise positioning.

Last-Position Convenience

Quickly place groups relative to the preceding diagram element:

\nskGroup[last-pos={below=1cm}]{...}

Practical Use Cases

\nskGroup proves invaluable in scenarios such as:

• Composite elements: Bundling multiple blocks to form a logical sub-diagram.
• Rotated annotations: Grouping annotations or labels to rotate collectively, maintaining relative placements.
• Scalable components: Reusable diagram sections that adjust uniformly across different figures.

Advanced Tips

Combine transformations for sophisticated layout effects:

\nskGroup[rotate=30, scale=0.9, shift-x=1cm]{
  \nskBlock[fill=nskBlue, text-center={Rotated & Scaled}]
}

Error Handling and Troubleshooting

• Ensure coordinates and references are correctly defined.
• Explicitly define block identifiers to avoid confusion in chained positioning.
• Avoid overly complex nested transformations without clear intermediate steps.

Reference Table

Integrating \nskGroup into your workflow enhances flexibility and expressive power, empowering users to create sophisticated, publication-ready diagrams with ease and precision.