README.md formatting tweaks
This commit is contained in:
Alexandre Perrin
parent
db4046f997
commit
b77da026c9
1 changed files with 121 additions and 120 deletions
241
README.md
241
README.md
|
|
@ -1,176 +1,177 @@
|
|||
Quirc
|
||||
=====
|
||||
|
||||
QR codes are a type of high-density matrix barcodes, and quirc is a
|
||||
library for extracting and decoding them from images. It has several
|
||||
features which make it a good choice for this purpose:
|
||||
QR codes are a type of high-density matrix barcodes, and quirc is a library for
|
||||
extracting and decoding them from images. It has several features which make it
|
||||
a good choice for this purpose:
|
||||
|
||||
* It is fast enough to be used with realtime video: extracting and
|
||||
decoding from VGA frame takes about 50 ms on a modern x86 core.
|
||||
* It is fast enough to be used with realtime video: extracting and decoding
|
||||
from VGA frame takes about 50 ms on a modern x86 core.
|
||||
|
||||
* It has a robust and tolerant recognition algorithm. It can
|
||||
correctly recognise and decode QR codes which are rotated and/or
|
||||
oblique to the camera. It can also distinguish and decode multiple
|
||||
codes within the same image.
|
||||
* It has a robust and tolerant recognition algorithm. It can correctly
|
||||
recognise and decode QR codes which are rotated and/or oblique to the camera.
|
||||
It can also distinguish and decode multiple codes within the same image.
|
||||
|
||||
* It is easy to use, with a simple API described in a single
|
||||
commented header file (see below for an overview).
|
||||
* It is easy to use, with a simple API described in a single commented header
|
||||
file (see below for an overview).
|
||||
|
||||
* It is small and easily embeddable, with no dependencies other than
|
||||
standard C functions.
|
||||
* It is small and easily embeddable, with no dependencies other than standard C
|
||||
functions.
|
||||
|
||||
* It has a very small memory footprint: one byte per image pixel,
|
||||
plus a few kB per decoder object.
|
||||
* It has a very small memory footprint: one byte per image pixel, plus a few kB
|
||||
per decoder object.
|
||||
|
||||
* It uses no global mutable state, and is safe to use in a
|
||||
multithreaded application.
|
||||
* It uses no global mutable state, and is safe to use in a multithreaded
|
||||
application.
|
||||
|
||||
* BSD-licensed, with almost no restrictions regarding use and/or
|
||||
modification.
|
||||
* BSD-licensed, with almost no restrictions regarding use and/or modification.
|
||||
|
||||
The distribution comes with, in addition to the library, several test
|
||||
programs. While the core library is very portable, these programs have
|
||||
some additional dependencies. All of them require libjpeg, and two
|
||||
(``quirc-demo`` and ``inspect``) require SDL. The camera demos use
|
||||
Linux-specific APIs:
|
||||
The distribution comes with, in addition to the library, several test programs.
|
||||
While the core library is very portable, these programs have some additional
|
||||
dependencies. All of them require libjpeg, and two (`quirc-demo` and `inspect`)
|
||||
require SDL. The camera demos use Linux-specific APIs:
|
||||
|
||||
``quirc-demo``
|
||||
### quirc-demo
|
||||
|
||||
~ This is an real-time demo which requires a camera and a graphical
|
||||
display. The video stream is displayed on screen as it's received,
|
||||
and any QR codes recognised are highlighted in the image, with the
|
||||
decoded information both displayed on the image and printed on
|
||||
stdout.
|
||||
This is an real-time demo which requires a camera and a graphical display. The
|
||||
video stream is displayed on screen as it's received, and any QR codes
|
||||
recognised are highlighted in the image, with the decoded information both
|
||||
displayed on the image and printed on stdout.
|
||||
|
||||
``quirc-scanner``
|
||||
### quirc-scanner
|
||||
|
||||
~ This program turns your camera into a barcode scanner. It's almost
|
||||
the same as the ``demo`` application, but it doesn't display the
|
||||
video stream, and thus doesn't require a graphical display.
|
||||
This program turns your camera into a barcode scanner. It's almost the same as
|
||||
the `demo` application, but it doesn't display the video stream, and thus
|
||||
doesn't require a graphical display.
|
||||
|
||||
``qrtest``
|
||||
### qrtest
|
||||
|
||||
~ This test is used to evaluate the performance of library. Given a
|
||||
directory tree containing a bunch of JPEG images, it will attempt
|
||||
to locate and decode QR codes in each image. Speed and success
|
||||
statistics are collected and printed on stdout.
|
||||
This test is used to evaluate the performance of library. Given a directory
|
||||
tree containing a bunch of JPEG images, it will attempt to locate and decode QR
|
||||
codes in each image. Speed and success statistics are collected and printed on
|
||||
stdout.
|
||||
|
||||
``inspect``
|
||||
### inspect
|
||||
|
||||
~ This test is used for debugging. Given a single JPEG image, it
|
||||
will display a diagram showing the internal state of the decoder
|
||||
as well as printing additional information on stdout.
|
||||
This test is used for debugging. Given a single JPEG image, it will display a
|
||||
diagram showing the internal state of the decoder as well as printing
|
||||
additional information on stdout.
|
||||
|
||||
Installation
|
||||
------------
|
||||
To build the library and associated demos/tests, type `make`. Type
|
||||
`make install` to install the library, header file and camera demos.
|
||||
|
||||
To build the library and associated demos/tests, type ``make``. Type
|
||||
``make install`` to install the library, header file and camera demos.
|
||||
You can specify one or several of the following targets if you don't want, or
|
||||
are unable to build everything:
|
||||
|
||||
You can specify one or several of the following targets if you don't
|
||||
want, or are unable to build everything:
|
||||
|
||||
* libquirc.a
|
||||
* libquirc.so
|
||||
* qrtest
|
||||
* inspect
|
||||
* quirc-scanner
|
||||
* quirc-demo
|
||||
* libquirc.a
|
||||
* libquirc.so
|
||||
* qrtest
|
||||
* inspect
|
||||
* quirc-scanner
|
||||
* quirc-demo
|
||||
|
||||
Library use
|
||||
-----------
|
||||
All of the library's functionality is exposed through a single header file,
|
||||
which you should include:
|
||||
|
||||
All of the library's functionality is exposed through a single header
|
||||
file, which you should include:
|
||||
```C
|
||||
#include <quirc.h>
|
||||
```
|
||||
|
||||
#include <quirc.h>
|
||||
To decode images, you'll need to instantiate a `struct quirc` object, which is
|
||||
done with the `quirc_new` function. Later, when you no longer need to decode
|
||||
anything, you should release the allocated memory with `quirc_destroy`:
|
||||
|
||||
To decode images, you'll need to instantiate a ``struct quirc``
|
||||
object, which is done with the ``quirc_new`` function. Later, when you
|
||||
no longer need to decode anything, you should release the allocated
|
||||
memory with ``quirc_destroy``:
|
||||
```C
|
||||
struct quirc *qr;
|
||||
|
||||
struct quirc *qr;
|
||||
qr = quirc_new();
|
||||
if (!qr) {
|
||||
perror("Failed to allocate memory");
|
||||
abort();
|
||||
}
|
||||
|
||||
qr = quirc_new();
|
||||
if (!qr) {
|
||||
perror("Failed to allocate memory");
|
||||
abort();
|
||||
}
|
||||
/* ... */
|
||||
|
||||
/* ... */
|
||||
quirc_destroy(qr);
|
||||
```
|
||||
|
||||
quirc_destroy(qr);
|
||||
Having obtained a decoder object, you need to set the image size that you'll be
|
||||
working with, which is done using `quirc_resize`:
|
||||
|
||||
Having obtained a decoder object, you need to set the image size that
|
||||
you'll be working with, which is done using ``quirc_resize``:
|
||||
```C
|
||||
if (quirc_resize(qr, 640, 480) < 0) {
|
||||
perror("Failed to allocate video memory");
|
||||
abort();
|
||||
}
|
||||
```
|
||||
|
||||
if (quirc_resize(qr, 640, 480) < 0) {
|
||||
perror("Failed to allocate video memory");
|
||||
abort();
|
||||
}
|
||||
|
||||
``quirc_resize`` and ``quirc_new`` are the only library functions
|
||||
which allocate memory. If you plan to process a series of frames (or a
|
||||
video stream), you probably want to allocate and size a single decoder
|
||||
and hold onto it to process each frame.
|
||||
`quirc_resize` and `quirc_new` are the only library functions which allocate
|
||||
memory. If you plan to process a series of frames (or a video stream), you
|
||||
probably want to allocate and size a single decoder and hold onto it to process
|
||||
each frame.
|
||||
|
||||
Processing frames is done in two stages. The first stage is an
|
||||
image-recognition stage called identification, which takes a grayscale
|
||||
image and searches for QR codes. Using ``quirc_begin`` and
|
||||
``quirc_end``, you can feed a grayscale image directly into the buffer
|
||||
that ``quirc`` uses for image processing:
|
||||
image-recognition stage called identification, which takes a grayscale image
|
||||
and searches for QR codes. Using `quirc_begin` and `quirc_end`, you can feed a
|
||||
grayscale image directly into the buffer that `quirc` uses for image
|
||||
processing:
|
||||
|
||||
uint8_t *image;
|
||||
int w, h;
|
||||
```C
|
||||
uint8_t *image;
|
||||
int w, h;
|
||||
|
||||
image = quirc_begin(qr, &w, &h);
|
||||
image = quirc_begin(qr, &w, &h);
|
||||
|
||||
/* Fill out the image buffer here.
|
||||
* image is a pointer to a w*h bytes.
|
||||
* One byte per pixel, w pixels per line, h lines in the buffer.
|
||||
*/
|
||||
/* Fill out the image buffer here.
|
||||
* image is a pointer to a w*h bytes.
|
||||
* One byte per pixel, w pixels per line, h lines in the buffer.
|
||||
*/
|
||||
|
||||
quirc_end(qr);
|
||||
quirc_end(qr);
|
||||
```
|
||||
|
||||
Note that ``quirc_begin`` simply returns a pointer to a previously
|
||||
allocated buffer. The buffer will contain uninitialized data. After
|
||||
the call to ``quirc_end``, the decoder holds a list of detected QR
|
||||
codes which can be queried via ``quirc_count`` and ``quirc_extract``.
|
||||
Note that `quirc_begin` simply returns a pointer to a previously allocated
|
||||
buffer. The buffer will contain uninitialized data. After the call to
|
||||
`quirc_end`, the decoder holds a list of detected QR codes which can be queried
|
||||
via `quirc_count` and `quirc_extract`.
|
||||
|
||||
At this point, the second stage of processing occurs -- decoding. This
|
||||
is done via the call to ``quirc_decode``, which is not associated with
|
||||
a decoder object.
|
||||
At this point, the second stage of processing occurs -- decoding. This is done
|
||||
via the call to `quirc_decode`, which is not associated with a decoder object.
|
||||
|
||||
int num_codes;
|
||||
int i;
|
||||
```C
|
||||
int num_codes;
|
||||
int i;
|
||||
|
||||
/* We've previously fed an image to the decoder via
|
||||
* quirc_begin/quirc_end.
|
||||
*/
|
||||
/* We've previously fed an image to the decoder via
|
||||
* quirc_begin/quirc_end.
|
||||
*/
|
||||
|
||||
num_codes = quirc_count(qr);
|
||||
for (i = 0; i < num_codes; i++) {
|
||||
struct quirc_code code;
|
||||
struct quirc_data data;
|
||||
quirc_decode_error_t err;
|
||||
num_codes = quirc_count(qr);
|
||||
for (i = 0; i < num_codes; i++) {
|
||||
struct quirc_code code;
|
||||
struct quirc_data data;
|
||||
quirc_decode_error_t err;
|
||||
|
||||
quirc_extract(qr, i, &code);
|
||||
quirc_extract(qr, i, &code);
|
||||
|
||||
/* Decoding stage */
|
||||
err = quirc_decode(&code, &data);
|
||||
if (err)
|
||||
printf("DECODE FAILED: %s\n", quirc_strerror(err));
|
||||
else
|
||||
printf("Data: %s\n", data.payload);
|
||||
}
|
||||
/* Decoding stage */
|
||||
err = quirc_decode(&code, &data);
|
||||
if (err)
|
||||
printf("DECODE FAILED: %s\n", quirc_strerror(err));
|
||||
else
|
||||
printf("Data: %s\n", data.payload);
|
||||
}
|
||||
```
|
||||
|
||||
``quirc_code`` and ``quirc_data`` are flat structures which don't need
|
||||
to be initialized or freed after use.
|
||||
`quirc_code` and `quirc_data` are flat structures which don't need to be
|
||||
initialized or freed after use.
|
||||
|
||||
Copyright
|
||||
---------
|
||||
|
||||
Copyright (C) 2010-2012 Daniel Beer <<dlbeer@gmail.com>>
|
||||
|
||||
Permission to use, copy, modify, and/or distribute this software for
|
||||
|
|
|
|||
Loading…
Reference in a new issue