usps_intelligent_barcode 0.3.1 → 1.1.0

data/examples/generate_pdf.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+
+lib_dir = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+require 'usps_intelligent_barcode'
+
+begin
+  require 'prawn'
+rescue LoadError
+  puts "This example requires the 'prawn' gem."
+  puts "Install it with: gem install prawn"
+  exit 1
+end
+
+# Generate a PDF using a USPS Intelligent Mail Barcode font
+#
+# Uses bundled USPS IMB fonts - no installation required.
+
+class BarcodeToPDFFont
+  OUTPUT_FILENAME = 'barcode_font.pdf'
+  FONT_NAME = 'USPSIMBStandard'
+  FONT_FILE = Imb::UspsFonts.standard_font_path
+  FONT_SIZE = Imb::UspsFonts.font_size
+
+  def initialize(barcode)
+    @barcode = barcode
+    @letters = barcode.barcode_letters
+  end
+
+  def generate(path)
+    Prawn::Document.generate(path, page_size: 'LETTER') do |pdf|
+      pdf.text "USPS Intelligent Mail Barcode (Font-Based)", size: 16, style: :bold
+      pdf.move_down 10
+      pdf.text "Barcode ID: #{@barcode.barcode_id.to_s}"
+      pdf.text "Service Type: #{@barcode.service_type.to_s}"
+      pdf.text "Mailer ID: #{@barcode.mailer_id.to_s}"
+      pdf.text "Serial Number: #{@barcode.serial_number.to_s}"
+      pdf.text "Routing Code: #{@barcode.routing_code.to_s}"
+      pdf.text "\n"
+      pdf.text "Barcode string: #{@letters}", size: 8
+      pdf.text "\n"
+      pdf.text "Barcode string printed with font #{FONT_NAME} #{FONT_SIZE}"
+      render_barcode(pdf)
+      pdf.move_down 10
+    end
+  end
+
+  private
+
+  def render_barcode(pdf)
+    pdf.font_families.update(FONT_NAME => { normal: FONT_FILE })
+    pdf.font(FONT_NAME) do
+      pdf.text @letters, size: FONT_SIZE
+    end
+  end
+end
+
+# Example usage
+barcode = Imb::Barcode.new(
+  '01',           # barcode_id
+  '234',          # service_type
+  '567094',       # mailer_id
+  '987654321',    # serial_number
+  '01234567891'   # routing_code
+)
+
+pdf_generator = BarcodeToPDFFont.new(barcode)
+path = "/tmp/barcode_to_pdf.pdf"
+pdf_generator.generate(path)
+puts "Generated #{path}"

data/fonts/LICENSE

@@ -0,0 +1,47 @@
+USPS Intelligent Mail Barcode Fonts License
+============================================
+
+Copyright © US Postal Service 2009
+
+LICENSE GRANT
+
+The Postal Service grants you a world-wide, royalty-free, non-exclusive license
+to use the Software, Documentation, and Fonts in the mailing industry without
+paying a royalty or other fee, including rights to reproduce, display, merge,
+sell, distribute, sublicense, and translate them; and the right to create
+derivative works.
+
+CONDITIONS
+
+Redistribution of the Software, Documentation, and/or Fonts must contain:
+(a) the copyright notice set forth above
+(b) this list of conditions
+(c) the disclaimer noted below
+
+You may redistribute your versions of the Software and/or Fonts if your versions
+were created by making modifications or improvements for a legitimate purpose in
+furtherance of your or another's business.
+
+The US Postal Service reserves the right to change this License in any manner
+within reason at its discretion.
+
+DISCLAIMER
+
+THE POSTAL SERVICE DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. IN NO EVENT SHALL THE POSTAL SERVICE BE LIABLE FOR ANY SPECIAL,
+INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+
+FONTS INCLUDED
+
+- USPSIMBStandard.ttf - Primary USPS Intelligent Mail Barcode font
+- USPSIMBCompact.ttf - Compact variant of the USPS Intelligent Mail Barcode font
+
+OFFICIAL SOURCE
+
+Official USPS font downloads and documentation:
+https://postalpro.usps.com/mailing/encoder-software-and-fonts
+https://postalpro.usps.com/onecodesolution

data/lib/usps_intelligent_barcode/bar_map.rb

@@ -4,9 +4,7 @@ require 'usps_intelligent_barcode/character_position'
 
 module Imb
 
