README

The bresenham module
====================

A simple implementation of Bresenham's line drawing algorithm.

See `the Wikipedia entry`_ for details on what that is.

.. _the Wikipedia entry: https://en.wikipedia.org/wiki/Bresenham's_line_algorithm

Note that this is a simple implementation.
It is written in Pure Python (without e.g. `numpy`), so it is relatively slow.

I found some beauty in combining the classic algorithm (whose ingenuity lies in
using only integers – a constraint that isn't really as relevant now)
with a Python generator (a modern device that follows the spirit of
“executable pseudocode”, abstracting away the output subroutine).
I hope others can appreciate the code as well.

For serious use, look at these:

* `skimage.draw.line`_, which solves the same problem *fast*.
* A `Numpy-based recipe`_ that generalizes the solution to <var>N</var>
  dimensions.
* `wasabigeom`_, a 2D vector library made for games

.. _`skimage.draw.line`: http://scikit-image.org/docs/dev/api/skimage.draw.html#skimage.draw.line
.. _`Numpy-based recipe`: http://code.activestate.com/recipes/578112-bresenhams-line-algorithm-in-n-dimensions/
.. _`wasabigeom`: https://pypi.org/project/wasabi-geom/


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

In a Python virtual environment, do::

    python -m pip install bresenham

To install from a Git checkout (in editable mode)::

    python -m pip install -e.

To install without a virtual envitonment, add the ``--user`` option.


Usage
=====

The ``bresenham(x0, y0, x1, y1)`` function returns a generator of
the coordinates of the line from ``(x0, y0)`` to ``(x1, y1)``.

For example, the coordinates of a line from (-1, -4) to (3, 2), are::

    >>> from bresenham import bresenham

    >>> list(bresenham(-1, -4, 3, 2))
    [(-1, -4), (0, -3), (0, -2), (1, -1), (2, 0), (2, 1), (3, 2)]


Development
===========

You're welcome to join this project!

If you spot an issue, please report it at the `Issues page`_ on Github.

If you'd like to start changing the code or documentation, check out the code
locally using::

    git clone https://github.com/encukou/bresenham

If you're new to this, please read the `this guide`_ about collaborating
on Github-hosted projects like this one.

If that doesn't make sense, please `e-mail the author <encukou@gmail.com>`_
for clarification. I'd be happy to help you get started.

.. _Issues page: https://github.com/encukou/bresenham/issues
.. _this guide: https://guides.github.com/activities/contributing-to-open-source/