Tile template format

Overview ¶

The tile view system was created to display various types of information for the render stats. The look and layout of the tiles is defined by a JSON template file.

The tile system is new and experimental, and lacks many desirable features, but it allows for some useful customization.

Each tile has a set of properties that control it’s look and contents. For render stats, you can map properties to JSONpaths, so the property is set according to information in the render stats. This is how you populate the template based on the stats from a rendered image.

For examples of tile templates, see $HFS/houdini/config/render_stats_toolbar.json (the template for the render stats sidebar) and $HFS/houdini/config/render_stats_overlay.json (the template for the render stats overlay utility).

Tip

This document uses JSON terminology, such as “array” for a list of values, and “object” for a key-value map.

Structure ¶

Tiles in the template are represented by JSON objects.

The simplest template is just a default tile:

{}

If an object doesn’t have a type key, it defaults to a text tile.

{
    "text": "If you <i>really</i> don't want to say a type, you don't have to"
}

The type key specifies the tile type.

{
    "type": "number",
    "value": 123.5
}

You can use the common properties and the tile type’s specific properties to change the look of the tile.

{
    "type": "number",
    "label": "Number",
    "value": 123.5,
    "text_size": "xlarge"
}

You usually want to display more than one tile, so the top-level tile will be a container tile, which lays out its sub-tiles.

{
    "type": "matrix",
    "margins": 20,
    "min_column_width": 80,
    "row_height": 60,
    "items": [
        {
            "type": "text",
            "label": "Text",
            "value": "Hello",
            "text_size": "xlarge"
        },
        {
            "type": "number",
            "label": "Number",
            "value": 123.5,
            "text_size": "xlarge"
        }
    ]
}

Pulling values from the render stats with JSONpaths ¶

To populate the tiles with information from the render stats, you map property names to JSONpaths. The tile system uses the JSONpaths to find information in the stats, and if they match, updates the corresponding properties.

Tip

To see the JSON data used by the render stats system, run iinfo -J ‹file› on an EXR file in a Houdini shell.

Mapping properties to JSONpaths ¶

Important

JSONpath is more of a collection of similar syntaxes than an actual standard. Currently the tile system uses jsonpath_ng with its extensions turned on. See the jsonpath_ng documentation to learn its syntax.

To associate JSONpaths with properties, set the properties key on a tile to an object, where the object’s keys are property names, and the values are JSONpath strings, for example:

{
    "type": "duration",
    "label": "Elapsed",
    "properties": {
        "value": "husk.system_time.wallclock"
    }
}

As a shortcut, setting the json_path key on a tile lets you specify a JSONpath for the tile’s value property (tiles that display a single piece of information usually have a value property). This is equivalent to the JSON above:

{
    "type": "duration",
    "label": "Elapsed",
    "text_size": "large",
    "json_path": "husk.system_time.wallclock"
}

You can also specify a JSONpath as a JSON object instead of a string. This lets you set a few options. The object can have the following keys:

path

string

The JSONpath string (required)

all

boolean

Technically, a JSONpath can match multiple places in the data, and always returns a list of matches. However, this is usually not what you want, and makes handling the results cumbersome. So, by default, we use the first match as the “value” of the JSONpath.

If you really need to get all the matches, set this to true.

Default is false.

default

any

If the JSONpath doesn’t match, use this as the value.

Note

If all is true, default is not used (if all is on and a JSONpath doesn’t match, it just returns an empty list).

Python expressions ¶

JSON path is useful for extracting values out of JSON, but if you need to manipulate the value, or want to show different things depending on the data, JSONpath is not very powerful. When you need more, the tile system lets you compute the values of properties using Python expressions.

A Python expression that always evaluated to the same value would not be very useful. We want the Python expression to take input from the data, and compute the property value from that. You define the

To set up variables you can use in your Python expressions, set the variables key on a tile to an object, where the object’s keys are variable names, and the values are JSONpath strings, for example:

{
    "type": "number",
    "variables": {
        "engine": "husk.render_settings.engine",
    }
}

In the properties, if the property name ends in .py, it is treated as a Python expression, rather than a JSONpath. The expression can use the variables defined in the variables object. For example, this sets the tile’s value property to the result of evaluating an expression:

{
    "type": "number",
    "variables": {
        "engine": "husk.render_settings.engine",
        "pixelsamples": "husk.render_settings.samplesperpixel",
        "pathsamples": "husk.render_settings.pathtracedsamples"
    },
    "properties": {
        "value.py": "pixelsamples if engine == 'cpu' else pathsamples"
    }
}

