Matplotlib Container Artist

doc/examples_sphinx-gallery/visual_style.py

@@ -47,3 +47,25 @@
 #    default, you can use igraph's `configuration instance
 #    :class:`igraph.configuration.Configuration`. A quick example on how to use
 #    it can be found here: :ref:`tutorials-configuration`.
+
+# %%
+# In the matplotlib backend, igraph creates a special container
+# :class:`igraph.drawing.matplotlib.graph.GraphArtist` which is a matplotlib Artist
+# and the first child of the target Axes. That object can be used to customize
+# the plot appearance after the initial drawing, e.g.:
+g = ig.Graph.Barabasi(n=30, m=1)
+fig, ax = plt.subplots()
+ig.plot(g, target=ax)
+artist = ax.get_children()[0]
+# Option 1:
+artist.set(vertex_color="blue")
+# Option 2:
+artist.set_vertex_color("blue")
+plt.show()
+
+# %%
+# .. note::
+#    The ``artist.set`` method can be used to change multiple properties at
+#    once and is generally more efficient than multiple calls to specific
+#    ``artist.set_...` methods.
+

src/igraph/drawing/__init__.py

@@ -264,13 +264,16 @@ def plot(obj, target=None, bbox=(0, 0, 600, 600), *args, **kwds):
             warn("%s does not support plotting" % (obj,))
             return
         else:
-            plotter(
+            result = plotter(
                 backend,
                 target,
                 palette=palette,
                 *args,
                 **kwds,
             )
+            # NOTE: for matplotlib, result is the container Artist. It would be
+            # good to return this instead of target, like we do for Cairo.
+            # However, that breaks API so let's wait for a major release
 
             if save_path is not None:
                 if backend == "matplotlib":

src/igraph/drawing/graph.py

@@ -555,4 +555,4 @@ def __plot__(self, backend, context, *args, **kwds):
         "drawer_factory",
         DrawerDirectory.resolve(self, backend)(context),
     )
-    drawer.draw(self, *args, **kwds)
+    return drawer.draw(self, *args, **kwds)

src/igraph/drawing/matplotlib/edge.py

@@ -51,11 +51,12 @@ class VisualEdgeBuilder(AttributeCollectorBase):
             width = 2.0
             background = None
             align_label = False
+            zorder = 1
 
         return VisualEdgeBuilder
 
     def draw_directed_edge(self, edge, src_vertex, dest_vertex):
-        if src_vertex == dest_vertex:  # TODO
+        if src_vertex == dest_vertex:
             return self.draw_loop_edge(edge, src_vertex)
 
         ax = self.context
@@ -163,16 +164,18 @@ def draw_directed_edge(self, edge, src_vertex, dest_vertex):
             path["codes"].append("LINETO")
 
         # Draw the edge
-        stroke = mpl.patches.PathPatch(
+        arrowshaft = mpl.patches.PathPatch(
             mpl.path.Path(
                 path["vertices"],
                 codes=[getattr(mpl.path.Path, x) for x in path["codes"]],
             ),
             edgecolor=edge.color,
             facecolor="none",
             linewidth=edge.width,
+            zorder=edge.zorder,
+            transform=ax.transData,
+            clip_on=True,
         )
-        ax.add_patch(stroke)
 
         # Draw the arrow head
         arrowhead = mpl.patches.Polygon(
@@ -184,8 +187,11 @@ def draw_directed_edge(self, edge, src_vertex, dest_vertex):
             closed=True,
             facecolor=edge.color,
             edgecolor="none",
+            zorder=edge.zorder,
+            transform=ax.transData,
+            clip_on=True,
         )
-        ax.add_patch(arrowhead)
+        return [arrowshaft, arrowhead]
 
     def draw_loop_edge(self, edge, vertex):
         """Draws a loop edge.
@@ -201,7 +207,7 @@ def draw_loop_edge(self, edge, vertex):
         radius = vertex.size * 1.5
         center_x = vertex.position[0] + cos(pi / 4) * radius / 2.0
         center_y = vertex.position[1] - sin(pi / 4) * radius / 2.0
-        stroke = mpl.patches.Arc(
+        art = mpl.patches.Arc(
             (center_x, center_y),
             radius / 2.0,
             radius / 2.0,
@@ -210,9 +216,11 @@ def draw_loop_edge(self, edge, vertex):
             linewidth=edge.width,
             facecolor="none",
             edgecolor=edge.color,
+            zorder=edge.zorder,
+            transform=ax.transData,
+            clip_on=True,
         )
-        # FIXME: make a PathCollection??
-        ax.add_patch(stroke)
+        return [art]
 
     def draw_undirected_edge(self, edge, src_vertex, dest_vertex):
         """Draws an undirected edge.
@@ -247,14 +255,16 @@ def draw_undirected_edge(self, edge, src_vertex, dest_vertex):
             path["vertices"].append(dest_vertex.position)
             path["codes"].append("LINETO")
 
-        stroke = mpl.patches.PathPatch(
+        art = mpl.patches.PathPatch(
             mpl.path.Path(
                 path["vertices"],
                 codes=[getattr(mpl.path.Path, x) for x in path["codes"]],
             ),
             edgecolor=edge.color,
             facecolor="none",
             linewidth=edge.width,
+            zorder=edge.zorder,
+            transform=ax.transData,
+            clip_on=True,
         )
-        # FIXME: make a PathCollection??
-        ax.add_artist(stroke)
+        return [art]