NAME

Graph::Layout::Aesthetic::Topology - Graph topology for use by Graph::Layout::Aesthetic

SYNOPSIS

  use Graph::Layout::Aesthetic::Topology;
  $topology = Graph::Layout::Aesthetic::Topology->from_graph($graph, %options);
  # Where %options can be:
  #  literal   => $boolean
  #  id_attribute => $name

  $topology = Graph::Layout::Aesthetic::Topology->new_vertices($nr_vertices);
  $topology->add_edge($from, $to ?,$forward?);
  $topology->finish;

  $nr_vertices   = $topology->nr_vertices;
  @vertices      = $topology->neighbors($vertex);
  @vertices      = $topology->forward_neighbors($vertex);
  @edges         = $topology->edges;
  @vertex_levels = $topology->levels;
  $boolean       = $topology->finished;

  $old_private_data = $topology->_private_data;
  $old_private_data = $topology->_private_data($new_private_data);
  $old_user_data    = $topology->user_data;
  $old_user_data    = $topology->user_data($new_user_data);

DESCRIPTION

A Graph::Layout::Aesthetic::Topology objects represents a directed graph topology and is used by Graph::Layout::Aesthetic as a simple and quickly accessible datastructure representing the graph that has to be laid out. Vertices are simply represented as consecutive numbers starting with 0. Edges may not go from a vertex to itself since that may confuse some aesthetic forces.

EXAMPLE

Set up a simple triangle:

  use Graph::Layout::Aesthetic::Topology;

  # Create an empty graph with 3 vertices
  my $topology = Graph::Layout::Aesthetic::Topology->new_vertices(3);

  # Add the edges
  $topology->add_edge(0, 1);
  $topology->add_edge(1, 2);
  $topology->add_edge(2, 0);

  # Say we are done
  $topology->finish;

  # Now we have something that could be passed to Graph::Layout::Aesthetic->new

METHODS

$topology = Graph::Layout::Aesthetic::Topology->from_graph($graph, %options)

Creates a new finished Graph::Layout::Aesthetic::Topology from a standard Graph object $graph. It does this by first creating a Graph::Layout::Aesthetic::Topology object with the right number of vertices and then enumerating all edges in $graph and adding these to the topology if the edge hasn't been seen yet in either direction and doesn't start and end on the same vertex.

The resulting $topology will then probably be passed to a Graph::Layout::Aesthetic constructor.

You can give key/value pairs as options. Currently supported are:

id_attribute => $name

If you don't give this attribute, it will behave as if you gave it the string "layout_id" (the same default as for the Graph::Layout::Aesthetic coordinates_to_graph method).

If you give this attribute an undefined value, it will do no tracking of graph vertices to topology vertices.

If you give it a hash reference, it will empty the hash and then add a key for each vertex in $graph with as value the number of the corresponding vertex in $topology.

If you give it a string, it will use that string as an attribute name for each vertex in $graph and set that attribute to the vertex number in $topology.

You'll probably want to use this options in some form so you'll know which vertex in the result corresponds to which vertex in your $graph.

literal => $boolean

If you give a true value here, the filtering of $graph->edges for duplicates and self-edges is not done. Every edge is simply passed on to add_edge.

$topology = Graph::Layout::Aesthetic::Topology->new_vertices($nr_vertices)

Creates a new unfinished Graph::Layout::Aesthetic::Topology object representing a graph with $nr_vertices vertices. After this you will probably start adding edges and finish the graph before passing it to a Graph::Layout::Aesthetic constructor.

$topology->add_edge($from, $to ?,$forward?)

Register an edge running from vertex $from to vertex $to if $forward is not given or true, a vertex from $to to $from otherwise. You can only add edges as long as the topology is unfinished.

It's possible to add an edge more than once or both in the forward and backward direction. All of these will be seen as different edges and be used as such in the aesthetic force calculations.

$topology->finish

Finishing a Graph::Layout::Aesthetic::Topology object makes it conceptually read-only. You won't be able to add edges anymore. Graph::Layout::Aesthetic constructors will only accept finished Graph::Layout::Aesthetic::Topology objects since they may internally cache information based on the topology of a given moment, and they don't want that cached information to suddenly become invalid because the topology got changed.

You can only finish a Graph::Layout::Aesthetic::Topology object once.

$nr_vertices = $topology->nr_vertices

Returns the number of vertices in $topology.

@vertices = $topology->neighbors($vertex)

Returns all direct neighbors of $vertex, following edges in any direction.

@vertices = $topology->forward_neighbors($vertex)

Returns all direct neighbors of $vertex, following edges in the forward direction only.

@edges = $topology->edges

Returns all forward edges in $topology as a list of anonymous array references. Each such reference is to a two element array containing the $from and $to vertex for that edge.

@vertex_levels = $topology->levels

Returns a level number for each vertex (list element n represents the level of vertex n). Levels basically correspond to distance from leafs (only following edges in the forward direction). These levels are used by some forces like Graph::Layout::Aesthetic::Force::MinLevelVariance.

Levels are only calculated once for a given topology and then cached. The call will croak if the $topology hasn't been finished yet.

$boolean = $topology->finished

Returns true if $topology has been finished, false otherwise.

$old_private_data = $topology->_private_data

Every topology object is associated with one scalar of private data (default undef). This is perl data meant for the implementer of a Topology class, and should normally not be manipulated by the user (see user_data for that).

This method returns that private data.

$old_private_data = $topology->_private_data($new_private_data)

Sets new private data, returns the old value.

$old_user_data = $topology->user_data

Every topology object is associated with one scalar of user data (default undef). This is perl data meant for the enduser of a topology class, and should normally not be manipulated inside the topology class (see private_data for that).

This method returns that user data.

$old_user_data = $topology->user_data($new_user_data)

Sets new user data, returns the old value.

EXPORT

None.

SEE ALSO

Graph, Graph::Layout::Aesthetic

BUGS

Not threadsafe. Different object may have method calls going on at the same time, but any specific object should only have at most one call active.

AUTHOR

Ton Hospel, <Graph-Layout-Aesthetic@ton.iguana.be>

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Ton Hospel

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.1 or, at your option, any later version of Perl 5 you may have available.