https://github.com/lucaslrodri/jupyter-tikz
IPython Magics for rendering TeX/TikZ in Jupyter Notebooks
https://github.com/lucaslrodri/jupyter-tikz
ipython-magic jupyter-notebook latex tikz
Last synced: 7 months ago
JSON representation
IPython Magics for rendering TeX/TikZ in Jupyter Notebooks
- Host: GitHub
- URL: https://github.com/lucaslrodri/jupyter-tikz
- Owner: lucaslrodri
- License: mit
- Created: 2024-06-20T06:34:40.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-10T01:09:17.000Z (12 months ago)
- Last Synced: 2025-02-15T09:37:04.463Z (8 months ago)
- Topics: ipython-magic, jupyter-notebook, latex, tikz
- Language: Jupyter Notebook
- Homepage: https://jupyter-tikz.readthedocs.io/
- Size: 978 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
IPython Magics for rendering TeX/TikZ in Jupyter Notebooks
Documentation | Getting Started notebook
# Installation
## Prerequisites
Jupyter-TikZ is a Python (3.10+) and IPython Magics library. However, in order for Jupyter-TikZ to work properly, some non-Python dependencies need to be installed first:
- LaTeX
- Poppler
### LaTeX
LaTeX must be installed using one of the following distributions:
- [TeX Live](https://tug.org/texlive/) (All Platforms)
- [MikTeX](https://miktex.org/) (Windows)
- [MacTeX](https://www.tug.org/mactex/) (Mac)
You can test if a LaTeX distribution is installed by using the following command:
```latex
pdflatex --version
```
### Poppler
This application requires Poppler's `pdftocairo`. You must install it beforehand.
#### Conda - Platform Independent
```shell
conda install -c conda-forge poppler
```
#### Windows
Download Poppler for Windows [here](https://github.com/oschwartz10612/poppler-windows/releases/). You must add the `bin` folder to your [PATH](https://www.c-sharpcorner.com/article/how-to-addedit-path-environment-variable-in-windows-11/).
#### Linux
Most distributions come with `pdftocairo`. If it is not installed, refer to your package manager to install `poppler-utils`.
#### Mac
Install using `brew`:
```shell
brew install poppler
```
#### Checking the Installation
Finally, you can check if the `pdftocairo` utility is installed by using the following command in your terminal:
```shell
pdftocairo -v
```
#### Using custom pdftocairo path
Alternatively, if you are facing issues, you can configure the `pdftocairo` location (exclusive for use in `jupyter_tikz`) by setting the environment variable `JUPYTER_TIKZ_PDFTOCAIROPATH`:
```python
import os
custom_pdftocairo_path = os.path.join(
os.getenv("LOCALAPPDATA"), "Poppler", "Library", "bin", "pdftocairo.exe"
)
os.environ["JUPYTER_TIKZ_PDFTOCAIROPATH"] = custom_pdftocairo_path
```
## Install Jupyter TikZ
You can install `jupyter-tikz` by using the following command in your terminal:
```shell
pip install jupyter-tikz
```
## Adding TikZ Syntax highlight
If you are using Jupyter Lab 4. You can add LaTeX highlight to `%%tikz` magic cells by using [JupyterLab-lsp](https://jupyterlab-lsp.readthedocs.io/en/latest/Installation.html) and editing [this part of the code in JupyterLab-lsp](https://github.com/jupyter-lsp/jupyterlab-lsp/blob/b159ae2736b26463d8cc8f0ef78f4b2ce9913370/packages/jupyterlab-lsp/src/transclusions/ipython/extractors.ts#L68-L74) in the file `extractor.ts`:
```ts
new RegExpForeignCodeExtractor({
language: 'latex',
pattern: '^%%(latex|tikz)( .*?)?\n([^]*)', // Add tikz support to this line
foreignCaptureGroups: [3],
isStandalone: false,
fileExtension: 'tex'
}),
```
Now, you will have LaTeX syntax code highlighting for `%%tikz` magic cells, as demonstrated below:
For more information refer to this [link](https://discourse.jupyter.org/t/getting-syntax-highlighting-to-work-for-custom-cell-magic/11734/9).
# Basic usage
To begin, load the `jupyter_tikz` extension:
```
%load_ext jupyter_tikz
```
Use it as cell magic, it executes the TeX/TikZ code within the cell:
```latex
%%tikz
\begin{tikzpicture}
\draw[help lines] grid (5, 5);
\draw[fill=black!10] (1, 1) rectangle (2, 2);
\draw[fill=black!10] (2, 1) rectangle (3, 2);
\draw[fill=black!10] (3, 1) rectangle (4, 2);
\draw[fill=black!10] (3, 2) rectangle (4, 3);
\draw[fill=black!10] (2, 3) rectangle (3, 4);
\end{tikzpicture}
```
Or use it as line magic, where the TeX/TikZ code is passed as an IPython string variable:
```python
%tikz "$ipython_string_variable_with_code"
```
Additional options can be passed to the magic command:
```latex
%%tikz -i -t=pgfplots -nt -S=docs/assets/quadratic -r --dpi=150
\begin{axis}[
xlabel=$x$,
ylabel={$f(x) = x^2 + 4$}
]
\addplot [red] {x^2 + 4};
\end{axis}
```
Going further, it is also possible to use it as a Python package:
```python
from jupyter_tikz import TexFragment
tikz_code = tex_template_code = r"""\begin{tikzpicture}
\draw[help lines] grid (5, 5);
\filldraw [color=orange, opacity=0.3] (2.5,2.5) circle (1.5);
\end{tikzpicture}"""
tikz = TexFragment(tikz_code) # Create the tex template object
tikz.run_latex() # Run LaTeX and shows the output
```
# Additional options
All additional options are listed below:
| Argument | Description |
| -------- | ----------- |
| `-as=`
`--input-type=` | Type of the input. Possible values are: `full-document`, `standalone-document` and `tikzpicture`.
*Example:* `-as=full-document`.
*Defaults* to `-as=standalone-document`. |
| `-i`
`--implicit-pic` | Alias for `-as=tikzpicture`. |
| `-f`
`--full-document` | Alias for `-as=full-document`. |
| `-p=`
`--latex-preamble=` | LaTeX preamble to insert before the document.
*Example:* `-p "$preamble"`, with the preamble being an IPython variable.
*Defaults* to None. |
| `-t=`
`--tex-packages=` | Comma-separated list of TeX packages.
*Example:* `-t=amsfonts,amsmath`.
*Defaults* to None. |
| `-nt`
`--no-tikz` | Force to not import the TikZ package. |
| `-l=`
`--tikz-libraries=` | Comma-separated list of TikZ libraries.
*Example:* `-l=calc,arrows`.
*Defaults* to None. |
| `-lp=`
`--pgfplots-libraries=` | Comma-separated list of pgfplots libraries.
*Example:* `-pl=groupplots,external`.
*Defaults* to None. |
| `-nj`
`--no-jinja` | Disable Jinja2 rendering. |
| `-pj`
`--print-jinja` | Print the rendered Jinja2 template. |
| `-pt`
`--print-tex` | Print the full LaTeX document. |
| `-sc=`
`--scale=` | The scale factor to apply to the TikZ diagram.
*Example:* `-sc=0.5`.
*Defaults* to `-sc=1.0`. |
| `-r`
`--rasterize` | Output a rasterized image (PNG) instead of SVG. |
| `-d=`
`--dpi=` | DPI to use when rasterizing the image.
*Example:* `--dpi=300`.
*Defaults* to `-d=96`. |
| `-g`
`--gray` | Set grayscale to the rasterized image. |
| `-e`
`--full-err` | Print the full error message when an error occurs. |
| `-k`
`--keep-temp` | Keep temporary files. |
| `-tp=`
`--tex-program=` | TeX program to use for compilation.
*Example:* `-tp=xelatex` or `-tp=lualatex`.
*Defaults* to `-tp=pdflatex`. |
| `-ta=`
`--tex-args=` | Arguments to pass to the TeX program.
*Example:* `-ta "$tex_args_ipython_variable"`.
*Defaults* to None. |
| `-nc`
`--no-compile` | Do not compile the TeX code. |
| `-s=`
`--save-tikz=` | Save the TikZ code to file.
*Example:* `-s filename.tikz`.
*Defaults* to None. |
| `-st=`
`--save-tex=` | Save full LaTeX code to file.
*Example:* `-st filename.tex`.
*Defaults* to None. |
| `-sp=`
`--save-pdf=` | Save PDF file.
*Example:* `-sp filename.pdf`.
*Defaults* to None. |
| `-S=`
`--save-image=` | Save the output image to file.
*Example:* `-S filename.png`.
*Defaults* to None. |
| `-sv=`
`--save-var=` | Save the TikZ or LaTeX code to an IPython variable.
*Example:* `-sv my_var`.
*Defaults* to None. |
# Contribute
Contributions are welcome from everyone! Whether you're reporting bugs, submitting feedback, or actively improving the codebase, your involvement is valuable. Here's how you can contribute:
- If you encounter any issues or have suggestions for improvements, please report them using the issues page.
- If you're interested in developing the software further, please refer to development guide.
# Changelog
All notable changes to this project are presented below.
## v0.5.6
**✨ Improvements**
- Docs: Added troubleshooting section to the Usage Guide.
## v0.5.5
**🐞 Bug Fixes**
- Removed quotation marks when using `arg "$var"` (e.g., `-p "$preamble"`).
## v0.5.4
**🐞 Bug Fixes**
- Docs: Removed the Jinja2 subsection from the README.
## v0.5.3
**🐞 Bug Fixes**
- Docs: Fixed Jinja section in `installation`.
## v0.5.2
**🐞 Bug Fixes**
- Docs: Fixed internal links in `index`.
## v0.5.1
**🐞 Bug Fixes**
- Docs: Minor fix in changelog.
## v0.5.0
**🚨 Breaking Changes**
- Significant changes to Jinja2 rendering:
- Replaced the default Jinja2 syntax with a custom one to avoid clashes with LaTeX braces (`{}`). Please refer to the documentation for more details.
- With the new syntax, conflicts with LaTeX are significantly reduced, thus Jinja2 is now enabled by default and has become a mandatory dependency.
- Added a `--no-jinja` flag to allow optional disabling of Jinja2 rendering.
## v0.4.2
**🐞 Bug Fixes**
- Doc: Fixed social cards image links.
## v0.4.1
**✨ Improvements**
- Switched temporary file names to MD5 hashing for deterministic hashes.
**🚀 Features**
- Doc: Support to social cards (Twitter and Facebook OG).
**🐞 Bug Fixes**
- Fixed indentation in `TexDocument.tikz_code`.
- Fixed docs issues.
## v0.4.0
**🚀 Features**
- Added support for PGFPlots with external data files.
- Introduced a new flag (`-k`) to retain LaTeX temporary files.
- Added support for grayscale output in rasterized mode.
- Introduced new flags `--save-tikz` and `--save-pdf` to save the TikZ and PDF files respectively; `--save-tex` now explicitly saves the full LaTeX document.
**🚨 Breaking Changes**
- Modified the save functionality: Options must now be passed in `TexDocument.run_latex(...)` as `TexDocument.save()` is no longer used.
- LaTeX rendering is now performed in the current folder, moving away from the use of a temporary directory (`tempdir`). This change facilitates access to external files for PGFPlots.
## v0.3.2
**🐞 Bug Fixes**
- Improved documentation visibility on mobile devices.
## v0.3.1
**🐞 Bug Fixes**
- Fixed DOCs links.
## v0.3.0
**🚀 Features**
- Web documentation.
- Flag (`--print-tex`) to print the full LaTeX document.
- UTF-8 support.
- Added support for Python 3.10.
**🚨 Breaking Changes**
- Replaced `--full-document` and `--implicit-pic` with `--input-type=`. `-f` and `-i` still working as aliases.
- Changed the `--as-jinja` flag to `--use-jinja`.
- Reworked the API to an object-oriented approach.
## v0.2.1
**🐞 Bug Fixes**
- Minor adjustments in the README and Getting Started Notebook.
## v0.2.0
**🚀 Features**
- Option to save output code to an IPython variable (`-sv=`).
- Flag (`--no-compile`) to prevent LaTeX compilation and image rendering.
- Support for LaTeX `\input{...}` commands.
## v0.1.1
**🐞 Bug Fixes**
- Minor fixes in README.
**🚀 Features**
- Added PyPI badge.
## v0.1.0
- First version released on PyPI.
# Thanks
I had been using [ITikZ](https://github.com/jbn/itikz) for years. However, it doesn't update often and relies on the outdated `pdf2svg` for converting PDFs to images, which causes problems in Windows environments. Inspired by ITikZ and [IPython TikZ Magic](https://github.com/mkrphys/ipython-tikzmagic), I decided to create my own package, adding new features such as support for preambles, new Jinja syntax, and the ability to save the LaTeX result to IPython variables. I also switched from `pdf2svg` to Poppler, which works perfectly on all plataforms, including Windows.
# License
Copyright 2024 © [Lucas Lima Rodrigues](https://github.com/lucaslrodri).
Distributed under the terms of the [MIT License](https://github.com/lucaslrodri/jupyter-tikz/blob/main/LICENSE), Jupyter-TikZ is free and open-source software.