Ticket #14175: trac_14175_plot_options.patch

sage/geometry/polyhedron/base.py

@@ -420 +420 @@
                     for other_H, self_V in
                     CartesianProduct(other.Hrepresentation(), self.Vrepresentation()) )
 
-    def plot(self, **kwds):
+    def plot(self,
+             point=None, line=None, polygon=None, # None means unspecified by the user
+             wireframe='blue', fill='green',
+             **kwds):
         """
         Return a graphical representation.
 
         INPUT:
 
-        - ``**kwds`` -- optional keyword parameters.
-
-        See :func:`render_2d`, :func:`render_3d`, :func:`render_4d`
-        for a description of available options for different ambient
-        space dimensions.
+        - ``point``, ``line``, ``polygon`` -- Parameters to pass to
+          point (0d), line (1d), and polygon (2d) plot commands.
+          Allowed values are:
+
+          * A Python dictionary to be passed as keywords to the plot
+            commands.
+
+          * A string or triple of numbers: The color. This is
+            equivalent to passing the dictionary ``{'color':...}``.
+
+          * ``False``: Switches off the drawing of the corresponding
+            graphics object
+
+        - ``wireframe``, ``fill`` -- Similar to ``point``, ``line``,
+          and ``polygon``, but ``fill`` is used for the graphics
+          objects in the dimension of the polytope (or of dimension 2
+          for higher dimensional polytopes) and ``wireframe`` is used
+          for all lower-dimensional graphics objects
+          (default: 'green' for fill and 'blue' for wireframe)
+
+        - ``**kwds`` -- optional keyword parameters that are passed to
+          all graphics objects.
 
         OUTPUT:
 
-        A graphics object.
+        A (multipart) graphics object.
+
+        EXAMPLES::
+
+            sage: square = polytopes.n_cube(2)
+            sage: point = Polyhedron([[1,1]])
+            sage: line = Polyhedron([[1,1],[2,1]])
+            sage: cube = polytopes.n_cube(3)
+            sage: hypercube = polytopes.n_cube(4)
+
+        By default, the wireframe is rendered in blue and the fill in green::
+
+            sage: square.plot()
+            sage: point.plot()
+            sage: line.plot()
+            sage: cube.plot()
+            sage: hypercube.plot()
+
+        Draw the lines in red and nothing else::
+
+            sage: square.plot(point=False, line='red', polygon=False)
+            sage: point.plot(point=False, line='red', polygon=False)
+            sage: line.plot(point=False, line='red', polygon=False)
+            sage: cube.plot(point=False, line='red', polygon=False)
+            sage: hypercube.plot(point=False, line='red', polygon=False)
+
+        Draw points in red, no lines, and a blue polygon::
+
+            sage: square.plot(point={'color':'red'}, line=False, polygon=(0,0,1))
+            sage: point.plot(point={'color':'red'}, line=False, polygon=(0,0,1))
+            sage: line.plot(point={'color':'red'}, line=False, polygon=(0,0,1))
+            sage: cube.plot(point={'color':'red'}, line=False, polygon=(0,0,1))
+            sage: hypercube.plot(point={'color':'red'}, line=False, polygon=(0,0,1))
+
+        If we instead use the ``fill`` and ``wireframe`` options, the
+        coloring depends on the dimension of the object::
+
+            sage: square.plot(fill='green', wireframe='red')
+            sage: point.plot(fill='green', wireframe='red')
+            sage: line.plot(fill='green', wireframe='red')
+            sage: cube.plot(fill='green', wireframe='red')
+            sage: hypercube.plot(fill='green', wireframe='red')
 
         TESTS::
 
-            sage: polytopes.n_cube(2).plot()
+            sage: for p in square.plot():
+            ...       print p.options()['rgbcolor'], p
+            blue Point set defined by 4 point(s)
+            blue Line defined by 2 points
+            blue Line defined by 2 points
+            blue Line defined by 2 points
+            blue Line defined by 2 points
+            green Polygon defined by 4 points
+
+            sage: for p in line.plot():
+            ...       print p.options()['rgbcolor'], p
+            blue Point set defined by 2 point(s)
+            green Line defined by 2 points
+
+            sage: for p in point.plot():
+            ...       print p.options()['rgbcolor'], p
+            green Point set defined by 1 point(s)
+
+        Draw the lines in red and nothing else::
+
+            sage: for p in square.plot(point=False, line='red', polygon=False):
+            ...       print p.options()['rgbcolor'], p
+            red Line defined by 2 points
+            red Line defined by 2 points
+            red Line defined by 2 points
+            red Line defined by 2 points
+
+        Draw vertices in red, no lines, and a blue polygon::
+
+            sage: for p in square.plot(point={'color':'red'}, line=False, polygon=(0,0,1)):
+            ...       print p.options()['rgbcolor'], p
+            red Point set defined by 4 point(s)
+            (0, 0, 1) Polygon defined by 4 points
+
+            sage: for p in line.plot(point={'color':'red'}, line=False, polygon=(0,0,1)):
+            ...       print p.options()['rgbcolor'], p
+            red Point set defined by 2 point(s)
+
+            sage: for p in point.plot(point={'color':'red'}, line=False, polygon=(0,0,1)):
+            ...       print p.options()['rgbcolor'], p
+            red Point set defined by 1 point(s)
+
+        Draw in red without wireframe::
+
+            sage: for p in square.plot(wireframe=False, fill="red"):
+            ...       print p.options()['rgbcolor'], p
+            red Polygon defined by 4 points
+
+            sage: for p in line.plot(wireframe=False, fill="red"):
+            ...       print p.options()['rgbcolor'], p
+            red Line defined by 2 points
+
+            sage: for p in point.plot(wireframe=False, fill="red"):
+            ...       print p.options()['rgbcolor'], p
+            red Point set defined by 1 point(s)
         """
