sudokuextract 0.8.6
Library for extracting Sudokus from images using scikit-image
License: MIT
Keywords: Image Processing,Sudoku

SudokuExtract
=============

.. image:: https://travis-ci.org/hbldh/sudokuextract.svg?branch=master
    :target: https://travis-ci.org/hbldh/sudokuextract
.. image:: http://img.shields.io/pypi/v/sudokuextract.svg
    :target: https://pypi.python.org/pypi/sudokuextract/
.. image:: http://img.shields.io/pypi/dm/sudokuextract.svg
    :target: https://pypi.python.org/pypi/sudokuextract/
.. image:: http://img.shields.io/pypi/l/sudokuextract.svg
    :target: https://pypi.python.org/pypi/sudokuextract/
.. image:: https://coveralls.io/repos/github/hbldh/sudokuextract/badge.svg?branch=master
    :target: https://coveralls.io/github/hbldh/sudokuextract?branch=master

Library for extracting Sudokus from images using `scikit-image <http://scikit-image.org/>`_.

Requirements
------------

* ``numpy>=1.9.2``
* ``scipy>=0.15.1``
* ``scikit-image<0.12.0``
* ``Pillow>=3.1.0``
* ``pyefd>=0.1.2``
* ``dlxsudoku>=0.10.0``

Usage
-----

Install via `pip`::

    $ pip install sudokuextract

SudokuExtract is a tool for parsing Sudokus from images, this primarily
to be able to send it forward to some kind of solver. It applies some
image analysis on the input image and then uses a K-Nearest Neighbours
classifier to determine which digits that are present in which box.

``SudokuExtract`` can be used as a command line tool::

    parse-sudoku -p /path/to/sudoku_image.jpg

which prints the parsed Sudoku in the terminal. In can also be called
with an url to an image::

    parse-sudoku -u http://www.domain.com/sudoku.jpg

It can also be used as a regular Python package::

    In [1]: from sudokuextract.extract import extract_sudoku, load_image, predictions_to_suduko_string

    In [2]: img = load_image('/path/to/sudoku_image.jpg')

    In [3]: predictions, sudoku_box_images, whole_sudoku_image = extract_sudoku(img)

    In [4]: print(predictions_to_suduko_string(predictions))
    800603001
    057401630
    000000000
    006109800
    400000007
    001805400
    000000000
    072504310
    900302004

There are possibilities of using a classifier of your own creation when
predicting digits; see the documentation for more details.

Testing
-------

Run tests with `pytest <http://pytest.org/>`_::

    $ py.test tests.py


Documentation
-------------

TBD.

References
----------

This library includes classifiers trained with data from the MNIST dataset
(This data is also included in SudokuExtract).

.. _1:

\[1\] `LeCun et al. (1999): The MNIST Dataset Of Handwritten Digits <http://yann.lecun.com/exdb/mnist/>`_

The current parsing strategy for the `sudokuextract` package is
inspired by this blog entry:

.. _2:

\[2\] `AI: SuDoKu Grabber with OpenCV <http://aishack.in/tutorials/sudoku-grabber-opencv-plot/>`_


v0.8.6 (2016-04-16)
===================
- Changed the main function of `sudokuextract.extract` to print and
  not return anything.

v0.8.5 (2016-03-10)
===================
- Replace ndi.binary_fill_holes with a binary_erosion and increased number of blobs to test to 2.

v0.8.4 (2016-03-10)
===================
- New classifiers.
- New data with additional data of 1:s.

v0.8.3 (2016-03-09)
===================
- Disabled the Corners parsing solution again.
- Warping image now creates a much smaller image to prevent memory issues.
- This also increased speed with a factor of at least 4.
- ``apply_gaussian`` now applies a Gaussian on entire image first.
- Testing can now use a tar-file of images that can be downloaded from the web.
- Also removed lambda functions in favour of ``functools.partial``.

v0.8.2 (2016-03-07)
===================
- Restricted scikit-image version to < 0.12.

v0.8.1 (2016-03-06)
===================
- New classifiers with both SudokuExtract and MNIST data.
- New data.
- MNIST data stored separately from SudokuExtract data.
- Number of Nearest Neighbours increased to 10 due to larger training data.
- Several small bugfixes for new features added in v0.8.0.

v0.8.0 (2016-03-05)
===================
- New classifiers with MNIST data.
- New multi-attempt approach to Sudoku parsing.
- Using DLXSudoku to attempt classification of correct parsing of Sudoku.
- Removed a lot of deprecated code.

v0.7.0 (2016-02-26)
===================
- Two different extraction methods:
    * Local thresholding
    * Adaptive thresholding for entire image
- Refactored extensively and updated classifiers.

v0.6.1 (2016-02-20)
===================
- Patch for tests in Python 3.

v0.6.0 (2016-02-19)
===================
- Simplified blob extraction.
- Added adaptive block_size for ``to_binary_adaptive``.
- Added tests that fetch Sudokus from Xanadoku.

v0.5.0 (2016-02-18)
===================
- Removed hard dependency on scikit-learn.
- Included an own K-Nearest-Neighbors classifier as default.

v0.4.0 (2016-02-17)
===================
- Initial release on PyPI