Class BitMatrix

  • All Implemented Interfaces:
    java.lang.Cloneable

    public final class BitMatrix
    extends java.lang.Object
    implements java.lang.Cloneable

    Represents a 2D matrix of bits. In function arguments below, and throughout the common module, x is the column position, and y is the row position. The ordering is always x, y. The origin is at the top-left.

    Internally the bits are represented in a 1-D array of 32-bit ints. However, each row begins with a new int. This is done intentionally so that we can copy out a row into a BitArray very efficiently.

    The ordering of bits is row-major. Within each int, the least significant bits are used first, meaning they represent lower x values. This is compatible with BitArray's implementation.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private int[] bits  
      private int height  
      private int rowSize  
      private int width  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        BitMatrix​(int dimension)
      Creates an empty square BitMatrix.
        BitMatrix​(int width, int height)
      Creates an empty BitMatrix.
      private BitMatrix​(int width, int height, int rowSize, int[] bits)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      private java.lang.String buildToString​(java.lang.String setString, java.lang.String unsetString, java.lang.String lineSeparator)  
      void clear()
      Clears all bits (sets to false).
      BitMatrix clone()  
      boolean equals​(java.lang.Object o)  
      void flip()
      Flips every bit in the matrix.
      void flip​(int x, int y)
      Flips the given bit.
      boolean get​(int x, int y)
      Gets the requested bit, where true means black.
      int[] getBottomRightOnBit()  
      int[] getEnclosingRectangle()
      This is useful in detecting the enclosing rectangle of a 'pure' barcode.
      int getHeight()  
      BitArray getRow​(int y, BitArray row)
      A fast method to retrieve one row of data from the matrix as a BitArray.
      int getRowSize()  
      int[] getTopLeftOnBit()
      This is useful in detecting a corner of a 'pure' barcode.
      int getWidth()  
      int hashCode()  
      static BitMatrix parse​(boolean[][] image)
      Interprets a 2D array of booleans as a BitMatrix, where "true" means an "on" bit.
      static BitMatrix parse​(java.lang.String stringRepresentation, java.lang.String setString, java.lang.String unsetString)  
      void rotate​(int degrees)
      Modifies this BitMatrix to represent the same but rotated the given degrees (0, 90, 180, 270)
      void rotate180()
      Modifies this BitMatrix to represent the same but rotated 180 degrees
      void rotate90()
      Modifies this BitMatrix to represent the same but rotated 90 degrees counterclockwise
      void set​(int x, int y)
      Sets the given bit to true.
      void setRegion​(int left, int top, int width, int height)
      Sets a square region of the bit matrix to true.
      void setRow​(int y, BitArray row)  
      java.lang.String toString()  
      java.lang.String toString​(java.lang.String setString, java.lang.String unsetString)  
      java.lang.String toString​(java.lang.String setString, java.lang.String unsetString, java.lang.String lineSeparator)
      Deprecated.
      call toString(String,String) only, which uses \n line separator always
      void unset​(int x, int y)  
      void xor​(BitMatrix mask)
      Exclusive-or (XOR): Flip the bit in this BitMatrix if the corresponding mask bit is set.
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • width

        private int width
      • height

        private int height
      • rowSize

        private int rowSize
      • bits

        private int[] bits
    • Constructor Detail

      • BitMatrix

        public BitMatrix​(int dimension)
        Creates an empty square BitMatrix.
        Parameters:
        dimension - height and width
      • BitMatrix

        public BitMatrix​(int width,
                         int height)
        Creates an empty BitMatrix.
        Parameters:
        width - bit matrix width
        height - bit matrix height
      • BitMatrix

        private BitMatrix​(int width,
                          int height,
                          int rowSize,
                          int[] bits)
    • Method Detail

      • parse

        public static BitMatrix parse​(boolean[][] image)
        Interprets a 2D array of booleans as a BitMatrix, where "true" means an "on" bit.
        Parameters:
        image - bits of the image, as a row-major 2D array. Elements are arrays representing rows
        Returns:
        BitMatrix representation of image
      • parse

        public static BitMatrix parse​(java.lang.String stringRepresentation,
                                      java.lang.String setString,
                                      java.lang.String unsetString)
      • get

        public boolean get​(int x,
                           int y)

        Gets the requested bit, where true means black.

        Parameters:
        x - The horizontal component (i.e. which column)
        y - The vertical component (i.e. which row)
        Returns:
        value of given bit in matrix
      • set

        public void set​(int x,
                        int y)

        Sets the given bit to true.

        Parameters:
        x - The horizontal component (i.e. which column)
        y - The vertical component (i.e. which row)
      • unset

        public void unset​(int x,
                          int y)
      • flip

        public void flip​(int x,
                         int y)

        Flips the given bit.

        Parameters:
        x - The horizontal component (i.e. which column)
        y - The vertical component (i.e. which row)
      • flip

        public void flip()

        Flips every bit in the matrix.

      • xor

        public void xor​(BitMatrix mask)
        Exclusive-or (XOR): Flip the bit in this BitMatrix if the corresponding mask bit is set.
        Parameters:
        mask - XOR mask
      • clear

        public void clear()
        Clears all bits (sets to false).
      • setRegion

        public void setRegion​(int left,
                              int top,
                              int width,
                              int height)

        Sets a square region of the bit matrix to true.

        Parameters:
        left - The horizontal position to begin at (inclusive)
        top - The vertical position to begin at (inclusive)
        width - The width of the region
        height - The height of the region
      • getRow

        public BitArray getRow​(int y,
                               BitArray row)
        A fast method to retrieve one row of data from the matrix as a BitArray.
        Parameters:
        y - The row to retrieve
        row - An optional caller-allocated BitArray, will be allocated if null or too small
        Returns:
        The resulting BitArray - this reference should always be used even when passing your own row
      • setRow

        public void setRow​(int y,
                           BitArray row)
        Parameters:
        y - row to set
        row - BitArray to copy from
      • rotate

        public void rotate​(int degrees)
        Modifies this BitMatrix to represent the same but rotated the given degrees (0, 90, 180, 270)
        Parameters:
        degrees - number of degrees to rotate through counter-clockwise (0, 90, 180, 270)
      • rotate180

        public void rotate180()
        Modifies this BitMatrix to represent the same but rotated 180 degrees
      • rotate90

        public void rotate90()
        Modifies this BitMatrix to represent the same but rotated 90 degrees counterclockwise
      • getEnclosingRectangle

        public int[] getEnclosingRectangle()
        This is useful in detecting the enclosing rectangle of a 'pure' barcode.
        Returns:
        left,top,width,height enclosing rectangle of all 1 bits, or null if it is all white
      • getTopLeftOnBit

        public int[] getTopLeftOnBit()
        This is useful in detecting a corner of a 'pure' barcode.
        Returns:
        x,y coordinate of top-left-most 1 bit, or null if it is all white
      • getBottomRightOnBit

        public int[] getBottomRightOnBit()
      • getWidth

        public int getWidth()
        Returns:
        The width of the matrix
      • getHeight

        public int getHeight()
        Returns:
        The height of the matrix
      • getRowSize

        public int getRowSize()
        Returns:
        The row size of the matrix
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        Returns:
        string representation using "X" for set and " " for unset bits
      • toString

        public java.lang.String toString​(java.lang.String setString,
                                         java.lang.String unsetString)
        Parameters:
        setString - representation of a set bit
        unsetString - representation of an unset bit
        Returns:
        string representation of entire matrix utilizing given strings
      • toString

        @Deprecated
        public java.lang.String toString​(java.lang.String setString,
                                         java.lang.String unsetString,
                                         java.lang.String lineSeparator)
        Deprecated.
        call toString(String,String) only, which uses \n line separator always
        Parameters:
        setString - representation of a set bit
        unsetString - representation of an unset bit
        lineSeparator - newline character in string representation
        Returns:
        string representation of entire matrix utilizing given strings and line separator
      • buildToString

        private java.lang.String buildToString​(java.lang.String setString,
                                               java.lang.String unsetString,
                                               java.lang.String lineSeparator)
      • clone

        public BitMatrix clone()
        Overrides:
        clone in class java.lang.Object