Tapirscan for Python

Scan Pillow images, NumPy arrays and PyTorch tensors with tapirscan.scan(image). Quick start · Functions · All arguments · Results

Installation

Python 3.10+ is required. Platform wheels bundle all four native modes. Registry publication is pending; until then, use the local build guide.

Quick start

Install tapirscan plus the image libraries you use. For these examples:

pip install tapirscan tifffile pillow torch

TIFF → NumPy array, using defaults:

import tifffile
import tapirscan

pixels = tifffile.imread("label.tif", key=0)  # NumPy array: first TIFF page
result = tapirscan.scan(pixels)
print(result.values)

This example assumes an 8-bit grayscale or RGB image. Defaults are Medium effort and EAN-13. No intermediate file or explicit scanner object is needed.

JPEG, with optional settings:

from PIL import Image
import tapirscan

with Image.open("label.jpg") as image:
    result = tapirscan.scan(image, mode="high", formats="1D")

for barcode in result:
    print(barcode.text, barcode.format, barcode.polygon)

formats="1D" enables all supported linear formats; "2D" and "all" are also available. Additional formats are experimental.

PyTorch tensor:

import torch

# Using the NumPy array from the TIFF example:
tensor = torch.from_numpy(pixels)
result = tapirscan.scan(tensor)
print(result.values)

GPU tensors and tensors with requires_grad=True work directly. Tapirscan detaches internally and transfers pixels to CPU; your tensor and its autograd graph are unchanged. Barcode decoding runs on CPU.

Moving from pyzbar or ZXing-C++

For a Pillow image or grayscale NumPy array, an EAN-13 values-only call changes like this:

# Before (pyzbar):
values = [barcode.data.decode("utf-8") for barcode in decode(image)]
# Before (zxing-cpp):
values = [barcode.text for barcode in zxingcpp.read_barcodes(image)]
# After (Tapirscan):
values = tapirscan.scan(image).values

The old calls assume their existing imports. Select your application's formats explicitly when it needs more than EAN13, for example formats=["EAN13", "Code128"]. Additional readers are experimental; verify coverage before replacing an existing scanner. API conventions are documented by pyzbar and ZXing-C++.

Start by running both libraries on your own images and comparing missing values, wrong reads and runtime. Preserve separate copies of equal-value symbols when counting instances. Reuse a Scanner for repeated images. A matching function shape alone does not make this a drop-in replacement.

Functions

Single-image function

tapirscan.scan(
    image, width=None, height=None, *,
    mode="medium", library_dir=None,
    channels=1, stride=None, multiple=True, debug=False,
    include_regions=None, formats=None, layout="auto", value_range="auto",
)

Returns ScanResult. Creates and closes a scanner automatically, including on failure. image is required; all other arguments are optional. Arguments after * must be passed by keyword. width and height are only needed for raw buffers.

Reusable scanner

tapirscan.Scanner(mode="medium", *, formats=None, library_dir=None)
scanner.scan(
    image, width=None, height=None, *,
    channels=1, stride=None, multiple=True, debug=False,
    include_regions=None, formats=None, layout="auto", value_range="auto",
)
scanner.close()

Use it for successive images to avoid initialization on every call:

import tapirscan

with tapirscan.Scanner(mode="high", formats="1D") as scanner:
    for image in images:
        result = scanner.scan(image)
        print(result.values)

The context manager calls close() even on exceptions. You can instead call close() in a finally block; repeated close is safe. Results remain valid after closure. Calls on one scanner serialize; separate scanners can run concurrently. Create another scanner to change mode. Per-call formats override the constructor selection for that call only; None inherits it.

All arguments

Library lookup: explicit library_dir, then TAPIRSCAN_LIBRARY_DIR, then bundled wheel libraries. The working directory is never searched implicitly.

Formats and group exports: Format, FormatSelection, retail_formats, linear_formats, matrix_formats. See exact identifiers and reader limitations. Presets cover supported symbologies. Additional readers use fixed effort; the four effort modes tune the EAN13/UPCA path.

Array and tensor inputs

Accepts one HW/HWC/CHW image, optionally with a leading batch axis of size one, with 1/3/4 channels. NumPy views and noncontiguous tensors are accepted. Colors are RGB/RGBA, not OpenCV BGR. Booleans become black/white. NaN, infinity and out-of-range values are rejected; explicitly scale higher-bit-depth intensities and undo mean/std normalization. The input buffer limit is 128 MiB.

GPU tensors (including CUDA and MPS) and requires_grad=True tensors can be passed directly. The adapter detaches internally, copies to CPU as needed, and makes pixels contiguous without changing the input or its autograd graph. The scan is not differentiable and decoding does not run on GPU. Device transfer adds latency. Sparse, quantized, complex and meta tensors are rejected.

Results and public types

ScanResult is an immutable sequence: iterate, index, slice, use len(result) or check its truth value. Empty results are false.

Coordinates start at the top left. The API returns geometry, not a cropped bitmap. If you resize before scanning, map coordinates back when drawing on the original. Other exported option types are Mode, Layout, ValueRange and ImageInput. The package includes py.typed for static type checkers.

Diagnostics

result = tapirscan.scan(image, debug=True)
if result.debug is not None and result.debug.regions is not None:
    print(result.debug.regions.proposals)
    print(result.debug.regions.search_windows)
    print(result.debug.regions.candidates)

Diagnostics also exposes barcodes (support, axis, candidate indices in result order), localization_limited and to_dict(). Region types are available in tapirscan.results. Reader-specific raw metadata, including GS1 and structured append, is retained in JSON. Evidence varies by reader. Candidate indices inside a recovery crop are local to that crop, not identifiers for tracking across frames.

Errors and migration helpers

Invalid input raises ValueError/TypeError; native errors raise ScannerError with a .code attribute. Scanning after close raises RuntimeError.

tapirscan.pyzbar.decode aliases tapirscan.scan. Barcode .data returns UTF-8 bytes, .type aliases format, .quality exposes the support heuristic, and .orientation is None. These ease migration but are not complete pyzbar compatibility; there is no symbols argument. Use the main API for new code.