Visualisation

Behaviour trees are significantly easier to design, monitor and debug with visualisations. Py Trees does provide minimal assistance to render trees to various simple output formats. Currently this includes dot graphs, strings or stdout.

Ascii Trees

You can get a very simple ascii representation of the tree on stdout with print_ascii_tree():

py_trees.display.print_ascii_tree(root, indent=0, show_status=False)

Print the ASCII representation of an entire behaviour tree.

Parameters:

• root (Behaviour) – the root of the tree, or subtree you want to show
• indent (int) – the number of characters to indent the tree
• show_status (bool) – additionally show feedback message and status of every element

Examples

Render a simple tree in ascii format to stdout.

root = py_trees.composites.Sequence("Sequence")
for action in ["Action 1", "Action 2", "Action 3"]:
    b = py_trees.behaviours.Count(
            name=action,
            fail_until=0,
            running_until=1,
            success_until=10)
    root.add_child(b)
py_trees.display.print_ascii_tree(root)

Tip

To additionally display status and feedbback message from every behaviour in the tree, simply set the show_status flag to True.

Ascii Trees (Runtime)

When a tree is ticking, it is important to be able to catch the status and feedback message from each behaviour that has been traversed. You can do this by using the SnapshotVisitor in conjunction with the ascii_tree() function:

py_trees.display.ascii_tree(tree, indent=0, snapshot_information=None)

Build an ascii tree representation as a string for redirecting to elsewhere other than stdout. This can be the entire tree, or a recorded snapshot of the tree (i.e. just the part that was traversed).

Parameters:

• tree (Behaviour) – the root of the tree, or subtree you want to show
• indent (int) – the number of characters to indent the tree
• snapshot_information (visitors) – a visitor that recorded information about a traversed tree (e.g. SnapshotVisitor)
• snapshot_information – a visitor that recorded information about a traversed tree (e.g. SnapshotVisitor)

Returns:

an ascii tree (i.e. in string form)

Return type:

str

Examples

Use the SnapshotVisitor and BehaviourTree to generate snapshot information at each tick and feed that to a post tick handler that will print the traversed ascii tree complete with status and feedback messages.

def post_tick_handler(snapshot_visitor, behaviour_tree):
    print(py_trees.display.ascii_tree(behaviour_tree.root,
          snapshot_information=snapshot_visitor))

root = py_trees.composites.Sequence("Sequence")
for action in ["Action 1", "Action 2", "Action 3"]:
    b = py_trees.behaviours.Count(
            name=action,
            fail_until=0,
            running_until=1,
            success_until=10)
    root.add_child(b)
behaviour_tree = py_trees.trees.BehaviourTree(root)
snapshot_visitor = py_trees.visitors.SnapshotVisitor()
behaviour_tree.add_post_tick_handler(
    functools.partial(post_tick_handler,
                      snapshot_visitor))
behaviour_tree.visitors.append(snapshot_visitor)

Render to File (Dot/SVG/PNG)

API

You can render trees into dot/png/svg files simply by calling the render_dot_tree() function.

Should you wish to capture the dot graph result directly (as a dot graph object), use the generate_pydot_graph() method.

Command Line Utility

You can also render any exposed method in your python packages that creates a tree and returns the root of the tree from the command line using the py-trees-render program.

Blackboxes and Visibility Levels

There is also an experimental feature that allows you to flag behaviours as blackboxes with multiple levels of granularity. This is purely for the purposes of showing different levels of detail in rendered dot graphs. A fullly rendered dot graph with hundreds of behaviours is not of much use when wanting to visualise the big picture.

The py-trees-demo-dot-graphs program serves as a self-contained example of this feature.