Adding in 3D graph visualization as an advanced visualization (#737)

* Multiple relationships between nodes in 3D graph & self-loops

* Refactoring graph code

* Renamed files for graph visualization interface

* Refactored 2D/3D graph to share a common base

* Enabled report actions

* Finalized 3D graph code

* Added docs for 3D graph

* Fixed non-https placeholder for advanced setting

* Actions/rule-based styling for 3d graph

docs/modules/ROOT/nav.adoc

@@ -9,6 +9,7 @@
 *** xref:user-guide/reports/bar-chart.adoc[Bar Chart]
 *** xref:user-guide/reports/pie-chart.adoc[Pie Chart]
 *** xref:user-guide/reports/line-chart.adoc[Line Chart]
+*** xref:user-guide/reports/graph3d.adoc[3D Graph]
 *** xref:user-guide/reports/sunburst.adoc[Sunburst]
 *** xref:user-guide/reports/circle-packing.adoc[Circle Packing]
 *** xref:user-guide/reports/choropleth.adoc[Choropleth]

docs/modules/ROOT/pages/user-guide/extensions/advanced-visualizations.adoc

@@ -5,7 +5,7 @@ For specific use-cases, these visualizations may convey information that a simpl
 To use advanced visualizations, enable them in the **Extensions Window**. This makes them selectable inside reports, as well as add examples to the Example window.
 
 The following visualizations are part of this extension:
-
+- A link:../../reports/graph3d[3D Graph] to visualize a graph in three dimensions.
 - A link:../../reports/sankey[Sankey Chart] to visualize flows.
 - Three charts to plot hierarchical data (link:../../reports/sunburst[Sunburst], link:../../reports/circle-packing[Circle Packing], link:../../reports/treemap[Treemap])
 - A link:../../reports/gauge-chart[Gauge Chart] to show percentages.

docs/modules/ROOT/pages/user-guide/reports/graph.adoc

@@ -26,7 +26,7 @@ RETURN p, a, m
 
 image::graph.png[Basic Graph]
 
-== Virtual Graph (apoc is required)
+== Virtual Graph
 
 ....
 MATCH (p:Person)-[:ACTED_IN]->(m:Movie)<-[:ACTED_IN]-(p2:Person)

docs/modules/ROOT/pages/user-guide/reports/graph3d.adoc

@@ -0,0 +1,135 @@
+= 3D Graph
+
+link:../../extensions/advanced-visualizations[label:Advanced Visualization[]]
+
+The 3D graph report extends the default graph visualization with another dimensions.
+It supports ~95% of the features & customizations for the regular (2D) graph, including rule-based styling and report actions.
+
+== Examples
+
+=== Basic Graph
+
+....
+MATCH (p:Person)-[a:ACTED_IN]->(m:Movie)
+WHERE m.title = 'The Matrix'
+RETURN p, a, m
+....
+
+image::graph3d.png[Basic 3D Graph]
+
+== Virtual Graph
+
+....
+MATCH (p:Person)-[:ACTED_IN]->(m:Movie)<-[:ACTED_IN]-(p2:Person)
+WHERE m.title = "The Matrix"
+RETURN p, p2, apoc.create.vRelationship(p, "KNOWS", {}, p2)
+....
+
+image::graph3dvirtual.png[Virtual 3D Graph]
+
+== Advanced Settings
+
+[width="100%",cols="12%,2%,3%,83%",options="header",]
+|===
+|Name |Type |Default Value |Description
+|Node Color Scheme |List |neodash |The color scheme to use for the node
+labels. Colors are assigned automatically (consequitevely) to the
+different labels returned by the Cypher query.
+
+|Node Label Color |Text |black |The color of the labels drawn on the
+nodes.
+
+|Node Label Font Size |Number |3.5 |Size of the labels drawn on the
+nodes.
+
+|Node Size |Number |2 |Default size of a node in the graph
+visualization. This size is applied if no custom size styling is defined
+and no Rule-Based styling is active.
+
+|Node Size Property |Text |size |Optionally, the name of the node
+property to map to the node size. This lets you define sizes on a
+node-specific level, if you have a property that directly maps to the
+numeric size value.
+
+|Node Color Property |Text |color |Optionally, the name of the node
+property to map to the node color. This lets you define colors on a
+node-specific level, if you have a property that directly maps to the
+HTML color value.
+
+|Relationship Color |Text |#a0a0a0 |The color used for drawing the
+relationship arrows in the visualization.
+
+|Relationship Width |Text |1 |The (default) width of the relationship
+arrows in the visualization.
+
+|Relationship Label Color |Text |#a0a0a0 |The color of the labels
+(relationship type) drawn next to the relationship arrows.
+
+|Relationship Label Font Size |Text |2.75 |The font size of the labels
+(relationship type) drawn next to the relationship arrows.
+
+|Relationship Color Property |Text |color |Optionally, the name of the
+relationship property to map to the arrow color. This lets you define
+colors on a relationship-specific level, if you have a property that
+directly maps to the HTML color value.
+
+|Relationship Width Property |Text |width |Optionally, the name of the
+relationship property to map to the arrow width. This lets you define
+widths on a relationship-specific level, if you have a property that
+directly maps to the width value.
+
+|Animated Particles on Relationships |on/off |off |If enabled, draw
+relationships with animated particles on them, moving in the direction
+of the relationship.
+
+|Arrow head size |Number |3 |Use this to set the length of the arrow head, size is adjusted automatically.
+If 0, no arrow will be drawn.
+
+|Background Color |Text |#fafafa |The background color of the
+visualization.
+
+|Layout (experimental) |List |force-directed |tree-top-down |tree-bottom-up |tree-left-right |tree-right-left |radial | Use this to switch from
+the main (force-directed) layout to one of the experimental layouts
+(tree, radial). For the experimental layouts, make sure
+your graph is a DAG (directed acyclic graph).
+
+| Graph Depth Separation | Number | 30 | Specify the level distance for the tree layout. 
+This setting controls the separation between different levels in the tree hierarchy. Adjusting this value impacts the overall spacing of the tree layout in your graph visualization.
+
+|Enable graph exploration |on/off |on |Enables basic exploration functionality for the graph. Exploration can be done by right clicking on a node, and choosing 'Expand' to choose a type to traverse. Data is retrieved real-time and not cached in the visualization.
+
+|Enable graph editing |on/off |off |Enables editing of nodes and relationships in the graph from the right-click context menu. In addition, lets users create new relationships with existing types/property keys as present in the database.
+
+|Show pop-up on Hover |on/off |on |if enabled, shows a pop-up when a
+user hovers over one of the nodes/relationships in the visualization.
+The pop-up contains the label and properties of the node/relationship.
+
+|Show properties on Click |on/off |on |if enabled, opens up a window
+when a user clicks on one of the nodes/relationships in the
+visualization. The window contains the label and properties of the
+node/relationship.
+
+|Drilldown Link |Text (URL) |(no value) |Specifying a URL here will
+display a floating button on the top right of the visualization. This
+button can be used to drilldown into a different tool (e.g. Bloom) so
+that the graph can be explored further. Dynamic Dashboard Parameters
+(e.g. $neodash_person_name) can be used in these links as well.
+
+|Hide Selections |on/off |off |If enabled, hides the property selector
+(footer of the visualization).
+
+|Override no data message |Text |Query returned no data. |Override the message displayed to the user when their query returns no data.
+
+|Auto-run query |on/off |on |when activated automatically runs the query
+when the report is displayed. When set to `off', the query is displayed
+and will need to be executed manually.
+|Report Description |markdown text | | When specified, adds another button the report header that opens a pop-up. This pop-up contains the rendered markdown from this setting. 
+|===
+
+== Rule-Based Styling
+
+Using the link:../#_rule_based_styling[Rule-Based Styling] menu, the
+following style rules can be applied to the graph: 
+
+- The background color of a node. 
+- The label color of a node.

docs/modules/ROOT/pages/user-guide/reports/index.adoc

@@ -93,6 +93,7 @@ pages:
 - link:bar-chart[Bar Chart]
 - link:pie-chart[Pie Chart] 
 - link:line-chart[Line Chart] 
+- link:graph3d[3D Graph]
 - link:sunburst[Sunburst]
 - link:circle-packing[Circle Packing] 
 - link:treemap[Treemap]

package.json

@@ -81,6 +81,7 @@
     "react-cool-dimensions": "^2.0.7",
     "react-dom": "^17.0.2",
     "react-force-graph-2d": "^1.23.8",
+    "react-force-graph-3d": "^1.24.1",
     "react-gauge-chart": "^0.4.1",
     "react-grid-layout": "^1.3.4",
     "react-leaflet": "^3.2.5",
@@ -97,6 +98,8 @@
     "remark-gfm": "^3.0.1",
     "reselect": "^4.1.8",
     "tailwindcss": "^3.3.2",
+    "three": "^0.159.0",
+    "three-spritetext": "^1.8.1",
     "use-neo4j": "^0.3.13",
     "yaml": "^2.2.1"
   },

src/chart/graph/GraphChart.tsx

@@ -21,18 +21,27 @@ import { getSettings } from '../SettingsUtils';
 import { getPageNumbersAndNamesList } from '../../extensions/advancedcharts/Utils';
 import { CloudArrowDownIconOutline } from '@neo4j-ndl/react/icons';
 
+export interface GraphChartProps extends ChartProps {
+  lockable?: boolean;
+  component?: any;
+}
+
+const DEFAULT_VISUALIZATION_COMPONENT = NeoGraphChartVisualization2D;
+
 /**
  * Draws graph data using a force-directed-graph visualization.
  * This visualization is powered by `react-force-graph`.
  * See https://github.com/vasturiano/react-force-graph for examples on customization.
  */
-const NeoGraphChart = (props: ChartProps) => {
+const NeoGraphChart = (props: GraphChartProps) => {
   if (props.records == null || props.records.length == 0 || props.records[0].keys == null) {
     return <>No data, re-run the report.</>;
   }
+  const Visualization = props.component ? props.component : DEFAULT_VISUALIZATION_COMPONENT;
 
   // Retrieve config from advanced settings
   const settings = getSettings(props.settings, props.extensions, props.getGlobalParameter);
+  const lockable = props.lockable !== undefined ? props.lockable : true;
   const linkDirectionalParticles = props.settings && props.settings.relationshipParticles ? 5 : undefined;
   const arrowLengthProp = props?.settings?.arrowLengthProp ?? 3;
   let nodePositions = props.settings && props.settings.nodePositions ? props.settings.nodePositions : {};
@@ -217,7 +226,7 @@ const NeoGraphChart = (props: ChartProps) => {
   }, [props.records]);
 
   return (
-    <div ref={observe} style={{ width: '100%', height: '95%' }}>
+    <div ref={observe} style={{ width: '100%', height: '100%' }}>
       <NeoGraphChartCanvas>
         <IconButtonArray
           aria-label={'graph icon'}
@@ -227,10 +236,10 @@ const NeoGraphChart = (props: ChartProps) => {
         >
           <GraphChartContextMenu {...chartProps} />
           <NeoGraphChartFitViewButton {...chartProps} />
-          {settings.lockable ? <NeoGraphChartLockButton {...chartProps} /> : <></>}
+          {lockable && settings.lockable ? <NeoGraphChartLockButton {...chartProps} /> : <></>}
           {settings.drilldownLink ? <NeoGraphChartDeepLinkButton {...chartProps} /> : <></>}
         </IconButtonArray>
-        <NeoGraphChartVisualization2D {...chartProps} />
+        <Visualization {...chartProps} />
         <NeoGraphChartInspectModal {...chartProps}></NeoGraphChartInspectModal>
         {settings.allowDownload && props.records && props.records.length > 0 ? (
           <IconButtonArray floating orientation='horizontal' className='n-z-10 n-absolute n-bottom-2 n-left-4'>

src/chart/graph/GraphChartVisualization.ts

@@ -143,6 +143,22 @@ export interface GraphChartVisualizationProps {
     customTablePropertiesOfModal: any[];
     pageIdAndParameterName: string;
   };
+  /**
+   * A set of configuration parameters used for the visualization engine.
+   */
+  config?: {
+    graphComponent: any;
+    cooldownAfterengineStop: number;
+    nodeCanvasObjectMode?: () => void;
+    nodeCanvasObject?: (node: any, ctx: any) => void;
+    linkCanvasObjectMode?: () => void;
+    linkCanvasObject?: (link: any, ctx: any) => void;
+    nodeThreeObjectExtend?: boolean;
+    nodeThreeObject?: (node) => void;
+    linkThreeObjectExtend?: boolean;
+    linkThreeObject?: (link) => void;
+    linkPositionUpdate?: (sprite: any, { start, end }: { start: any; end: any }, link: any, ref: any) => void;
+  };
   /**
    * entries in 'extensions' let users plug in extra functionality into the visualization based on enabled plugins.
    */

src/chart/graph/GraphChartVisualization2D.tsx

@@ -5,103 +5,33 @@ import { getTooltip } from './component/GraphChartTooltip';
 import { GraphChartVisualizationProps } from './GraphChartVisualization';
 import { generateNodeCanvasObject } from './util/NodeUtils';
 import { generateRelCanvasObject } from './util/RelUtils';
+import { NeoGraphChartVisualizationBase } from './GraphChartVisualizationBase';
 
 /*
- * TODO: check if makes sense to change zoom logic from panning to buttons
- * (when i scroll the graphCharts has the priority )
+ *
  */
 export const NeoGraphChartVisualization2D = (props: GraphChartVisualizationProps) => {
-  const fgRef: React.MutableRefObject<any> = useRef();
-
-  if (!props.style.width || !props.style.height) {
-    return <></>;
-  }
-  props.interactivity.zoomToFit = () => fgRef.current && fgRef.current.zoomToFit(400);
-
-  return (
-    <ForceGraph2D
-      ref={fgRef}
-      width={props.style.width - 20}
-      height={props.style.height}
-      linkCurvature='curvature'
-      backgroundColor={props.style.backgroundColor}
-      linkDirectionalArrowLength={props.style.linkDirectionalArrowLength}
-      linkDirectionalArrowRelPos={1}
-      dagMode={props.engine.layout}
-      dagLevelDistance={props.engine.graphDepthSep}
-      linkWidth={(link: any) => link.width}
-      linkLabel={(link: any) => (props.interactivity.showPropertiesOnHover ? `<div>${getTooltip(link)}</div>` : '')}
-      nodeLabel={(node: any) => (props.interactivity.showPropertiesOnHover ? `<div>${getTooltip(node)}</div>` : '')}
-      nodeVal={(node: any) => node.size}
-      onNodeClick={(item) => {
-        let rules = getRuleWithFieldPropertyName(item, props.extensions.actionsRules, 'onNodeClick', 'labels');
-        rules != null
-          ? rules.forEach((rule) => executeActionRule(rule, item, { ...props.interactivity }))
-          : props.interactivity.onNodeClick(item);
-      }}
-      onLinkClick={(item) => {
-        let rules = getRuleWithFieldPropertyName(item, props.extensions.actionsRules, 'onLinkClick', 'type');
-        rules != null
-          ? rules.forEach((rule) => executeActionRule(rule, item, props.interactivity.setGlobalParameter))
-          : props.interactivity.onRelationshipClick(item);
-      }}
-      onNodeRightClick={(node, event) => props.interactivity.onNodeRightClick(node, event)}
-      onLinkRightClick={(link, event) => props.interactivity.onRelationshipRightClick(link, event)}
-      onBackgroundClick={() => props.interactivity.onNodeClick(undefined)}
-      onBackgroundRightClick={() => props.interactivity.onNodeClick(undefined)}
-      linkLineDash={(link) => (link.new ? [2, 1] : null)}
-      linkDirectionalParticles={props.style.linkDirectionalParticles}
-      linkDirectionalParticleSpeed={props.style.linkDirectionalParticleSpeed}
-      cooldownTicks={props.engine.cooldownTicks}
-      onEngineStop={() => {
-        props.engine.setCooldownTicks(0);
-        if (props.engine.recenterAfterEngineStop) {
-          fgRef.current.zoomToFit(400);
-          props.engine.setRecenterAfterEngineStop(false);
-        }
-      }}
-      onZoom={() => {
-        props.interactivity.setContextMenuOpen(false);
-      }}
-      onNodeDrag={() => {
-        props.interactivity.setContextMenuOpen(false);
-        props.engine.setCooldownTicks(1);
-        props.engine.setRecenterAfterEngineStop(false);
-      }}
-      onNodeDragEnd={(node) => {
-        props.engine.setCooldownTicks(0);
-        if (props.interactivity.fixNodeAfterDrag) {
-          node.fx = node.x;
-          node.fy = node.y;
-        }
-        if (props.interactivity.layoutFrozen) {
-          const key = node.id;
-          const val = [node.x, node.y];
-          const old = { ...props.interactivity.nodePositions };
-          old[key] = val;
-          props.interactivity.setNodePositions(old);
-        }
-      }}
-      nodeCanvasObjectMode={() => 'after'}
-      nodeCanvasObject={(node: any, ctx: any) =>
-        generateNodeCanvasObject(
-          node,
-          ctx,
-          props.style.nodeIcons,
-          props.interactivity.layoutFrozen,
-          props.interactivity.nodePositions,
-          props.style.nodeLabelFontSize,
-          props.style.defaultNodeSize,
-          props.style.nodeLabelColor,
-          props.extensions.styleRules,
-          props.engine.selection
-        )
-      }
-      linkCanvasObjectMode={() => 'after'}
-      linkCanvasObject={(link: any, ctx: any) =>
-        generateRelCanvasObject(link, ctx, props.style.relLabelFontSize, props.style.relLabelColor)
-      }
-      graphData={props.style.width ? { nodes: props.data.nodes, links: props.data.links } : { nodes: [], links: [] }}
-    />
-  );
+  const config2d = {
+    graphComponent: ForceGraph2D,
+    cooldownAfterengineStop: 0,
+    nodeCanvasObjectMode: () => 'after',
+    nodeCanvasObject: (node: any, ctx: any) =>
+      generateNodeCanvasObject(
+        node,
+        ctx,
+        props.style.nodeIcons,
+        props.interactivity.layoutFrozen,
+        props.interactivity.nodePositions,
+        props.style.nodeLabelFontSize,
+        props.style.defaultNodeSize,
+        props.style.nodeLabelColor,
+        props.extensions.styleRules,
+        props.engine.selection
+      ),
+    linkCanvasObjectMode: () => 'after',
+    linkCanvasObject: (link: any, ctx: any) =>
+      generateRelCanvasObject(link, ctx, props.style.relLabelFontSize, props.style.relLabelColor),
+  };
+  const props2d = { ...props, config: config2d };
+  return <NeoGraphChartVisualizationBase {...props2d} />;
 };