https://github.com/dmoj/texoid

Lightweight Python server for securely rendering LaTeX diagrams to SVG and PNG within Docker.
https://github.com/dmoj/texoid

latex png python renderer server svg

Last synced: about 1 month ago
JSON representation

Lightweight Python server for securely rendering LaTeX diagrams to SVG and PNG within Docker.

• Host: GitHub
• URL: https://github.com/dmoj/texoid
• Owner: DMOJ
• License: agpl-3.0
• Created: 2016-08-15T17:33:47.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2023-03-09T12:00:23.000Z (almost 2 years ago)
• Last Synced: 2024-11-09T13:45:13.523Z (about 2 months ago)
• Topics: latex, png, python, renderer, server, svg
• Language: Python
• Homepage: https://dmoj.ca/
• Size: 39.1 KB
• Stars: 11
• Watchers: 6
• Forks: 2
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Texoid [![Build Status](https://img.shields.io/travis/DMOJ/texoid.svg)](https://travis-ci.org/DMOJ/texoid)  [![PyPI](https://img.shields.io/pypi/v/texoid.svg)](https://pypi.org/project/texoid/) [![PyPI - Format](https://img.shields.io/pypi/format/texoid.svg)](https://pypi.org/project/texoid/) [![PyPI - License](https://img.shields.io/pypi/l/texoid.svg)](https://pypi.org/project/texoid/)

Python server for LaTeX math rendering to SVG and PNG.

It is lightweight and perfect for embedding LaTeX documents into webpages, without the hassle of rendering the documents yourself.

## Installation

Texoid is super simple to set up and use.

```shell

$ pip install texoid

```

Texoid uses [`texbox`](https://github.com/DMOJ/texbox), a Docker image built for converting LaTeX documents to SVG and PNG securely, without exposing your system to malicious LaTeX code. To use Texoid with `texbox`, [install Docker](https://docs.docker.com/install/).

Alternatively, Texoid can directly use LaTeX to render documents to DVI format, `dvisvgm` to convert to SVGs, and ImageMagick to convert SVGs into PNGs. On a typical Debian or Ubuntu machine, you can the dependencies for this with:

```shell

$ apt-get install texlive-latex-base texlive-binaries imagemagick

```

## Running Texoid

### With Docker

To run Texoid with Docker, simply run the following command with a user in the `docker` group:

```shell

$ texoid --port= --docker

```

This will automatically pull the latest `texbox` image and start using it.

### Without Docker

To start the Texoid without Docker, use:

```shell

$ export LATEX_BIN=

$ export DVISVGM_BIN=

$ export CONVERT_BIN=

$ texoid --port=

```

The environment variables are not necessary if the respective executables are present in `$PATH`. Here, `convert` refers to ImageMagick's `convert` tool.

## Using Texoid

Texoid expects POST body to contain the LaTeX document to render. You should send the request with an appropriate `Content-Type`, for example, `text/plain`, `application/x-tex`, or `text/x-tex`. Do not use `application/x-www-form-urlencoded`.

Texoid also has a legacy API. This API uses `application/x-www-form-urlencoded` as `Content-Type`, and sends the LaTeX code form-encoded in the `q` field.

### Response

The response will always contain a boolean field, `success`.

If `success` is `true`:

* `svg` will contain the SVG source of the rendered document

* `png` will contain a base64-encoded binary PNG file

* `meta` will be a dict containing two entries:

  * `width`, the width of the rendered document in pixels

  * `height`, the height of the rendered document, again in pixels

  * these arguments are what the SVG/PNGs generated should be sized by to display properly in webpages

If `success` is `false`, the response will contain an `error` field with the LaTeX error output.

### Examples

In these examples, a Texoid server is assumed to be running on `localhost`, port 8888. We will be rendering a simple LaTeX document:

```latex

\documentclass{standalone}

\begin{document}

$E=mc^2$

\end{document}

```

#### A successful render

```shell

$ curl -H 'Content-Type: text/plain' --data-raw '\documentclass{standalone}\begin{document}$E=mc^2$\end{document}' localhost:8888

{

    "success": true,

    "svg": "",

    "png": "iVBORw0KGgoA...RK5CYII=",

    "meta": {

        "width": "48", 

        "height": "10"

    }

}

```

#### A malformed request

```shell

$ curl -H 'Content-Type: text/plain' --data 'malformed' localhost:8888

{

    "success": false,

    "error": "This is pdfTeX, Version 3.14159265-2.6-1.40.15...LaTeX Error: Missing \\begin{document}..."

}

```

And that's it!