Graph::Layouter - lay out graph onto an abstract plane

  my $graph = new Graph;
  ...

  use Graph::Layouter qw(layout);
  my $layouted = layout($graph);

  use Graph::Layouter;
  my $layouted = Graph::Layouter->layout($graph);
  ...
  $layouted->layout();

This module provides an abstract class for various algorithms of graph nodes positioning at a virtual surface. That is, if you have a graph stuffed into a Graph object, Graph::Layouter will take it and assign each node in the graph virtual coordinates in a plane.

Graph::Layouter does not do anything besides assigning the coordinates --- you will need to have the nodes and edges laid out to some real plane on your own, or use a bundled Graph::Renderer modules family.

This module contains only the abstract class, you will probably want to get an instance of some particular layouting algorithm instead; Graph::Layouter::Spring is bundled with this distribution. The general interface for all the subclasses is described below, but be sure consult also the particular class' documentation for remarks, special notes and specific extensions.

layout()

This subroutine is the only entry point of this module, taking a given graph and laying it out appropriately. The subroutine can be called in several ways:

Functional interface

The subroutine can be called as a function (it is not automatically exported, but you can import it on your own if you really want; see the synopsis above). It takes one parameter, the Graph class (or any descendant) instance. It will set the layout back into the graph and return its parameter back for convenience.

Class constructor interface

The subroutine can be called as a class constructor, like $g = Graph::Layouter-layout($graph)>. It will take the $graph, do stuff on it and returns reference to $graph back, however reblessed to a Graph::Layouter instance.

In human language this means that after the call $graph will still be the original object, only with some more attributes attached, whereas $g will be a Graph::Layouter instance; however any changes to $g will be propagated to $graph and vice versa.

Class method interface

When you already got a Graph::Layouter instance, you can call this subroutine as $g-layout()>. It will relayout an already layouted graph.

The layouting function saves the layout data (coordinates of nodes) back to the Graph object, in a form of vertex attributes - layout_pos1 and layout_pos2 (pos1 is the x dimension, pos2 the y dimension; it is planned to make it possible to layout in three or unlimited number of dimensions space).

We also provide layout_min1, layout_max1 as well as layout_min2, layout_max2 global graph attributes, containing the extreme values in the respective dimensions. This is usually needed to properly map the virtual coordinates to some physical points.

If you intend to use Graph attributes in conjunction with the Graph::Layouter, you are advised not to infrige the layout_ namespace. If you are writing a Graph::Layouter subclass, you are advised to put your attributes to a layout__subclassname_ namespace.

Graph, Graph::Renderer

Some more universal layout calling interface (hash parameters) is missing.

Copyright 2004 by Petr Baudis <pasky@ucw.cz>.

This code is distributed under the same copyright terms as Perl itself.

Version 0.03

$Id: Layouter.pm,v 1.3 2006/02/11 17:11:39 pasky Exp $