Skip to main content

annular-text-rectifier

CI

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_geometry validates a polygon and estimates its polar bounds.
  • build_rectification_map produces reproducible source coordinate maps.
  • rectify_annular_text estimates 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)

Source distribution for annular-text-rectifier 0.1.0
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)

Table of built distributions (wheels) for annular-text-rectifier 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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