Removes expit normalization from OnnxDetectionPredictor

While a custom post-processor can reverse the normalization back to the
original values via logit, it would make more sense to leave
normalization to the post-processor. This way the post-processor gets
the raw values from the model, which is easier to reason with, instead
of being forced to run `logit` on everything to get raw values...

Additionally, with this change there should be fewer expit calls, as
we only need it for the box prediction scores now.

THIS IS A BACKWARDS COMPATIBILITY BREAKAGE! If a user made a custom
detection post-processor, it will start getting different values in the
buffer than before!

Author: Eswcvlad

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/detection/IDetectionPostProcessor.java

@@ -29,8 +29,8 @@ This file is part of the iText (R) project.
 import java.util.List;
 
 /**
- * Interface for post-processors, which convert normalized, but still raw output
- * of an ML model and returns rotated boxes with the detected objects.
+ * Interface for post-processors, which convert raw output of an ML model and
+ * returns rotated boxes with the detected objects.
  *
  * <p>
  * Output point arrays should represent a rectangle and contain 4 points. Order
@@ -48,7 +48,7 @@ public interface IDetectionPostProcessor {
      * detected objects.
      *
      * @param input input image, which was used to produce the inputs to the ML model
-     * @param output normalized output of the ML model
+     * @param output output of the ML model
      *
      * @return a list of detected objects. See interface documentation for more information
      */

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/detection/OnnxDetectionPostProcessor.java

