From e91f9efba279ac40f9cbd45686f97ca05079e868 Mon Sep 17 00:00:00 2001
From: Paul Brodersen <paulbrodersen@gmail.com>
Date: Thu, 18 Apr 2024 12:03:59 +0100
Subject: [PATCH] Add line actor (#334)

* Implement Line actor class

* Add Line actor to imports in actors.__init__.py

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add minimal-ish, reproducible example of the Line actor class

* Add Line actor test

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Expand documentation of color specification

* Remove reference to atlas resolution

* Indicate how path coordinates were pre-computed.

* Retain references to instantiated actors.

* Replace ABA ID with corresponding abbreviation.

* Format array in line with the pre-commit style.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 brainrender/actors/__init__.py |  1 +
 brainrender/actors/line.py     | 22 ++++++++++++++++
 examples/line.py               | 48 ++++++++++++++++++++++++++++++++++
 tests/test_line.py             | 24 +++++++++++++++++
 4 files changed, 95 insertions(+)
 create mode 100644 brainrender/actors/line.py
 create mode 100644 examples/line.py
 create mode 100644 tests/test_line.py

diff --git a/brainrender/actors/__init__.py b/brainrender/actors/__init__.py
index 969a57d6..b15cd725 100644
--- a/brainrender/actors/__init__.py
+++ b/brainrender/actors/__init__.py
@@ -4,3 +4,4 @@
 from brainrender.actors.cylinder import Cylinder
 from brainrender.actors.volume import Volume
 from brainrender.actors.streamlines import Streamlines
+from brainrender.actors.line import Line
diff --git a/brainrender/actors/line.py b/brainrender/actors/line.py
new file mode 100644
index 00000000..d7ce8cb6
--- /dev/null
+++ b/brainrender/actors/line.py
@@ -0,0 +1,22 @@
+from vedo import shapes
+
+from brainrender.actor import Actor
+
+
+class Line(Actor):
+    def __init__(
+        self, coordinates, color="black", alpha=1, linewidth=2, name=None
+    ):
+        """
+        Creates an actor representing a single line.
+
+        :param coordinates: list, np.ndarray with shape (N, 3) of ap, dv, ml coordinates.
+        :param color: CSS named color str, hex code, or RGB tuple, e.g. "white", "#ffffff", or (255, 255, 255)
+        :param alpha: float in range 0.0 to 1.0
+        :param linewidth: float
+        :param name: str
+        """
+
+        # Create mesh and Actor
+        mesh = shapes.Line(p0=coordinates, lw=linewidth, c=color, alpha=alpha)
+        Actor.__init__(self, mesh, name=name, br_class="Line")
diff --git a/examples/line.py b/examples/line.py
new file mode 100644
index 00000000..f6f40497
--- /dev/null
+++ b/examples/line.py
@@ -0,0 +1,48 @@
+import numpy as np
+import vedo
+
+vedo.settings.default_backend = "vtk"
+
+from brainrender import Scene
+from brainrender.actors import Points, Line
+
+# Display the Allen Brain mouse atlas.
+scene = Scene(atlas_name="allen_mouse_25um")
+
+# Highlight the cerebral cortex.
+scene.add_brain_region("CTX", alpha=0.2, color="green")
+
+# Add two points identifying the positions of two cortical neurons.
+point_coordinates = np.array([[4575, 5050, 9750], [4275, 2775, 6100]])
+
+points = Points(point_coordinates, radius=100, colors="blue")
+scene.add(points)
+
+# Display the shortest path within cortex between the two points.
+# The path was pre-calculated with https://github.com/seung-lab/dijkstra3d/.
+path_coordinates = np.array(
+    [
+        [4575, 5050, 9750],
+        [4575, 4800, 9500],
+        [4575, 4550, 9250],
+        [4575, 4300, 9000],
+        [4575, 4050, 8750],
+        [4350, 3800, 8500],
+        [4225, 3550, 8250],
+        [4200, 3300, 8000],
+        [4200, 3100, 7750],
+        [4200, 2950, 7500],
+        [4200, 2800, 7250],
+        [4200, 2700, 7000],
+        [4200, 2650, 6750],
+        [4200, 2650, 6500],
+        [4200, 2650, 6250],
+        [4275, 2775, 6100],
+    ]
+)
+
+line = Line(path_coordinates, linewidth=3, color="black")
+scene.add(line)
+
+# Render the scene and display the figure.
+scene.render()
diff --git a/tests/test_line.py b/tests/test_line.py
new file mode 100644
index 00000000..f6aab799
--- /dev/null
+++ b/tests/test_line.py
@@ -0,0 +1,24 @@
+import numpy as np
+
+from brainrender import Scene
+from brainrender.actor import Actor
+from brainrender.actors import Line
+
+
+def test_line():
+    s = Scene()
+
+    line = Line(
+        np.array(
+            [
+                [0, 0, 0],
+                [1, 1, 1],
+                [2, 2, 2],
+            ]
+        )
+    )
+
+    s.add(line)
+    assert isinstance(line, Actor)
+
+    del s