zxing_ffi 0.1.0

data/lib/zxing_ffi/sniffer.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # Identifies inputs by their magic bytes, never by file name or extension.
+  #
+  # @example
+  #   ZXingFFI::Sniffer.sniff("upload.bin")      # => :tiff
+  #   ZXingFFI::Sniffer.detect("%PDF-1.7\n...")  # => :pdf
+  module Sniffer
+    # Every kind {detect} and {sniff} can return.
+    KINDS = %i[pdf png jpeg tiff gif bmp webp heif avif pnm].freeze
+    # Number of leading bytes examined. {sniff} reads at most this many.
+    HEAD_SIZE = 1024
+
+    PNG_MAGIC = "\x89PNG\r\n\x1A\n".b.freeze
+    JPEG_MAGIC = "\xFF\xD8\xFF".b.freeze
+    # Classic TIFF and BigTIFF, little- and big-endian.
+    TIFF_MAGICS = ["II*\0", "MM\0*", "II+\0", "MM\0+"].freeze
+    GIF_MAGICS = %w[GIF87a GIF89a].freeze
+    PDF_MAGIC = "%PDF-"
+    # Sizes of the known BMP DIB headers (BITMAPCOREHEADER, OS/2 v2, BITMAPINFOHEADER .. BITMAPV5HEADER).
+    BMP_HEADER_SIZES = [12, 16, 40, 52, 56, 64, 108, 124].freeze
+    AVIF_BRANDS = %w[avif avis].freeze
+    HEIF_BRANDS = %w[heic heix heim heis hevc hevx].freeze
+    # Generic HEIF image / image-sequence brands: AVIF when an AVIF brand is also listed, HEIF otherwise.
+    MIAF_BRANDS = %w[mif1 msf1].freeze
+    # P1-P6 followed by whitespace or a comment. P7 (PAM) is not supported.
+    PNM_MAGIC = /\AP[1-6][ \t\n\v\f\r#]/n
+    NON_PRINTABLE = /[^\x20-\x7E]/n
+    private_constant :PNG_MAGIC, :JPEG_MAGIC, :TIFF_MAGICS, :GIF_MAGICS, :PDF_MAGIC, :BMP_HEADER_SIZES,
+      :AVIF_BRANDS, :HEIF_BRANDS, :MIAF_BRANDS, :PNM_MAGIC, :NON_PRINTABLE
+
+    class << self
+      # Detects the kind of data from its first bytes.
+      #
+      # Signatures at offset 0 are checked first. A PDF is recognized by +%PDF-+ anywhere in the first
+      # {HEAD_SIZE} bytes, because PDF readers accept leading junk.
+      #
+      # @param head [String, nil] the first bytes of the input, in any encoding (always treated as bytes);
+      #   only the first {HEAD_SIZE} bytes are examined
+      # @return [Symbol, nil] one of {KINDS}, or nil if the format is not recognized
+      def detect(head)
+        return nil if head.nil?
+        raise TypeError, "expected a String, got #{head.class}" unless head.is_a?(String)
+
+        bytes = head.b.byteslice(0, HEAD_SIZE)
+        signature_kind(bytes) || (bytes.include?(PDF_MAGIC) ? :pdf : nil)
+      end
+
+      # Detects the kind of a file or IO from its content.
+      #
+      # @param input [String, Pathname, IO] a path, or an IO read from its current position. At most
+      #   {HEAD_SIZE} bytes are read, and a seekable IO is moved back to where it was (bytes read from a pipe
+      #   stay consumed).
+      # @return [Symbol] one of {KINDS}
+      # @raise [UnsupportedInput] if the input is empty or its format is not recognized
+      # @raise [SystemCallError] if the file cannot be read (e.g. +Errno::ENOENT+)
+      # @raise [TypeError] if +input+ is neither a path nor an IO
+      def sniff(input)
+        head, label = read_head(input)
+        raise UnsupportedInput, "empty input: #{label} contains no data" if head.empty?
+
+        detect(head) || raise(UnsupportedInput, unrecognized_message(head, label))
+      end
+
+      private
+
+      def signature_kind(bytes)
+        if bytes.start_with?(PNG_MAGIC) then :png
+        elsif bytes.start_with?(JPEG_MAGIC) then :jpeg
+        elsif bytes.start_with?(*TIFF_MAGICS) then :tiff
+        elsif bytes.start_with?(*GIF_MAGICS) then :gif
+        elsif bmp?(bytes) then :bmp
+        elsif bytes.start_with?("RIFF") && bytes.byteslice(8, 4) == "WEBP" then :webp
+        elsif bytes.byteslice(4, 4) == "ftyp" then iso_bmff_kind(bytes)
+        elsif bytes.match?(PNM_MAGIC) then :pnm
+        end
+      end
+
+      # "BM" alone is too weak (plain text can start with it): also require a known DIB header size.
+      def bmp?(bytes)
+        bytes.start_with?("BM") && bytes.bytesize >= 18 &&
+          BMP_HEADER_SIZES.include?(bytes.unpack1("V", offset: 14))
+      end
+
+      # HEIF and AVIF files start with an ISO-BMFF ftyp box: size (uint32 BE, 0 = to the end of the file),
+      # "ftyp", major brand, minor version, then compatible brands up to the end of the box.
+      def iso_bmff_kind(bytes)
+        return nil if bytes.bytesize < 12
+
+        size = bytes.unpack1("N")
+        return nil if size.between?(1, 15) # 1 = 64-bit size (never used for ftyp); 2..15 can't hold the brands
+
+        box_end = size.zero? ? bytes.bytesize : [size, bytes.bytesize].min
+        compatible = (16..box_end - 4).step(4).map { |offset| bytes.byteslice(offset, 4) }
+        brand_kind(bytes.byteslice(8, 4), compatible)
+      end
+
+      def brand_kind(major, compatible)
+        return :avif if AVIF_BRANDS.include?(major)
+        return :heif if HEIF_BRANDS.include?(major)
+        return nil unless MIAF_BRANDS.include?(major)
+
+        compatible.intersect?(AVIF_BRANDS) ? :avif : :heif
+      end
+
+      # Returns the first bytes (BINARY) and a label for messages.
+      def read_head(input)
+        if input.is_a?(String) || (defined?(::Pathname) && input.is_a?(::Pathname))
+          path = input.to_s
+          [File.open(path, "rb") { |file| file.read(HEAD_SIZE) }.to_s, path]
+        elsif input.respond_to?(:read)
+          [read_io_head(input), io_label(input)]
+        else
+          raise TypeError, "expected a path (String or Pathname) or an IO, got #{input.class}"
+        end
+      end
+
+      def read_io_head(io)
+        position = io_position(io)
+        begin
+          io.read(HEAD_SIZE).to_s.b
+        ensure
+          io.seek(position) if position
+        end
+      end
+
+      def io_position(io)
+        return nil unless io.respond_to?(:pos) && io.respond_to?(:seek)
+
+        io.pos
+      rescue SystemCallError, IOError # pipes, sockets and other unseekable streams
+        nil
+      end
+
+      def io_label(io)
+        path = io.path if io.respond_to?(:path)
+        path ? path.to_s : io.class.to_s
+      rescue IOError
+        io.class.to_s
+      end
+
+      def unrecognized_message(head, label)
+        "unrecognized input format: #{label} is not a PDF, PNG, JPEG, TIFF, GIF, BMP, WebP, HEIF, AVIF or " \
+          "PNM file (first bytes: #{hex_dump(head)}); the format is detected from the content, not the file name"
+      end
+
+      # "25 50 44 46 |%PDF|": hex and printable ASCII of the first 16 bytes.
+      def hex_dump(bytes)
+        sample = bytes.byteslice(0, 16)
+        "#{sample.unpack1("H*").scan(/../).join(" ")} |#{sample.gsub(NON_PRINTABLE, ".")}|"
+      end
+    end
+  end
+end

data/lib/zxing_ffi/source.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module ZXingFFI
+  # A scan input normalized to an absolute file path plus its sniffed kind.
+  #
+  # Paths are made absolute so a leading "-" can never be read as a CLI option. IO inputs are spooled to a
+  # 0600 Tempfile that {.open} always removes.
+  class Source
+    # @return [String] absolute path
+    attr_reader :path
+    # @return [Symbol] sniffed kind (see {Sniffer::KINDS})
+    attr_reader :kind
+    # @return [String, nil] a display name (original path, or the IO's path if it has one)
+    attr_reader :name
+
+    # Yields a Source for +input+ and cleans up any temp file afterwards.
+    #
+    # @param input [String, Pathname, IO, #read] a path or a readable IO (read from its current position)
+    # @yieldparam source [Source]
+    # @raise [UnsupportedInput] for unknown file types or unsupported input objects
+    def self.open(input)
+      tempfile = nil
+      path, name =
+        # Pathname responds to #read too, so check it before the IO branch (it must not be spooled).
+        if input.is_a?(String) || (defined?(::Pathname) && input.is_a?(::Pathname)) || (input.respond_to?(:to_path) && !input.respond_to?(:read))
+          full = File.expand_path(input.respond_to?(:to_path) ? input.to_path : input)
+          raise Errno::ENOENT, full unless File.file?(full)
+
+          [full, input.to_s]
+        elsif input.respond_to?(:read)
+          tempfile = spool(input)
+          [tempfile.path, (input.respond_to?(:path) ? input.path : nil)]
+        else
+          raise UnsupportedInput, "expected a path, an IO or a ZXingFFI::Image, got #{input.class}"
+        end
+      yield new(path, Sniffer.sniff(path), name)
+    ensure
+      if tempfile
+        tempfile.close
+        File.unlink(tempfile.path) if File.exist?(tempfile.path)
+      end
+    end
+
+    # Copies an IO into a private temp file.
+    # @return [File] closed-for-writing temp file (caller removes it)
+    def self.spool(io)
+      file = Tempfile.create(["zxing_ffi", ".input"], binmode: true) # created 0600
+      IO.copy_stream(io, file)
+      file.flush
+      file
+    rescue
+      if file
+        file.close
+        File.unlink(file.path) if File.exist?(file.path)
+      end
+      raise
+    end
+
+    def initialize(path, kind, name = nil)
+      @path = path
+      @kind = kind
+      @name = name || path
+    end
+
+    # @return [Integer] file size in bytes
+    def size
+      File.size(path)
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{kind} #{name}>"
+    end
+  end
+end

data/lib/zxing_ffi/strategy.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # The escalating pass ladder run on one page.
+  #
+  # Every pass decodes the page's base image or a derivative of it (a re-render, an upscale, tiles, a rotation)
+  # and maps its results back to base-image coordinates with an {Geometry::Affine}. Results are filtered,
+  # deduplicated against earlier passes (the earliest pass wins) and the ladder stops according to +stop+.
+  class Strategy
+    # Pass names in ladder order.
+    PASSES = %i[base inverted global_binarizer high_res tiles rotated_45 denoise].freeze
+
+    # Passes per effort level.
+    EFFORTS = {
+      fast: %i[base],
+      normal: %i[base inverted global_binarizer high_res],
+      thorough: PASSES
+    }.freeze
+
+    # Raster images whose longest side is below this get a 2× upscale in the high_res pass.
+    UPSCALE_BELOW = 2000
+
+    # Tile geometry for the tiles pass.
+    TILES = {min_tile: 1024, max_tile: 1536, overlap: 0.2}.freeze
+
+    # Rotation of the rotated pass (with try_rotate it also covers 135°, 225° and 315°).
+    ROTATED_DEGREES = 45
+
+    # @!attribute barcodes [Array<Barcode>] positions in base-image pixels, +pass+ set
+    # @!attribute passes_run [Array<Symbol>]
+    # @!attribute skipped_passes [Hash{Symbol => String}] passes that could not run, with the reason
+    Result = Data.define(:barcodes, :passes_run, :skipped_passes)
+
+    # An image (or a crop of it) to decode plus the transform from its pixels to the base image.
+    # +negative+ marks a pixel-inverted copy: its results are reported as inverted.
+    View = Data.define(:image, :to_base, :crop, :negative) do
+      def initialize(image:, to_base:, crop: nil, negative: false)
+        super
+      end
+    end
+
+    class << self
+      # @param effort [Symbol] +:fast+, +:normal+, +:thorough+
+      # @param passes [Array<Symbol>, nil] explicit ladder, overrides +effort+
+      # @return [Array<Symbol>]
+      # @raise [ArgumentError]
+      def passes_for(effort: :normal, passes: nil)
+        if passes
+          list = Array(passes).map(&:to_sym)
+          unknown = list - PASSES
+          raise ArgumentError, "unknown pass(es) #{unknown.map(&:inspect).join(", ")}; valid: #{PASSES.join(", ")}" if unknown.any?
+          raise ArgumentError, "passes must not be empty" if list.empty?
+
+          return list.uniq
+        end
+        EFFORTS.fetch(effort) { raise ArgumentError, "effort must be one of #{EFFORTS.keys.join(", ")}, got #{effort.inspect}" }
+      end
+
+      # @param stop [Symbol, Integer] +:found+, +:exhaustive+ or a positive Integer
+      # @return [Symbol, Integer]
+      # @raise [ArgumentError]
+      def validate_stop(stop)
+        return stop if stop == :found || stop == :exhaustive || (stop.is_a?(Integer) && stop.positive?)
+
+        raise ArgumentError, "stop must be :found, :exhaustive or a positive Integer, got #{stop.inspect}"
+      end
+    end
+
+    # @param passes [Array<Symbol>]
+    # @param stop [Symbol, Integer]
+    # @param options [Reader::Options] options of the base pass (library defaults + gem defaults + user options)
+    # @param config [Config] effective configuration
+    # @param min_length [Hash{Symbol => Integer}] minimum text length per format or symbology
+    # @param transformer [#call, nil] returns a {Transformers::Base} or nil, called only when a pass needs one
+    def initialize(passes:, stop:, options:, config:, min_length: {}, transformer: nil)
+      @passes = passes
+      @stop = stop
+      @options = options
+      @config = config
+      @min_length = min_length
+      @transformer_factory = transformer
+      @pass_options = {}
+    end
+
+    # Runs the ladder on one page.
+    #
+    # @param page [Loaders::Page] the base page (not released here)
+    # @param rerender [#call, nil] +->(dpi) { Loaders::Page }+ for PDF pages; nil for rasters
+    # @param page_info [Loaders::PageInfo, nil] page size in points, for the PDF high_res pixel cap
+    # @param deadline [Float, nil] monotonic clock time after which no further pass starts (the first pass always runs)
+    # @param notify [#call, nil] +->(event, payload)+, receives +:pass_completed+
+    # @return [Result]
+    def run(page, rerender: nil, page_info: nil, deadline: nil, notify: nil)
+      base = View.new(page.image, Geometry::Affine.identity, nil)
+      found = []
+      passes_run = []
+      skipped = {}
+      best = base # highest-resolution image so far (tiles pass)
+      owned = [] # derived images to release
+
+      @passes.each do |name|
+        break if stop?(found, passes_run)
+        if deadline && passes_run.any? && monotonic > deadline # the first pass always runs
+          skipped[name] = "page timeout"
+          next
+        end
+
+        started = monotonic
+        begin
+          views, options, reason = prepare(name, page, base, best, rerender, page_info, owned)
+          if reason
+            skipped[name] = reason
+            next
+          end
+          results = views.flat_map { |view| decode(name, view, options) }
+        rescue Error => e
+          raise if passes_run.empty? # the first pass failing is the page failing
+          # an escalation pass failing (re-render timeout, transformer error, …) must not lose earlier results
+          skipped[name] = "failed: #{e.class.name.split("::").last}: #{e.message.lines.first&.strip}"
+          next
+        end
+        best = views.first if name == :high_res
+        added = merge!(found, filter(results))
+        passes_run << name
+        release!(owned.pop) if %i[inverted rotated_45].include?(name) # single-use derived images
+        notify&.call(:pass_completed, {pass: name, found: results.size, added: added, duration: monotonic - started})
+      end
+      Result.new(barcodes: found, passes_run: passes_run, skipped_passes: skipped)
+    ensure
+      owned&.each { |image| release!(image) }
+    end
+
+    private
+
+    def stop?(found, passes_run)
+      return false if passes_run.empty?
+
+      case @stop
+      when :found then found.any?
+      when :exhaustive then false
+      else found.size >= @stop
+      end
+    end
+
+    # @return [Array(Array<View>, Reader::Options, nil), Array(nil, nil, String)] views + options, or a skip reason
+    def prepare(name, page, base, best, rerender, page_info, owned)
+      case name
+      when :base
+        [[base], @options]
+      when :inverted
+        prepare_inverted(base, owned)
+      when :global_binarizer
+        return [nil, nil, "binarizer is already :global_histogram"] if @options[:binarizer] == :global_histogram
+
+        [[base], options_for(name) { @options.merge(binarizer: :global_histogram) }]
+      when :high_res
+        prepare_high_res(page, base, rerender, page_info, owned)
+      when :tiles
+        grid = Geometry.tile_grid(best.image.width, best.image.height, **TILES)
+        views = grid.map do |x, y, w, h|
+          View.new(best.image, best.to_base.compose(Geometry::Affine.translation(x, y)), [x, y, w, h])
+        end
+        [views, options_for(name) { @options.merge(try_downscale: false) }]
+      when :rotated_45
+        prepare_rotated(base, owned)
+      when :denoise
+        return [nil, nil, "try_denoise is not supported by this libZXing (needs ZXING_EXPERIMENTAL_API)"] unless Native.supports?(:try_denoise)
+
+        [[base], options_for(name) { @options.merge(try_denoise: true) }]
+      end
+    end
+
+    def prepare_high_res(page, base, rerender, page_info, owned)
+      image, reason = (rerender && page.dpi) ? rerender_high_res(page, rerender, page_info) : upscale(base)
+      return [nil, nil, reason] unless image
+
+      owned << image
+      scale = Geometry::Affine.scale(base.image.width.to_f / image.width, base.image.height.to_f / image.height)
+      [[View.new(image, scale, nil)], @options]
+    end
+
+    # PDF pages: re-render at 2x the base DPI, within max_dpi and the pixel cap.
+    def rerender_high_res(page, rerender, page_info)
+      return [nil, "no page size to compute the high-res DPI"] unless page_info
+
+      dpi = Dpi.high_res(page.dpi, width_pt: page_info.width, height_pt: page_info.height,
+        max_dpi: @config.max_dpi, max_pixels: @config.max_pixels)
+      return [nil, "already at max_dpi or the pixel cap (#{page.dpi} DPI)"] unless dpi
+
+      [rerender.call(dpi).image, nil]
+    end
+
+    # Rasters: 2x upscale when the longest side is below UPSCALE_BELOW.
+    def upscale(base)
+      return [nil, "the upscale needs a :lum image"] unless base.image.format == :lum
+
+      longest = [base.image.width, base.image.height].max
+      return [nil, "image is already #{longest} px (>= #{UPSCALE_BELOW})"] if longest >= UPSCALE_BELOW
+      return [nil, "upscaled image would exceed max_pixels"] if @config.max_pixels && base.image.width * base.image.height * 4 > @config.max_pixels
+
+      transformer = self.transformer or return [nil, "no transformer available"]
+      [transformer.resize(base.image, 2), nil]
+    end
+
+    # White-on-black codes. zxing-cpp's try_invert only helps its 2D readers (linear readers scan raw rows), so this
+    # pass decodes a pixel-inverted copy: restricted to linear formats when try_invert already covers 2D, all
+    # selected formats otherwise.
+    def prepare_inverted(base, owned)
+      return [nil, nil, "the inverted pass needs a :lum image"] unless base.image.format == :lum
+
+      linear_only = effective(:try_invert)
+      formats = linear_only ? Formats.linear_subset(@options[:formats]) : nil
+      return [nil, nil, "try_invert already covers the selected formats (no linear format selected)"] if linear_only && formats.empty?
+
+      image = base.image.inverted
+      owned << image
+      options = options_for(:inverted) do
+        linear_only ? @options.merge(formats: formats, try_invert: false) : @options.merge(try_invert: false)
+      end
+      [[View.new(image, Geometry::Affine.identity, nil, true)], options]
+    end
+
+    def prepare_rotated(base, owned)
+      return [nil, nil, "the rotated pass needs a :lum image"] unless base.image.format == :lum
+
+      formats = Formats.linear_subset(@options[:formats])
+      return [nil, nil, "no linear formats selected"] if formats.empty?
+
+      to_canvas, width, height = Geometry.rotation_canvas(base.image.width, base.image.height, ROTATED_DEGREES)
+      if @config.max_pixels && width * height > @config.max_pixels
+        return [nil, nil, "rotated canvas #{width}x#{height} would exceed max_pixels"]
+      end
+
+      transformer = self.transformer or return [nil, nil, "no transformer available"]
+      image = transformer.rotate(base.image, ROTATED_DEGREES, background: 255)
+      owned << image
+      # transformers may round the expanded canvas differently (±1 px): keep the image centered on the actual canvas
+      to_canvas = Geometry::Affine.translation((image.width - width) / 2.0, (image.height - height) / 2.0).compose(to_canvas)
+      [[View.new(image, to_canvas.invert, nil)], options_for(:rotated_45) { @options.merge(formats: formats) }]
+    end
+
+    def transformer
+      return @transformer if defined?(@transformer)
+
+      @transformer = @transformer_factory&.call
+    end
+
+    def options_for(name)
+      @pass_options[name] ||= yield
+    end
+
+    # Effective value of a reader option: the caller's, else the library default.
+    def effective(key)
+      @options[key].nil? ? LIBRARY_DEFAULTS[key] : @options[key]
+    end
+
+    def decode(pass, view, options)
+      rotation = view.to_base.rotation_degrees
+      Reader.read(view.image, options, crop: view.crop).map do |barcode|
+        barcode.with(
+          position: view.to_base.apply_quad(barcode.position).round,
+          rotation: (barcode.rotation + rotation).round % 360,
+          inverted: barcode.inverted ^ view.negative,
+          pass: pass
+        )
+      end
+    end
+
+    def filter(barcodes)
+      barcodes.select do |barcode|
+        next false unless barcode.valid? || @options[:return_errors]
+
+        minimum = @min_length[barcode.format] || @min_length[barcode.symbology]
+        minimum.nil? || barcode.text.length >= minimum
+      end
+    end
+
+    # Adds results that are not duplicates of earlier ones; returns how many were added.
+    def merge!(found, results)
+      before = found.size
+      results.each { |barcode| found << barcode unless found.any? { |kept| Dedupe.duplicate?(kept, barcode) } }
+      found.size - before
+    end
+
+    def release!(image)
+      image&.release!
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end