Metadata-Version: 2.4
Name: dotcode-extracter
Version: 0.1.0
Summary: Decode DotCode bitstreams and fixed-grid DotCode images
Author: Shreejit Gautam, Pranav Subedi
License-Expression: MIT
Project-URL: Homepage, https://github.com/Shreejit-gautam/dotcode-decoder
Project-URL: Repository, https://github.com/Shreejit-gautam/dotcode-decoder.git
Project-URL: Issues, https://github.com/Shreejit-gautam/dotcode-decoder/issues
Project-URL: Changelog, https://github.com/Shreejit-gautam/dotcode-decoder/blob/main/CHANGELOG.md
Keywords: barcode,computer-vision,decoder,dotcode,opencv
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: opencv-python>=4.7
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# dotcode-extracter

[![CI](https://github.com/Shreejit-gautam/dotcode-decoder/actions/workflows/ci.yml/badge.svg)](https://github.com/Shreejit-gautam/dotcode-decoder/actions/workflows/ci.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

`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:

```console
python -m pip install dotcode-extracter
```

For local development:

```console
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:

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

## Python API

Decode a bitstream:

```python
from dotcode_decoder import decode_dotcode_bits

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

Decode a cropped image:

```python
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

```console
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

```text
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

- [Shreejit Gautam](https://github.com/Shreejit-gautam)
- Pranav Subedi

## Contributing and releases

See [CONTRIBUTING.md](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](https://github.com/Shreejit-gautam/dotcode-decoder/issues).

## License

MIT. See [LICENSE](LICENSE).
