docs: private static int[][] calculateBlackPoints(byte[] luminances,
                                                int subWidth,
                                                int subHeight,
                                                int width,
                                                int height) {
      int maxYOffset = height - BLOCK_SIZE;
      int maxXOffset = width - BLOCK_SIZE;
      int[][] blackPoints = new int[subHeight][subWidth];
      for (int y = 0; y < subHeight; y++) {
        int yoffset = y << BLOCK_SIZE_POWER;
        if (yoffset > maxYOffset) {
          yoffset = maxYOffset;
        }
        for (int x = 0; x < subWidth; x++) {
          int xoffset = x << BLOCK_SIZE_POWER;
          if (xoffset > maxXOffset) {
            xoffset = maxXOffset;
          }
          int sum = 0;
          int min = 0xFF;
          int max = 0;
          for (int yy = 0, offset = yoffset * width + xoffset; yy < BLOCK_SIZE; yy++, offset += width) {
            for (int xx = 0; xx < BLOCK_SIZE; xx++) {
              int pixel = luminances[offset + xx] & 0xFF;
              sum += pixel;
              // still looking for good contrast
              if (pixel < min) {
                min = pixel;
              }
              if (pixel > max) {
                max = pixel;
              }
            }
            // short-circuit min/max tests once dynamic range is met
            if (max - min > MIN_DYNAMIC_RANGE) {
              // finish the rest of the rows quickly
              for (yy++, offset += width; yy < BLOCK_SIZE; yy++, offset += width) {
                for (int xx = 0; xx < BLOCK_SIZE; xx++) {
                  sum += luminances[offset + xx] & 0xFF;
                }
              }
            }
          }
  
          // The default estimate is the average of the values in the block.
          int average = sum >> (BLOCK_SIZE_POWER * 2);
          if (max - min <= MIN_DYNAMIC_RANGE) {
            // If variation within the block is low, assume this is a block with only light or only
            // dark pixels. In that case we do not want to use the average, as it would divide this
            // low contrast area into black and white pixels, essentially creating data out of noise.
            //
            // The default assumption is that the block is light/background. Since no estimate for
            // the level of dark pixels exists locally, use half the min for the block.
            average = min / 2;
  
            if (y > 0 && x > 0) {
              // Correct the "white background" assumption for blocks that have neighbors by comparing
              // the pixels in this block to the previously calculated black points. This is based on
              // the fact that dark barcode symbology is always surrounded by some amount of light
              // background for which reasonable black point estimates were made. The bp estimated at
              // the boundaries is used for the interior.
  
              // The (min < bp) is arbitrary but works better than other heuristics that were tried.
              int averageNeighborBlackPoint =
                  (blackPoints[y - 1][x] + (2 * blackPoints[y][x - 1]) + blackPoints[y - 1][x - 1]) / 4;
              if (min < averageNeighborBlackPoint) {
                average = averageNeighborBlackPoint;
              }
            }
          }
          blackPoints[y][x] = average;
        }
      }
      return blackPoints;
    }