Metadata-Version: 2.1
Name: matplotlib-layout
Version: 0.0.1
Summary: A package for laying out figures with geometric constraints
Author-email: Jonathan Deng <jonathan.j.deng@gmail.com>
Project-URL: Homepage, https://github.com/jon-deng/mpl-layout
Project-URL: Bug Tracker, https://github.com/jon-deng/mpl-layout/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENCE


![Project logo](logo.svg)

## Summary

MPLLayout is a package used to create figure layouts for [matplotlib](https://matplotlib.org/) using geometric constraints.

MPLLayout can be used to:

* align figure elements (axes, text label location, x and y axis, etc.),
* specify margins around axes,
* specify the figure size,
* and more!

## Motivation

Matplotlib contains several strategies for creating figure layouts (for example, `GridSpec` and `subplots` for grid-based layouts).
These strategies work well, however, they can be insufficient for complex figures or if you want precise placement of figure elements.
To address this, this package uses geometric primitives and constraints to represent and position figure elements.

It consists of:

* geometric primitives to represent figure elements (for example, a `Quadrilateral` primitive represents a figure, a `Point` represents a text anchor, etc.),
* geometric constraints to position figure elements (for example, `Collinear` constraints align lines, `Length` constraints fix line lengths, etc.),
* a solver to find primitives that satisfy the constraints,
* and utilities to generate matplotlib figures and axes from the primitives.

## Installation

To install this package, clone the repository into a local drive.
Navigate to the project directory and run
```
pip install .
```

The package requires `numpy`, `matplotlib`, and `jax`.

## How to use

Usage of the package is very simple if you are familiar with geometric constraints from CAD programs like AutoCAD, SolidWorks, etc.
The tutorial notebook in `examples/tutorial.ipynb` demonstrates the basic usage of the package and explains some of the commonly used geometric constraints.
Other examples are also given in the `examples` folder.

The notebook at `examples/ten_simple_rules_demo.ipynb` contains an interactive demo to recreate figures from ["Ten Simple Rules For Better Figures"](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1003833) (Rougier, Droettboom and Bourne 2014).

## Contributing

This project is a work in progress so there are likely bugs and missing features.
If you would like to contribute a bug fix, a feature, refactor etc. thank you!
All contributions are welcome.

## Motivation and Similar Projects

A similar project with a geometric constraint solver is [`pygeosolve`](https://github.com/SeanDS/pygeosolve).
There is also another project prototype for a constraint-based layout engine for `matplotlib` [`MplLayouter`](https://github.com/Tillsten/MplLayouter), although it doesn't seem active as of 2023.
