Aztec tool 🛸

A fast, pure‑Python Aztec Code reader with auto‑orientation and Reed-Solomon correction.

Please note that the library is still under development, and some features are unstable. Typically, some Aztec files can be read incorrectly because the image has been exported incorrectly in matrix.

All contributions are welcome!

Table of content

1. Installation
2. Usage
3. Useful links
   • Contributing
   • Security
   • Changelog
   • TODO
   • License
   • Code of Conduct
4. Resources

Installation

This library is compatible with Python 3.9 and above.

To install the latest version of Aztec tool, you can use pip. Open your terminal and run the following command (in a virtual environment if you want to keep your system clean):

pip install --upgrade aztec_tool

If you cloned the repository, you can install it using pip as well, in the root directory of the project:

pip install --upgrade .

This library installs the following dependencies:

• OpenCV for image processing
• NumPy for numerical operations
• Reed-Solomon for error correction
• toml for version reading

Usage

The library allows you to decode Aztec barcodes from images.

The most common way to use the library is to use the AztecDecoder class. You can create an instance of the class and call the decode method with the path to the image file as an argument. With this class, you need to have your Aztec barcode perfectly cropped in an image.

>>> from aztec_tool import decode
>>> decode("welcome_lib.jpg")
'Welcome to Aztec tool lib !'
>>>

If you need to access more specific data, you can use the AztecDecoder class directly:

>>> from aztec_tool import AztecDecoder
>>> decoder = AztecDecoder("welcome_lib.jpg")
>>> decoder.aztec_type
<AztecType.COMPACT: 0>
>>> decoder.mode_info
{'layers': 3, 'data_words': 21, 'ecc_bits': [0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0]}
>>> decoder.decode()
'Welcome to Aztec tool lib !'

If you don't have the Aztec barcode perfectly cropped in an image, you can use this class to cropper it automatically:

>>> from aztec_tool import MultiAztecDecoder
>>> multi_decoder = MultiAztecDecoder("welcome_lib_non_cropped.jpg")
>>> decoder = multi_decoder.decoders[0]
>>> decoder.aztec_type
<AztecType.COMPACT: 0>
>>> decoder.mode_info
{'layers': 3, 'data_words': 21, 'ecc_bits': [0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0]}
>>> decoder.decode()
'Welcome to Aztec tool lib !'

When you're using the decode function or the AztecDecoder (or MultiAztecDecoder) class, you can also pass three optional parameters:

• auto_orient: Default is True. If set to True, the image will be automatically rotated to the correct orientation before decoding. This is useful if the barcode is reversed or rotated.
• auto_correct: Default is True. If set to True, the data in the Aztec barcode will be automatically corrected. This is useful if the barcode is damaged or has errors.
• auto_mode_correct: Default is True. If set to True, the mode data in the Aztec barcode will be automatically corrected. This is useful if the barcode is damaged or has errors.

If you have some problems with the correction, it can be useful to set auto_correct and/or auto_mode_correct to False.

If you need very specific data, you can access the AztecDecoder class attributes, or directly the various classes used in the library.

This library has its own exceptions. You can find them in the exceptions.py file. The most common exception is AztecDecoderError, which is the parent class of all the exceptions in the library.

The tool is also available as a command line interface (CLI). You can use it by running the following command in your terminal:

$ aztec-tool welcome_lib.jpg
Welcome to Aztec tool lib !

If you want to print the metadata of the Aztec code, you can use the --info option:

$ aztec-tool welcome_lib.jpg --info
Type:         COMPACT
Layers:       3
Data words:   21
ECC bits:     01010101010010101000

You can view all available options by running aztec-tool -h.

Useful links

Contributing

Contributions are welcome! If you want to contribute to the project, please read the CONTRIBUTING.md file.

Security

If you discover any security vulnerabilities, please read the procedure in the SECURITY.md file.

Changelog

The full changelog is available in the CHANGELOG.md file.

TODO

The plan for the next releases is available in the TODO.md file.

License

The Aztec tool is licensed under the MIT License. See the LICENSE file for more details.

Code of Conduct

The Aztec tool is committed to providing a friendly, safe, and welcoming environment for all. Please read the CODE_OF_CONDUCT.md file for more details.

Resources

These resources were very useful to understand the Aztec code and build this library:

• Wikipedia - Aztec code
• Youtube - How to Decode the Aztec Code
• ISO/IEC 24778:2024: Information technology - Automatic identification and data capture techniques - Aztec Code bar code symbology specification