iplotx 0.10.0__tar.gz → 0.11.0__tar.gz

{iplotx-0.10.0 → iplotx-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 0.10.0
+Version: 0.11.0
 Summary: Plot networkx from igraph and networkx.
 Project-URL: Homepage, https://github.com/fabilab/iplotx
 Project-URL: Documentation, https://readthedocs.org/iplotx

{iplotx-0.10.0 → iplotx-0.11.0}/docs/source/sg_execution_times.rst

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:00.060** total execution time for 73 files **from all galleries**:
+**00:00.114** total execution time for 73 files **from all galleries**:
 
 .. container::
 
@@ -33,7 +33,7 @@ Computation times
      - Time
      - Mem (MB)
    * - :ref:`sphx_glr_gallery_basic_plot_3d.py` (``../../gallery/basic/plot_3d.py``)
-     - 00:00.060
+     - 00:00.114
      - 0.0
    * - :ref:`sphx_glr_gallery_basic_plot_basic.py` (``../../gallery/basic/plot_basic.py``)
      - 00:00.000

iplotx-0.11.0/gallery/basic/plot_3d.py

@@ -0,0 +1,59 @@
+"""
+3D layouts
+==========
+
+This example shows how to visualise graphs or networks in 3D using `iplotx`. Of course, a 3D layout is needed
+for this. Here, we use the Fruchterman-Reingold layout algorithm from ``igraph`` to generate a 3D layout.
+
+.. note::
+    3D visualisation is most useful when used **interactively**, so you can rotate and pan the plot to inspect
+    it from different angles. Matplotlib supports this both in Jupyter notebooks and in IPython via
+    multiple interactive backends (e.g., TkAgg, Qt5Agg, etc.). These plots can also be saved as static
+    images (the ones you see below were generated this way), however these static images can be quite
+    difficult to interpret.
+"""
+
+import igraph as ig
+import iplotx as ipx
+
+# Make the graph
+g = ig.Graph.Erdos_Renyi(30, m=50)
+
+# Make a 3D layout
+layout = g.layout_fruchterman_reingold_3d()
+
+# Visualise the graph in 3D
+ipx.network(
+    g,
+    layout,
+    vertex_alpha=0.7,
+    edge_alpha=0.4,
+    figsize=(8, 8),
+)
+
+# %%
+# Below is a variation using arrows and vertex labels:
+
+import igraph as ig
+import iplotx as ipx
+
+# Make the graph
+g = ig.Graph.Erdos_Renyi(30, m=50, directed=True)
+
+# Make a 3D layout
+layout = g.layout_fruchterman_reingold_3d()
+
+# Visualise the graph in 3D
+ipx.network(
+    g,
+    layout,
+    vertex_alpha=0.3,
+    edge_alpha=0.5,
+    vertex_labels=True,
+    figsize=(8, 8),
+)
+
+# %%
+# .. warning::
+#    3D visualisation does not support all features of 2D visualisation yet. Curved edges, waypoints, and edge
+#    labels are currently unsupported. PRs are welcome!

iplotx-0.11.0/iplotx/art3d/edge/__init__.py

@@ -0,0 +1,147 @@
+"""
+Module containing code to manipulate edge visualisations in 3D, especially the Edge3DCollection class.
+"""
+
+from mpl_toolkits.mplot3d import Axes3D
+from mpl_toolkits.mplot3d.art3d import (
+    Line3DCollection,
+)
+
+from ...utils.matplotlib import (
+    _forwarder,
+)
+from ...edge import (
+    EdgeCollection,
+)
+from .arrow import (
+    arrow_collection_2d_to_3d,
+)
+from .geometry import (
+    _compute_edge_segments as _compute_single_edge_segments,
+)
+
+
+@_forwarder(
+    (
+        "set_clip_path",
+        "set_clip_box",
+        "set_snap",
+        "set_sketch_params",
+        "set_animated",
+        "set_picker",
+    )
+)
+class Edge3DCollection(Line3DCollection):
+    """Collection of vertex patches for plotting."""
+
+    def get_children(self) -> tuple:
+        children = []
+        if hasattr(self, "_subedges"):
+            children.append(self._subedges)
+        if hasattr(self, "_arrows"):
+            children.append(self._arrows)
+        if hasattr(self, "_label_collection"):
+            children.append(self._label_collection)
+        return tuple(children)
+
+    def set_figure(self, fig) -> None:
+        super().set_figure(fig)
+        for child in self.get_children():
+            child.set_figure(fig)
+
+    @property
+    def axes(self):
+        return Line3DCollection.axes.__get__(self)
+
+    @axes.setter
+    def axes(self, new_axes):
+        Line3DCollection.axes.__set__(self, new_axes)
+        for child in self.get_children():
+            child.axes = new_axes
+
+    _get_adjacent_vertices_info = EdgeCollection._get_adjacent_vertices_info
+
+    def _compute_edge_segments(self):
+        """Compute the edge segments for all edges."""
+        vinfo = self._get_adjacent_vertices_info()
+
+        segments3d = []
+        for vcoord_data in vinfo["offsets"]:
+            segment = _compute_single_edge_segments(
+                vcoord_data,
+            )
+            segments3d.append(segment)
+        self.set_segments(segments3d)
+
+    def _update_before_draw(self) -> None:
+        """Update the collection before drawing."""
+        if isinstance(self.axes, Axes3D) and hasattr(self, "do_3d_projection"):
+            self.do_3d_projection()
+
+        # TODO: Here's where we would shorten the edges to fit the vertex
+        # projections from 3D onto 2D, if we wanted to do that. Because edges
+        # in 3D are chains of segments rathen than splines, the shortening
+        # needs to be done in a different way to how it's done in 2D.
+
+    def draw(self, renderer) -> None:
+        """Draw the collection of vertices in 3D.
+
+        Parameters:
+            renderer: The renderer to use for drawing.
+        """
+        # Prepare the collection for drawing
+        self._update_before_draw()
+
+        # Render the Line3DCollection
+        # NOTE: we are NOT calling EdgeCollection.draw here
+        super().draw(renderer)
+
+        # This sets the labels offsets
+        # TODO: implement labels in 3D (one could copy the function from 2D,
+        # but would also need to promote the 2D labels into 3D labels similarly to
+        # how it's done for 3D vertices).
+        # self._update_labels()
+
+        # Now attempt to draw the arrows
+        for child in self.get_children():
+            child.draw(renderer)
+
+
+def edge_collection_2d_to_3d(
+    col: EdgeCollection,
+    zdir: str = "z",
+    axlim_clip: bool = False,
+):
+    """Convert a 2D EdgeCollection to a 3D Edge3DCollection.
+
+    Parameters:
+        col: The 2D EdgeCollection to convert.
+        zs: The z coordinate(s) to use for the 3D vertices.
+        zdir: The axis to use as the z axis (default is "z").
+        depthshade: Whether to apply depth shading (default is True).
+        axlim_clip: Whether to clip the vertices to the axes limits (default is False).
+    """
+    if not isinstance(col, EdgeCollection):
+        raise TypeError("vertices must be a VertexCollection")
+
+    # NOTE: after this line, none of the EdgeCollection methods will work
+    # It's become a static drawer now. It uses segments instead of paths.
+    col.__class__ = Edge3DCollection
+    col._compute_edge_segments()
+
+    col._axlim_clip = axlim_clip
+
+    # Convert the arrow collection if present
+    if hasattr(col, "_arrows"):
+        segments3d = col._segments3d
+
+        # Fix the x and y to the center of the target vertex (for now)
+        col._arrows._offsets[:] = [segment[-1][:2] for segment in segments3d]
+        zs = [segment[-1][2] for segment in segments3d]
+        arrow_collection_2d_to_3d(
+            col._arrows,
+            zs=zs,
+            zdir=zdir,
+            depthshade=False,
+            axlim_clip=axlim_clip,
+        )

iplotx-0.11.0/iplotx/art3d/edge/arrow.py

@@ -0,0 +1,115 @@
+"""
+Module containing code to manipulate arrow visualisations in 3D, especially the EdgeArrow3DCollection class.
+"""
+
+from typing import (
+    Sequence,
+)
+from math import atan2, cos, sin
+import numpy as np
+from matplotlib import (
+    cbook,
+)
+from mpl_toolkits.mplot3d import Axes3D
+from mpl_toolkits.mplot3d.art3d import (
+    Path3DCollection,
+)
+
+from ...utils.matplotlib import (
+    _forwarder,
+)
+from ...edge.arrow import (
+    EdgeArrowCollection,
+)
+
+
+@_forwarder(
+    (
+        "set_clip_path",
+        "set_clip_box",
+        "set_snap",
+        "set_sketch_params",
+        "set_animated",
+        "set_picker",
+    )
+)
+class EdgeArrow3DCollection(EdgeArrowCollection, Path3DCollection):
+    """Collection of vertex patches for plotting."""
+
+    def _update_before_draw(self) -> None:
+        """Update the collection before drawing."""
+        if (
+            isinstance(self.axes, Axes3D)
+            and hasattr(self, "do_3d_projection")
+            and (self.axes.M is not None)
+        ):
+            self.do_3d_projection()
+
+        # The original EdgeArrowCollection method for
+        # _update_before_draw cannot be used because it
+        # relies on paths, whereas edges are now a
+        # Line3DCollection which uses segments.
+        self.set_sizes(self._sizes, self.get_figure(root=True).dpi)
+
+        if (not hasattr(self, "_z_markers_idx")) or (
+            not isinstance(self._z_markers_idx, np.ndarray)
+        ):
+            return
+
+        trans = self.get_offset_transform().transform
+
+        # The do_3d_projection method above reorders the
+        # arrow offsets in some way, so we might have to figure out
+        # what edge index corres
+        for i, ie in enumerate(self._z_markers_idx):
+            segments_2d = self._edge_collection.get_segments()[ie]
+
+            # We could reset the 3d projection here, might be a way to
+            # skip the function call above.
+            v2 = trans(segments_2d[-1])
+            v1 = trans(segments_2d[-2])
+            dv = v2 - v1
+            theta = atan2(*(dv[::-1]))
+            theta_old = self._angles[i]
+            dtheta = theta - theta_old
+            mrot = np.array([[cos(dtheta), sin(dtheta)], [-sin(dtheta), cos(dtheta)]])
+
+            apath = self._paths[i]
+            apath.vertices = apath.vertices @ mrot
+            self._angles[i] = theta
+
+    def draw(self, renderer) -> None:
+        """Draw the collection of vertices in 3D.
+
+        Parameters:
+            renderer: The renderer to use for drawing.
+        """
+        with self._use_zordered_offset():
+            with cbook._setattr_cm(self, _in_draw=True):
+                EdgeArrowCollection.draw(self, renderer)
+
+
+def arrow_collection_2d_to_3d(
+    col: EdgeArrowCollection,
+    zs: np.ndarray | float | Sequence[float] = 0,
+    zdir: str = "z",
+    depthshade: bool = True,
+    axlim_clip: bool = False,
+):
+    """Convert a 2D EdgeArrowCollection to a 3D EdgeArrow3DCollection.
+
+    Parameters:
+        col: The 2D EdgeArrowCollection to convert.
+        zs: The z coordinate(s) to use for the 3D vertices.
+        zdir: The axis to use as the z axis (default is "z").
+        depthshade: Whether to apply depth shading (default is True).
+        axlim_clip: Whether to clip the vertices to the axes limits (default is False).
+    """
+    if not isinstance(col, EdgeArrowCollection):
+        raise TypeError("vertices must be a EdgeArrowCollection")
+
+    col.__class__ = EdgeArrow3DCollection
+    col._offset_zordered = None
+    col._depthshade = depthshade
+    col._in_draw = False
+    col.set_3d_properties(zs, zdir, axlim_clip)

iplotx-0.10.0/iplotx/edge/geometry3d.py → iplotx-0.11.0/iplotx/art3d/edge/geometry.py

@@ -7,19 +7,14 @@ from typing import (
     Sequence,
 )
 import numpy as np
-import matplotlib as mpl
 
-from ..typing import (
+from ...typing import (
     Pair,
 )
 
 
-def _compute_edge_path_straight(
+def _compute_edge_segments_straight(
     vcoord_data,
-    vpath_fig,
-    vsize_fig,
-    trans,
-    trans_inv,
     layout_coordinate_system: str = "cartesian",
     shrink: float = 0,
     **kwargs,
@@ -45,37 +40,11 @@ def _compute_edge_path_straight(
             f"Layout coordinate system not supported for straight edges in 3D: {layout_coordinate_system}.",
         )
 
-    vcoord_data_cart = vcoord_data
+    segments = [vcoord_data[0], vcoord_data[1]]
+    return segments
 
-    # Coordinates in figure (default) coords
-    vcoord_fig = trans(vcoord_data_cart)
 
-    points = []
-
-    # Angles of the straight line
-    # FIXME: In 2D, this is only used to make space for loops
-    # let's ignore for now
-    # theta = atan2(*((vcoord_fig[1] - vcoord_fig[0])[::-1]))
-    theta = 0
-
-    # TODO: Shorten at starting vertex (?)
-    vs = vcoord_fig[0]
-    points.append(vs)
-
-    # TODO: Shorten at end vertex (?)
-    ve = vcoord_fig[1]
-    points.append(ve)
-
-    codes = ["MOVETO", "LINETO"]
-    path = mpl.path.Path(
-        points,
-        codes=[getattr(mpl.path.Path, x) for x in codes],
-    )
-    path.vertices = trans_inv(path.vertices)
-    return path, (theta, theta + np.pi)
-
-
-def _compute_edge_path_3d(
+def _compute_edge_segments(
     *args,
     tension: float = 0,
     waypoints: str | tuple[float, float] | Sequence[tuple[float, float]] | np.ndarray = "none",
@@ -98,7 +67,7 @@ def _compute_edge_path_3d(
         # )
 
     if np.isscalar(tension) and (tension == 0):
-        return _compute_edge_path_straight(
+        return _compute_edge_segments_straight(
             *args,
             layout_coordinate_system=layout_coordinate_system,
             **kwargs,

{iplotx-0.10.0 → iplotx-0.11.0}/iplotx/art3d/vertex.py

@@ -9,7 +9,11 @@ import numpy as np
 from matplotlib import (
     cbook,
 )
-from mpl_toolkits.mplot3d.art3d import Path3DCollection
+from mpl_toolkits.mplot3d import Axes3D
+from mpl_toolkits.mplot3d.art3d import (
+    Path3DCollection,
+    text_2d_to_3d,
+)
 
 from ..utils.matplotlib import (
     _forwarder,
@@ -32,6 +36,14 @@ from ..vertex import (
 class Vertex3DCollection(VertexCollection, Path3DCollection):
     """Collection of vertex patches for plotting."""
 
+    def _update_before_draw(self) -> None:
+        """Update the collection before drawing."""
+        # Set the sizes according to the current figure dpi
+        VertexCollection._update_before_draw(self)
+
+        if isinstance(self.axes, Axes3D) and hasattr(self, "do_3d_projection"):
+            self.do_3d_projection()
+
     def draw(self, renderer) -> None:
         """Draw the collection of vertices in 3D.
 
@@ -56,7 +68,7 @@ def vertex_collection_2d_to_3d(
         col: The 2D VertexCollection to convert.
         zs: The z coordinate(s) to use for the 3D vertices.
         zdir: The axis to use as the z axis (default is "z").
-        depthshade: Whether to apply depth shading (default is True).
+        depthshade: Whether to aply depth shading (default is True).
         axlim_clip: Whether to clip the vertices to the axes limits (default is False).
     """
     if not isinstance(col, VertexCollection):
@@ -67,3 +79,9 @@ def vertex_collection_2d_to_3d(
     col._depthshade = depthshade
     col._in_draw = False
     col.set_3d_properties(zs, zdir, axlim_clip)
+
+    # Labels if present
+    if col.get_labels() is not None:
+        for z, art in zip(zs, col.get_labels()._labelartists):
+            # zdir=None means the text is always horizontal facing the camera
+            text_2d_to_3d(art, z, zdir=None, axlim_clip=axlim_clip)

{iplotx-0.10.0 → iplotx-0.11.0}/iplotx/edge/__init__.py

@@ -9,7 +9,7 @@ from typing import (
     Optional,
     Any,
 )
-from math import atan2, cos, pi, sin
+from math import pi
 from collections import defaultdict
 import numpy as np
 import pandas as pd
@@ -181,17 +181,23 @@ class EdgeCollection(mpl.collections.PatchCollection):
 
     def set_figure(self, fig) -> None:
         super().set_figure(fig)
-        self._update_paths()
+        self._update_before_draw()
         # NOTE: This sets the correct offsets in the arrows,
         # but not the correct sizes (see below)
-        self._update_children()
+        self._update_labels()
         for child in self.get_children():
             # NOTE: This sets the sizes with correct dpi scaling in the arrows
             child.set_figure(fig)
 
-    def _update_children(self):
-        self._update_arrows()
-        self._update_labels()
+    @property
+    def axes(self):
+        return mpl.artist.Artist.axes.__get__(self)
+
+    @axes.setter
+    def axes(self, new_axes):
+        mpl.artist.Artist.axes.__set__(self, new_axes)
+        for child in self.get_children():
+            child.axes = new_axes
 
     def set_transform(self, transform: mpl.transforms.Transform) -> None:
         """Set the transform for the edges and their children."""
@@ -303,7 +309,7 @@ class EdgeCollection(mpl.collections.PatchCollection):
             "sizes": vsizes,
         }
 
-    def _update_paths(self, transform=None):
+    def _update_before_draw(self, transform=None):
         """Compute paths for the edges.
 
         Loops split the largest wedge left open by other
@@ -512,42 +518,6 @@ class EdgeCollection(mpl.collections.PatchCollection):
         if not style.get("rotate", True):
             self._label_collection.set_rotations(rotations)
 
-    def _update_arrows(
-        self,
-    ) -> None:
-        """Extract the start and/or end angles of the paths to compute arrows.
-
-        Parameters:
-            which: Which end of the edge to put an arrow on. Currently only "end" is accepted.
-
-        NOTE: This function does *not* update the arrow sizes/_transforms to the correct dpi
-        scaling. That's ok since the correct dpi scaling is set whenever there is a different
-        figure (before first draw) and whenever a draw is called.
-        """
-        if not hasattr(self, "_arrows"):
-            return
-
-        transform = self.get_transform()
-        trans = transform.transform
-
-        for i, epath in enumerate(self.get_paths()):
-            # Offset the arrow to point to the end of the edge
-            self._arrows._offsets[i] = epath.vertices[-1]
-
-            # Rotate the arrow to point in the direction of the edge
-            apath = self._arrows._paths[i]
-            # NOTE: because the tip of the arrow is at (0, 0) in patch space,
-            # in theory it will rotate around that point already
-            v2 = trans(epath.vertices[-1])
-            v1 = trans(epath.vertices[-2])
-            dv = v2 - v1
-            theta = atan2(*(dv[::-1]))
-            theta_old = self._arrows._angles[i]
-            dtheta = theta - theta_old
-            mrot = np.array([[cos(dtheta), sin(dtheta)], [-sin(dtheta), cos(dtheta)]])
-            apath.vertices = apath.vertices @ mrot
-            self._arrows._angles[i] = theta
-
     @_stale_wrapper
     def draw(self, renderer):
         # Visibility affects the children too
@@ -555,11 +525,15 @@ class EdgeCollection(mpl.collections.PatchCollection):
             return
 
         # This includes the subedges if present
-        self._update_paths()
-        # This sets the arrow offsets
-        self._update_children()
+        self._update_before_draw()
 
+        # Now you can draw the edges
         super().draw(renderer)
+
+        # This sets the labels offsets
+        self._update_labels()
+
+        # Now you can draw arrows and labels
         for child in self.get_children():
             child.draw(renderer)
 

{iplotx-0.10.0 → iplotx-0.11.0}/iplotx/edge/arrow.py

@@ -4,6 +4,7 @@ Module for edge arrows in iplotx.
 
 from typing import Never, Optional
 
+from math import atan2, cos, sin
 import numpy as np
 import matplotlib as mpl
 from matplotlib.patches import PathPatch
@@ -91,9 +92,7 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
     def set_figure(self, fig) -> None:
         """Set the figure for this artist and all children."""
         super().set_figure(fig)
-        self.set_sizes(self._sizes, self.get_figure(root=True).dpi)
-        for child in self.get_children():
-            child.set_figure(fig)
+        self._update_before_draw()
 
     def get_offset_transform(self):
         """Get offset transform for the edge arrows. This sets the tip of each arrow."""
@@ -126,6 +125,30 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
 
         return patches, sizes
 
+    def _update_before_draw(self) -> None:
+        """Update the arrow paths and directions before drawing, based on the edge collection."""
+        self.set_sizes(self._sizes, self.get_figure(root=True).dpi)
+
+        trans = self.get_offset_transform().transform
+
+        for i, epath in enumerate(self._edge_collection.get_paths()):
+            # Offset the arrow to point to the end of the edge
+            self._offsets[i] = epath.vertices[-1]
+
+            # Rotate the arrow to point in the direction of the edge
+            apath = self._paths[i]
+            # NOTE: because the tip of the arrow is at (0, 0) in patch space,
+            # in theory it will rotate around that point already
+            v2 = trans(epath.vertices[-1])
+            v1 = trans(epath.vertices[-2])
+            dv = v2 - v1
+            theta = atan2(*(dv[::-1]))
+            theta_old = self._angles[i]
+            dtheta = theta - theta_old
+            mrot = np.array([[cos(dtheta), sin(dtheta)], [-sin(dtheta), cos(dtheta)]])
+            apath.vertices = apath.vertices @ mrot
+            self._angles[i] = theta
+
     def set_array(self, A: np.ndarray) -> Never:
         """Set the array for cmap/norm coloring, but keep the facecolors as set (usually 'none')."""
         raise ValueError("Setting an array for arrows directly is not supported.")
@@ -145,7 +168,7 @@ class EdgeArrowCollection(mpl.collections.PatchCollection):
 
     @mpl.artist.allow_rasterization
     def draw(self, renderer):
-        self.set_sizes(self._sizes, self.get_figure(root=True).dpi)
+        self._update_before_draw()
         super().draw(renderer)