-  # Maps intelligent barcode "characters" to codes that indicate what
-  # type of bar to print at each given position.
-
+  # Maps intelligent barcode "characters" to the actual barcode.
   class BarMap
 
     def initialize
@@ -15,9 +13,11 @@ module Imb
 
     # Given an array of intelligent barcode "characters", return an
     # the symbols for each position.
-    # @param [[Integer]] characters array of characters
-    # @return [[BarSymbol]] array of symbols
-
+    #
+    # @param characters [Array<Integer>] array of 13-bit "characters"
+    #   between 0 and 1364
+    # @return [Array<BarSymbol>] array of symbols,
+    #   e.g. [BarSymbol::TRACKER, BarSymbol::ASCENDER, ...]
     def symbols(characters)
       @mapping.map do |bar_position|
         bar_position.map(characters)
@@ -34,8 +34,10 @@ module Imb
       mapping_data.map do |descender, ascender|
         descender_character_position = CharacterPosition.new(*descender)
         ascender_character_position = CharacterPosition.new(*ascender)
-        BarPosition.new(descender_character_position,
-                        ascender_character_position)
+        BarPosition.new(
+          descender_character_position,
+          ascender_character_position,
+        )
       end
     end
 

data/lib/usps_intelligent_barcode/bar_position.rb

@@ -2,14 +2,17 @@ module Imb
 
   # @!group Internal
 
-  # Represents a position (one line) in the barcode.  This class is
-  # internal and may change.
-
+  # Represents a position (a vertical bar) in the barcode.  This class
+  # is internal and may change.
+  #
+  # Each bar represents two bits, but which two bits it represents is
+  # determined by the "Bar to Character Mapping" table in the
+  # specification (see Table 22, "Bar to Character Mapping", appendix
+  # E) in the specification linked to in the README.
   class BarPosition
 
-    # @param [CharacterPosition] descender_character_position
-    # @param [CharacterPosition] ascender_character_position
-
+    # @param descender_character_position [CharacterPosition]
+    # @param ascender_character_position [CharacterPosition]
     def initialize(descender_character_position, ascender_character_position)
       @descender_character_position = descender_character_position
       @ascender_character_position = ascender_character_position
@@ -17,12 +20,13 @@ module Imb
 
     # Given an array of characters, return a symbol for this
     # barcode position.
-    # @param [[Integer]] characters character codes
+    # @param characters [Array<Integer>] character codes
     # @return [BarSymbol] symbol code
-
     def map(characters)
-      BarSymbol.make(ascender_bit(characters),
-                     descender_bit(characters))
+      BarSymbol.make(
+        ascender_bit(characters),
+        descender_bit(characters),
+      )
     end
 
     private

data/lib/usps_intelligent_barcode/bar_symbol.rb

@@ -2,14 +2,34 @@ module Imb
 
   # @!group Internal
 
-  # Represents a symbol in the barcode.
-
+  # Represents a symbol in the barcode.  A symbol encodes two bits,
+  # and is represented as one of four characters to be printed using
+  # one of the USPS Intelligent Barcode fonts.  Each character, when
+  # printed using that font, results in a vertical bar having three
+  # part: An ascender, which may be present or missing; a descender,
+  # which may be present or missing; and between the ascender and the
+  # descender, a tracker which is always present.
+  #
+  # This chart shows the bits being encoded (ascender bit, then
+  # descender bit), the code (ASCII character) used for the barcode
+  # font, and an ASCII art repsentation of the bar that is printed by
+  # that code:
+  #
+  #     bits:           00          01           10        11
+  #
+  #     ascender:                                 |         |
+  #     tracker:         |           |            |         |
+  #     descender:                   |                      |
+  #
+  #     code:            T           D            A         F
+  #     mnemonic:     tracker    descender    ascender    full
   class BarSymbol
 
-    # @param [Integer] ascender_bit (0..1)
-    # @param [Integer] descender_bit (0..1)
+    # Return the symbol for a given ascender bit and descender bit.
+    #
+    # @param ascender_bit  [Integer] 0 or 1
+    # @param descender_bit [Integer] 0 or 1
     # @return [BarSymbol]
-
     def self.make(ascender_bit, descender_bit)
       case [ascender_bit, descender_bit]
       when [0, 0]