You can also use ‹name›.py expressions in the variables. This lets you compute the value of a variable from an expression.

For example, in the default render stats, for the number of samples, we want to show the “path samples” setting if the render engine is XPU, or if the convergence mode was “Path Traced”. And we want to set both the label and value differently based on that. Instead of duplicating the code the code to compute the mode for both the label and value, we set the use_path variable using a Python expression

{
    "type": "number",
    "text_size": "large",
    "variables": {
        "engine": "husk.render_settings.engine",
        "mode": "husk.render_settings.convergence_mode",
        "pixelsamples": "husk.render_settings.samplesperpixel",
        "pathsamples": "husk.render_settings.pathtracedsamples",
        "use_path.py": "engine == 'xpu' or mode == 'Path Traced'"
    },
    "properties": {
        "label.py": "'Path Samples' if use_path else 'Pixel Samples'",
        "value.py": "pathsamples if use_path else pixelsamples"
    }
}

For each tile, the system computes values in the following order:

The system computes the variables defined by JSONpaths.
The system computes the variables defined by Python expressions. The Python expressions can use variables from the previous step.
The system computes properties. Python expressions in the properties can use variables from the previous steps.

JSONpath helpers ¶

The JSON stats data available during an interactive render (as in the render stats sidebar) and the data from an EXR file (as in the render stats overlay) have a different shape (the JSON data provided for an interactive render is the equivalent of aovs[0].metadata.'husk:render_stats' in EXR data). The stats system provides some top-level keys in the data to make it easier to work with both.

If you are customizing interactive stats (the render stats sidebar), you should only use paths starting with husk.

`aovs`	In stats from an EXR file, this is the list of AOV data. In interactive stats, this key does not exist.
`md`	In stats from an EXR file, this is the `metadata` object of the first AOV. (This is the “arbitrary” key-value metadata that the image creator embedded in the image. The other keys are in the JSON are intrinsic data about the image.) In interactive stats, this key does not exist.
`husk`	In stats from an EXR file, this is the `husk:render_stats` object in the first AOV’s metadata. In interactive stats, these are the only stats available.

Testing your template ¶

You can make a simple shelf tool that looks and displays a tile template file, so you can check if it works and how it looks.

Create the template file you want to view.
If you want to test JSONpaths, you should also have a rendered EXR file to load stats from.

Create a new shelf tool with the following script. Remember to replace /path/to/template.json and /path/to/image.exr in the script below with the actual paths to your files.

from PySide2 import QtWidgets
import hou
from hutil.qt.data import tiles

class TestWindow(QtWidgets.QMainWindow):
    def __init__(self, parent: QtWidgets.QWidget = None):
        parent = parent or hou.qt.mainWindow()
        super().__init__(parent)
        view = tiles.StatsViewer(self)
        self.setCentralWidget(view)

        # The template file you want to load and view
        view.loadTemplate("/path/to/template.json")
        # This is optional: fill in the template with data from an image
        view.loadStatsFromImage("/path/to/image.exr")

        self.resize(640, 480)

hou.session.w = TestWindow()
hou.session.w.show()

Any time you change and save your template you can click the shelf tool in Houdini to re-read and show the template in a window.

Note

The script above uses internal Houdini Python modules. This script is provided as a helper for this specific purpose, and you should not otherwise use or rely on these internal modules. SideFX reserves the right to change, rename, or remove them at any time.

Tips and notes ¶

In this document, where it says a number is specified “in pixels”, the actual size of the item on screen will be affected by the global UI scale and any view zoom/scale.

By default, most “container” tiles have their label and background turned off, so you only see the contained tiles, not the container itself.

You can create complex compound tiles by doing the turning a container’s label and/or background on, and turning them off on the sub-tiles, so the sub-tiles look like information displayed on the “parent” tile.

In this example, we show the background on the parent tile, and hide the backgrounds of the sub-tiles, to create the look of a single tile containing multiple bits of data.

{
    "type": "grid",
    "col_width": 60,
    "bg_visible": true,
    "label": "Record",
    "items": [
        {
            "type": "number",
            "value": 20,
            "text_size": "xlarge",
            "label": "Wins",
            "label_edge": "bottom",
            "bg_visible": false
        },
        {
            "type": "number",
            "value": 5,
            "text_size": "xlarge",
            "label": "Losses",
            "label_edge": "bottom",
            "bg_visible": false
        },
        {
            "type": "number",
            "value": 1,
            "text_size": "xlarge",
            "label": "Ties",
            "label_edge": "bottom",
            "bg_visible": false
        }
    ]
}

