Positioning Mechanisms

Positioning is fundamental to crafting clear, accurate, and visually appealing diagrams. NeuralSketch provides robust, flexible, and intuitive positioning mechanisms designed for both straightforward and complex diagramming tasks.

Overview

NeuralSketch positions diagram elements using two primary methods:

• Absolute positioning: Explicitly define exact coordinates.
• Relative positioning: Place elements in relation to other diagram primitives, containers, groups, or blocks.

Each method supports nuanced control through additional positioning keys, allowing you to precisely adjust or align elements with minimal boilerplate.

Absolute Positioning

Absolute positioning allows you to define the exact coordinates for placing a primitive on the canvas. This method is ideal for scenarios requiring explicit spatial precision.

Basic Usage

Define absolute positions using the x and y keys, representing horizontal and vertical coordinates respectively:

\nskBlock[
  x = 3, y = 1.5,
  text-center = {Absolute Block},
]

Coordinate Shifting

After establishing an absolute position, you can apply additional fine-grained adjustments using shift-x and shift-y keys:

\nskBlock[
  x = 3,
  y = 1.5,
  shift-x = 0.5,
  shift-y = -0.25,
  text-center = {Shifted Block},
]

This moves the block horizontally to the right by 0.5 units and vertically downward by 0.25 units, relative to the specified coordinates.

Relative Positioning

Relative positioning aligns primitives with reference to other primitives by ID, significantly simplifying complex diagram layouts.

Using the pos Keyword

NeuralSketch’s pos key uses natural-language-inspired syntax, based on TikZ’s positioning library. This allows expressive, readable placements without numerical guesswork:

\nskBlock[id=ablock, text-center={Base Block}]
\nskBlock[
  id=bblock,
  pos = {above right = 1cm and 0.5cm of ablock},
  text-center = {Relative Block},
]

Here, the second block (bblock) is positioned exactly 1 cm above and 0.5 cm to the right of the first block (ablock).

Using the last-pos Keyword

When positioning a series of primitives sequentially, use the last-pos key to easily chain elements relative to the previously drawn primitive:

\nskBlock[text-center={First Block}]
\nskBlock[
  last-pos = {right = 1cm},
  text-center = {Second Block},
]
\nskBlock[
  last-pos = {below = 0.8cm},
  text-center = {Third Block},
]

This syntax intuitively chains the second and third blocks, significantly streamlining diagram creation and removing the need to manually declare or reference IDs.

Error Handling with last-pos

When employing loops or conditional logic, the previous primitive might not always exist. Using the standard last-pos would produce errors if no preceding primitive is defined. NeuralSketch elegantly handles this with the last-pos-s (safe) key.

Using last-pos-s

The last-pos-s key gracefully handles missing references by applying the position transformation only if a valid registered primitive exists

\foreach \i in {1,...,5}{
  \nskBlock[
    last-pos-s = {right=1cm},
    text-center = {Block \i},
  ]
}

On the first iteration, since no preceding block exists, the command simply has no effect. Subsequent blocks correctly position relative to their predecessors.

Custom Errors with last-pos

If you explicitly use last-pos and the referenced block does not exist, NeuralSketch will issue a custom error clearly indicating the missing or invalid index, aiding debugging.

Intelligent Alignment

NeuralSketch intelligently infers alignment intentions, simplifying diagrams that rely heavily on aligned elements.

For example, horizontally aligning adjacent blocks does not require explicit anchors—NeuralSketch automatically chooses appropriate edges:

\nskBlock[id=A, text-center={Block A}]
\nskBlock[
  pos = {right=1cm of A},
  text-center = {Block B},
]

In this scenario, NeuralSketch aligns the left edge of Block B with the right edge of Block A, automatically interpreting your intent without needing explicit anchors.

Combining Positioning with Containers and Groups

Positioning mechanisms extend naturally to containers and groups, allowing cohesive positioning and transformation of composite diagram components.

Containers

Containers wrap multiple primitives, allowing global transformations alongside internal relative positioning while providing handy stylings:

\nskContainer[shift-x=2, shift-y=1, fill=nskLightGray]{
  \nskBlock[x=0, y=0, text-center={Inside Container}]
  \nskBlock[last-pos={right=1cm}, text-center={Relative Inside Container}]
}

This container moves as a unit, while blocks inside maintain local relative positioning.

Groups

Groups logically cluster primitives, making collective transformations (e.g., rotation or scaling) straightforward while maintaining local positional consistency:

\nskGroup[rotate=45]{
  \nskBlock[x=0, y=0, fill=nskMainAccent, text-center={Rotated A}]
  \nskBlock[pos={right=2cm of Rotated A}, fill=nskSecondaryAccent, text-center={Rotated B}]
}

Both blocks rotate cohesively, preserving their relative positions within the transformed group.

Best Practices

• Absolute positioning is ideal for single, fixed, or foundational elements.
• Relative positioning reduces redundancy and complexity in interconnected or iterative diagrams.
• Use last-pos-s within loops or uncertain contexts to avoid unnecessary errors gracefully.
• Use NeuralSketch’s intelligent alignment for cleaner, simpler code.