Rxing

rxing decodes barcodes from image binaries using a source-built Rustler NIF powered by the Rust rxing crate.

Installation

def deps do
  [
    {:rxing, "~> 0.1.0"}
  ]
end

rxing compiles its native library from source when the dependency is compiled. Install Rust 1.91 or newer (rustc and cargo) before running mix compile.

Immediate Example (binary input)

image = File.read!("path/to/barcode.png")

{:ok, [%Rxing.Result{format: :qr_code} | _results]} =
  Rxing.decode(image, formats: [:qr_code])

Public APIs

Rxing exposes three decoding entry points:

• Rxing.decode/2 decodes every supported barcode in an image binary.
• Rxing.decode_one/2 decodes the first supported barcode or returns {:error, :not_found}.
• Rxing.decode_file/2 reads an image from a path and decodes it.

All APIs share the same option vocabulary and stable error vocabulary.

Decoding Binaries, One Result, and Files

image = File.read!("path/to/barcodes.png")

# Decode every result up to the configured bound.
{:ok, results} =
  Rxing.decode(image, formats: [:qr_code, :data_matrix], max_results: 32)

# Decode only the first result.
{:ok, first} = Rxing.decode_one(image, formats: [:qr_code, :data_matrix])
%Rxing.Result{} = first

# Let Rxing read a regular file after applying the input-size pre-check.
{:ok, file_results} =
  Rxing.decode_file("path/to/barcodes.png", formats: [:qr_code, :data_matrix])

results and file_results are lists of %Rxing.Result{} values in upstream detection order. When no barcode is recognized, decoding returns {:ok, []}.

Supported Barcode Formats

Rxing.formats/0 returns the guaranteed format set in stable order:

• :qr_code
• :data_matrix
• :code_128
• :ean_13

Supported Image Encodings

The binary API accepts these content-detectable formats from image 0.25:

• BMP
• DDS
• OpenEXR
• farbfeld
• GIF
• HDR
• ICO
• JPEG
• PNG
• PNM
• QOI
• TIFF
• WebP

Committed integration fixtures guarantee representative decoding coverage for PNG, JPEG, GIF, BMP, and WebP. Other enabled encodings use the same content-based classification and decoding pipeline.

AVIF and TGA are not accepted by the current binary-only pipeline: AVIF decoding requires the separate image/avif-native feature, while image::guess_format cannot identify TGA without a filename extension.

Options, Filtering, and Defaults

Public options:

• :formats (default: [:qr_code, :data_matrix, :code_128, :ean_13])
• :try_harder (default: false)
• :try_inverted (default: false)
• :max_results (default: 32, allowed range 1..256)
• :max_input_bytes (default: 20 * 1024 * 1024)
• :max_width (default: 10_000)
• :max_height (default: 10_000)
• :max_pixels (default: 40_000_000)
• :max_alloc_bytes (default: 256 * 1024 * 1024)

Filtering examples:

• Restrict formats: formats: [:qr_code]
• Enable rotated scan retries: try_harder: true
• Enable inverted scan retries: try_inverted: true
• Raise result bound for dense images: max_results: 64

Stable Errors

Decode operations return:

• {:error, :invalid_image}
• {:error, :internal_error}
• {:error, {:unsupported_format, format}}
• {:error, {:invalid_option, key}}
• {:error, {:limit_exceeded, limit}}
• {:error, {:file, reason}} (decode_file/2)
• {:error, :not_found} (decode_one/2)

Result Payload, Raw Bytes, and Metadata

Every successful decode returns %Rxing.Result{} values:

• :format - one of the supported barcode format atoms.
• :text - decoded UTF-8 text when available, else nil.
• :raw_bytes - raw decoded bytes when available, else nil.
• :points - list of %{x: float(), y: float()} result points.
• :metadata - decoder metadata map. Supported keys include: :orientation, :byte_segments, :error_correction_level, :structured_append_sequence, :structured_append_parity, :symbology_identifier, :is_inverted, and :is_mirrored.

Runtime and Concurrency Notes

• Native decoding runs on dirty CPU schedulers to avoid monopolizing normal BEAM schedulers.
• Callers remain responsible for choosing safe request-level concurrency and backpressure limits.

Source Build Requirements and Platforms

• Elixir: ~> 1.15.
• Tested runtime pairs: Elixir 1.15.8 / OTP 26 and Elixir 1.20 / OTP 29.
• Rust toolchain: rustc/cargo 1.91 or newer.
• The native crate is built from source during dependency compilation.
• Supported CI platforms: Linux and macOS.

Benchmarks

From a repository checkout with development dependencies installed, run:

mix run bench/rxing_bench.exs

The non-gating Benchee report includes throughput, median, p95, and p99 latency, BEAM memory, scheduler counts, run-queue snapshots, and heartbeat observations. It covers the guaranteed barcode formats, clean/rotated/inverted/damaged/multiple and no-code scenarios, an image-size sweep, and concurrency levels 1 through 32.

Treat the output as a baseline for comparisons made on the same host and toolchain. It deliberately contains no pass/fail latency thresholds or portable speed claims.

Non-goals (0.1.0)

• Barcode encoding/generation APIs.
• Precompiled NIF artifacts in Hex packages.
• Alternative native backends beyond Rust rxing.

License

MIT. See LICENSE.