@@ -29,9 +49,12 @@ module Imb
     # @return [String] the letter for this symbol
     attr_reader :letter
 
-    # @param [Integer] code (0..3)
-    # @param [String] letter
-
+    # Make an instance.
+    #
+    # @param code [Integer] Binary number from 0b00 to 0b11.  Bit 1
+    #   controls the ascender; bit 0 controls the descender.
+    # @param letter [String] The character to print in the barcode
+    #   font.
     def initialize(code, letter)
       @code = code
       @letter = letter
@@ -39,10 +62,17 @@ module Imb
 
     private
 
-    TRACKER = BarSymbol.new(0, 'T')
-    DESCENDER = BarSymbol.new(1, 'D')
-    ASCENDER = BarSymbol.new(2, 'A')
-    FULL = BarSymbol.new(3, 'F')
+    TRACKER = BarSymbol.new(0b00, 'T')
+    private_constant :TRACKER
+    
+    DESCENDER = BarSymbol.new(0b01, 'D')
+    private_constant :DESCENDER
+    
+    ASCENDER = BarSymbol.new(0b10, 'A')
+    private_constant :ASCENDER
+    
+    FULL = BarSymbol.new(0b11, 'F')
+    private_constant :FULL
 
   end
 

data/lib/usps_intelligent_barcode/bar_to_character_mapping.yml

@@ -1,3 +1,27 @@
+# Represents the table from the spec. that controls how the bits of
+# the "characters" are mapped to barcode positions.  Each line of this
+# file represents a single barcode position (or vertical line), with
+# the leftmost position first.
+#
+# Let's decode the first line:
+#
+#     [
+#       [
+#         7,    # descender character index (0..)
+#         2,    # descender bit number (0..)
+#       ],
+#       [
+#         4,    # ascender character index (0..)
+#         3,    #ascender bit number (0..)
+#       ]
+#     ]
+#
+# This means that the first barcode position's ascender is controlled
+# by bit 2 of character 7; the descender is controlled by bit 3 of
+# character 4.
+#
+# See spec. section 10.0 ("Appendix E -- Tables for Converting
+# Characters"), Table 22 ("Bar to Character Mapping")
 ---
 - [[7, 2], [4, 3]]
 - [[1, 10], [0, 0]]

data/lib/usps_intelligent_barcode/barcode.rb

@@ -1,12 +1,13 @@
+# coding: utf-8
+
 require 'usps_intelligent_barcode/codeword_map'
 require 'usps_intelligent_barcode/crc'
 
 # The namespace for everything in this library.
-
 module Imb
 
-  # This class represents a barcode.
-
+  # This class turns a collection of fields into a string of symbols
+  # for printing using a barcode font.
   class Barcode
 
     include Memoizer
@@ -26,8 +27,6 @@ module Imb
     # @return [RoutingCode]
     attr_reader :routing_code
 
-    # @param 
-
     # Create a new barcode
     #
     # @param barcode_id [String] Nominally a String, but can be
@@ -40,12 +39,13 @@ module Imb
     #   anything that {SerialNumber.coerce} will accept.
     # @param routing_code [String] Nominally a String, but can be
     #   anything that {RoutingCode.coerce} will accept.
-
-    def initialize(barcode_id,
-                   service_type,
-                   mailer_id,
-                   serial_number,
-                   routing_code)
+    def initialize(
+          barcode_id,
+          service_type,
+          mailer_id,
+          serial_number,
+          routing_code
+        )
       @barcode_id = BarcodeId.coerce(barcode_id)
       @service_type = ServiceType.coerce(service_type)
       @mailer_id = MailerId.coerce(mailer_id)
@@ -61,39 +61,18 @@ module Imb
     # * 'D' for a descender mark
     # * 'F' for a full mark (both ascender and descender)
     # @return [String] A string that represents the barcode.
-
     def barcode_letters
       symbols.map(&:letter).join
     end
-    
-    private
-
-    # :stopdoc:
-    BAR_MAP = BarMap.new
-    CODEWORD_MAP = CodewordMap.new
-    CRC = Crc.new
-    # :startdoc:
 
-    def validate_components
-      components.each do |component|
-        component.validate(long_mailer_id?)
-      end
-    end
-
-    def components
-      [
-        @routing_code,
-        @barcode_id,
-        @service_type,
-        @mailer_id,
-        @serial_number,
-      ]
-    end
-
-    def long_mailer_id?
-      @mailer_id.long?
-    end
+    # @!group Algorithm Steps - Public for testing
 
