Add file `sage/misc/latex_standalone.py` and class `TikzPicture`

[seblabbe]

The goal of this ticket is to import the TikzPicture module from the optional SageMath package slabbe into SageMath. This module has been created in 2016 and has evolved to a stable state and it is mature enough to go into SageMath now.

Here is a demo inside a Jupyter notebook (notice that the import line was since changed to from sage.misc.latex_standalone import TikzPicture):

More examples:

sage: from sage.misc.latex_standalone import TikzPicture
sage: V = [[1,0,1],[1,0,0],[1,1,0],[0,0,-1],[0,1,0],[-1,0,0],[0,1,1],[0,0,1],[0,-1,0]]
sage: P = Polyhedron(vertices=V).polar()
sage: s = P.projection().tikz([674,108,-731],112)
sage: t = TikzPicture(s)
sage: t.pdf()             # opens the pdf in a viewer                                                        
'/home/slabbe/.sage/temp/miami/5032/tikz_gvem9vu8.pdf'
sage: t.pdf('image.pdf')  # when a filename is provided, it doesn't open in a viewer                                            
'/home/slabbe/image.pdf'

It may create the image into png format (translation pdf -> png made with convert from imagemagick) or svg format (translation pdf -> svg made with pdf2svg):

sage: path_to_file = t.png()                                              
sage: path_to_file = t.svg()
sage: path_to_file = t.tex()

In a Jupyter notebook, this shows the picture below the cell (using rich repr):

sage: t

In the terminal, this shows the header and tail of the tikzpicture code:

