Package boofcv.alg.fiducial.calib.ecocheck

Class ECoCheckCodec

java.lang.Object
boofcv.alg.fiducial.calib.ecocheck.ECoCheckCodec
public class ECoCheckCodec extends Object
Encodes and decodes the marker ID and cell ID from an encoded cell in a calibration target. The maximum number of possible markers and cells in a marker must be known in advance to decode and encode [1]. Validation is done using a checksum and optional Reed Solomon error correction code (ECC) is provided to fix errors. The amount of ECC is configurable. If ECC is turned on and there are extra bits, then those bits will be used for additional error correction, if possible.

The checksum was provided as a way to catch some invalid encoding and employs a simple xor strategy. It was found that this checksum was needed even when ECC was turned on because for smaller messages it had an unacceptable false positive rate. The number of bits for the checksum is configurable.

The Reed Solomon encoding used in ECoCheck is the same as what's used in QR Codes. It can detect and fix errors inside of 8-bit words. Two words are needed to detect and recover from an error in a single word. This will increase the packet size as an encoded message has to now be contained inside of "word" sized chunks and several extra words are required to fix errors. The amount of error correction can be configured.

Number of bits used to encode the two ID numbers is dynamically determined based on their maximum value. The minimum number of bits is computed using this formula: bit count = ceil(log(max_number)/log(2))

Packet Format:
  • N-bits: Marker ID
  • M-bits: Cell ID
  • K-bits: XOR Checksum
[1] An earlier design was considered that did encode this information in the marker. It typically increased the bit grid size by 1 but didn't remove the need to have prior information about the target to decode the target.

  • Field Details

    • MAX_ECC_LEVEL

      public static final int MAX_ECC_LEVEL
      See Also:

    • MAX_CHECKSUM_BITS

      public static final int MAX_CHECKSUM_BITS
      See Also:

    • WORD_BITS

      public static final int WORD_BITS
      Number of bits per word
      See Also:

    • checksumMask

      protected int checksumMask

    • dataWords

      protected int dataWords

    • eccWords

      protected int eccWords

    • paddingBits

      protected int paddingBits

    • message

      protected final DogArray_I8 message

    • ecc

      protected final DogArray_I8 ecc

    • bits

      protected final PackedBits8 bits

  • Constructor Details

    • ECoCheckCodec

      public ECoCheckCodec()

  • Method Details

    • configure

      public void configure(int numUniqueMarkers, int numUniqueCells)
      Computes how large of a grid will be needed to encode the coordinates + overhead. Pre-allocates any memory that will be needed
      Parameters:
      numUniqueMarkers - Maximum number of unique markers required
      numUniqueCells - Maximum number of unique cell IDs in a marker required

    • encode

      public void encode(int markerID, int cellID, PackedBits8 encodedPacket)
      Encodes the coordinate and copies the results into 'encodedPacket'
      Parameters:
      markerID - (Input) The marker's unique ID
      cellID - (input) The cell's unique ID inside the marker
      encodedPacket - (Output) The encoded packet

    • decode

      public boolean decode(PackedBits8 readBits, CellValue cell)
      Decodes the read in bit array and converts it into a coordinate. If true is returned then it believes it is a valid packet and has corrected minor errors. This won't catch every single failure but should catch most of them.
      Parameters:
      readBits - (Input) Read in bits from an image
      cell - (Output) Found marker and cell ID
      Returns:
      True is returned if it believes all errors have been fixed and the data is not corrupted.

    • errorCorrectionFraction

      public double errorCorrectionFraction()
      Converts the level into a fraction