========== labella.py ==========

.. image:: https://github.com/GjjvdBurg/labella.py/workflows/build/badge.svg :target: https://github.com/GjjvdBurg/labella.py/actions?query=workflow%3Abuild

.. image:: https://badge.fury.io/py/labella.svg :target: https://pypi.org/project/labella

.. image:: https://pepy.tech/badge/labella :target: https://pepy.tech/project/labella

Labella.py is a Python 3 clone of labella.js <https://github.com/twitter/labella.js>_ that supports all the features of labella.js and addionally can generate TikZ PDF images for use in LaTeX.

Note: This package is for the most part a direct translation of the original labella.js <https://github.com/twitter/labella.js>_ code to Python

• All the credit for the labella code goes to Krist Wongsuphasawat

(@kristw <https://twitter.com/kristw>_), I only added the code that generates PDF output. Labella.py also includes code from d3 <https://github.com/mbostock/d3>_ for axis scaling, and WebCola <https://github.com/tgdwyer/WebCola>_ for the VPSC code (label placement optimization).

Why? ==== I wrote this for multiple reasons, the most important of which is that I wanted to incorporate label graphs like the ones generated by labella.js <https://github.com/twitter/labella.js>_ in PDF documents, but wasn't satisfied with the PDF output generated by SVG-to-PDF converters. Additionally, it seemed like a fun way to learn some more Javascript, and learn about how labella.js <https://github.com/twitter/labella.js>_ works.

Screenshots =========== These screenshots show the PDF output generated by labella.py (converted to .png)

Time scale:

.. image:: https://raw.githubusercontent.com/GjjvdBurg/labella.py/master/examples/timelinekit3.png :alt: Example of Labella.py output for a timeline :width: 100% :align: center

Linear scale:

.. image:: https://raw.githubusercontent.com/GjjvdBurg/labella.py/master/examples/timelinekit5.png :alt: Example of Labella.py output for a timeline :width: 100% :align: center

Usage ===== Using labella.py is extremely similar to using labella.js <https://github.com/twitter/labella.js>_. See the examples <https://github.com/GjjvdBurg/labella.py/tree/master/examples>_ directory for examples of how to use labella.py. These examples are translations of the examples included in labella.js and in d3kit-timeline <https://kristw.github.io/d3kit-timeline/>_.

For ease of use only the Timeline interface is implemented, which works similar to d3kit-timeline <https://kristw.github.io/d3kit-timeline/>_. Here is a minimal working example for exporting to PDF::

>>> from labella.scale import LinearScale >>> from labella.timeline import TimelineTex >>> tl = TimelineTex([ {'time': 1, 'text': 'Minimal'}, {'time': 2, 'text': 'Working'}, {'time': 3, 'text': 'Example'} ], options={'scale': LinearScale()}) >>> tl.export('minimal.tex')

See also the documentation here <https://github.com/GjjvdBurg/labella.py/tree/master/docs>_.

Installation ============

Labella.py is available through PyPi, so you can do::

pip install labella

to install it.

Note: Labella.py requires a working LaTeX distribution for both SVG and PDF output (see also the documentation <https://github.com/GjjvdBurg/labella.py/tree/master/docs>_), and has only been tested on Linux. If you run into problems, please open an issue on GitHub.

Author ======

Gertjan van den Burg (@GjjvdBurg <https://twitter.com/GjjvdBurg>_).

Licensed under the Apache License Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>_.