We are in early beta, and may not have tested Walnut in your browser/OS combination yet, so it may not look perfect. Thanks for your patience! ×
We are in early beta, and the documentation may be incomplete and/or have missing links. Thanks for your patience! ×

Visualization definition reference

The Walnut visualization language provides a way to declaratively describe visual representations of traces.

It follows a syntax heavily based in the Walnut Core Language

visualization ::= component*
component ::= kind [comprehension] "{" argument* component* "}"
kind ::= "text"
     |   "grid"
     |   "layer" NAME
     |   "cell"
     |   "sprite"
     | "polyline"

Essentially, a visualization is a collection of component descriptions. Each component is some sort of graphical object (a text label, a bitmap, etc.) and contains several attributes that define their visual properties (size, color, font, etc); those attributes are set to expressions that can depend on the trace. Components can be nested into one another, and some geometric properties (position and size) are relative to the parent. It is possible to define a variable number of components that depend on trace information.

Attribute expressions are evaluated in a context that extends the agent context (for the agent currently acting/perceiving) with some additional information:

If an attribute expression fails to evaluate, you'll see a warning displayed, and the attribute will not be set, but other components will be displayed unaffected.

When defining a component with a comprehension, an item will be included for each element in the source list that satisfies the condition. The context for all attribute expresssions inside will be modified by the pattern match.

Component Nesting and Geometry

Each component defines a coordinate system, which is used to place its children. The component attributes defining position and size use this coordinate system.

The whole canvas has a base coordinate system that is used to place top-level components. This coordinate canvas is centered in (0, 0), and measures 1×1 .This means that the upper left coordinate is at (-0.5, -0.5) and the lower right at (+0.5, +0.5).

Most components have a similar coordinate system, with (0,0) at their center, and size 1 × 1. Components of grid type have cells with size 1×1, and the (0,0) is the center of the upper left cell. For example a grid 8 cells wide a 5 cells tall has a coordinate system where the grid has 8×5 units, the top-left corner fo the grid is at (-0.5, -0.5), and the lower right corner is at (7.5, 4.5). Note that integer coordinates are always cell centers.

Generic Component Properties

Some attributes are present in every component. Each attribute is described with its type and meaning.

  • x: Number. Default: 0. Column or x-axis position of this component relative to its parent coordinate system. Can be overwritten by h_align.
  • y: Number. Default: 0. Row or y-axis position of this component relative to its parent coordinate system. Can be overwritten by v_align.
  • position: {x: Number, y: Number}. Optional. If given, sets the x and y attributes; it is not allowed to specify both position and x or y. You can also use any custom value with x and y fields here, including Point.
  • width: Number. Default: 1. Width of this component measured on its parent coordinate system.
  • height: Number. Default: 1. Height of this component measured on its parent coordinate system.
  • h_align: Number. This is an alternative way of specifying x. It should be a value between 0 and 1, and it measures the balance of empty space at the left and at the right with respect to the parent. 0 means left aligned, 0.5 is centered, 1 is right aligned. Overwrites the x attribute.
  • v_align: Number. This is an alternative way of specifying y. It should be a value between 0 and 1, and it measures the balance of empty space at the top and at the bottom with respect to the parent. 0 means top aligned, 0.5 is centered, 1 is bottom aligned. Overwrites the y attribute.
  • color: String. Default: "black". A color name or code. Component's fill or background color. See the [colors] section for details
  • background_color: String. Alias for color.
  • opacity: Number. Default: 1. Opacity of the component and its children. 1 means opaque, 0 means completely transparent.
  • rotation: Number. Default: 0. Rotation of the component in degrees.
  • visible: Boolean. Default: True. States whether this component (and its children) must be rendered or not. False means that it is not rendered.

Bordered Component Properties

Some components are considered “bordered” and share a set of attributes related to border drawing. Currently only the grid and cell components are considered bordered.

A bordered component has four borders: top, left, bottom and right. Each border, if visible, has two properties: width and color.

The component attributes allow to specify properties for each border independently. Also, shortcut attributes are provided to set many values together. More specific attributes overwrite the more general ones. It does not matter the order in which they are specified. So, if the following attributes are set:

border_top_width = 1
border_color = "red"
border = [3, "black"]

Then the component will have:

  • 4 visible borders,
  • all borders are red
  • all but the top-border have width 3
  • the top-border has width 1

By default, all borders are visible, of width 1 and with color black.

