Scala Force Layout

Scala Force Layout is a force-directed graph layout implementation in Scala. The project originally started out as a port of the Springy JavaScript graph layout code by Dennis Hotson. In addition, I added Barnes-Hut simulation to improve performance on bigger graphs (here's a video), and based my physics model parameters on those used in VivaGraphJS by Andrei Kashcha.

Getting Started

Create a graph from collections of nodes and edges.

val nodes = Seq(
    Node("id_a", "Node A"),
    Node("id_b", "Node B"),
    Node("id_c", "Node C"),
    Node("id_d", "Node D"))
      
val edges = Seq(
    Edge(nodes(0), nodes(1)),
    Edge(nodes(1), nodes(2)),
    Edge(nodes(2), nodes(3)),
    Edge(nodes(0), nodes(3)))
      
val graph = new SpringGraph(nodes, edges)

Run the layout algorithm using the graph.doLayout() method. Attach onIteration and onComplete handlers to capture intermediate and final results of the layout process.

graph.doLayout(
        onIteration = (it => { ... do something on every layout iteration ... })
        onComplete = (it => { println("completed in " + it + " iterations") }))

Rendering an Image

The ImageRenderer is a simple utility for rendering an image of your graph. If all you want is to store an image of the final layout, this is what you're looking for:

graph.doLayout(
  onComplete = (it => {
    // Renders a 500x500 pixel image of the final graph layout  
    val image = ImageRenderer.drawGraph(graph, 500, 500)
        
    // Writes the image to a PNG file
    ImageIO.write(image, "png", new File("my-graph.png"))
  }))

Opening a Viewer

If you want to open your graph in a window on the screen (with mouse pan and zoom included), use this code:

// Creates a zoom- and pan-able view of the graph
val vis = new BufferedInteractiveGraphRenderer(graph)
  
// Creates a JFrame, with the graph renderer in the content pane
val frame = new JFrame("Les Miserables")
frame.setSize(920, 720)
frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE)
frame.getContentPane().add(vis) 
frame.pack()
    
// Pops up the JFrame on the screen, and starts the layout process
frame.setVisible(true)
vis.start

You may also want to take a look at the Hello World and LesMiserables examples for complete, working code.

Current Version

The current version of Scala Force Layout is 0.4.0. Download the jar for Scala 2.10 here: scala-force-layout_2.10-0.4.0.jar, or include it in your SBT project through the Maven Central Repository:

libraryDependencies += "at.ait.dme.forcelayout" % "scala-force-layout_2.10" % "0.4.0"

Building From Source & Running the Examples

Scala Force Layout uses SBT as a build tool. Please refer to the SBT documentation for instructions on how to install SBT on your machine. Once you have installed SBT, you can run the examples by typing sbt run. To build a .jar package type sbt package. To generate a project for the Eclipse IDE, type sbt eclipse.

Future Work

There are many things on the list - feel free to help out if you care to!

"The last thing we need is another graph API." // TODO use the Tinkerpop Blueprints graph model
"Speed is of the essence." // TODO I'm sure there is much room for performance optimization. Any thoughts & experiences welcome!
"Where can I click?" // TODO create a renderer that produces an interactive graph, complete with draggable nodes and such
"Sorry, I don't code." // TODO A simple command-line wrapper that opens some GraphSON, with no coding involved, would be nice

License

Scala Force Layout is released under the MIT License.

rsimon / scala-force-layout Goto Github PK