@@ -56,8 +56,13 @@ public class OnnxDetectionPostProcessor implements IDetectionPostProcessor {
      * Threshold value used, when binarizing a monochromatic image. If pixel
      * value is greater or equal to the threshold, it is mapped to 1, otherwise
      * it is mapped to 0.
+     *
+     * <p>
+     * This is not the original binarization threshold, provided by the user,
+     * but the value of logit on it. This is so we don't need to run expit
+     * over the model output for binarization.
      */
-    private final float binarizationThreshold;
+    private final float binarizationThresholdLogit;
     /**
      * Score threshold for a detected box. If score is lower than this value,
      * the box gets discarded.
@@ -73,7 +78,7 @@ public class OnnxDetectionPostProcessor implements IDetectionPostProcessor {
      *                       the box gets discarded
      */
     public OnnxDetectionPostProcessor(float binarizationThreshold, float scoreThreshold) {
-        this.binarizationThreshold = binarizationThreshold;
+        this.binarizationThresholdLogit = (float) MathUtil.logit(MathUtil.clamp(binarizationThreshold, 0., 1.));
         this.scoreThreshold = scoreThreshold;
     }
 
@@ -96,7 +101,7 @@ public List<Point[]> process(BufferedImage input, FloatBufferMdArray output) {
         // or use a smaller mask with only the contour. Though based on profiling, it doesn't look
         // like it is that bad, when it is only once per input image.
         try (final Mat scoreMask = new Mat(height, width, CvType.CV_8U, new Scalar(0));
-             final MatVector contours = findTextContours(output, binarizationThreshold)) {
+             final MatVector contours = findTextContours(output, binarizationThresholdLogit)) {
             final long contourCount = contours.size();
             for (long contourIdx = 0; contourIdx < contourCount; ++contourIdx) {
                 try (final Mat contour = contours.get(contourIdx);
@@ -159,7 +164,8 @@ private static float getPredictionScore(
         /*
          * Algorithm here is pretty simple. We go over all the points, painted
          * by the contour shape, and calculate the mean prediction score
-         * value over the original normalized output array.
+         * value over the original output array, values of which we normalize
+         * via expit.
          */
         final FloatBufferMdArray hwMdArray = predictions.getSubArray(0);
         final int height = hwMdArray.getDimension(0);
@@ -180,7 +186,7 @@ private static float getPredictionScore(
                     if (maskIndexer.get(y, x) != 1) {
                         continue;
                     }
-                    final float prediction = predictionsRow.getScalar(x);
+                    final float prediction = MathUtil.expit(predictionsRow.getScalar(x));
                     if (prediction > 0) {
                         sum += prediction;
                         ++nonZeroCount;

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/detection/OnnxDetectionPredictor.java

@@ -188,12 +188,6 @@ protected FloatBufferMdArray toInputBuffer(List<BufferedImage> batch) {
     @Override
     protected List<List<Point[]>> fromOutputBuffer(List<BufferedImage> inputBatch, FloatBufferMdArray outputBatch) {
         final IDetectionPostProcessor postProcessor = properties.getPostProcessor();
-        // Normalizing pixel values via a sigmoid expit function
-        final float[] outputBuffer = outputBatch.getData().array();
-        int offset = outputBatch.getArrayOffset();
-        for (int i = offset; i < offset + outputBatch.getArraySize(); ++i) {
-            outputBuffer[i] = MathUtil.expit(outputBuffer[i]);
-        }
         final List<List<Point[]>> batchTextBoxes = new ArrayList<>(inputBatch.size());
         for (int i = 0; i < inputBatch.size(); ++i) {
             final BufferedImage image = inputBatch.get(i);

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/exceptions/PdfOcrOnnxTrExceptionMessageConstant.java

@@ -57,6 +57,7 @@ public final class PdfOcrOnnxTrExceptionMessageConstant {
     public static final String UNEXPECTED_SHAPE_SIZE = "Shape should be a {0}-element array (BCHW).";
     public static final String UNEXPECTED_STD_CHANNEL_COUNT = "Std should be a {0}-element array.";
     public static final String VALUES_SHOULD_BE_A_NON_EMPTY_ARRAY = "Values should be a non-empty array.";
+    public static final String X_SHOULD_BE_IN_0_1_RANGE = "X should be in [0; 1] range.";
 
     private PdfOcrOnnxTrExceptionMessageConstant() {
         // Private constructor will prevent the instantiation of this class directly.

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/util/MathUtil.java

@@ -114,6 +114,39 @@ public static float expit(float x) {
         return (float) (1 / (1 + Math.exp(-x)));
     }
 
+    /**
+     * Computes the logit function, which is the inverse of expit, for the given input.
+     *
+     * @param x the input value
+     *
+     * @return the logit of the input value
+     */
+    public static double logit(double x) {
+        if (0 < x && x < 1) {
+            return Math.log(x / (1.0 - x));
+        }
+        if (x == 0F) {
+            return Float.NEGATIVE_INFINITY;
+        }
+        if (x == 1F) {
+            return Float.POSITIVE_INFINITY;
+        }
+        throw new IllegalArgumentException(
+                PdfOcrOnnxTrExceptionMessageConstant.X_SHOULD_BE_IN_0_1_RANGE
+        );
+    }
+
+    /**
+     * Computes the logit function, which is the inverse of expit, for the given input.
+     *
+     * @param x the input value
+     *
+     * @return the logit of the input value
+     */
+    public static float logit(float x) {
+        return (float) logit((double) x);
+    }
+
     /**
      * Computes the Euclidean modulo (non-negative remainder) of {@code x} modulo {@code y}.
      *

pdfocr-onnxtr/src/test/java/com/itextpdf/pdfocr/onnxtr/util/MathUtilTest.java

@@ -63,6 +63,15 @@ public void clampWithValidArgs() {
         Assertions.assertEquals(1.9, MathUtil.clamp(2.0, 1.1, 1.9));
     }
 
+    @Test
+    public void logitTest() {
+        Assertions.assertThrows(IllegalArgumentException.class, () -> MathUtil.logit(-0.1F));
+        Assertions.assertEquals(Float.NEGATIVE_INFINITY, MathUtil.logit(0F));
+        Assertions.assertEquals(0F, MathUtil.logit(0.5F));
+        Assertions.assertEquals(Float.POSITIVE_INFINITY, MathUtil.logit(1F));
+        Assertions.assertThrows(IllegalArgumentException.class, () -> MathUtil.logit(1.1F));
+    }
+
     @Test
     public void levenshteinDistanceTest(){
         Assertions.assertEquals(5, MathUtil.calculateLevenshteinDistance("kitten", "meat"));