Python API

Using the DiagramDef class

If you want to create a diagram using Python, you can start by creating an empty diagram definition object:

from orthogram import Color, DiagramDef, write_png

d = DiagramDef(label="A hand-made diagram", text_fill=Color(0, 0, 1))

You can pass any diagram Attributes to the constructor as key-value pairs.

You may add elements to the diagram definition in any order. This is how you define the layout grid, one row at a time:

d.add_row(["a"])
d.add_row(["b", "", "c"])

The add_row() method takes a list of cell tags. Use an empty string or None to insert a cell without a tag.

You define blocks using the add_block() method:

d.add_block("a", label="Hello")
d.add_block("b", label="Beautiful")
d.add_block("c", tags=["c1", "c2"], label="World")

The first argument is the name of the block. You can optionally provide the tags of the cells that you want the block to cover (besides the cells tagged with the name of the block), as well as Attributes for the block as key-value pairs.

Use the set_auto_block_attributes() method to set default attributes for the blocks that the program creates automatically from the “leftover” tags.

You create connections between blocks using the add_connection() method:

d.add_connection("a", "b", group="fire", stroke=Color(1, 0, 0))
d.add_connection("c", ("d", "n"), stroke=Color(0, 0, 1))

The start and the end of the connection can be either a block name or a pair of a block name and a cell tag. Use the second form to target specific cells of a block. The DiagramDef class offers an add_connections() method as well, which lets you create connections en masse (all having the same attributes). Use the Python help() function to learn more about it.

To add labels to a connection, you can use the following methods on the connection definition:

• set_start_label()

• set_middle_label()

• set_end_label()

For example:

# Assuming Color, FontWeight and TextOrientation have been imported
# from module orthogram...

c = d.add_connection("a", "b")
c.set_start_label("Go!")
c.set_middle_label(
    "Keep going!",
    font_weight=FontWeight.BOLD,
    text_fill=Color(0, 0.5, 0)
    text_orientation=TextOrientation.HORIZONTAL,
)

After you have finished building your diagram, use the write_png() function to write the PNG file:

write_png(d, "hello.png")

Using the Builder class

The Builder class lets you create a DiagramDef object from Python dictionaries like the ones you load from a YAML file. The add() method imports a complete diagram definition into the builder:

import yaml
from orthogram import Builder, write_png

builder = Builder()
with open("diagram.yaml") as f:
    data = yaml.safe_load(f)
    builder.add(data)
write_png(builder.diagram_def, "diagram.png")

If you have to be more specific, Builder provides the following methods:

Do one	Do many
add_style()	add_styles()
add_group()	add_groups()
add_row()	add_rows()
add_block()	add_blocks()
add_connection()	add_connections()
configure_diagram()

For example:

block_def = {
    'name': "hello",
    'label': "Hello",
    'fill': [1, 1, 0],
    'stroke': None,
}
builder.add_block(block_def)

Use the help() Python function to access the documentation for each method.

The diagram_def property of a Builder object holds the definition for the diagram you are building. If you want to use the DiagramDef API on it, as described in the previous section, after or while using the builder, you can certainly do so.

Convenience functions

The orthogram module provides the following functions as shortcuts:

load_ddf()

Loads a diagram definition file and returns a DiagramDef object.

translate()

Translates a diagram definition file to a PNG file directly.

translate_dir()

Translates a whole directory of definition files.

The use of these functions is straightforward:

from orthogram import load_ddf, translate, translate_dir, write_png

# You can do this:
d = load_ddf("diagram.yaml")
write_png(d, "diagram.png")

# also this:
translate("diagram.yaml", "diagram.png")

# and even this:
translate_dir("~/diagrams")