You can give the content of a tile a subtle “glow” by setting the content shadow to a bright color and the shadow offset to 0,0. You could then set the content_shadow_visible property based on data so, for example, a number “glows” when it’s higher than a certain threshold.
{ "label": "Glowing Value", "text": "100", "text_size": "xlarge", "content_shadow_visible": true, "content_shadow_offset": [0, 0], "content_shadow_color": "#ffff80", "content_shadow_blur": 20.0 }

Common tile properties ¶

`name`	string	The internal name of the tile. This is mostly useful as a comment, and for debugging.
`visible`	boolean	Whether this tile is shown. You can set this with a jsonpath or Python expression to show or hide different tiles depending on the data. Tiles that are not visible are removed from the parent container’s layout.
`text_color`	color	The value color (for text and number display tiles).
`bg_visible`	boolean	Whether to draw the tile’s background.
`bg_color`	color	The fill color of the tile background.
`margins`	margins	How much space to add between the tile content and the tile boundary, in pixels.
`left_margin`	number	Shortcut for setting the left margin.
`top_margin`	number	Shortcut for setting the top margin.
`right_margin`	number	Shortcut for setting the right margin.
`bottom_margin`	number	Shortcut for setting the bottom margin.
`label`	string	The tile’s label text.
`label_visible`	boolean	Whether to show the label.
`label_size`	text_size	The font size of the label text.
`label_color`	color	The label text color.
`label_bg`	brush	The fill color for the label background.
`label_bg_visible`	boolean	Whether to draw the label background.
`label_edge`	edge	Which edge of the tile to position the label on.
`label_align`	alignment	How to position the label within its area.
`label_margins`	margins	How much space to add around the label text, in pixels.
`overlay_label`	boolean	If this is `true`, the tile label is overlayed on the content, instead of having its own reserved space.
`corner_radius`	number	The amount of rounding of corners of the tile background, in pixels. Set this to `0` to get square corners.
`scale`	number	Scales the tile by this multiplier.
`rotation`	number	Rotation of the tile, in degrees.
`blur`	number	How much to blur the tile (default is `0`). This is the radius (in pixels) of a gaussian blur applied to the tile’s graphic. See also `content_blur` below.
`content_blur`	number	Like `blur`, but only applies to the tile contents, not the entire tile.
`shadow_visible`	boolean	Whether to draw a shadow below the tile. The shadow is applied to the tile’s pixels. If the tile background is visible (`bg_visible` is `true`), the background will cast the shadow. if the tile background is hidden (`bg_visible` is `false`), everything in the tile will cast the shadow. See also `content_shadow_visible` below.
`shadow_color`	color	The color of the tile shadow. The default is black.
`shadow_blur`	number	The blur radius of the tile shadow.
`shadow_offset`	array of two numbers	Sets the horizontal and vertical offset of the tile shadow.
`shadow_offset_x`	number	The horizontal offset of the tile shadow.
`shadow_offset_y`	number	The vertical offset of the tile shadow.
`content_shadow_visible`	boolean	Like `shadow_visible`, but only applies to the tile contents, not the tile label or background.
`content_shadow_color`	color	The color of the content shadow.
`content_shadow_blur`	number	The blur radius of the content shadow.
`shadow_offset`	array of two numbers	Sets the horizontal and vertical offset of the content shadow.
`content_shadow_offset_x`	number	The horizontal offset of the content shadow.
`content_shadow_offset_y`	number	The vertical offset of the content shadow.
`label_line_width`	number	The pen width (in pixels) of a line drawn between the label and the content. If this is `0` (the default), the line is not drawn.
`label_line_color`	color	The color of the label line.
`min_width`	number	Sets the minimum width of the tile, in pixels.
`fixed_height`	number	Sets the height of the tile to a fixed size, in pixels.

Styling ¶

The current tile system does not have great support for common styles, re-use of templates and styles, cascading styles, theming, or color schemes. Future versions will hopefully improve on this.

The tile system currently supports the following keys:

`styles`	object mapping strings to style property maps	(On container tiles) Associates names with “style” objects (objects mapping property names to values). These “styles” are available to any descendant tiles.
`style`	string	Applies the named style to this tile, assuming it’s defined on an ancestor tile.
`item_style`	string	(On container tiles) sets the default style for any child tiles that don’t have their own `style` property.

Currently this only allows a tile to have one “style” at a time.

For example, you can define some common styles on the root tile with the styles key, and then apply those styles to individual tiles with the style key:

