From 26364be13687c871a2ec70c779be4e137f7cd97c Mon Sep 17 00:00:00 2001
From: Robert Chisholm <robadob@robadob.org>
Date: Sat, 19 Oct 2024 18:59:45 +0100
Subject: [PATCH] Document graph visualisation additions

See https://github.com/FLAMEGPU/FLAMEGPU2/pull/1239
---
 src/guide/visualisation/adding-details.rst    | 38 ++++++++++++++++++-
 src/guide/visualisation/setting-up-vis.rst    |  3 ++
 .../visualisation/visualising-agents.rst      |  4 +-
 3 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/src/guide/visualisation/adding-details.rst b/src/guide/visualisation/adding-details.rst
index 7db61bc43..f50cbcf29 100644
--- a/src/guide/visualisation/adding-details.rst
+++ b/src/guide/visualisation/adding-details.rst
@@ -77,7 +77,42 @@ The below image demonstrates how the above interface appears during a visualisat
 .. note::
 
   It is not possible to add multiple inputs for the same environment property or environment array property element to the same panel.
+  
+Environment Directed Graphs
+---------------------------
+
+FLAME GPU visualisations provide basic visualisation support for graphs defined within a model's environment.
+
+When configuring the visualisation, graphs to be rendered can be specified by name. Following this, their vertex properties which correspond to the spatial coordinates and :ref:`desired color<static-colors>` should be specified. The graph will then be rendered with the simulation, and will update whenever it is modified via the host API.
+
+.. tabs::
+
+  .. code-tab:: cpp C++
 
+    // Configure the visualisation
+    flamegpu::visualiser::ModelVis m_vis = cudaSimulation.getVisualisation();
+    // Mark and configure graph "mygraph" for visualisation
+    flamegpu::visualiser::EnvironmentGraphVis g = visualisation.addGraph("mygraph");
+    g.setColor(flamegpu::visualiser::Color{"#ff0000"});
+    g.setXProperty("x");
+    g.setYProperty("y");
+    // g.setZProperty("z");
+    // g.setXYProperty("xy");
+    // g.setXYZProperty("xyz");
+    
+  .. code-tab:: py Python
+
+    # Configure the visualisation
+    m_vis = cudaSimulation.getVisualisation();
+    # Mark and configure graph "mygraph" for visualisation
+    g = visualisation.addGraph("mygraph")
+    g.setColor(pyflamegpu.Color("#ff0000"))
+    g.setXProperty("x")
+    g.setYProperty("y")
+    # g.setZProperty("z")
+    # g.setXYProperty("xy")
+    # g.setXYZProperty("xyz")
+    
 
 Lines
 -----
@@ -166,4 +201,5 @@ Related Links
 * Full API documentation for :class:`ModelVis<flamegpu::visualiser::ModelVis>`
 * Full API documentation for :class:`PanelVis<flamegpu::visualiser::PanelVis>`
 * Full API documentation for :class:`LineVis<flamegpu::visualiser::LineVis>`
-* Full API documentation for :class:`StaticModelVis<flamegpu::StaticModelVis>`
\ No newline at end of file
+* Full API documentation for :class:`StaticModelVis<flamegpu::StaticModelVis>`
+* Full API documentation for :class:`ModelVis<flamegpu::visualiser::EnvironmentGraphVis>`
\ No newline at end of file
diff --git a/src/guide/visualisation/setting-up-vis.rst b/src/guide/visualisation/setting-up-vis.rst
index 466e55d96..9f1b134dd 100644
--- a/src/guide/visualisation/setting-up-vis.rst
+++ b/src/guide/visualisation/setting-up-vis.rst
@@ -61,6 +61,9 @@ The most important of these settings are presented below:
    * - :func:`setInitialCameraTarget()<flamegpu::visualiser::ModelVis::setInitialCameraTarget>`
      - ``x``, ``y``, ``z``
      - Sets the initial target that the visualisation's 'camera' faces. (Defaults to the origin [0,0,0])
+   * - :func:`setInitialCameraRoll()<flamegpu::visualiser::ModelVis::setInitialCameraRoll>`
+     - ``roll``
+     - Sets the initial roll angle of the camera in radians. (Defaults to 0)
    * - :func:`setSimulationSpeed()<flamegpu::visualiser::ModelVis::setSimulationSpeed>`
      - ``speed``
      - Sets the speed of camera movement, in units travelled per millisecond. (Defaults to 0.05)
diff --git a/src/guide/visualisation/visualising-agents.rst b/src/guide/visualisation/visualising-agents.rst
index 7484bbe83..b83b98b45 100644
--- a/src/guide/visualisation/visualising-agents.rst
+++ b/src/guide/visualisation/visualising-agents.rst
@@ -252,11 +252,13 @@ First you should set the base model scale (with :func:`setModelScale()<flamegpu:
     # Or, set agent scale multiplier with a single float[3] variable
     boid_agt.setScaleXYZVariable("scale_xyz")
 
-    
+
 Agent Color
 -----------
 There are a wide range of options for controlling the color of agent models.
 
+.. _static-colors:
+
 Static Colors
 ^^^^^^^^^^^^^