Trac #33002: Method tikz of polyhedron class can now return an object…

… of type TikzPicture

As a follow up of #20343, the current branch now allows to specify the
output type of the `tikz` method of a polyhedron:

{{{
sage: co = polytopes.cuboctahedron()
sage: t = co.tikz([674,108,-731], 112, output_type='TikzPicture')
sage: t
\documentclass[tikz]{standalone}
\begin{document}
\begin{tikzpicture}%
        [x={(0.249656cm, -0.577639cm)},
        y={(0.777700cm, -0.358578cm)},
        z={(-0.576936cm, -0.733318cm)},
        scale=1.000000,
---
92 lines not printed (5190 characters in total).
Use print to see the full content.
---
\node[vertex] at (1.00000, 0.00000, 1.00000)     {};
\node[vertex] at (1.00000, 1.00000, 0.00000)     {};
%%
%%
\end{tikzpicture}
\end{document}
sage: t.pdf()
'/tmp/tmpobwhg3p7/tikz_o9dkz419.pdf'
}}}

We also change the default behavior in favor of
`output_type='TikzPicture'`. A deprecation warnings is now sent when
`output_type` is not given:

{{{
sage: co = polytopes.cuboctahedron()
sage: t = co.tikz([674,108,-731], 112)
... DeprecationWarning: Since SageMath 5.13 (ticket #12083), the method
 .tikz() of a polyhedron returns an object of type ``LatexExpr`` which
is a
Python str. Since SageMath 9.7, this default behavior of returning an
object
 of type LatexExpr is deprecated as the default output will soon change
to
an object of type ``TikzPicture`` from the module
sage.misc.latex_standalone
 (newly introduced in SageMath 9.6). Please update your code to specify
the
 desired output type as ``.tikz(output_type='LatexExpr')`` to keep the
old
 behavior or ``.tikz(output_type='TikzPicture')`` to use the future
default
 behavior.
See https://trac.sagemath.org/33002 for details.
}}}

URL: https://trac.sagemath.org/33002
Reported by: slabbe
Ticket author(s): Sébastien Labbé
Reviewer(s): Laith Rastanawi

src/doc/en/thematic_tutorials/geometry/polytope_tikz.rst

@@ -15,8 +15,9 @@ paper. TikZ is a very versatile tool to draw in scientific documents
 and Sage can deal easily with 3-dimensional polytopes. Finally sagetex
 makes everything work together nicely between Sage, TikZ and
 LaTeX. Since version 6.3 of Sage, there is a function for (projection
-of) polytopes to output a TikZ picture of the polytope.  This short
-tutorial shows how it all works.
+of) polytopes to output a TikZ picture of the polytope. Since version 9.7 of
+SageMath, the tikz output can be a ``TikzPicture`` object from the sage module
+``sage.misc.latex_standalone``. This short tutorial shows how it all works.
 
 Instructions
 """"""""""""
@@ -30,21 +31,23 @@ To put an image of a 3D-polytope in LaTeX using TikZ and Sage, simply follow the
 - Visualize the polytope P using the command ``P.show(aspect_ratio=1)``
 - This will open an interactive view in your default browser, where you can rotate the polytope.
 - Once the desired view angle is found, click on the information icon in the lower right-hand corner and select *Get Viewpoint*. This will copy a string of the form '[x,y,z],angle' to your local clipboard.
-- Go back to Sage and type ``Img = P.tikz([x,y,z],angle)``. You can paste the string here to save some typing.
-- *Img* now contains a Sage object of type ``LatexExpr`` containing the raw TikZ picture of your polytope
+- Go back to Sage and type ``Img = P.tikz([x,y,z],angle,output_type='LatexExpr')``. You can paste the string here to save some typing.
+- *Img* now contains a Sage object of type ``LatexExpr`` containing the raw TikZ picture of your polytope.
 
-Then, you can either copy-paste it to your article by typing ``Img`` in Sage or save it to a file, by doing
+Alternatively, you can save the tikz image to a file, by doing
 
 .. CODE-BLOCK:: python
 
-  f = open('Img_poly.tex','w')
-  f.write(Img)
-  f.close()
+  Img = P.tikz([x,y,z], angle, output_type='TikzPicture')
+  Img.tex('Img_poly.tex')
+  Img.tex('Img_poly.tex', content_only=True)
+  Img.pdf('Img_poly.pdf')
 
 .. end of output
 
 Then in the pwd (present working directory of sage, the one of your article)
-you will have a file named ``Img_poly.tex`` containing the tikzpicture of your polytope.
+you will have two files named ``Img_poly.tex`` and ``Img_poly.pdf`` containing the
+tikzpicture of the polytope ``P``.
 
 Customization
 """""""""""""
@@ -57,6 +60,9 @@ You can customize the polytope using the following options in the command ``P.ti
 - ``vertex_color`` : string (default: ``green``) representing colors which tikz recognize,
 - ``opacity`` : real number (default: ``0.8``) between 0 and 1 giving the opacity of the front facets,
 - ``axis`` : Boolean (default: ``False``) draw the axes at the origin or not.
+- ``output_type`` : string (default: ``None``) ``None``, ``'LatexExpr'`` or
+  ``'TikzPicture'``, the type of the output. Since SageMath 9.7, the value ``None`` is deprecated
+  as the default value will soon be changed from ``'LatexExpr'`` to ``'TikzPicture'``.
 
 Examples
 """"""""
@@ -80,15 +86,20 @@ When you found a good angle, follow the above procedure to obtain the values
 
 ::
 
-    Img = P.tikz([674,108,-731],112)
+    Img = P.tikz([674,108,-731], 112, output_type='TikzPicture')
 
 .. end of output
 
+Note: the ``output_type='TikzPicture'`` is necessary since SagMath 9.7 to avoid
+a deprecation warning message since the default output type will soon change
+from a ``LatexExpr`` (Python str) to a ``TikzPicture`` object (allowing more
+versatility, like being able to view it directly in the Jupyter notebook).
+
 Or you may want to customize using the command
 
 ::
 
-    Img = P.tikz([674,108,-731],112,scale=2, edge_color='orange',facet_color='red',vertex_color='blue',opacity=0.4)
+    Img = P.tikz([674,108,-731],112,scale=2, edge_color='orange',facet_color='red',vertex_color='blue',opacity=0.4, output_type='TikzPicture')
 
 .. end of output
 
@@ -134,16 +145,16 @@ some possibilities.
 
 .. CODE-BLOCK:: latex
 
-  \sagestr{(polytopes.permutahedron(4)).tikz([4,5,6],45,scale=0.75, facet_color='red',vertex_color='yellow',opacity=0.3)}
+  \sagestr{(polytopes.permutahedron(4)).tikz([4,5,6],45,scale=0.75, facet_color='red',vertex_color='yellow',opacity=0.3, output_type='LatexExpr')}
 
 .. end of output
 
 2) You may create the following tex commands
 
 .. CODE-BLOCK:: latex
 
