File: README.rst

package info (click to toggle)
python-pylibdmtx 0.1.9-3
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, sid
  • size: 224 kB
  • sloc: python: 1,120; makefile: 11
file content (133 lines) | stat: -rw-r--r-- 4,252 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
pylibdmtx
=========

.. image:: https://img.shields.io/badge/python-2.7%2C%203.4%2C%203.5%2C%203.6%2C%203.7-blue.svg
    :target: https://github.com/NaturalHistoryMuseum/pylibdmtx

.. image:: https://badge.fury.io/py/pylibdmtx.svg
    :target: https://pypi.python.org/pypi/pylibdmtx

.. image:: https://travis-ci.org/NaturalHistoryMuseum/pylibdmtx.svg?branch=master
    :target: https://travis-ci.org/NaturalHistoryMuseum/pylibdmtx

.. image:: https://coveralls.io/repos/github/NaturalHistoryMuseum/pylibdmtx/badge.svg?branch=master
    :target: https://coveralls.io/github/NaturalHistoryMuseum/pylibdmtx?branch=master

Read and write Data Matrix barcodes from Python 2 and 3 using the
`libdmtx <http://libdmtx.sourceforge.net/>`__ library.

-  Pure python
-  Works with PIL / Pillow images, OpenCV / numpy ``ndarray``\ s, and raw bytes
-  Decodes locations of barcodes
-  No dependencies, other than the libdmtx library itself
-  Tested on Python 2.7, and Python 3.4 to 3.7

The older
`pydmtx <https://sourceforge.net/p/libdmtx/dmtx-wrappers/ci/master/tree/python/>`__
package is stuck in Python 2.x-land.

Installation
------------

The ``libdmtx`` ``DLL``\ s are included with the Windows Python wheels.
On other operating systems, you will need to install the ``libdmtx`` shared
library.

Mac OS X:

::

   brew install libdmtx

Linux:

::

   sudo apt-get install libdmtx0a

Install this Python wrapper; use the second form to install dependencies of the
``read_datamatrix`` and ``write_datamatrix`` command-line scripts:

::

   pip install pylibdmtx
   pip install pylibdmtx[scripts]

Example usage
-------------

The ``decode`` function accepts instances of ``PIL.Image``.

::

   >>> from pylibdmtx.pylibdmtx import decode
   >>> from PIL import Image
   >>> decode(Image.open('pylibdmtx/tests/datamatrix.png'))
   [Decoded(data='Stegosaurus', rect=Rect(left=5, top=6, width=96, height=95)),
    Decoded(data='Plesiosaurus', rect=Rect(left=298, top=6, width=95, height=95))]

It also accepts instances of ``numpy.ndarray``, which might come from loading
images using `OpenCV <http://opencv.org/>`__.

::

   >>> import cv2
   >>> decode(cv2.imread('pylibdmtx/tests/datamatrix.png'))
   [Decoded(data='Stegosaurus', rect=Rect(left=5, top=6, width=96, height=95)),
    Decoded(data='Plesiosaurus', rect=Rect(left=298, top=6, width=95, height=95))]

You can also provide a tuple ``(pixels, width, height)``

::

   >>> image = cv2.imread('pylibdmtx/tests/datamatrix.png')
   >>> height, width = image.shape[:2]
   >>> decode((image.tobytes(), width, height))
   [Decoded(data='Stegosaurus', rect=Rect(left=5, top=6, width=96, height=95)),
    Decoded(data='Plesiosaurus', rect=Rect(left=298, top=6, width=95, height=95))]

The ``encode`` function generates an image containing a Data Matrix barcode:

::

  >>> from pylibdmtx.pylibdmtx import encode
  >>> encoded = encode('hello world')
  >>> img = Image.frombytes('RGB', (encoded.width, encoded.height), encoded.pixels)
  >>> img.save('dmtx.png')


Windows error message
---------------------

If you see an ugly ``ImportError`` when importing ``pylibdmtx`` on
Windows you will most likely need the `Visual C++ Redistributable Packages for
Visual Studio 2013
<https://www.microsoft.com/en-US/download/details.aspx?id=40784>`__.
Install ``vcredist_x64.exe`` if using 64-bit Python, ``vcredist_x86.exe`` if
using 32-bit Python.

Limitations
-----------

Feel free to submit a PR to address any of these.

-  I took the bone-headed approach of copying the logic in
   ``pydmtx``\ ’s ``decode`` function (in
   `pydmtxmodule.c <https://sourceforge.net/p/libdmtx/dmtx-wrappers/ci/master/tree/python/>`__); there might be more of ``libdmtx``\ ’s functionality that could usefully
   be exposed

-  I exposed the bare minimum of functions, defines, enums and typedefs neede to
   reimplement ``pydmtx``\ ’s ``decode`` function

Contributors
------------

-  Vinicius Kursancew (@kursancew) - first implementation of barcode writing
-  Joseph Weston (@jbweston) - support for ``libdmtx`` 0.7.5

License
-------

``pylibdmtx`` is distributed under the MIT license (see ``LICENCE.txt``).
The ``libdmtx`` shared library is distributed under the Simplified BSD license
(see ``libdmtx-LICENCE.txt``).