{
    "type": "matrix",
    "min_column_width": 80,
    "row_height": 60,
    "styles": {
        "simple": {
            "bg_visible": false,
            "text_size": "xlarge"
        },
        "ok": {
            "bg_color": "#405040",
            "text_size": "xlarge"
        },
        "warn": {
            "label_bg": "#505030",
            "label_color": "#ffff00",
            "text_size": "xlarge"
        }
    },
    "items": [
        {
            "label": "Warning",
            "style": "warn",
            "text": "Not Found"
        },
        {
            "label": "Generic",
            "style": "simple",
            "text": "Hello"
        },
        {
            "label": "Good News",
            "style": "ok",
            "text": "Finished"
        }
    ]
}

Tile types ¶

Text ¶

Displays HTML/text.

{
    "type": "text",
    "label": "Text",
    "text": "Text Tile",
    "text_size": "xlarge"
}

`type`	string	`text`
`text`	string	The text to display in the tile.
`value`	string	This is an alias for `text`.
`text_alignment`	alignment	The alignment of the text.
`text_size`	text size	Font size.
`text_weight`	font weight	The font weight to use for the text.
`text_family`	string	Font family to use for the text.
`value_map`	object mapping string to string	If the text matches one of the keys in the object, it is changed to the corresponding value. This is sometimes useful to “rewrite” strings, for example taken from render stats, into more readable terms. For example, if the sometimes displays the value `"unk"`, you could rewrite that into `"Unknown"` like this: { "name": "source", "type": "text", "json_path": "husk.example.source", "value_map": { "unk": "Unkown" } }

Number ¶

Formats a numeric value as text using a configurable formatter. The number tile is a subclass of text and supports the same properties.

{
    "type": "number",
    "label": "Number",
    "value": 123456,
    "brief": true,
    "text_size": "xlarge"
}

`type`	string	`number`
`value`	number	The number to display. This value is converted into display text by the formatter.
`formatter`	formatter	Controls how the tile displays numbers. See how to set the formatter.
`brief`	string	When to display numbers in abbreviated units. One of `"always"`, `"never"`, or `"auto"`. The default is `"auto"`. This is a shortcut to set the formatter’s brief mode.
`decimal_places`	number	The number of decimal places to round to. This is a shortcut to set the formatter’s decimal places.

Chart ¶

Displays a number or numbers as a chart.

{
    "type": "chart",
    "label": "Chart",
    "chart": {
        "type": "stacked_donut"
    },
    "values": [1, 3, 2]
}

`type`	string	`chart`
`chart`	chart	The type of chart to display.
`monochrome`	boolean	Sets the chart’s `monochrome` property.
`value`	number or array of number	The number, or numbers, to display in chart form.
`values`	array of number	Alias of `value`.
`total`	number	Sets the chart’s `total` property.
`text`	string	Overlays the given text on the chart.
`formatter`	formatter	Controls how the tile displays numbers (when `auto_text` is `true`). See how to set the formatter.
`number`	number	Like `text`, but converts the number to text using the tile’s formatter.
`auto_text`	boolean	When this is `true`, when `value` is set to a number, that number is automatically formatted and displayed over the chart, as if you had set the tile’s `number` property.

Duration ¶

Displays a number of seconds (such as elapsed time or remaining time) as hours, minutes, and seconds. This is a subclass of the number tile, and supports the same properties.

{
    "type": "duration",
    "label": "Duration",
    "value": 58327,
    "text_size": "xlarge"
}

type

string

duration

value

number

The number of seconds in the duration.

long

boolean

When this is true, the tile always displays hours, minutes, and seconds in 00:00:00.0 format. When it is false, the tile only displays the needed units, and if the duration is less than a minute, displays seconds like 32.5s.

Estimated time remaining ¶

This is a subclass of the duration tile, and supports the same properties.

Given an elapsed time in seconds, and percent complete, displays the estimated time remaining. If the percent/fraction complete is not set or is 0, the tile displays a question mark. (You can do the same thing yourself in a duration tile using a Python expression, but this is provided as a convenience.)

`type`	string	`est_remaining`
`percent_complete`	number	Percent complete as a number from 0.0 to 100.0.
`fraction_complete`	number	Fraction complete as a number from 0.0 to 1.0.
`value`	number	The elapsed time, in seconds.

Path ¶

The tile is a subclass of text and supports the same properties.

It formats the text specifically as a file path. Currently this tile just displays the last component of the path (the filename) in bold.

{
    "type": "path",
    "label": "Path",
    "value": "/foo/bar/baz",
    "text_size": "large",
    "filename_weight": 900
}

`type`	string	`path`
`value`	string	The path string to format.
`filename_weight`	font weight	The font weight to use for the last segment of the path.

