[08/10] incubator-tinkerpop git commit: Update docs around Gephi plugin.

[sp...@apache.org]

Update docs around Gephi plugin.


Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/2ea16261
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/2ea16261
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/2ea16261

Branch: refs/heads/master
Commit: 2ea1626183e824e1f8ee9534c0964618f495ae56
Parents: 329fa96
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Thu Jul 23 13:53:47 2015 -0400
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Thu Jul 23 13:53:47 2015 -0400

----------------------------------------------------------------------
 docs/src/gremlin-applications.asciidoc | 46 +++++++++++++----------------
 1 file changed, 21 insertions(+), 25 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/2ea16261/docs/src/gremlin-applications.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/gremlin-applications.asciidoc b/docs/src/gremlin-applications.asciidoc
index cf9b4e3..a4aaa78 100644
--- a/docs/src/gremlin-applications.asciidoc
+++ b/docs/src/gremlin-applications.asciidoc
@@ -971,41 +971,34 @@ NOTE: Issuing `:> graph` again will clear the Gephi workspace and then re-write
 
 Now that the graph is visualized in Gephi, it is possible to link:https://gephi.github.io/users/tutorial-layouts/[apply a layout algorithm], change the size and/or color of vertices and edges, and display labels/properties of interest.  Further information can be found in Gephi's tutorial on link:https://gephi.github.io/users/tutorial-visualization/[Visualization].  After applying the Fruchterman Reingold layout, increasing the node size, decreasing the edge scale, and displaying the id, name, and weight attributes the graph looks as displayed in the right image above.
 
-NOTE: It's recommended to choose a continuously running layout algorithm like Fruchterman Reingold or Force Atlas, because every update to color the visited vertices causes their positions to be reset, so these layouts will constantly adjust to account for these changes and make visualization of the traversals.  This also explains why the graph seems to rotate each store step in the screenshots below.
-
-Consider the following traversal:
+In addition to providing a way to pipe a `Graph` instance to Gephi, the plugin also enables methods for visualizing a `Path` and a `Traversal`.  In both cases, the `Graph` underlying the `Path` and `Traversal` must be visualized in Gephi as defined above.  To visualize a `Path`, simple get a `Path` object and `:submit` it:
 
 [source,groovy]
-----
-g = graph.traversal()
-g.V(2).in().out('knows').
-      has('age',gt(30)).outE('created').
-      has('weight',gt(0.5d)).inV()
-----
+gremlin> :> g.V(1).repeat(both().dedup()).until(hasId(582)).path().next()
+
+The above line of code will visualize the "shortest path" between vertex `1` and vertex `582`, highlighting vertex `1` first then stepping through the path to `582` highlighting each vertex found as it goes.
 
-To visualize it insert the appropriately named `store('n')` steps where `n` is an integer, and the vertices will be highlighted in ascending store step order.
+WARNING: On some platforms, Gephi may not properly refresh the edges in the "Overview" panel for `Path` visualizations.  If this problem occurs, manually refreshing the "Overview" will allow the `Path` visualization to become fully realized (e.g. click the "Show Hulls" button).
+
+Visualization of a `Traversal` has a different approach as the visualization occurs as the `Traversal` is executing, thus showing a real-time view of its execution.  A `Traversal` must be "configured" to operate in this format and for that it requires use of the `visualTraversal` option on the `config` function of the `:remote` command:
 
 [gremlin-groovy,modern]
 ----
-g = graph.traversal()
-g.V(2).in('knows').out('knows').has('age',gt(30)).
-       outE('created').has('weight',gt(0.5d)).inV().values('name')
-traversal = g.V(2).store('1').
-       in('knows').store('2').
-       out('knows').has('age',gt(30)).store('3').
-       outE('created').has('weight',gt(0.5d)).inV().store('4')
-traversal.getSideEffects().get('1')
-traversal.getSideEffects().get('2')
-traversal.getSideEffects().get('3')
-traversal.getSideEffects().get('4')
-:> traversal
+:remote config visualTraversal graph                   <1>
+traversal = vg.V(2).in().out('knows')
+                   .has('age',gt(30)).outE('created')
+                   .has('weight',gt(0.5d)).inV()
+:> traversal                                           <2>
 ----
 
