Skip to main content

dotcode-extracter

CI Python 3.10+ License: MIT

dotcode-extracter is a Python library and command-line program for extracting and decoding DotCode bitstreams and already-cropped, fixed-grid DotCode images. It contains the original 5-of-9 mapping, code-set handling, masking, and Reed-Solomon logic over GF(113), wrapped in an import-safe package.

This is an alpha release. The image pipeline defaults to the 10-row by 47-column symbols used by the original project and will need calibration for other cameras, dot sizes, or symbol layouts.

Features

  • DotCode 5-of-9 codeword mapping and code-set decoding
  • Mask removal and Reed-Solomon error/erasure correction over GF(113)
  • OpenCV image pipeline for detecting and sampling fixed DotCode grids
  • Python API and dotcode-decode command-line interface
  • Typed package metadata and cross-platform automated tests

Installation

After the first release is published:

python -m pip install dotcode-extracter

For local development:

python -m venv .venv
.venv\Scripts\activate
python -m pip install -e ".[dev]"
pytest

On macOS or Linux, activate the environment with source .venv/bin/activate.

You can also install the current development version directly from GitHub:

python -m pip install "git+https://github.com/Shreejit-gautam/dotcode-decoder.git"

Python API

Decode a bitstream:

from dotcode_decoder import decode_dotcode_bits

result = decode_dotcode_bits("00...")
print(result["message"])

Decode a cropped image:

from dotcode_decoder import ImageDecoderConfig, decode_file

config = ImageDecoderConfig(threshold=180, rows=10, columns=47)
result = decode_file("symbol.png", config)
print(result.message)

If the dots are dark on a light background, set invert=True.

Command line

dotcode-extract bits "00..." --json
dotcode-extract image symbol.png --threshold 180 --json
dotcode-extract image dark-dots.png --invert

Commands print only the decoded message by default and return exit code 2 with a readable error when decoding fails.

The former dotcode-decode command remains available as a compatibility alias.

Project layout

src/dotcode_decoder/
  bitstream.py       Bit mapping, error correction, and code sets
  image.py           Dot detection, grid sampling, and image API
  region.py          Optional contour-based region extraction
  cli.py             Console entry point
tests/                Unit and CLI tests

The former dot_code.py, dot_locator.py, and dot_region.py names remain as local compatibility shims. New integrations should import dotcode_decoder.

Developers

Contributing and releases

See CONTRIBUTING.md for the development workflow. Releases should first be uploaded to TestPyPI, installed into a clean environment, and then published to PyPI. The included release workflow supports PyPI trusted publishing after the repository is configured as a trusted publisher.

Please report bugs and feature requests through GitHub Issues.

License

MIT. See LICENSE.

Metadata

Release files for dotcode-extracter 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dotcode-extracter 0.1.0
File Size Uploaded Provenance Actions
dotcode_extracter-0.1.0.tar.gz 19.3 kB With provenance Details for dotcode_extracter-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dotcode-extracter 0.1.0
File Interpreter ABI Platform Actions
dotcode_extracter-0.1.0-py3-none-any.whl Python 3 none any Details for dotcode_extracter-0.1.0-py3-none-any.whl

Total release size: 36.4 kB

Release files / dotcode_extracter-0.1.0.tar.gz

Download URL dotcode_extracter-0.1.0.tar.gz
Size 19.3 kB
Tags Source
SHA-256 checksum
How to use checksums
17bfb87d7ea605c4533c051f8957f51f324e5748f4537b968e32209dbd04947f
BLAKE2b-256 checksum
How to use checksums
e4ba30850dc2058bc4070d475bd36772028d89d720a97f0dfb8e6141ae8c3c7e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.

Transparency log

Release files / dotcode_extracter-0.1.0-py3-none-any.whl

Download URL dotcode_extracter-0.1.0-py3-none-any.whl
Size 17.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
34ed22cb9e68037d087bc2646fcf4db08097cc2c51ed4489a9cc18661e686fd8
BLAKE2b-256 checksum
How to use checksums
3c83ef3870218131bb8f8f581b4e82dc8b904e8f529c36c8e6838aac5bf222d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.

Transparency log

Security for dotcode-extracter 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for dotcode_extracter-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page