Bordered components have the following attributes

  • border: [?]. If given, set all the borders width with the first element (which must be a Number) and all the borders color to the second element (which must be a String).
  • border_visible: Boolean. If given, set all the borders visibility property.
  • border_width: Number. If given, set all the borders width property.
  • border_color: String. If given, set all the borders color property.
  • border_top_visible: Boolean.
  • border_top_width: Number.
  • border_top_color: String.
  • border_right_visible: Boolean.
  • border_right_width: Number.
  • border_right_color: String.
  • border_bottom_visible: Boolean.
  • border_bottom_width: Number.
  • border_bottom_color: String.
  • border_left_visible: Boolean.
  • border_left_width: Number.
  • border_left_color: String.

grid

A grid is a bordered component to display a rectangular grid. The grid is positioned through its central point.

The only required, user-defined attribute is the dimension, which is a pair with the number of columns and rows. All the other attributes, inherited or specific, have reasonable default values.

Grid components define a coordinate system for its children with the origin centered in the top-left row, and the unit in each dimension equal to the size of the cell

Attributes:
  • dimension: [Number, Number]. Required. The number of columns and rows.
  • inner_lines_visible: Boolean. Default: True. If True, the grid's inner lines (between cells) are visible.
  • inner_lines_width: Number. Default: 1.0. The width of the grid's inner lines.
  • inner_lines_color: String. Default: "black". The color of the grid's inner lines.

cell

Represents a set of cells within a grid, and usually has a grid as its parent. All attribute expressions (direct and from children) are evaluated in a context that has a position attribute (of Point type) including the position of the cell.

Note that a single cell component controls a display of every cell in its parent component (the 1×1 blocks centered on integer coordinates). Whatever display attributes you set and children that you add will be repeated as many times as cells there are in the parent, although each cell will be computed with a different position value.

grid {
    dimension = [3,3]
    inner_lines_visible = False
    cell {
        color = "red"
        visible = position.y == 2
    }
}

In this case, the grid has no visible internal divisions and the cells in the bottom row are red, with visible borders.

A cell has all the attributes of a bordered component. Note that you can not set a cell position, width or height, they are automatically set.

Cell components define a coordinate system for its children with the origin centered in their center, and the whole cell measuring 1×1.

text

A text component displays lines of text. If the string has \n characters inside the string may be multiline; also you can set the word_wrap attribute to True and word_wrap_width to a value greater than 0 to cut lines at a certain width. Text is positioned by its center point.

Besides the base component attributes, a text component has the following attributes:

Attributes:
  • label: String. Required. The text to display.
  • font: String. Default: "bold 20px Arial". The style and size of the font.
  • color: String. Default: "black". A color code for the text.
  • align: String. Default: "left". Alignment of lines with respect to each other("left", "center" or "right"), does not affect single line text.
  • word_wrap: Boolean. Default: False. Indicates if word wrap should be used.
  • word_wrap_width: Number. Default: 100. The width at which text will wrap, it needs word_wrap to be set to True. Note that this is measured in pixels relative to the font size.

A text component has no default width and height value, but will instead compute its size based on the string and font size. If you set a explicit width or height, the text box will then be scaled to fit the requested area.

Text components define a coordinate system for its children with the origin centered in their center, and the whole text label measuring 1×1.

sprite

A sprite component loads an image from a given URL and displays it.

Attributes:
  • image: String. Required. An image's URL.
  • anchor: [Number, Number]. Default: [0, 0]. Origin point of the sprite, which is the point that will go at position x, y at the parent. The default (0,0) means the sprite's origin is the center. An anchor of [0.5, 0.5] means the origin is the bottom right. Setting the anchor to [-0.5, -0.5] would mean the sprite's origin points will be the upper left corner.
  • rotation: Number. Default: 0. Degrees to rotate the sprite, around the anchor point. Positive value means clockwise.

Sprite components define a coordinate system for its children with the origin centered in their anchor, and the whole sprite measuring 1×1.

polyline

A polyline component shows a segmented line.

Attributes:
  • points: [Point]. Required. A list of points (values with x and y labeled fields).
  • color: String. Default: "black". The line's color.
  • line_width: Number. Default: 3. The line's width.

Polyline components define a coordinate system for its children with the origin centered in the center of tis rectangular bounding box, and the whole bounding box measuring 1×1.

layer

A layer does not display anything, but it just acts as an invisible container to group other components. A layer has a label.