+    # The components ("fields" in the spec) are turned into a single
+    # number that the spec calls "binary_data").  This is done through
+    # a series of multiplications and additions.  See spec. section
+    # 2.2.1 ("Step 1--Conversion of Data Fields into Binary Data").
+    #
+    # @return [Integer]
     def binary_data
       components.inject(0) do |data, component|
         component.shift_and_add_to(data, long_mailer_id?)
@@ -101,11 +80,20 @@ module Imb
     end
     memoize :binary_data
 
+    # Compute the "frame check sequence."  See spec. section 2.2.2
+    # ("Step 2--Generation of 11-Bit CRC on Binary Data").
+    #
+    # @return [Integer]
     def frame_check_sequence
       CRC.crc(binary_data)
     end
     memoize :frame_check_sequence
 
+    # Compute the "code words."  This is an array of 10 integers
+    # computed from the binary data.  See spec. section 2.2.3 ("Step
+    # 3--Conversion from Binary Data to Codewords").
+    #
+    # @return [Array<Integer>] 10 "characters."
     def codewords
       codewords = []
       data = binary_data
@@ -117,22 +105,45 @@ module Imb
     end
     memoize :codewords
 
+    # Insert the orientation into the codewords.  The spec. doesn't
+    # say much about this, other than to multiply codeword "J" by two.
+    # This will cause the LSB to be zero, which is presumably the
+    # orientation.  See spec. section 2.4.4 ("Step 4--Inserting
+    # Additional Information into Codewords").
+    #
+    # @return [Array<Integer>] 10 "characters."
     def codewords_with_orientation_in_character_j
       result = codewords.dup
       result[9] *= 2
       result
     end
 
+    # Insert the most significant bit of the FCS into codeword A.  See
+    # spec. section 2.4.4 ("Step 4--Inserting Additional Information
+    # into Codewords").
+    #
+    # @return [Array<Integer>] 10 "characters."
     def codewords_with_fcs_bit_in_character_a
       result = codewords_with_orientation_in_character_j.dup
       result[0] += 659 if frame_check_sequence[10] == 1
       result
     end      
 
+    # Convert the codewords to "characters".  Each character is a
+    # 13-bit integer; there are 10 of them, labeled "A" through "J" by
+    # the spec.  See spec. section 2.2.5 ("Step 5--Conversion from
+    # Codewords to Characters"), para. "A".
+    #
+    # @return [Array<Integer>] 10 "characters."
     def characters
       CODEWORD_MAP.characters(codewords_with_fcs_bit_in_character_a)
     end
 
+    # Fold the least-significant 10 bits of the FCS into the
+    # "characters".  See spec. section 2.2.5 ("Step 5--Conversion from
+    # Codewords to Characters"), para. "B".
+    #
+    # @return [Array<Integer>] 10 "characters".
     def characters_with_fcs_bits_0_through_9
       characters.each_with_index.map do |character, i|
         if frame_check_sequence[i] == 1
@@ -143,6 +154,39 @@ module Imb
       end
     end
 
+    # @!endgroup
+
+    private
+
+    # :stopdoc:
+    BAR_MAP = BarMap.new
+    CODEWORD_MAP = CodewordMap.new
+    CRC = Crc.new
+    # :startdoc:
+
+    def validate_components
+      components.each do |component|
+        component.validate(long_mailer_id?)
+      end
+    end
+
+    def components
+      [
+        @routing_code,
+        @barcode_id,
+        @service_type,
+        @mailer_id,
+        @serial_number,
+      ]
+    end
+
+    def long_mailer_id?
+      @mailer_id.long?
+    end
+
+    # Map the "characters" to symbols.  Here is where the barcode is made.
+    #
+    # @return [Array<BarSymbol>]
     def symbols
       BAR_MAP.symbols(characters_with_fcs_bits_0_through_9)
     end

data/lib/usps_intelligent_barcode/barcode_id.rb

@@ -1,7 +1,7 @@
 module Imb
 
-  # This class represents a Barcode ID
-
+  # This class represents a Barcode ID, one of the fields that is used
+  # to generate a barcode.
   class BarcodeId
 
     # The allowable range of a barcode ID