sage: t                                                                                                    
\documentclass[tikz]{standalone}
\usepackage{amsmath}
\begin{document}
\begin{tikzpicture}%
    [x={(0.249656cm, -0.577639cm)},
    y={(0.777700cm, -0.358578cm)},
    z={(-0.576936cm, -0.733318cm)},
    scale=1.000000,
---
91 lines not printed (5169 characters in total).
Use print to see the full content.
---
\node[vertex] at (0.00000, -1.00000, 0.00000)     {};
\node[vertex] at (-0.50000, -0.50000, -0.50000)     {};
%%
%%
\end{tikzpicture}
\end{document}

Use print to see the full content:

sage: print(t) 

A second example shows that it is faster than view and better (avoids to crop the vertices):

sage: g = graphs.PetersenGraph()
sage: %time _ = TikzPicture(latex(g), standalone_options=["border=4mm"], usepackage=['tkz-graph']).pdf()
CPU times: user 3.52 ms, sys: 12.7 ms, total: 16.2 ms
Wall time: 2.24 s     

compared to using view (which crops the vertices and creates two pages pdf on mac):

sage: %time view(g, tightpage=True)               
CPU times: user 126 ms, sys: 85 ms, total: 211 ms 
Wall time: 6.06 s

Also, if dot2tex and graphviz available, one may directly construct a tikzpicture from a sagemath graph:

sage: t = TikzPicture.from_graph(g, prog='dot')  # optional: dot2tex

The tikzpicture.py was developped within optional package slabbe since 2015. Its interface should be stable enough to go into sage now.

Meanwhile any user can use this tikzpicture module by installing the package:

sage -pip install slabbe

and

sage: from slabbe import TikzPicture

An example of usage of this module can be found at this url:

• https://nbviewer.jupyter.org/url/www.slabbe.org/Publications/arXiv_1906_01104.ipynb

associated to the preprint

• https://arxiv.org/abs/1906.01104

published in Journal of Modern Dynamics at

• http://dx.doi.org/10.3934/jmd.2021017

Depends on #32650 Depends on #33005

CC: @dkrenn @jplab @slel @fchapoton

Component: misc

Author: Sébastien Labbé

Branch: 5c9b41c

Reviewer: Jean-Philippe Labbé, Xavier Caruso, Vincent Delecroix, Matthias Koeppe

Issue created by migration from https://trac.sagemath.org/ticket/20343

[seblabbe]

Description changed:

--- 
+++ 
@@ -1,3 +1,23 @@
-From my optional Sage package [1] slabbe-0.2.spkg.
+Importing a file from my optional Sage package [slabbe-0.2.spkg](https://github.com/seblabbe/slabbe) into Sage.

-[1] https://github.com/seblabbe/slabbe
+```
+sage: from sage.misc.tikz_picture import TikzPicture
+sage: V = [[1,0,1],[1,0,0],[1,1,0],[0,0,-1],[0,1,0],[-1,0,0],[0,1,1],[0,0,1],[0,-1,0]]
+sage: P = Polyhedron(vertices=V).polar()
+sage: s = P.projection().tikz([674,108,-731],112)
+sage: t = TikzPicture(s)
+sage: t.pdf()
+```
+
+```
+sage: g = graphs.PetersenGraph()
+sage: s = latex(g)
+sage: t = TikzPicture(s, standalone_configs=["border=4mm"], packages=['tkz-graph'])
+sage: _ = t.pdf()
+```
+
+If dot2tex and graphviz available:
+
+```
+sage: t = TikzPicture.from_graph(g)  # optional: dot2tex
+```

[seblabbe]

Commit: 476b574

[seblabbe]

Branch: u/slabbe/20343

[seblabbe]

New commits:

476b574

20343: Adding tikzpicture.py in sage/misc

[seblabbe]

Description changed:

--- 
+++ 
@@ -1,7 +1,9 @@
-Importing a file from my optional Sage package [slabbe-0.2.spkg](https://github.com/seblabbe/slabbe) into Sage.
+Importing `TikzPicture` class from my optional Sage package [slabbe-0.2.spkg](https://github.com/seblabbe/slabbe) into Sage.
+
+One example:

-sage: from sage.misc.tikz_picture import TikzPicture +sage: from sage.misc.tikzpicture import TikzPicture sage: V = [[1,0,1],[1,0,0],[1,1,0],[0,0,-1],[0,1,0],[-1,0,0],[0,1,1],[0,0,1],[0,-1,0]] sage: P = Polyhedron(vertices=V).polar() sage: s = P.projection().tikz([674,108,-731],112) @@ -9,15 +11,27 @@ sage: t.pdf()

+Second example:
+

sage: g = graphs.PetersenGraph() -sage: s = latex(g) -sage: t = TikzPicture(s, standaloneconfigs=["border=4mm"], packages=['tkz-graph']) -sage: = t.pdf() +sage: %time _ = TikzPicture(latex(g), standalone_configs=["border=4mm"], packages=['tkz-graph']).pdf() +CPU times: user 3.52 ms, sys: 12.7 ms, total: 16.2 ms +Wall time: 2.24 s

-If dot2tex and graphviz available:
+compared to using view (which crops the vertices and creates two pages pdf on mac):

-sage: t = TikzPicture.from_graph(g) # optional: dot2tex +sage: %time view(g, tightpage=True)
+CPU times: user 126 ms, sys: 85 ms, total: 211 ms +Wall time: 6.06 s

+
+Also, if dot2tex and graphviz available:
+
+```
+sage: t = TikzPicture.from_graph(g, prog='dot')  # optional: dot2tex
+```
+
+

[dkrenn]

comment:5

A comment:

t = TikzPicture(latex(transducers.GrayCode()))
t.pdf()

does not work as the preamble is not set correctly. However, there is

from sage.combinat.finite_state_machine import setup_latex_preamble
setup_latex_preamble()

(as well as the corresponding function in sage.graphs.graph_latex) to set this correctly, but it seems to be ignored by TikzPicture.

In contrast,

view(transducers.GrayCode())

works, but I have no idea if setup_latex_preamble is called (not needed to be done manually) or if tikz is included anyways.

[seblabbe]

comment:6

Replying to @dkrenn:

A comment:

t = TikzPicture(latex(transducers.GrayCode()))
t.pdf()

does not work as the preamble is not set correctly.

As it is now, the user must set the libraries. This should work:

t = TikzPicture(latex(transducers.GrayCode()), tikzlibraries=['automata'])
t.pdf()

I am still not sure about the proper way to choose the arguments for the __init__ function and their especially their default values. Should the arguments be empty by default? equal to the current sage latex preamble? or full of a big load of libraries?

[dkrenn]

comment:7

Replying to @seblabbe:

Replying to @dkrenn:

A comment:

t = TikzPicture(latex(transducers.GrayCode()))
t.pdf()

does not work as the preamble is not set correctly.

As it is now, the user must set the libraries. This should work:

t = TikzPicture(latex(transducers.GrayCode()), tikzlibraries=['automata'])
t.pdf()

Works, thanks.

I am still not sure about the proper way to choose the arguments for the __init__ function and their especially their default values. Should the arguments be empty by default? equal to the current sage latex preamble? or full of a big load of libraries?

Without much thinking, I vote for: The second, equal to the current sage latex preamble.

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

7512091	20343: Adding tikzpicture.py in sage/misc
4ae7f63	20343: improving the default argument choices for TikzPicture

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 476b574 to 4ae7f63

[seblabbe]

Description changed:

--- 
+++ 
@@ -15,7 +15,7 @@

sage: g = graphs.PetersenGraph() -sage: %time _ = TikzPicture(latex(g), standaloneconfigs=["border=4mm"], packages=['tkz-graph']).pdf() +sage: %time = TikzPicture(latex(g), standalone_options=["border=4mm"], usepackage=['tkz-graph']).pdf() CPU times: user 3.52 ms, sys: 12.7 ms, total: 16.2 ms Wall time: 2.24 s

[seblabbe]

Changed commit from 4ae7f63 to none

[seblabbe]

Changed branch from u/slabbe/20343 to none

[seblabbe]

Description changed:

--- 
+++ 
@@ -34,4 +34,14 @@
 sage: t = TikzPicture.from_graph(g, prog='dot')  # optional: dot2tex

+To avoid losing my time, I will not post a branch here until somebody tells me he is willing to review this module. Meanwhile any user can use this tikzpicture module by installing my package:

+ +sage -pip install slabbe + + +and + + +sage: from slabbe import TikzPicture +

[seblabbe]

comment:10

My module has evolved in my package slabbe, therefore the branch here is not up to date anymore. Also, I intend to make it more general during the next year allowing any content not only tikzpicture code. Therefore, I deleted the branch posted here.

[seblabbe]

Description changed:

--- 
+++ 
@@ -34,7 +34,9 @@
 sage: t = TikzPicture.from_graph(g, prog='dot')  # optional: dot2tex

-To avoid losing my time, I will not post a branch here until somebody tells me he is willing to review this module. Meanwhile any user can use this tikzpicture module by installing my package: +I intend to make further improvements to this module during the next year. Also, I will wait until somebody tells me he is willing to review this module before publishing a branch here. + +Meanwhile any user can use this tikzpicture module by installing my package:

 sage -pip install slabbe

[seblabbe]

comment:11

Changing status to needs work.

[jplab]

Reviewer: Jean-Philippe Labbé

[jplab]

comment:12

As a follow-up ticket to make use of this is #22506.

[xcaruso]

Branch: u/caruso/tikzpicture

[xcaruso]

comment:14

I'll be happy to revive this ticket.

---

New commits:

88c048c

import tikz_picture.py from slabbe gitlab repository

[xcaruso]

Commit: 88c048c

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

2917f4b

doctests pass

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 88c048c to 2917f4b

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

8cfc834

typos

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 2917f4b to 8cfc834

[xcaruso]

comment:17

I'm not convinced by all the methods from_dot_string, from_graph, etc. in the class TikzPicture. I would say that this code should instead be in the classes implementing the object we want to display. E.g. it could be a method _tikz_, just as _latex_, and TikzPicture just calls it.

What's your opinion?

[seblabbe]

comment:18

There is no class for dot strings. Graphs already have a _latex_ method which returns a tikz picture string. It is what is used with for instance view(G). The from_graph class method really is using dot2tex + graphviz which is not the same layout sometimes. It is true that maybe adding a _tikz_ would avoid to replace the current behavior of _latex_. But then, having two different behaviors will be non pedagogical (how to know there is another one). Also, changing the default behavior will lead to problems...

I think it will be easier to add the new module as is and later on, in other tickets, add such _tikz_ methods in other parts of sage where it makes sense.

[xcaruso]

comment:19

OK. Let's keep it for another ticket.

[xcaruso]

Changed reviewer from Jean-Philippe Labbé to Jean-Philippe Labbé, Xavier Caruso

[fchapoton]

comment:22

please no "from future import ..."

Returns should be Return

[xcaruso]

comment:23

Also if pdflatex is not installed on the machine, some doctests fail. I don't know if this should be fixed but I think so because otherwise patchbots complain.

[seblabbe]

Changed branch from u/caruso/tikzpicture to u/slabbe/20343

[seblabbe]

New commits:

665db0b

20343: removed from `__future__` imports

[seblabbe]

Changed commit from 8cfc834 to 665db0b

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 665db0b to 0022eb2

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

0022eb2

20343: Returns -> Return

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

03aa1bc

20343: adding few optional tags

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 0022eb2 to 03aa1bc

[seblabbe]

comment:27

I added a bunch of #optional latex and #optional imagemagick tags. That should fix most of the issues.

I also added one # optional pdf2svg for which I am not sure about. I don't know if the doctest framework know about this tag. I change to needs review to check that on the patchbot.

[videlec]

comment:28

Why do you make it part of Sage and not an independent Python module? These could easily be declared as optional/standard packages afterwards.

[seblabbe]

comment:29

Yes, I agree with that option too. Lately, I was thinking more about this option.

But, the module also depends on many things that are in Sage which would make this module quite unusable outside of sage as it is currently. For example:

To check if Graphviz is there:

from sage.features.graphviz import Graphviz

To check if pdflatex, convert and other programs are available:

from sage.misc.latex import have_pdflatex, have_convert, have_program

To load the latex macros from sage:

from sage.misc.latex import _Latex_prefs
from sage.misc.latex_macros import sage_latex_macros

To create a temporary file inside the sage folder of temporary files:

from sage.misc.temporary_file import tmp_filename

To open viewers:

from sage.misc.viewer import browser
from sage.misc.viewer import pdf_viewer
from sage.misc.viewer import png_viewer

To check whether we are in the JupyterNotebook or not:

from sage.repl.rich_output.backend_ipython import BackendIPythonNotebook
from sage.repl.rich_output.buffer import OutputBuffer

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

7d59034

20343: adding few optional latex tags

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 03aa1bc to 7d59034

[videlec]

comment:31

Replying to @seblabbe:

Yes, I agree with that option too. Lately, I was thinking more about this option.

The main advantage with that option is that the package can change versions independently of sage.

But, the module also depends on many things that are in Sage which would make this module quite unusable outside of sage as it is currently. For example:

This would be a Python module that depends on sage. There is nothing bad with that situation. And this is not the only one.

[seblabbe]

comment:32

I am thinking about what to do now, either work on this ticket or create a new package. If I create a sagemath-tikzpicture package that imports many parts of sagemath, I will be responsible for fixing the package each time sagemath changes something that I import. On the other hand, if that modules goes into sagemath, then, it will become the responsability of the person which changes the dependencies to also fix the tikzpicture module. I agree with the idea of modularization, but for the above reason, I would prefer to make it go into sage. What do you think?

[xcaruso]

comment:33

I prefer to have this directly in sage since I think that there are many other places in sage where it would be great to have a tikz output.

[mkoeppe]

comment:34

Because this module does not depend on any external libraries, there is nothing gained in the direction of modularization by making this a separate distribution package.

But perhaps you can find a better place for it than sage.misc? How about sage.typeset or sage.plot?

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

d84b6a3	Merge branch 'u/slabbe/20343' of trac.sagemath.org:sage into 20343
ee56d32	adding optional tag latex to one doctest
2692685	20343:avoid use of doctest continuation since it is not one
2acfe61	20343: misc/tikz_picture.py -> plot/tikzpicture.py
388a5f8	from misc.tikz_picture -> from plot.tikzpicture
b04ea0d	updated authors and copyright
9f9f5ec	20343: redoing recent changes by Vincent Delecroix in slabbe package (check_call -> run); improved header documentation

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 7d59034 to 9f9f5ec