Blockdiag Package Diagrams

The blockdiag package provides tools for generating several types of diagram, from simple box and arrows diagrams to various diagrams familiar to communications and system engineers.

The diagrams are defined using simple text structures. Various IPython block magics allow these descriptions to be entered directly in to a magicked code cell, and the diagram generated directly therefrom.

The diagrams are generated by default as SVG diagrams and can be saved to a named file if required; .png format images may also be created.

All the magics are enabled from a single load command:

%%capture
try:
    import blockdiag_magic
except:
    %pip install blockdiagMagic
%load_ext blockdiag_magic

Block Diagrams

%%blockdiag
A -> B -> C;
B -> D;
../_images/blockdiag_4_0.svg

Network Diagrams

The network diagram type can be used to demonstrate the connectivity of nodes to different IP (internet protocol) network ranges.

In the following diagram, we save the SVG image to an explicit file as an additional output. (The direct output is hidden using a publishing system tag in the original source document.)

%%nwdiag --outfile demo1.svg
  network dmz {
      address = "210.x.x.x/24"

      web01 [address = "210.x.x.1"];
      web02 [address = "210.x.x.2"];
  }
  network internal {
      address = "172.x.x.x/24";

      web01 [address = "172.x.x.1"];
      db01;
      app01;
  }
../_images/blockdiag_7_0.svg

We can then explicitly render the image, from the saved file, as required:

from IPython.display import SVG
SVG('demo1.svg')
../_images/blockdiag_9_0.svg

Nodes can also be grouped in coloured blocks.

The network diagram type can also be used to sketch higher level network diagrams:

%%nwdiag

  inet [shape = cloud];
  inet -- router;

  network {
    router;
    web01;
    web02;
  }
../_images/blockdiag_11_0.svg

Activity Diagrams

The activity diagram type can be used to describe a linear series of activities carried out by one or more actors:

%%actdiag --outfile delme1.svg
  write -> convert -> image

  lane user {
     label = "User"
     write [label = "Writing reST"];
     image [label = "Get diagram IMAGE"];
  }
  lane actdiag {
     convert [label = "Convert reST to Image"];
  }
../_images/blockdiag_13_0.svg

Sequence Diagram

A sequence diagram can be used to visualise the message passing sequence used by a communication protocol.

%%seqdiag
browser  -> webserver [label = "GET /index.html"];
browser <-- webserver;
browser  -> webserver [label = "POST /blog/comment"];
          webserver  -> database [label = "INSERT comment"];
          webserver <-- database;
browser <-- webserver;
../_images/blockdiag_15_0.svg

Packet Diagram

The packet diagram type can be used to illustrate the bit an bytewise structure of a data packet:

%%packetdiag
  colwidth = 32
  node_height = 72

  0-15: Source Port
  16-31: Destination Port
  32-63: Sequence Number
  64-95: Acknowledgment Number
  96-99: Data Offset
  100-105: Reserved
  106: URG [rotate = 270]
  107: ACK [rotate = 270]
  108: PSH [rotate = 270]
  109: RST [rotate = 270]
  110: SYN [rotate = 270]
  111: FIN [rotate = 270]
  112-127: Window
  128-143: Checksum
  144-159: Urgent Pointer
  160-191: (Options and Padding)
  192-223: data [colheight = 3]
../_images/blockdiag_17_0.svg

Rack Diagrams

The rack diagram (rackdiag) type is useful for generating diagrams that illustrate the different components that might be present in a physical rack server cabinet.

%%rackdiag --outfile delme2.svg

12U

1: UPS [2U];
3: DB Server
4: Web Server 1 
4: Web Server 2
5: Web Server 3
5: Web Server 4
7: Load Balancer
8: L3 Switch
../_images/blockdiag_19_0.svg