gvmap
Generate image map from Graphviz layout
TLDR
Generate a clustered map layout from a DOT format graph
Generate a map using existing cluster subgraphs from the input
Include graph edges in the [o]utput map
Specify a [c]olor scheme (1: pastel, 2: blue-yellow, 3: white-red, etc.)
Set the maximum number of [C]lusters (by default 0, meaning there is no limit)
Only draw cluster 2 (by default, all clusters are drawn)
SYNOPSIS
gvmap [options] [files]
PARAMETERS
-s scale
Sets the global scale factor for node positions and sizes.
-c margin
Specifies a margin around the mapped layout in graph units.
-d node_size
Sets the default size for nodes that don't have explicit size attributes.
-m map_file
Specifies the path to the map file containing spatial data for node mapping.
-f font_size
Sets the default font size for node labels.
-h, -?
Displays a help message with command usage and options.
files
One or more input graph files in DOT language format. If omitted, reads from standard input.
DESCRIPTION
gvmap is a specialized filter command within the Graphviz suite, designed to facilitate the creation of graph layouts based on geographic or spatial data. It reads a graph described in the DOT language and, using an external map file, transforms node attributes into geometric positions and sizes. This allows users to generate layouts where graph nodes accurately reflect real-world locations or specific spatial arrangements without manually specifying coordinates for each node in the DOT file. The command is typically employed as part of a larger Graphviz pipeline, often preceding a layout engine like sfdp to achieve spatially aware graph visualizations. Its primary utility lies in automating the placement of nodes according to predefined spatial relationships or coordinates provided in the map file, thereby simplifying the creation of complex geographical graph diagrams.
CAVEATS
gvmap requires a properly formatted map file to perform its core function, making its utility dependent on external data.
It does not perform layout generation on its own but rather preprocesses the graph for subsequent layout engines, usually sfdp.
Intended primarily for graphs where nodes have a meaningful spatial or geographic dimension, rather than arbitrary graph structures.
Part of the Graphviz suite; a full Graphviz installation is required for its functionality.
<B>INPUT/OUTPUT</B>
gvmap reads a graph in DOT language from standard input or specified files and outputs a modified DOT graph to standard output. The output graph will have added or modified pos (position) attributes for nodes, suitable for layout by Graphviz engines.
<B>MAP FILE FORMAT</B>
The map file (specified by -m) is a plain text file where each line typically contains a node name followed by its spatial coordinates. A common format is: nodename x y [width height]. For example: city_a 100 200 or country_b 50 50 30 20. These coordinates are then used to place the corresponding nodes in the graph.
<B>TYPICAL USAGE</B>
gvmap is rarely used in isolation. A typical pipeline might look like: cat graph.dot | gvmap -m map.txt | sfdp -Tpng > graph.png. Here, gvmap adds positional data, and sfdp (a layout engine) then uses that data to render the graph, creating a spatially informed visualization.
HISTORY
gvmap is an integral component of the open-source Graphviz graph visualization software project, which originated at Bell Labs in the 1990s. Its development arose from the need to visualize complex networks and data structures, specifically catering to scenarios where graph nodes represent geographical locations or have inherent spatial coordinates. Over time, as Graphviz evolved into a comprehensive suite of tools for various graph layout challenges, gvmap solidified its role as the go-to utility for incorporating external spatial data into graph layouts, automating what would otherwise be a tedious manual process of coordinate assignment.