Size ¶

It Takes a list of numbers as the value, and formats them as dimensions (for example 1920 x 1080). The tile is a subclass of text and supports the same properties.

{
    "type": "size",
    "label": "Size",
    "value": [100, 200],
    "text_size": "xlarge"
}

`type`	string	`size`
`value`	array of number	The dimensions to display in the tile. For example, the value `[640, 480]` would display as `640 ᳵ 480`.

Logo ¶

Displays an image.

{
    "type": "logo",
    "label": "Logo",
    "image_path": "$HFS/houdini/pic/karma_logo.svg",
    "image_size": [32, 32],
    "alignment": "center"
}

`type`	string	`logo`
`image_path`	string	Path to the image file to display.
`stretch`	boolean	If the image is smaller than the available space in the tile, stretches the image to fill the tile (preserving the aspect ratio).
`alignment`	alignment	How the image is positioned within the tile.
`image_size`	size	Resize the image to this width and height (in pixels).
`tint_color`	color	Tints the image with the given hue. { "type": "logo", "image_path": "$HFS/houdini/pic/karma_logo.svg", "tint": "#ff00ff" } Tip You can set this to black to desaturate the image.

Logo text ¶

Displays an image and a text string. The image is positioned first (using image_alignment), and then the text is positioned in the remaining space (using text_alignment).

{
    "type": "logo_text",
    "label": "Logo Text",
    "tint_color": "#000000",
    "tint_amount": 1.0,
    "top_margin": 5,
    "text_size": "small",
    "image_size": [32, 32],
    "gap": 5,
    "image_path": "$HFS/houdini/pic/karma_logo.svg",
    "value": "Karma"
}

`type`	string	`logo_text`
`image_path`	string	Path to the image file to display.
`text`	string	Text to display next to the image.
`value`	string	Alias for the `text` property.
`text_alignment`	alignment	How to position the text within the tile.
`image_size`	size	Resize the image to this width and height (in pixels).
`image_alignment`	alignment	How to position the image within the tile.
`gap`	number	The spacing between the image and text, in pixels.
`tint_color`	color	Tints the image with the given hue. You can set this to black to desaturate the image.

Chart table ¶

Displays data as a chart and a table of out name/value pairs laid out in rows and columns, like a spreadsheet.

`type`	string	`"chart_table"`
`rows`	various	Usually you will set this up to pull from the stats data. It can handle various forms of data: An object mapping label strings to value numbers: `{"foo": 1.0, "bar": 2.0, "baz": 3.0}` A list of label/value pairs: `[["foo", 1.0], ["bar", 2.0], ["baz", 3.0]]` A list of label strings: `["foo", "bar", "baz"]` A list of value numbers: `[1.0, 2.0, 3.0]` If you have data in a different form, you can change it into one of the supported forms using a Python expression.
`show_zero`	boolean	If this is `true`, the table shows rows where the value is `0`. If this is `false` items where the value is `0` are not shown.
`chart`	chart	See the `chart` property of the chart tile.
`total`	number	See the `total` property of the chart tile.
`formatter`	formatter	Formatter for the values in the table.
`decimal_places`	number	Convenience to set the number of decimal places on the formatter.
`hide_when_empty`	boolean	If this `true`, the tile automatically hides itself if it contains no data. Default is `false`.
`min_column_width`	number	The minimum width for cells in the table, in pixels. This prevents the cells from becomming too narrow.
`max_column_width`	number	The maximum width for cells in the table, in pixels. This prevents the labels and values from growing too far apart.
`row_height`	number	The height of cells in the table, in pixels. If this is `0` or `null` (the default), the height is calculated from the font size.
`column_gap`	number	The horizontal space between columns, in pixels.
`item_decorations_visible`	boolean	Whether to show any color chips or icons associated with each item.
`value_key`	string	If the “items” found by the jsonpath are dictionaries, use this key to get the item’s value.
`sorted`	boolean	If this is `false` (the default), the items appear in the order they were found. If this is `true`, the items are sorted. By default, the items are sorted by their labels. Set `sort_column` to `1` to sort by the value instead. By default, the sort is from lowest to highest. Use `reversed` to change the sort order.
`sort_column`	number	If `sorted` is `true` and this is `0`, the items are sorted by their label. If this is `1`, the items are sorted by their value.
`reversed`	boolean	If `sorted` is `true` and this is `true`, the items are sorted from highest to lowest.
`key_label_map`	object mapping string to string	When the label of an item is a key in this mapping, it is “rewritten” to the corresponding value. This can be useful for displaying more “human-readable” labels for data pulled from the stats.
`included_keys`	array of string	Only items with labels in this list (before applying any `key_label_map`) appear in the table.
`excluded_keys`	array of string	Any items with labels in this list (before applying any `key_label_map`) do not appear in the table.