@@ -14,6 +14,7 @@ module Imb
     # * {BarcodeId}
     # * String
     # * Integer
+    #
     # @return [BarcodeId]
     # @raise [ArgumentError] If the argument cannot be coerced
 
@@ -31,15 +32,15 @@ module Imb
     end
 
     # Create a new BarcodeId
-    # @param [Integer] value The barcode ID
-
+    #
+    # @param value [Integer] The barcode ID
     def initialize(value)
       @value = value
     end
 
     # Return true if this object is equal to o
-    # @param [Object] o Any object acceptable to {.coerce}
-
+    #
+    # @param o [Object] Any object acceptable to {.coerce}
     def ==(o)
       BarcodeId.coerce(o).to_i == to_i
     rescue ArgumentError
@@ -47,17 +48,22 @@ module Imb
     end
 
     # @return [Integer] The integer value of the barcode ID
-
     def to_i
       @value
     end
 
+    # @return [String] The string value of the barcode ID
+    def to_s
+      "%02d" % @value
+    end
+
     # @!group Internal
 
     # Validate the value.
-    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    #
+    # @param long_mailer_id [boolean] truthy if the mailer ID is long
+    #   (9 digits).
     # @raise ArgumentError if invalid
-
     def validate(long_mailer_id)
       unless RANGE === @value
         raise ArgumentError, "Must be #{RANGE}"
@@ -69,10 +75,11 @@ module Imb
 
     # Add this object's value to target, shifting it left as many
     # digts as are needed to make room.
-    # @param [Integer] target The target to be shifted and added to
-    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    #
+    # @param target [Integer] The target to be shifted and added to
+    # @param long_mailer_id [boolean] truthy if the mailer ID is long
+    #   (9 digits).
     # @return [Integer] The new value of the target
-
     def shift_and_add_to(target, long_mailer_id)
       target *= 10
       target += most_significant_digit

data/lib/usps_intelligent_barcode/character_position.rb

@@ -2,23 +2,25 @@ module Imb
 
   # @!group Internal
 
-  # Represents the position of one bit in the array of intelligent
-  # barcode "characters".
-
+  # For a given barcode position, maps to the "character" index and
+  # bit number used to drive either the ascender or descender of that
+  # position.
   class CharacterPosition
 
-    # @param [Integer] character_index
-    # @param [Integer] bit_number
-
+    # Construct an instance.
+    #
+    # @param character_index [Integer] The character's index within an
+    #   array of characters.
+    # @param bit_number [Integer] The character's bit number 
     def initialize(character_index, bit_number)
       @character_index = character_index
       @bit_number = bit_number
     end
 
     # Given an array of characters, return the bit for this position.
-    # @param [[Integer]] characters
+    #
+    # @param characters [Array<Integer>]
     # @return [Integer] bit (0 or 1)
-
     def extract_bit_from_characters(characters)
       characters[@character_index][@bit_number]
     end

data/lib/usps_intelligent_barcode/codeword_map.rb

@@ -3,7 +3,6 @@ module Imb
   # @!group Internal
 
   # Maps codewords to characters.
-
   class CodewordMap
 
     # Constructor

data/lib/usps_intelligent_barcode/codeword_to_character_mapping.yml

@@ -1,3 +1,10 @@
+# Represents the table from the spec. that maps from codewords to
+# "characters."  A codeword is an integer between 0 and 1364, so this
+# table is an array of 1365 entries.
+#
+# See spec. section 10.0 ("Appendix E -- Tables for Converting
+# Characters"), Tables 19 ("5 of 13 Characters") and 20 ("2 of 13
+# Characters")
 ---
 - 31
 - 7936

data/lib/usps_intelligent_barcode/crc.rb

@@ -5,15 +5,15 @@ module Imb
   # @!group Internal
 
   # Calculates the Intelligent Mail Barcode CRC.
-
+  #
+  # See spec. section 9.1 ("CRC Generating Code")
   class Crc
 
     include NumericConversions
 
     # Calculate a CRC.
-    # @param [Integer] binary_data A 102-bit integer
+    # @param binary_data [Integer] A 102-bit integer
     # @return [Integer] An 11-bit CRC
-
     def crc(binary_data)
       crc = MASK
       bytes = numeric_to_bytes(binary_data, NUM_INPUT_BYTES)