Graph::Layout::Aesthetic::Force - Base class for graph layout aesthetic forces
# This module is normally used as base class for particular force modules: package Whatever; use base qw(Graph::Layout::Aesthetic::Force); sub name { return "Whatever"; } $force = some_new_force_object(); $force->register($name); $force->register; $old_private_data = $force->_private_data; $old_private_data = $force->_private_data($new_private_data); $old_user_data = $force->user_data; $old_user_data = $force->user_data($new_user_data);
or
Graph::Layout::Aesthetic::Force::name2force($name);
Graph::Layout::Aesthetic::Force is a base class for the aesthetic forces used by the Graph::Layout::Aesthetic package. Each force represents one aspect the graph should be optimized for, concepts like "Nodes should be not too close together" or "edges should not be too long". This works by passing the current configuration to the aesth_gradient function in the force module, which then returns a "force" for each node corresponding to how much it would like to move that node in that direction to improve the target aesthetic.
The combination of all forces will then determine the direction and size of the step that's applied to all nodes. The step sizes get restricted by a scalar that's called the "temperature". Since initial step sizes can be big, they don't necessarily improve on the target aesthetics since a step can reach far beyond the minimum for an aesthetic in the given direction (this is intentional so that a state will be able to escape from a local minimum). But as the temperature lowers and the steps get smaller, the steps will more and more tend to optimize the target aesthetic.
The Graph::Layout::Aesthetic package comes with a number of predefined aesthetics, these being:
Repulsion from the centroid of the current configuration, magnitude 1/d
Nodes connected to each other by an edge attract each other with force d**2
Nodes repel each other with a force 1/d
Nodes repel from the nearest point on the line through an edge if that point is between the endpoints of the edge. Magnitude 1/d.
Crossed edge midpoints repel each other with a constant magnitude of 1. Only works in 2 dimensions.
Crossed edge midpoints repel each other with a force d. Only works in 2 dimensions.
This is mainly meant for DAGs (Directed Acyclic Graphs). If a node gets placed to the left of it's parent (position on the first coordinate, the x-axis) plus 5, it wants to move to the other side with a force d**2.
This is again mainly meant for DAGs (Directed Acyclic Graphs). Each node gets assigned a level (its distance from the leafs). Then it tries to give all nodes with the same level at the same distance from the left (position on the first coordinate, the x-axis). The force is d**3 (d is how much the node is to the left or the right from the average position of all nodes of its own level).
The main role of this module is to function as base class for particular forces that are written as XS extension modules. It has a default DESTROY method that frees an assumed underlying C structure, so don't use this as a baseclass for pure perl modules. However, see Graph::Layout::Aesthetic::Force::Perl for how to write forces in perl. On the other hand, if you want to write your own standalone force packages based on XS code, then you'll need to look at Graph::Layout::Aesthetic::Include to get the right definitions of the C level datastructures.
A typical derived class should normally have a module file that loads the XS object and creates one standard instance of the force which it then registers with Graph::Layout::Aesthetic::Force.
The XS object should have a constructor that encapsulates a struct aglo_force (see include/aglo.h) with 3 callback function pointers:
Called once when a force is added to a state (see Graph::Layout::Aesthetic::add_force). It should do any necessary preparation for later aesth_gradient (e.g. Graph::Layout::Aesthetic::Force::MinLevelVariance uses it to calculate the levels of each node in a graph so they don't have to be recalculated every time). It should return a pointer that will be passed to every aesth_gradient call and later to aesth_cleanup for any needed cleanup. This for example can be used to set up scratch memory that will be needed during calculations.
This gets called when a forced gets detached from a state, and should do any needed cleanup, for example cleaning up the scratch memory allocated by aesth_setup
The actual workhorse of the aesthetic force. It will be passed the current state, the pointer returned by aesth_setup and a gradient pointer which is to be filled in with the aesthetic force. The gradient pointer is already initialized with zeros.
The Graph::Layout::Aesthetic::Force module holds a mapping from names to forces. This method registers such a force. The name will be $name, unless that is undefined or not given, in which case it is determined by calling the name method on the given $force. The force corresponding to a given name can be looked up using name2force after this call. A given name can only be registered once.
This methods should return the "official" name for a given force. If it's not overridden in the subclass, it defaults to the last component of the class the force belongs to.
This looks up $name in the name to force mapping of this module. If found, it directly returns the corresponding force. If not, it tries to require Graph::Layout::Aesthetic::Force::$name and tries again. If still not found, it throws an exception.
This method gets used by Graph::Layout::Aesthetic to load forces on demand.
Every force object is associated with one scalar of private data (default undef). This is perl data meant for the implementer of a force class, and should normally not be manipulated by the user (see user_data for that).
This method returns that private data.
Don't confuse this with the closure data returned by aesth_setup. That one is associated with a force/state combination and normally only exists as long as a certain force is associated with a certain state, while this one is associated with the force itself.
Sets new private data, returns the old value.
Every force object is associated with one scalar of user data (default undef). This is perl data meant for the enduser of a force class, and should normally not be manipulated inside the force class (see private_data for that).
This method returns that user data.
Sets new user data, returns the old value.
None.
Graph::Layout::Aesthetic, Graph::Layout::Aesthetic::Force::Perl, Graph::Layout::Aesthetic::Force::Centripetal, Graph::Layout::Aesthetic::Force::MinEdgeLength, Graph::Layout::Aesthetic::Force::NodeRepulsion, Graph::Layout::Aesthetic::Force::MinEdgeIntersect, Graph::Layout::Aesthetic::Force::MinLevelVariance, Graph::Layout::Aesthetic::Force::ParentLeft, Graph::Layout::Aesthetic::Force::MinEdgeIntersect2, Graph::Layout::Aesthetic::Force::NodeEdgeRepulsion, Graph::Layout::Aesthetic::Include
Ton Hospel, <Graph-Layout-Aesthetic@ton.iguana.be>
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.
To install Graph::Layout::Aesthetic, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Graph::Layout::Aesthetic
CPAN shell
perl -MCPAN -e shell install Graph::Layout::Aesthetic
For more information on module installation, please visit the detailed CPAN module installation guide.