annular-text-rectifier
annular-text-rectifier straightens text printed along a circular arc into a rectangular image suitable for OCR. It uses deterministic inverse polar mapping, requires no trained model, and depends only on NumPy.
It is intended for text on seals, stamps, bottle caps, coins, bearings, rings, gauges, and circular labels. It does not claim to rectify arbitrary free-form curves.
Installation
pip install annular-text-rectifier
For local development:
python -m pip install -e ".[dev]"
Basic usage
import numpy as np
from annular_text_rectifier import rectify_annular_text
image = np.asarray(...) # (height, width) or (height, width, channels)
polygon = np.array([
[120, 80],
[160, 65],
[205, 80],
[195, 105],
[160, 92],
[130, 105],
])
result = rectify_annular_text(
image,
polygon,
center=(160, 160),
direction="clockwise",
radial_order="inner-to-outer",
output_height=48,
)
rectified = result.image
print(result.geometry.as_dict())
With OpenCV for file input/output (OpenCV is optional and not installed by this package):
import cv2
import numpy as np
from annular_text_rectifier import rectify_annular_text
image = cv2.imread("seal.png")
polygon = np.load("seal_polygon.npy")
result = rectify_annular_text(
image,
polygon,
center=(350, 380),
direction="clockwise",
radial_order="outer-to-inner",
output_height=48,
)
cv2.imwrite("seal_rectified.png", result.image)
Supplying the circle center is recommended. For sufficiently long, well-described annular polygons, the center can be estimated:
result = rectify_annular_text(image, polygon)
Inspect result.geometry.normalized_fit_error when using automatic estimation. Ambiguous estimates raise GeometryEstimationError rather than silently producing a misleading crop. Short arcs should use an explicit center.
Reading direction
Image geometry cannot determine the language's natural reading order or whether glyphs point inward or outward. Configure both explicitly:
direction="clockwise"or"counterclockwise"controls horizontal order.radial_order="inner-to-outer"or"outer-to-inner"controls vertical order.
An OCR orientation classifier can be applied after rectification if these properties are unknown.
Stable integration API
The package exposes three public operations:
from annular_text_rectifier import (
build_rectification_map,
estimate_annular_geometry,
rectify_annular_text,
)
estimate_annular_geometryvalidates a polygon and estimates its polar bounds.build_rectification_mapproduces reproducible source coordinate maps.rectify_annular_textestimates geometry, remaps pixels, and returns metadata.
The separation lets OCR libraries use their own tensor or GPU sampling implementation while sharing the same geometry.
Limitations
- The text baseline must be approximately circular.
- Automatic center estimation requires at least six useful boundary points.
- A short arc usually needs a known center.
- The polygon should cover both inner and outer boundaries of the text band.
- Perspective distortion of the circular plane should be corrected before polar rectification.
Development checks
python -m pytest
python -m ruff check .
python -m build
python -m twine check dist/*
Publishing
The GitHub Actions workflow tests Python 3.9 through 3.14, builds both distributions, and uploads them as a workflow artifact. Publishing a GitHub Release additionally publishes the validated distributions to PyPI through Trusted Publishing.
Configure the PyPI trusted publisher with:
- Owner:
Shreejit-gautam - Repository:
annular-text-rectifier - Workflow:
workflow.yml - Environment:
pypi
The GitHub Release tag should match the package version, for example v0.1.0.
License
MIT License.
Developers
- Shreejit Gautam
- Pranav Subedi
Metadata
Release files for annular-text-rectifier 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| annular_text_rectifier-0.1.0.tar.gz | 13.4 kB | With provenance | Details for annular_text_rectifier-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| annular_text_rectifier-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for annular_text_rectifier-0.1.0-py3-none-any.whl |
Total release size: 25.1 kB
Release files / annular_text_rectifier-0.1.0.tar.gz
| Download URL | annular_text_rectifier-0.1.0.tar.gz |
|---|---|
| Size | 13.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c919b3cfd05aef957c68a8e660c87ea2916fe2db465659295b8bb23081a4ea05
|
|
BLAKE2b-256 checksum How to use checksums |
e40452a385cc6548acd1d88614da4187175743c6969d22bd000d0f5bae85ca5a
|
| 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 logRelease files / annular_text_rectifier-0.1.0-py3-none-any.whl
| Download URL | annular_text_rectifier-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
abe155cd5c39b9e91131116fadc10de27a68106f1c86e0773ff57a376a51a756
|
|
BLAKE2b-256 checksum How to use checksums |
6992ecdb51aa3b769a37dcd861aabf234a306624f1deeff35e80dd74d3973430
|
| 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 logSecurity for annular-text-rectifier 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.
Attestation for annular_text_rectifier-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 logA 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.