How to use the command 'circo' (with examples)

Graphviz is a popular open-source tool that enables users to create network diagrams with ease. Among its several layout engines, ‘circo’ specializes in producing circular network graphs. This can be particularly effective for visualizing hierarchies and cyclical data structures, where relationships naturally fit into a circular arrangement. Below we explore various applications of the ‘circo’ command and how it can be utilized to generate different formats of circular network diagrams from Graphviz files.

Use case 1: Render a PNG image with a filename based on the input filename and output format

Code:

circo -T png -O path/to/input.gv

Motivation:

This use case is ideal for users who want to quickly generate a PNG image from a Graphviz file, in such a way that the output image’s filename is automatically derived from the input file’s name. It streamlines the process, reducing manual effort and potential errors in naming.

Explanation:

• circo: This specifies the Graphviz layout engine to use, particularly ‘circo’ for circular layouts.
• -T png: The -T option defines the desired output format, in this case, ‘png’ for a Portable Network Graphics file.
• -O: The uppercase ‘O’ option automatically generates output filenames based on the input file but adjusts for the specified format.
• path/to/input.gv: The path to the Graphviz file that contains the graph description.

Example Output:

Executing this command will create ‘path/to/input.png’ as the output file if ‘path/to/input.gv’ is the given filename. This PNG file will visually represent the circular structure of the input graph data.

Use case 2: Render an SVG image with the specified output filename

Code:

circo -T svg -o path/to/image.svg path/to/input.gv

Motivation:

Choosing this approach is beneficial when one needs to create an SVG file with a specific filename. This is suitable for projects requiring particular naming conventions and paths for systematic organization.

Explanation:

• circo: Again, specifies the circular layout engine.
• -T svg: Indicates that the output format should be SVG (Scalable Vector Graphics), a flexible format for vector-based images.
• -o path/to/image.svg: The lowercase ‘-o’ allows the user to define exactly where and under what name the SVG file should be saved.
• path/to/input.gv: The input Graphviz file location and name.

Example Output:

The generated output will be saved as ‘path/to/image.svg’, providing an easily scalable vector image based on the circular graph defined in ‘input.gv’.

Use case 3: Render the output in various formats like PS, PDF, SVG, etc.

Code:

circo -T format -O path/to/input.gv

Motivation:

Such versatility is designed for users who require flexibility in output formats. Whether for embedding graphics in documents (PDF) or sharing across platforms (JSON), this use case covers extensive possibilities.

Explanation:

• circo: Uses the ‘circo’ layout engine.
• -T format: Placeholder for the user to substitute their required format, such as PS, PDF, SVG, Fig, PNG, GIF, JPEG, JSON, or DOT.
• -O: Again, creates an output with a filename derived from the input file and adjusts for the specified format.
• path/to/input.gv: The file containing the graph data structure input.

Example Output:

If ‘PDF’ is chosen as the format, the output file might be ‘path/to/input.pdf’, allowing for a print-ready document that represents the graph’s circular layout.

Use case 4: Render a GIF image using stdin and stdout

Code:

echo "digraph {this -> that}" | circo -T gif > path/to/image.gif

Motivation:

This case is perfect for dynamically generating graphs directly from the command line without the need for intermediary files. It’s particularly useful in scripting and automation where graphs are transient and meant for quick use.

Explanation:

• echo "digraph {this -> that}": Directly inputs the graph description using a simple digraph example.
• |: Pipes the output of echo as the input (stdin) to the ‘circo’ command.
• circo -T gif: Specifies ‘gif’ as the output format.
• > path/to/image.gif: Redirects the output of circo into the specified GIF file.

Example Output:

The command will result in the creation of ‘path/to/image.gif’ containing a simple graph where node ’this’ points to node ’that’, showcased in a looping GIF format.

Use case 5: Display help

Code:

circo -?

Motivation:

Checking the built-in help is a beneficial first step for new users or those revisiting ‘circo’ after some time. It provides a quick reminder of available options and syntax without needing external resources.

Explanation:

• circo -?: The -? flag requests Graphviz to display the ‘circo’ command’s help information directly on the console.

Example Output:

The console will display the help text, including usage, options, and a brief description of what the ‘circo’ command does.

Conclusion:

The ‘circo’ tool is highly versatile for graph visualization needs within the Graphviz suite, providing a wide range of formatting options for rendering and ease of use with various output file specifications. Whether automating graph generation or requiring a quick conversion to a specific file type, each use case presented offers practical solutions tailored to diverse user requirements.