Container tiles ¶

Container tiles take a list of sub-tiles and arrange them in a layout inside the tile. By default, container tiles have their background and label hidden.

Container tile types support the following common options:

`items`	array of tile objects	Each object in this list specifies a tile to display inside this tile.
`item_style`	string	The value is the name of a style. The container applies this style to all sub-tiles that don’t have their own `style` property.

Line ¶

Lays out the sub-tiles in a single row or column.

`type`	string	`"line"`
`orientation`	orientation	Whether to lay out the tiles in a `"horizontal"` row or `"vertical"` column.

Matrix ¶

Lays out the sub-tiles in even rows and columns. This tile gives all its sub-tiles a uniform width and height. The layout fills each row with the tiles that will fit given the min_column_width, then wraps to the next row.

This can be useful for quickly laying out a list of similarly-sized tiles (for example, a bunch of single-number stats). For more complex grid layouts, use the grid containers instead.

{
    "type": "matrix",
    "min_column_width": 120,
    "row_height": 80,
    "items": [
        {"label": "First"},
        {"label": "Second"},
        {"label": "Third"},
        {"label": "Fourth"}
    ]
}

`min_column_width`	number	The minimum column size, in pixels. The default is 128. This keeps the sub-tiles from becoming too narrow to read.
`max_column_width`	number	The maximum column size, in pixels.
`row_height`	number	The height of the rows, in pixels. You should set this value.
`orientation`	orientation	If `"horizontal"`, the cells are filled row-by-row, left to right. If `"vertical"`, the cells are filled column-by-column, top to bottom.

Grid ¶

Lays out the tiles using a bin-packing algorithm to fit the sub-tiles into the available width.

This layout “snaps” the contained tiles to multiples of a certain grid size, so they line up nicely.

Note that when dense is true (the default), the layout puts tiles where there’s space, which can result in tiles appearing in a different order from the order they're defined in the JSON file.

{
    "type": "grid",
    "cell_size": [80, 60],
    "items": [
        {"label": "First", "grid:cols":  2},
        {"label": "Second"},
        {"label": "Third"},
        {"label": "Fourth"},
        {"label": "Fifth", "grid:rows": 2},
        {"label": "Sixth"},
        {"label": "Seventh"}
    ]
}

Properties on the grid container ¶

`cell_size`	array of two numbers	A convenience property to set the grid cell size (`col_width` and `row_height`).
`col_width`	number	The width of the grid squares, in pixels.
`row_height`	number	The height of the grid squares, in pixels.
`spacing`	number	This is a convenience property to set the horziontal and vertical spacing between tiles (`h_spacing` and `v_spacing`) to the same number.
`h_spacing`	number	The horizontal distance between tiles, in pixels.
`v_spacing`	number	The vertical distance between tiles, in pixels.
`dense`	boolean	Whether later tiles will fill in available space left in the layout by previous tiles. Default is `true`.
`stretch`	boolean	If this is `true`, if the available horizontal space is not an exact multiple of the column width, the tiles are stretched to fill the space. The default is `true`.
`max_cols`	number	The maximum number of columns in the layout, when using a `"horizontal"` orientation. This property on the `grid` tile may be useful for the render stats overlay template to control the tile layout. You should avoid using it in the render stats toolbar template, which automatically fills available horizontal space.

Properties on the tiles in the grid ¶

The following properties on tiles inside the grid tile affect how the tiles are layed out:

grid:cols

number

The number of columns the tile spans. The default is 1.

grid:rows

number

The number of rows the tile spans. The default is 1.

grid:pos

array of two numbers

Instead of laying out the tile whereever it fits, “pins” the tile at a specific grid coordinate. The other tiles will fill in the space around “pinned” tiles.

If the horizontal coordinate is negative, it counts backwards from the right edge of the available space. So, for example, [-1, 0] would pin a the tile to the top right corner (assuming the tile is 1 unit wide).

Tip

It is possible to specify exact sizes on the sub-tiles using width and height, instead of specifying their sizes in grid units with cols and rows, however then the tiles will not line up nicely.

Special property types ¶

Besides the usual JSON data types (string, number, boolean, null, object, array), some properties have special interpretations of their values:

Color

This can be any of the following:

A string containing a web-style “hex color” in the form "#rrggbb" or "#rrggbbaa", for example "#808080", or a name such as "white", "black", or "transparent".
An arrow of floating-point [r, g, b] or [r, g, b, a] numbers, for example [1.0, 0.6, 0.0, 0.5].
A single float, which is interpreted as a gray-scale value (so 0.7 is the same as [0.7, 0.7, 0.7]).

Text size

Either a number representing the font size in pixels, or one of xsmall (or x-small), small, medium, large, xlarge (or x-large), or huge.

Font weight

A weight number (such as 400 or 700), or a weight name, one of "thin", "extralight", "light", "normal", "demibold", "bold", "extrabold", or "black". Note that not all weights are available in all font families.

Margins

This can be any of the following:

An array of four numbers, representing the left, top, right, and bottom pixel margins.
An array of two numbers, representing the horizontal and vertical pixel margins.
A single number, representing the pixel margins on all sides.

Brush

Currently this is the same as the color type.

Edge

A string value of "top", "left", "right", or "bottom".

Alignment

A space-separated string that contains combination of left, right, or hcenter, and/or top, bottom, or vcenter.

You can use center to mean hcenter vcenter.
You can also use topleft, topright, bottomleft, or bottomright, or compass directions such as n, nw, e, se, and so on.

Orientation

One of "horizontal" or "vertical".

Number formatter ¶

If this is an object, the "type" key must be a string specifying the formatter type, and the other keys are arguments to configure the formatter. If this is a string, it specifies the formatter type with the default configuration.

The following formatters are availble:

number

A generic number formatter, with the following options:

decimal_places (number)

Round to this number of decimal places, default is 2.

auto_decimal (number)

If decimal_places is 0, and this number is not 0, the formatter rounds to this number of decimal places if the value is less than 1.0. Default is 1.

This is for situations where you usually want to display whole numbers, but don’t want to display numbers such as 0.5 as just 0.

whole_weight (string)

The font weight for the whole part a number.

fraction_weight (string)

The font weight for the fractional part of a number.

brief (boolean or string)

"always" or true: the formatter always abbreviates the number.
"never" or false: the formatter never abbreviates the number.
"auto": the formatter only abbreviates numbers greater than 999.

The default is "auto".

brief

This is the same as number with brief set to true.

memory / bytes / disk

A brief formatter with specialized unit suffixes for byte counts.

percent

Formats fractional values (for example, 0.5) as percentages (for example, 50%). Supports the decimal_places option with a default of 1.

duration

Formats seconds as hours, minutes, and seconds.

long (boolean)

If this is true, the formatter always displays hours, minutes, and seconds.

Chart types ¶

Some tile types, such as chart and chart_table, display “charts” (small visual representations of a number or series of numbers). These tiles let you set up the chart using a chart key.

If the value for chart is a string, it specifies the type of the chart (with default values). If chart is an object, the type key specifies the chart type, and different chart types may allow other keys for configuring options.

You can set the actual value(s) displayed in the chart on the parent tile (for example, using the value or values properties on the chart tile type).

As a convenience, tile types that display charts will often have their own properties that correspond to properties on the chart. You should use the tile properties when available because you can set them from data.

All chart types have the following common keys:

`type`	string	Sets the chart type.
`total`	number	The maximum value in the chart space. For example, if the `total` for a donut chart is `1.0`, then a value of `0.25` will draw an arc filling 25% if the available space. If the `total` for a bar chart is `700`, then a value of `70` will draw a bar 1/10 the height of the chart. If you don’t specify a `total`, different chart types have different behavior. Some might have a default total, some might compute the total from the values (for example, using the sum of the values or the maximum value as the total). See the individual chart types below for details.
`color`	color	The color to use for chart items. This sets all items in the chart to use the same color.
`colors`	array of color	A set of colors to use for chart items. If there are more values in the chart than colors, the colors loop around.
`monochrome`	boolean	If this is `true`, the chart colors all items with a single color based on the color scheme, rather than cycling through the chart colors.
`track_visible`	boolean	Whether to draw a faint “track” behind the chart values. Different chart types may draw the “track” in different ways.
`track_color`	color	The color to use to draw the track.
`track_alpha`	number	Sets the opacity of the default track color, from 0.0 to 1.0. If you specify an explicit `track_color`, this overrides any alpha channel in that color. Default is `0.25`.
`square`	boolean	If this is `true`, the chart maintains a square aspect ratio, instead of stretching to fill the available space. The default is `false`. Note Circular (donut and pie) charts are always draw with a square aspect ratio.
`alignment`	alignment	When `square` is `true`, this controls the positioning of the chart within the available space.