-When `:> traversal` is called, it iterates through the sideEffects of the traversal accessing the vertices stored at each corresponding step. It then updates the vertices' color with `startRGBColor`, which in this case is a lime-green blue: [0.0,1.0,0.5]. After the first step visualization, it sleeps for the configured `stepDelay` in milliseconds. On the second step, it decays the configured `colorToFade` of all the previously visited vertices in prior steps, by multiplying the current `colorToFade` value for each vertex with the `colorFadeRate`.  To avoid color decay on prior steps, then provide a `colorFadeRate` value of `1.0`.  The screenshots below show how the visualization evolves over the 4 steps:
+<1> Configure a "visual traversal" from your "graph" - this must be a `Graph` instance.
+<2> Submit the `Traversal` to visualize to Gephi.
+
+When the `:>` line is called, each step of the `Traversal` that produces or filters vertices generates events to Gephi. The events update the color and size of the vertices at that step with `startRGBColor` and `startSize` respectively. After the first step visualization, it sleeps for the configured `stepDelay` in milliseconds. On the second step, it decays the configured `colorToFade` of all the previously visited vertices in prior steps, by multiplying the current `colorToFade` value for each vertex with the `colorFadeRate`.  Setting the `colorFadeRate` value to `1.0` will prevent the color decay.  The screenshots below show how the visualization evolves over the four steps:
 
 image::gephi-traversal.png[width=1200]
 
-Once a traversal visualization has executed, clear the colors in Gephi by selecting the grey square icon under the magnifying glass icon on the lower left tool bar next to the graph canvas.  Run another traversal against the same graph and it will update the appropriate vertices.  To get a sense of how the visualization configuration parameters affect the output, see the example below:
+To get a sense of how the visualization configuration parameters affect the output, see the example below:
 
 [gremlin-groovy,modern]
 ----
@@ -1017,7 +1010,7 @@ Once a traversal visualization has executed, clear the colors in Gephi by select
 
 image::gephi-traversal-config.png[width=400]
 
-The visualization configuration above starts with a blue color now (most recently visited), fading the blue color (so that dark green remains on oldest visited), and fading the blue color more quickly so that the gradient from dark green to blue across steps has higher contrast. Here is a more detailed description of Gephi plugin configuration parameters, in the order accepted on the `:remote connect gephi` command, or modified via the `:remote config` command:
+The visualization configuration above starts with a blue color now (most recently visited), fading the blue color (so that dark green remains on oldest visited), and fading the blue color more quickly so that the gradient from dark green to blue across steps has higher contrast. The following table provides a more detailed description of the Gephi plugin configuration parameters as accepted via the `:remote config` command:
 
 [width="100%",cols="3,10,^2",options="header"]
 |=========================================================
@@ -1025,10 +1018,13 @@ The visualization configuration above starts with a blue color now (most recentl
 |workspace |The name of the workspace that your Graph Streaming server is started for. |workspace0
 |host |The host URL where the Graph Streaming server is configured for. |localhost
 |port |The port number of the URL that the Graph Streaming server is listening on. |8080
+|sizeDecrementRate |The rate at which the size of an element decreases on each step of the visualization. |0.33
 |stepDelay |The amount of time in milliseconds to pause between step visualizations. |1000
 |startRGBColor |A size 3 float array of RGB color values which define the starting color to update most recently visited nodes with.  |[0.0,1.0,0.5]
+|startSize |The size an element should be when it is most recently visited. |20
 |colorToFade |A single char from the set `{r,g,b,R,G,B}` determining which color to fade for vertices visited in prior steps |g
 |colorFadeRate |A float value in the range `(0.0,1.0]` which is multiplied against the current `colorToFade` value for prior vertices; a `1.0` value effectively turns off the color fading of prior step visited vertices |0.7
+|visualTraversal |Creates a `TraversalSource` variable in the Console named `vg` which can be used for visualizing traversals. This configuration option takes two parameters.  The first is required and is the name of the `Graph` instance variable that will generate the `TraversalSource`.  The second parameter is the variable name that the `TraversalSource` should have when referenced in the Console.  If left unspecified, this value defaults to `vg`.
 |=========================================================
 
 [[server-plugin]]