= 3D Renderer (In Beta) =

This is a plugin for Cytoscape 3 that is capable of replacing the default Ding 2D renderer with a 3D renderer. Underneath, it uses the [[http://en.wikipedia.org/wiki/Java_OpenGL|JOGL library]] which allows access to C/C++ based OpenGL libraries from Java. The renderer is currently under development.

{{attachment:screenshot-0.57.2.png}}

== Current Features ==

 * Node and edge manipulation, addition/removal
 * 3D camera movement and rotation
 * Interactive bird's eye view
 * Basic visual properties: node shapes, edge line types, edge widths, color
 * Integration with visual style editor/previewer
 * Node label rendering

== Download ==

Windows: [[attachment:cytoscape-windows-3.0.0-M4-SNAPSHOT-3d-0.6.zip]]

Mac, Linux, UNIX OS: [[attachment:cytoscape-unix-3.0.0-M4-SNAPSHOT-3d-0.6.tar.gz]]

== Installation ==

Windows: Extract the .zip file and run cytoscape.bat.

Mac, Linux, UNIX OS: Extract the .tar.gz file and run cytoscape.sh.

== Bird's eye view ==

Under the Network tab to the left, click or drag the mouse on the bird's eye view display to move the main camera

== Visual Properties and VizMapper ==

For node shapes, the following settings in VizMapper will give the following results:

|| '''VizMapper setting''' || '''3D result''' ||
|| Ellipse || Sphere ||
|| Diamond || Cube ||
|| Triangle || Tetrahedron ||

(New as of v0.52) For edge line types, the following settings give the following results:

|| '''VizMapper setting''' || '''3D result''' ||
|| Solid || Regular edges ||
|| Equal Dash || Dashed edges ||
|| Dots || Dotted edges ||

=== Camera Controls ===

Movement:

|| W || Move up ||
|| A || Move left ||
|| S || Move down ||
|| D || Move right ||
|| E || Move forward ||
|| Q || Move backward ||

Rotation:

|| Z || Roll camera clockwise ||
|| X || Roll camera counter-clockwise ||
|| Shift + Left || Rotate about Y-Axis, towards the left ||
|| Shift + Right || Rotate about Y-Axis, towards the right ||
|| Shift + Up || Rotate about X-Axis, upwards ||
|| Shift + Down || Rotate about X-Axis, downwards ||

First-person camera turning:

|| Left || Turn camera left ||
|| Right || Turn camera right ||
|| Up || Tilt camera upwards ||
|| Down || Tilt camera downwards ||

=== Network Manipulation Controls ===

Node, edge addition and removal:
|| N || Creates a new node under the mouse cursor ||
|| J || Creates a new edge between currently selected nodes and the node currently under the mouse cursor ||
|| Delete || Removes currently selected nodes and edges ||

'''Selection''':
 * Drag the mouse to select objects, or click on nodes to select them.
 * Hold SHIFT to add additional objects to the current selection.

'''Node dragging''':
 * Hold CTRL and drag the mouse to move currently selected nodes.

=== Miscellaneous Controls ===

|| K || Toggle frames-per-second display at bottom left of network window ||
|| L || Toggle rendering all node labels or only labels of selected nodes and nodes under the mouse cursor ||

== Currently Supported Visual Properties ==

Nodes:
 * Node fill color
 * Node shape
 * Node dimensions: width, height, depth (as of v0.55)
 * Node labels (v0.57)

Edges:
 * Edge fill color
 * Edge line type (new in v0.52)
 * Edge line width

Network:
 * Network background color (as of v0.55)

Lighting (Under "Network" category)
 * Light ambient, diffuse, specular colors
 * Light position (x, y, z)

== Planned Features ==

 * Faster rendering speed
 * More complete set of supported visual properties
 * Add additional node shapes and edge styles as needed
 * Additional 3D layouts
 * Incorporation of different lighting setups to Cytoscape visual styles, and possibly addition of preset lighting configurations to existing visual styles

== Source Code ==

The source code for the 3D renderer plugin may be found at the following SVN repository: http://chianti.ucsd.edu/svn/csplugins/trunk/toronto/yuedong/paperwing-impl

== Known Issues ==

 * Node labels may not edit properly when attempting to change them through VizMapper.
 * For areas containing densely packed edges, some edges may appear to flicker when viewed from a distance
 * Cytoscape sometimes hangs on start-up (not known if this error is specific to the 3D renderer, but attempt to resolve by restarting Cytoscape)
 * Bird's eye view may not show all nodes if the nodes are too far away from the bird's eye camera. This is caused by very wide networks.

== Cytoscape Redmine Page ==

The Redmine page for the renderer is: http://code.cytoscape.org/redmine/projects/3d-renderer

== Contact ==

I can be found in my post on the Cytoscape mailing list: http://groups.google.com/group/cytoscape-discuss/browse_thread/thread/aae8bb3d265d0ced

== Version History ==

=== March 30, 2012 ===
v0.6
 * Spherical, box, grid 3D layouts available under Layouts > 3D Layouts in the menu
 * Toolbar buttons such as zoom in/out, zoom to extents, select first neighbors, and invert node selection now supported
 * Renderer now pauses rendering unless a button is clicked or a button is pressed to conserve CPU/GPU and battery resources

=== March 19, 2012 ===
v0.58
 * Right-click pop up menu added with similar capabilities as default 2D renderer
 * Framerate increased by approximately 50% via TextRenderer implementation change and re-using edge segment coordinates
 * Pressing K toggles frames per second display at bottom left of window
 * Network lighting properties for a single light editable via VizMapper and the visual style editor: light coordinates, ambient, diffuse, and specular color components
 * When multiple network windows are open, inactive network viewing windows will now pause rendering

=== March 5, 2012 ===

v0.57.2
 * Reduced shininess of edges and nodes by a small amount (hopefully shininess will be a customizable property in the future)
 * JOGL library version upgraded from 2.0-b23-20110303 to 2.0-b48-20120215
 * Fixed memory leak-related slowdown caused by text rendering mechanism

=== February 11, 2012 ===

v0.57.1
 * Fixed dependency error during start-up

=== February 10, 2012 ===
v0.57
 * Re-implemented node label rendering; text now always faces camera and has persistent size
 * Slightly tweaked selected node and edge color
 * Fixed crash when switching between multiple network windows
 * Slightly increased radius of circular edges going from a node to itself to decrease stacking when multiple self-edges are present on the same node

=== February 6, 2012 ===
v0.55
 * Added support for previewing and editing visual styles via the VizMapper panel
 * Decreased lighting on edges to give a slightly cleaner appearance
 * Added support for the following visual properties: node width, height, and depth; network background color
 * Node label rendering temporarily disabled while a way to rotate the text to face the camera is found
 * Performed a bit of cleanup on the output messages from the console

=== January 31, 2012 ===

v0.52
 * Added support for drawing edges that lead from a node to itself
 * Added support for the following edge line types: dashes, dots, solid lines
 * Adjusted the mouse wheel zoom function to no longer move the center of rotation for shift + arrow key rotates
 * Node creation now places nodes at a fixed distance from the camera
 
=== January 24, 2012 ===

v0.5: Initial beta release