-  \newcommand{\polytopeimg}[4]{\sagestr{(#1).tikz(#2,#3,#4)}}
-  \newcommand{\polytopeimgopt}[9]{\sagestr{(#1).tikz(#2,#3,#4,#5,#6,#7,#8,#9)}}
+  \newcommand{\polytopeimg}[4]{\sagestr{(#1).tikz(#2,#3,#4,output_type='LatexExpr')}}
+  \newcommand{\polytopeimgopt}[9]{\sagestr{(#1).tikz(#2,#3,#4,#5,#6,#7,#8,#9,output_type='LatexExpr')}}
 
 .. end of output
 

src/doc/en/thematic_tutorials/geometry/visualization.rst

@@ -113,11 +113,22 @@ This method returns a tikz picture of the polytope (must be 2 or
 ::
 
     sage: c = polytopes.cube()
-    sage: c.tikz().splitlines()[:5]
-    ['\\begin{tikzpicture}%',
-     '\t[x={(1.000000cm, 0.000000cm)},',
-     '\ty={(-0.000000cm, 1.000000cm)},',
-     '\tz={(0.000000cm, -0.000000cm)},',
-     '\tscale=1.000000,']
+    sage: c.tikz(output_type='TikzPicture')
+    \documentclass[tikz]{standalone}
+    \begin{document}
+    \begin{tikzpicture}%
+            [x={(1.000000cm, 0.000000cm)},
+            y={(-0.000000cm, 1.000000cm)},
+            z={(0.000000cm, -0.000000cm)},
+            scale=1.000000,
+    ...
+    Use print to see the full content.
+    ...
+    \node[vertex] at (-1.00000, -1.00000, 1.00000)     {};
+    \node[vertex] at (-1.00000, 1.00000, 1.00000)     {};
+    %%
+    %%
+    \end{tikzpicture}
+    \end{document}
 
 .. end of output

src/sage/geometry/polyhedron/base6.py

@@ -48,7 +48,10 @@ class Polyhedron_base6(Polyhedron_base5):
         sage: P = polytopes.cube()
         sage: Polyhedron_base6.plot(P)
         Graphics3d Object
-        sage: Polyhedron_base6.tikz(P)
+        sage: print(Polyhedron_base6.tikz(P, output_type='TikzPicture'))
+        \RequirePackage{luatex85}
+        \documentclass[tikz]{standalone}
+        \begin{document}
         \begin{tikzpicture}%
             [x={(1.000000cm, 0.000000cm)},
             y={(-0.000000cm, 1.000000cm)},
@@ -125,6 +128,7 @@ class Polyhedron_base6(Polyhedron_base5):
         %%
         %%
         \end{tikzpicture}
+        \end{document}
 
         sage: Q = polytopes.hypercube(4)
         sage: Polyhedron_base6.show(Q)
@@ -473,9 +477,11 @@ def show(self, **kwds):
 
     def tikz(self, view=[0, 0, 1], angle=0, scale=1,
              edge_color='blue!95!black', facet_color='blue!95!black',
-             opacity=0.8, vertex_color='green', axis=False):
+             opacity=0.8, vertex_color='green', axis=False,
+             output_type=None):
         r"""
-        Return a string ``tikz_pic`` consisting of a tikz picture of ``self``
+        Return a tikz picture of ``self`` as a string or as a
+        :class:`~sage.misc.latex_standalone.TikzPicture`
         according to a projection ``view`` and an angle ``angle``
         obtained via the threejs viewer. ``self`` must be bounded.
 
@@ -494,10 +500,15 @@ def tikz(self, view=[0, 0, 1], angle=0, scale=1,
         - ``opacity`` - real number (default: 0.8) between 0 and 1 giving the opacity of
           the front facets.
         - ``axis`` - Boolean (default: False) draw the axes at the origin or not.
+        - ``output_type`` - string (default: ``None``), valid values
+          are ``None`` (deprecated), ``'LatexExpr'`` and ``'TikzPicture'``,
+          whether to return a LatexExpr object (which inherits from Python
+          str) or a ``TikzPicture`` object from module
+          :mod:`sage.misc.latex_standalone`
 
         OUTPUT:
 
-        - LatexExpr -- containing the TikZ picture.
+        - LatexExpr object or TikzPicture object
 
         .. NOTE::
 
@@ -535,18 +546,25 @@ def tikz(self, view=[0, 0, 1], angle=0, scale=1,
         EXAMPLES::
 
             sage: co = polytopes.cuboctahedron()
-            sage: Img = co.tikz([0,0,1], 0)
-            sage: print('\n'.join(Img.splitlines()[:9]))
+            sage: Img = co.tikz([0,0,1], 0, output_type='TikzPicture')
+            sage: Img
+            \documentclass[tikz]{standalone}
+            \begin{document}
             \begin{tikzpicture}%
-                [x={(1.000000cm, 0.000000cm)},
-                y={(0.000000cm, 1.000000cm)},
-                z={(0.000000cm, 0.000000cm)},
-                scale=1.000000,
-                back/.style={loosely dotted, thin},
-                edge/.style={color=blue!95!black, thick},
-                facet/.style={fill=blue!95!black,fill opacity=0.800000},
-                vertex/.style={inner sep=1pt,circle,draw=green!25!black,fill=green!75!black,thick}]
-            sage: print('\n'.join(Img.splitlines()[12:21]))
+                    [x={(1.000000cm, 0.000000cm)},
+                    y={(0.000000cm, 1.000000cm)},
+                    z={(0.000000cm, 0.000000cm)},
+                    scale=1.000000,
+            ...
+            Use print to see the full content.
+            ...
+            \node[vertex] at (1.00000, 0.00000, 1.00000)     {};
+            \node[vertex] at (1.00000, 1.00000, 0.00000)     {};
+            %%
+            %%
+            \end{tikzpicture}
+            \end{document}
+            sage: print('\n'.join(Img.content().splitlines()[12:21]))
             %% with the command: ._tikz_3d_in_3d and parameters:
             %% view = [0, 0, 1]
             %% angle = 0
@@ -556,15 +574,40 @@ def tikz(self, view=[0, 0, 1], angle=0, scale=1,
             %% opacity = 0.8
             %% vertex_color = green
             %% axis = False
-            sage: print('\n'.join(Img.splitlines()[22:26]))
+            sage: print('\n'.join(Img.content().splitlines()[22:26]))
             %% Coordinate of the vertices:
             %%
             \coordinate (-1.00000, -1.00000, 0.00000) at (-1.00000, -1.00000, 0.00000);
             \coordinate (-1.00000, 0.00000, -1.00000) at (-1.00000, 0.00000, -1.00000);
+
+        When output type is a :class:`sage.misc.latex_standalone.TikzPicture`::
+
+            sage: co = polytopes.cuboctahedron()
+            sage: t = co.tikz([674,108,-731], 112, output_type='TikzPicture')
+            sage: t
+            \documentclass[tikz]{standalone}
+            \begin{document}
+            \begin{tikzpicture}%
+                    [x={(0.249656cm, -0.577639cm)},
+                    y={(0.777700cm, -0.358578cm)},
+                    z={(-0.576936cm, -0.733318cm)},
+                    scale=1.000000,
+            ...
+            Use print to see the full content.
+            ...
+            \node[vertex] at (1.00000, 0.00000, 1.00000)     {};
+            \node[vertex] at (1.00000, 1.00000, 0.00000)     {};
+            %%
+            %%
+            \end{tikzpicture}
+            \end{document}
+            sage: path_to_file = t.pdf()     # not tested
+
         """
         return self.projection().tikz(view, angle, scale,
                                       edge_color, facet_color,
-                                      opacity, vertex_color, axis)
+                                      opacity, vertex_color, axis,
+                                      output_type=output_type)
 
     def _rich_repr_(self, display_manager, **kwds):
         r"""