Pikchr

Pikchr is supported across various platforms and tools:

• Web/Online: Use the online editor to enter Pikchr text and see results immediately.
• Documentation Tools:
  • mdbook-pikchr: A pikchr-aware preprocessor for mdBook.
  • pandoc: A Lua-based pikchr filter is available.
  • kroki.io: Integrated into the Kroki diagram-rendering service.
• IDEs and Editors:
  • IntelliJ-based IDEs: Support via IntelliPikchr.
  • Obsidian: Support via Adamantine Pick.
• Runtimes:
  • Go: gopikchr.
  • Node.js: pikchr module.
• CLI: pikchr-cmd is a command-line preprocessor tool for use with any Markdown formatter.

A place is a specific, named point on an object. While a position refers to any arbitrary X,Y coordinate, a place is a predefined anchor point on an existing object (like a box, ellipse, or line).

You can refer to a place using several syntaxes:

• object (refers to the center of the object)
• object.dot-edgename (e.g., B.n for the north point of object B)
• edgename of object (e.g., north of B)
• ORDINAL vertex of object (e.g., 1st vertex of B, used for line objects)

Most places lie on the object's boundary, but special places like .center or .c are located in the middle. For line objects, .start and .end may reside in the interior.

By default, text annotations are anchored to the center of an object's bounding box. For multi-segment lines (like complex arrows), this center might be far from the actual path.

To position text beside a specific segment of a multi-segment line, create an invisible line (line invis) that overlays that specific segment and attach the text to that invisible line instead.

# Overlaying an invisible line to anchor text to a specific segment
line invis from 2nd vertex of last arrow to 3rd vertex of last arrow \
    "text" below aligned

Pikchr uses four primary numeric properties to control the size and appearance of objects. Most other property names are simply aliases for these four:

• width (alias: wid): The horizontal size of most objects.
• height (alias: ht): The vertical size of most objects.
• radius (alias: rad): Used to set the size of circles, cylinders, files, and corner rounding.
• thickness: The width of lines used to draw objects.

Note: diameter is an alias for twice the radius.

If you omit the at attribute, Pikchr automatically positions the object using the rule: with .start at previous.end. (The first object in a script is positioned with .c at (0,0)).

Every object has 9 standard anchor points:

• Compass directions: .n, .ne, .e, .se, .s, .sw, .w, .nw
• Center: .c

Additionally, every object has .start and .end anchor points. The physical location of .start and .end depends on the current layout direction:

Pikchr supports nested macros up to a maximum depth (currently 10).

When passing arguments to a nested macro, you must follow one of two rules:

1. Pass arbitrary text as arguments.
2. Pass a single $N parameter.

You cannot mix arbitrary text and a $N parameter in the same argument list for a nested macro call.

The previous qualifier allows you to refer to the most recently created object of the same type. This is useful for aligning objects or calculating dimensions relative to the last element added.

Note: If you insert a new object of a different type between two objects, previous still refers to the last object of the same type. If you insert a new object of the same type, previous will point to the new one. To avoid broken references when inserting objects, assign an explicit name to your objects and use that name instead of previous.

Example: box same width previous.e.x - C2.w.x uses the eastern edge (.e.x) of the previous box to calculate the new width.

The specific locations of .start and .end depend on the object's layout direction. For block objects, the mapping is as follows:

For line objects:

• .start always refers to the first vertex of the line.
• .end is usually the last vertex. However, if the close keyword is used, .end behaves like a block object's end point (e.g., .e in 'right' direction) rather than the final vertex.

By default, Pikchr draws objects in the order they appear in the input script. The behind object attribute allows you to override this behavior, causing the object currently being constructed to be drawn before the referenced object.

This is particularly useful for creating background effects. For example, if you define your primary content boxes first and then define large background-colored boxes later in the script, you can use behind [content_box] to ensure the background box is rendered underneath the content rather than covering it up.

# Example pattern:
box "Content" wid 100 ht 100

# This box will be drawn first because of the 'behind' attribute,
# appearing underneath the "Content" box.
box wid 150 ht 150 fill 0xcccccc behind "Content"

Unlike legacy PIC which uses only inches, Pikchr allows you to attach unit designators to numeric literals. This makes expressing distances more intuitive. Note that units must be attached directly to the number without whitespace (e.g., 2.3cm, not 2.3 cm). Internally, Pikchr still performs all calculations in inches.

Supported units:

• cm: centimeters
• in: inches (default)
• mm: millimeters
• pc: picas
• pt: points
• px: pixels