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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
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")