layers are used to modify a set of related components, typically hide/show (with the visible attribute) and apply transparency (opacity attribute). Layers can also be manipulated through the user interface by its label. If many layers share the same label, the user will manipulate every layer with the same label as a single element.

Layers inherit the coordinate system of their parents, do not define their own. Their positioning and size attribtues are ignored.

Colors

Many attributes return a string with a color representation. The string must follow a set of rules to be valid"

If R, G, B and A represents an hex value ([0 .. F]) for the red, green, blue, and alpha (opacity) properties, then valid values for color attributes are the following Strings:

  • "#RRGGBBAA": A color with the given red, green, blue, and alpha values.
  • "#RGB" (equals "#RRGGBBFF"),
  • "#RGBA" (equals "#RRGGBBAA"),
  • "#RRGGBB" (equals "#RRGGBBFF"),
  • One of the following color names: "transparent, aqua,  aliceblue,  antiquewhite, black, blue, cyan, darkblue, darkcyan, darkgreen, darkturquoise, deepskyblue, green, lime, mediumblue, mediumspringgreen, navy, springgreen, teal, midnightblue, dodgerblue, lightseagreen, forestgreen, seagreen, darkslategray, darkslategrey, limegreen, mediumseagreen, turquoise, royalblue, steelblue, darkslateblue, mediumturquoise, indigo, darkolivegreen, cadetblue, cornflowerblue, mediumaquamarine, dimgray, dimgrey, slateblue, olivedrab, slategray, slategrey, lightslategray, lightslategrey, mediumslateblue, lawngreen, aquamarine, chartreuse, gray, grey, maroon, olive, purple, lightskyblue, skyblue, blueviolet, darkmagenta, darkred, saddlebrown, darkseagreen, lightgreen, mediumpurple, darkviolet, palegreen, darkorchid, yellowgreen, sienna, brown, darkgray, darkgrey, greenyellow, lightblue, paleturquoise, lightsteelblue, powderblue, firebrick, darkgoldenrod, mediumorchid, rosybrown, darkkhaki, silver, mediumvioletred, indianred, peru, chocolate, tan, lightgray, lightgrey, thistle, goldenrod, orchid, palevioletred, crimson, gainsboro, plum, burlywood, lightcyan, lavender, darksalmon, palegoldenrod, violet, azure, honeydew, khaki, lightcoral, sandybrown, beige, mintcream, wheat, whitesmoke, ghostwhite, lightgoldenrodyellow, linen, salmon, oldlace, bisque, blanchedalmond, coral, cornsilk, darkorange, deeppink, floralwhite, fuchsia, gold, hotpink, ivory, lavenderblush, lemonchiffon, lightpink, lightsalmon, lightyellow, magenta, mistyrose, moccasin, navajowhite, orange, orangered, papayawhip, peachpuff, pink, red, seashell, snow, tomato, white, yellow, rebeccapurple"

Visualization built-ins

The visualization language has some additional built-ins in addition to the ones defined in the core language. Most of them help with color manipulation

  • gradient: Build a color following a gradient.
  • hsl: Build color strings for numeric values for HSL components
  • hsla: Build color strings for numeric values for HSLA components
  • rgb: Build color strings for numeric values for RGB components
  • rgba: Build color strings for numeric values for RGBA components

gradient

Type: gradient(String, Number)

Returns a step into a gradient. The Number should be between 0 and 1, and the String is one of the available gradient names. This function is useful to map continuous values to color representations

Available gradient names are:

  • rgb: starts at red, goes to green, then to blue
  • grayscale: goes from black to white.
  • hot: starts at dark red, goes to strong red, then yellow, then white.
  • red: starts at red, goes to white.
  • green: starts at green, goes to white.
  • blue: starts at blue, goes to white.

hsl

Type: hsl(Number, Number, Number)

Build an opaque color based on arguments which are hue, saturation, and luminance. All values must be between 0.0 and 1.0

hsla

Type: hsla(Number, Number, Number, Number)

Build a color based on arguments which are hue, saturation, luminance, and alpha. All values must be between 0.0 and 1.0

rgb

Type: rgb(Number, Number, Number)

Build an opaque color based on arguments which are red, green and blue components. All values must be between 0.0 and 1.0

rgba

Type: rgba(Number, Number, Number, Number)

Build a color based on arguments which are red, green, blue, and alpha components. All values must be between 0.0 and 1.0