Stacked donut ¶

Displays the values as a “stack” of arcs.

If you don’t specify a total, the chart uses the sum of the values.

`type`	string	`stacked_donut`
`pen_width`	number	The width of the arcs. This a fraction of the chart size, not pixels (so the width scales with the tile size). The default is `0.1`.
`rounded`	boolean	Draw arcs with rounded ends. If this is false, the arcs have flat ends. Default is `true`.
`clockwise`	boolean	Arcs for positive values advance clockwise. Default is `true`.
`gap_angle`	number	Insert a gap of this number of degrees between the start and end of the chart range.
`start_angle`	number	The chart range visually starts at this absolute angle (where `0` is the right edge, `90` is the top edge, and so on). If `gap_angle` is greater than `0`, it offsets the actual start from this angle.
`sweep`	number	The chart range is visually this number of degrees long. Default is `360`. If `gap_angle` is greater than `0`, it offsets the actual sweep from this angle.
`spacing`	number	Inserts spaces of this number of degrees between the stacked arcs. Default is `0`. If you're using this property, you probably want to `rounded` to `false`.

Pie ¶

This is the same as stacked_donut but displays the segments as pie slices rather than arcs.

type

string

pie

Concentric donut ¶

Displays the values as separate concentric arcs.

If you don’t specify a total, the chart uses the maximum of the values.

This chart type supports the same properties as stacked_donut, with the following differences:

`type`	string	`concentric_donut`
`spacing`	number	The space between the concentric arcs, as a fraction of the chart size, from 0.0 to 1.0. The default is `0.025`.

Segmented donut ¶

This chart type does not use total. Instead, the value is displayed as a fraction of the integer segment_count.

`type`	string	`segmented_donut`
`segment_count`	number	The number of segments to display.

Segmented bar ¶

This chart type does not use total. Instead, the value is displayed as a fraction of the integer segment_count.

`type`	string	`segmented_bar`
`orientation`	orientation	Whether the segments are in a `horizontal` or `vertical` line. Default is `horizontal`.
`segment_count`	number	The number of segments to display.
`analog`	boolean	If this is true, and `value` is between two whole numbers, the corresponding segment is “lit up” a fraction amount. For example, if the value is `1.25`, first segment would be fully opaque and the second segment would be drawn with 25% opacity. Default is `true`.
`reversed`	boolean	If true, fill segments from right to left, instead of left to right.
`spacing`	number	The size of the gap between segments, in pixels. Default is `1`.

Choice ¶

Like segmented_bar, but the value sets which segment is drawn, not how many segments are drawn. The first segment is numbered 0. If you specify multiple values on the tile, the chart “turns on” all the corresponding segments.

type

string

choice

segment_style

string

The visual look of the segments, one of rectangle, circle, or box. The default is rectangle.

Bar ¶

Depicts the values as a bar graph.

If you don’t specify a total, the chart uses the maximum of the values.

`type`	string	`bar`
`orientation`	orientation	The orientation of the bars, `horizontal` or `vertical`. Default is `vertical`.
`centered`	boolean	The “zero” value is centered in the chart area. This is useful for showing negative values.
`spacing`	number	The size of the gap between bars, in pixels. Default is `1`.

Line ¶

Depicts the values as a line graph.

If you don’t specify a total, the chart uses the maximum of the values.

`type`	string	`line`
`dot_radius`	number	The radius of the dots at the value points, in pixels. Set this to `0` to hide the dots.

Area ¶

Like line, but draws a filled polygon instead of a polyline.

type

string

area

Overview ¶

Structure ¶

Pulling values from the render stats with JSONpaths ¶

Mapping properties to JSONpaths ¶

Python expressions ¶

JSONpath helpers ¶

Testing your template ¶

Tips and notes ¶

Common tile properties ¶

Styling ¶

Tile types ¶

Text ¶

Number ¶

Chart ¶

Duration ¶

Estimated time remaining ¶

Path ¶

Size ¶

Logo ¶

Logo text ¶

Chart table ¶

Container tiles ¶

Line ¶

Matrix ¶

Grid ¶

Properties on the grid container ¶

Properties on the tiles in the grid ¶

Special property types ¶

Number formatter ¶

Chart types ¶

Stacked donut ¶

Pie ¶

Concentric donut ¶

Segmented donut ¶

Segmented bar ¶

Choice ¶

Bar ¶

Line ¶

Area ¶

Solaris and Karma

USD ¶

Geometry ¶

Layout ¶

Look Development ¶

Karma User Guide ¶

Karma basics and workflows ¶