+        def merge_options(*opts):
+            merged = dict()
+            for i in range(len(opts)):
+                opt = opts[i]
+                if opt is None:
+                    continue
+                elif opt is False:
+                    return False
+                elif isinstance(opt, (basestring, list, tuple)):
+                    merged['color'] = opt
+                else:
+                    merged.update(opt)
+            return merged
+
+        d = min(self.dim(), 2)
+        opts = [wireframe] * d + [fill] + [False] * (2-d)
+        # The point/line/polygon options take precedence over wireframe/fill
+        opts = [merge_options(opt1, opt2, kwds)
+                for opt1, opt2 in zip(opts, [point, line, polygon])]
+
         from plot import render_2d, render_3d, render_4d
         render_method = [ None, None, render_2d, render_3d, render_4d ]
         if self.ambient_dim() < len(render_method):
             render = render_method[self.ambient_dim()]
             if render != None:
-                return render(self,**kwds)
+                return render(self, *opts)
         raise NotImplementedError('Plotting of '+str(self.ambient_dim())+
                                   '-dimensional polyhedra not implemented')
 

sage/geometry/polyhedron/plot.py

@@ -29 +29 @@
 
 
 #############################################################
-def render_2d(projection, **kwds):
+def render_2d(projection, point_opts={}, line_opts={}, polygon_opts={}):
     """
     Return 2d rendering of the projection of a polyhedron into
     2-dimensional ambient space.
@@ -54 +54 @@
     """
     if is_Polyhedron(projection):
         projection = Projection(projection)
-    return \
-        projection.render_points_2d(zorder=2, pointsize=10, **kwds) + \
-        projection.render_outline_2d(zorder=1, **kwds) + \
-        projection.render_fill_2d(zorder=0, rgbcolor=(0,1,0), **kwds)
+    from sage.plot.graphics import Graphics
+    plt = Graphics()
+    if isinstance(point_opts, dict):
+        point_opts.setdefault('zorder', 2)
+        point_opts.setdefault('pointsize', 10)
+        plt += projection.render_points_2d(**point_opts)
+    if isinstance(line_opts, dict):
+        line_opts.setdefault('zorder', 1)
+        plt += projection.render_outline_2d(**line_opts)
+    if isinstance(polygon_opts, dict):
+        polygon_opts.setdefault('zorder', 0)
+        plt += projection.render_fill_2d(**polygon_opts)
+    return plt
 
 
-def render_3d(projection, **kwds):
+def render_3d(projection, point_opts={}, line_opts={}, polygon_opts={}):
     """
     Return 3d rendering of a polyhedron projected into
     3-dimensional ambient space.
@@ -90 +99 @@
     """
     if is_Polyhedron(projection):
         projection = Projection(projection)
-    return \
-        projection.render_vertices_3d(width=3, color='green', **kwds) +\
-        projection.render_wireframe_3d(width=3, color='green', **kwds) + \
-        projection.render_solid_3d(**kwds)
+    from sage.plot.plot3d.base import Graphics3d
+    plt = Graphics3d()
+    if isinstance(point_opts, dict):
+        point_opts.setdefault('width', 3)
+        plt += projection.render_vertices_3d(**point_opts)
+    if isinstance(line_opts, dict):
+        line_opts.setdefault('width', 3)
+        plt += projection.render_wireframe_3d(**line_opts)
+    if isinstance(polygon_opts, dict):
+        plt += projection.render_solid_3d(**polygon_opts)
+    return plt
 
-
-def render_4d(polyhedron, **kwds):
+def render_4d(polyhedron, point_opts={}, line_opts={}, polygon_opts={}, projection_direction=None):
     """
     Return a 3d rendering of the Schlegel projection of a 4d
     polyhedron projected into 3-dimensional space.
@@ -111 +126 @@
     - ``polyhedron`` -- A
       :mod:`~sage.geometry.polyhedron.constructor.Polyhedron` object.
 
-    - ``kwds`` -- plot keywords. Passing
-      ``projection_direction=<list>`` sets the projetion direction of
-      the Schlegel projection. If it is not given, the center of a
-      facet is used.
+    - ``point_opts``, ``line_opts``, ``polygon_opts`` -- dictionaries
+      of plot keywords or ``False`` to disable. 
+
+    - ``projection_direction`` -- list/tuple/iterable of coordinates
+      or ``None`` (default). Sets the projetion direction of the
+      Schlegel projection. If it is not given, the center of a facet
+      is used.
 
     EXAMPLES::
 
@@ -135 +153 @@
         sage: tach_str.count('FCylinder')
         32
     """
-    projection_direction = None
-    try:
-        projection_direction = kwds.pop('projection_direction')
-    except KeyError:
+    if projection_direction is None:
         for ineq in polyhedron.inequality_generator():
             center = [v() for v in ineq.incident() if v.is_vertex()]
             center = sum(center) / len(center)
@@ -146 +161 @@
                 projection_direction = center
                 break
     projection_3d = Projection(polyhedron).schlegel(projection_direction)
-    return render_3d(projection_3d, **kwds)
+    return render_3d(projection_3d, point_opts, line_opts, polygon_opts)