Check if onnxruntime is available before its usage

DEVSIX-9248

Author: AnhelinaM

pdfocr-api/src/main/java/com/itextpdf/pdfocr/util/PdfOcrTextBuilder.java

@@ -188,7 +188,7 @@ private static void updateBBoxes(List<TextInfo> line) {
                         .orElseThrow(UnsupportedOperationException::new).getBboxRect().getHeight();
                 lineBottom = line.stream().reduce((lhs, rhs) -> Float.compare(lhs.getBboxRect().getBottom(), rhs.getBboxRect().getBottom()) > 0 ? rhs : lhs)
                         .orElseThrow(UnsupportedOperationException::new).getBboxRect().getBottom();
-                delta = (lineTop - lineBottom - lineHeight)/2;
+                delta = (lineTop - lineBottom - lineHeight) / 2;
                 for (TextInfo word : line) {
                     word.getBboxRect().setY(lineBottom + delta).setHeight(lineHeight);
                 }
@@ -203,9 +203,9 @@ private static void updateBBoxes(List<TextInfo> line) {
                         .orElseThrow(UnsupportedOperationException::new).getBboxRect().getWidth();
                 lineBottom = line.stream().reduce((lhs, rhs) -> Float.compare(lhs.getBboxRect().getLeft(), rhs.getBboxRect().getLeft()) > 0 ? rhs : lhs)
                         .orElseThrow(UnsupportedOperationException::new).getBboxRect().getLeft();
-                delta = (lineTop - lineBottom - lineHeight)/2;
+                delta = (lineTop - lineBottom - lineHeight) / 2;
                 for (TextInfo word : line) {
-                    word.getBboxRect().setX(lineBottom).setWidth(lineHeight);
+                    word.getBboxRect().setX(lineBottom + delta).setWidth(lineHeight);
                 }
                 break;
             default:

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/AbstractOnnxPredictor.java

@@ -22,10 +22,6 @@ This file is part of the iText (R) project.
  */
 package com.itextpdf.pdfocr.onnxtr;
 
-import com.itextpdf.pdfocr.exceptions.PdfOcrException;
-import com.itextpdf.pdfocr.onnxtr.util.BatchProcessingGenerator;
-import com.itextpdf.pdfocr.onnxtr.util.Batching;
-
 import ai.onnxruntime.NodeInfo;
 import ai.onnxruntime.OnnxJavaType;
 import ai.onnxruntime.OnnxTensor;
@@ -39,6 +35,12 @@ This file is part of the iText (R) project.
 import ai.onnxruntime.OrtSession.SessionOptions.OptLevel;
 import ai.onnxruntime.TensorInfo;
 import ai.onnxruntime.ValueInfo;
+import com.itextpdf.commons.utils.MessageFormatUtil;
+import com.itextpdf.pdfocr.exceptions.PdfOcrException;
+import com.itextpdf.pdfocr.onnxtr.exceptions.PdfOcrOnnxTrExceptionMessageConstant;
+import com.itextpdf.pdfocr.onnxtr.util.BatchProcessingGenerator;
+import com.itextpdf.pdfocr.onnxtr.util.Batching;
+
 import java.nio.FloatBuffer;
 import java.util.Arrays;
 import java.util.Collection;
@@ -76,6 +78,21 @@ public abstract class AbstractOnnxPredictor<T, R> implements IPredictor<T, R> {
      */
     private final String inputName;
 
+    /**
+     * Close status of the predictor.
+     */
+    private boolean closed = false;
+
+    static {
+        try {
+            // OnnxRuntime.init() is used under the hood.
+            new OrtSession.SessionOptions().close();
+        } catch (RuntimeException | UnsatisfiedLinkError e) {
+            DependencyLoadChecker.processException(e);
+            throw e;
+        }
+    }
+
     /**
      * Creates a new abstract predictor.
      *
@@ -93,20 +110,21 @@ protected AbstractOnnxPredictor(String modelPath, OnnxInputProperties inputPrope
         try {
             this.sessionOptions = createDefaultSessionOptions();
         } catch (OrtException e) {
-            throw new PdfOcrException("Failed to init ONNX Runtime session options", e);
+            throw new PdfOcrException(PdfOcrOnnxTrExceptionMessageConstant.FAILED_TO_INIT_SESSION_OPTIONS, e);
         }
 
         try {
             this.session = OrtEnvironment.getEnvironment().createSession(modelPath, sessionOptions);
         } catch (Exception e) {
             this.sessionOptions.close();
-            throw new PdfOcrException("Failed to init ONNX Runtime session", e);
+            throw new PdfOcrException(PdfOcrOnnxTrExceptionMessageConstant.FAILED_TO_INIT_ONNX_RUNTIME_SESSION, e);
         }
 
         try {
             this.inputName = validateModel(this.session, inputProperties, outputShape);
         } catch (Exception e) {
-            final PdfOcrException userException = new PdfOcrException("ONNX Runtime model did not pass validation", e);
+            final PdfOcrException userException = new PdfOcrException(
+                    PdfOcrOnnxTrExceptionMessageConstant.MODEL_DID_NOT_PASS_VALIDATION, e);
             try {
                 this.session.close();
             } catch (OrtException closeException) {
@@ -123,23 +141,28 @@ public Iterator<R> predict(Iterator<T> inputs) {
                 Batching.wrap(inputs, inputProperties.getBatchSize()),
                 (List<T> batch) -> {
                     try (final OnnxTensor inputTensor = createTensor(toInputBuffer(batch));
-                            final Result outputTensor = session.run(Collections.singletonMap(inputName, inputTensor))) {
+                         final Result outputTensor = session.run(Collections.singletonMap(inputName, inputTensor))) {
                         return fromOutputBuffer(batch, parseModelOutput(outputTensor));
                     } catch (OrtException e) {
-                        throw new PdfOcrException("ONNX Runtime operation failed", e);
+                        throw new PdfOcrException(
+                                PdfOcrOnnxTrExceptionMessageConstant.ONNX_RUNTIME_OPERATION_FAILED, e);
                     }
                 }
         );
     }
 
     @Override
     public void close() {
+        if (closed) {
+            return;
+        }
         try {
             session.close();
             sessionOptions.close();
         } catch (OrtException e) {
-            throw new PdfOcrException("Failed to close an ONNX Runtime session", e);
+            throw new PdfOcrException(PdfOcrOnnxTrExceptionMessageConstant.FAILED_TO_CLOSE_ONNX_RUNTIME_SESSION, e);
         }
+        closed = true;
     }
 
     /**
@@ -205,51 +228,47 @@ private static String validateModel(OrtSession session, OnnxInputProperties prop
     private static String validateModelInput(OrtSession session, OnnxInputProperties properties) throws OrtException {
         final Collection<NodeInfo> inputInfo = session.getInputInfo().values();
         if (inputInfo.size() != 1) {
-            throw new IllegalArgumentException(
-                    "Expected 1 input, but got " + inputInfo.size() + " instead"
-            );
+            throw new IllegalArgumentException(MessageFormatUtil.format(
+                    PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_INPUT_SIZE, inputInfo.size()));
         }
         final NodeInfo inputNodeInfo = inputInfo.iterator().next();
         final ValueInfo inputNodeValueInfo = inputNodeInfo.getInfo();
         if (!(inputNodeValueInfo instanceof TensorInfo)) {
-            throw new IllegalArgumentException("Unexpected input type, expected float32 tensor");
+            throw new IllegalArgumentException(PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_INPUT_TYPE);
         }
         final TensorInfo inputTensorInfo = (TensorInfo) inputNodeValueInfo;
         if (inputTensorInfo.type != OnnxJavaType.FLOAT) {
-            throw new IllegalArgumentException("Unexpected input type, expected float32 tensor");
+            throw new IllegalArgumentException(PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_INPUT_TYPE);
         }
         final long[] inputShape = inputTensorInfo.getShape();
         if (isShapeIncompatible(properties.getShape(), inputShape)) {
-            throw new IllegalArgumentException(
-                    "Expected " + Arrays.toString(properties.getShape()) + " input shape, "
-                            + "but got " + Arrays.toString(inputShape) + " instead"
-            );
+            throw new IllegalArgumentException(MessageFormatUtil.format(
+                    PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_INPUT_SHAPE, Arrays.toString(properties.getShape()),
+                    Arrays.toString(inputShape)));
         }
         return inputNodeInfo.getName();
     }
 
     private static void validateModelOutput(OrtSession session, long[] expectedOutputShape) throws OrtException {
         final Collection<NodeInfo> outputInfo = session.getOutputInfo().values();
         if (outputInfo.size() != 1) {
-            throw new IllegalArgumentException(
-                    "Expected 1 output, but got " + outputInfo.size() + " instead"
-            );
+            throw new IllegalArgumentException(MessageFormatUtil.format(
+                    PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_OUTPUT_SIZE, outputInfo.size()));
         }
         final NodeInfo outputNodeInfo = outputInfo.iterator().next();
         final ValueInfo outputNodeValueInfo = outputNodeInfo.getInfo();
         if (!(outputNodeValueInfo instanceof TensorInfo)) {
-            throw new IllegalArgumentException("Unexpected output type, expected float32 tensor");
+            throw new IllegalArgumentException(PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_OUTPUT_TYPE);
         }
         final TensorInfo outputTensorInfo = (TensorInfo) outputNodeValueInfo;
         if (outputTensorInfo.type != OnnxJavaType.FLOAT) {
-            throw new IllegalArgumentException("Unexpected output type, expected float32 tensor");
+            throw new IllegalArgumentException(PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_OUTPUT_TYPE);
         }
         final long[] actualOutputShape = outputTensorInfo.getShape();
         if (isShapeIncompatible(expectedOutputShape, actualOutputShape)) {
-            throw new IllegalArgumentException(
-                    "Expected " + Arrays.toString(expectedOutputShape) + " output shape, "
-                            + "but got " + Arrays.toString(actualOutputShape) + " instead"
-            );
+            throw new IllegalArgumentException(MessageFormatUtil.format(
+                    PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_OUTPUT_SHAPE, Arrays.toString(expectedOutputShape),
+                    Arrays.toString(actualOutputShape)));
         }
     }
 

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/DependencyLoadChecker.java

@@ -0,0 +1,88 @@
+/*
+    This file is part of the iText (R) project.
+    Copyright (c) 1998-2025 Apryse Group NV
+    Authors: Apryse Software.
+
+    This program is offered under a commercial and under the AGPL license.
+    For commercial licensing, contact us at https://itextpdf.com/sales.  For AGPL licensing, see below.
+
+    AGPL licensing:
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.itextpdf.pdfocr.onnxtr;
+
+import com.itextpdf.commons.utils.StringNormalizer;
+import com.itextpdf.pdfocr.exceptions.PdfOcrException;
+import com.itextpdf.pdfocr.onnxtr.exceptions.PdfOcrOnnxTrExceptionMessageConstant;
+
+/**
+ * Internal helper class to construct a friendlier error in case some dependency couldn’t be loaded.
+ *
+ * <p>
+ * NOTE: for internal usage only. Be aware that its API and functionality may be changed in the future.
+ */
+final class DependencyLoadChecker {
+    private DependencyLoadChecker() {
+        // Private constructor will prevent the instantiation of this class directly.
+    }
+
+    /**
+     * Processes the exception or error: checks if exception is related to some dependency that couldn’t be loaded and
+     * in that case constructs exception with a friendlier error message, otherwise, throws exception as is.
+     *
+     * @param throwable exception or error to process
+     */
+    public static void processException(Throwable throwable) {
+        String throwableMessage = throwable.getMessage();
+        boolean isOnnxRuntime = (throwable instanceof RuntimeException &&
+                throwableMessage.contains("Failed to load onnx-runtime library")) ||
+                (throwable instanceof UnsatisfiedLinkError && throwableMessage.contains("onnxruntime"));
+        if (isOnnxRuntime) {
+            String message = getOnnxRuntimeError();
+            throw new PdfOcrException(message, throwable);
+        }
+    }
+
+    private static String getOnnxRuntimeError() {
+        String message = PdfOcrOnnxTrExceptionMessageConstant.FAILED_TO_LOAD_ONNXRUNTIME;
+        if (isWindows()) {
+            message += "\nPossible causes for Windows:\n" +
+                    "lack of the latest version of the VC++ redistributable " +
+                    "(solution: install it);\n" +
+                    "for Oracle JVMs, mismatch of MSVC runtime version " +
+                    "(solution: upgrade the JVM to a version compiled with newer VC libraries).\n";
+        }
+        return message;
+    }
+
+    /**
+     * Checks current OS type.
+     *
+     * @return boolean {@code true} is current OS is Windows, otherwise - {@code false}
+     */
+    private static boolean isWindows() {
+        return StringNormalizer.toLowerCase(identifyOsType()).contains("win");
+    }
+
+    /**
+     * Identifies type of current OS and return it (win, linux).
+     *
+     * @return type of current os as {@link java.lang.String}
+     */
+    private static String identifyOsType() {
+        String os = System.getProperty("os.name") == null
+                ? System.getProperty("OS") : System.getProperty("os.name");
+        return StringNormalizer.toLowerCase(os);
+    }
+}

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/FloatBufferMdArray.java

@@ -23,6 +23,8 @@ This file is part of the iText (R) project.
 package com.itextpdf.pdfocr.onnxtr;
 
 import ai.onnxruntime.OrtUtil;
+import com.itextpdf.pdfocr.onnxtr.exceptions.PdfOcrOnnxTrExceptionMessageConstant;
+
 import java.nio.FloatBuffer;
 import java.util.Objects;
 
@@ -47,10 +49,10 @@ public FloatBufferMdArray(FloatBuffer data, long[] shape) {
         Objects.requireNonNull(data);
         Objects.requireNonNull(shape);
         if (!OrtUtil.validateShape(shape)) {
-            throw new IllegalArgumentException("Shape is not valid");
+            throw new IllegalArgumentException(PdfOcrOnnxTrExceptionMessageConstant.SHAPE_IS_NOT_VALID);
         }
         if (data.remaining() != OrtUtil.elementCount(shape)) {
-            throw new IllegalArgumentException("Data element count does not match shape");
+            throw new IllegalArgumentException(PdfOcrOnnxTrExceptionMessageConstant.ELEM_COUNT_DOES_NOT_MATCH_SHAPE);
         }
         this.data = data.duplicate();
         this.shape = shape.clone();

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/OnnxInputProperties.java

@@ -22,6 +22,9 @@ This file is part of the iText (R) project.
  */
 package com.itextpdf.pdfocr.onnxtr;
 
+import com.itextpdf.commons.utils.MessageFormatUtil;
+import com.itextpdf.pdfocr.onnxtr.exceptions.PdfOcrOnnxTrExceptionMessageConstant;
+
 import java.util.Arrays;
 import java.util.Objects;
 
@@ -70,22 +73,26 @@ public class OnnxInputProperties {
     public OnnxInputProperties(float[] mean, float[] std, long[] shape, boolean symmetricPad) {
         Objects.requireNonNull(mean);
         if (mean.length != EXPECTED_CHANNEL_COUNT) {
-            throw new IllegalArgumentException("mean should be a " + EXPECTED_CHANNEL_COUNT + "-element array");
+            throw new IllegalArgumentException(MessageFormatUtil.format(
+                    PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_MEAN_CHANNEL_COUNT, EXPECTED_CHANNEL_COUNT));
         }
         Objects.requireNonNull(std);
         if (std.length != EXPECTED_CHANNEL_COUNT) {
-            throw new IllegalArgumentException("std should be a " + EXPECTED_CHANNEL_COUNT + "-element array");
+            throw new IllegalArgumentException(MessageFormatUtil.format(
+                    PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_STD_CHANNEL_COUNT, EXPECTED_CHANNEL_COUNT));
         }
         Objects.requireNonNull(shape);
         if (shape.length != EXPECTED_SHAPE_SIZE) {
-            throw new IllegalArgumentException("shape should be a " + EXPECTED_SHAPE_SIZE + "-element array (BCHW)");
+            throw new IllegalArgumentException(MessageFormatUtil.format(
+                    PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_SHAPE_SIZE, EXPECTED_SHAPE_SIZE));
         }
         if (shape[1] != EXPECTED_CHANNEL_COUNT) {
-            throw new IllegalArgumentException("Model only supports RGB images with a BCHW input format");
+            throw new IllegalArgumentException(PdfOcrOnnxTrExceptionMessageConstant.MODEL_ONLY_SUPPORTS_RGB);
         }
         for (final long dim : shape) {
             if (dim <= 0 || ((int) dim) != dim) {
-                throw new IllegalArgumentException("Unexpected dimension value: " + dim);
+                throw new IllegalArgumentException(MessageFormatUtil.format(
+                        PdfOcrOnnxTrExceptionMessageConstant.UNEXPECTED_DIMENSION_VALUE, dim));
             }
         }
 

pdfocr-onnxtr/src/main/java/com/itextpdf/pdfocr/onnxtr/OnnxTrEngineProperties.java

@@ -36,6 +36,7 @@ public class OnnxTrEngineProperties {
     public OnnxTrEngineProperties() {
 
     }
+
     /**
      * Defines the way text is retrieved and grouped from onnxtr engine output.
      * It changes the way text is selected in the result pdf document.
@@ -44,8 +45,7 @@ public OnnxTrEngineProperties() {
     private TextPositioning textPositioning;
 
     /**
-     * Defines the way text is retrieved from ocr engine output using
-     * {@link TextPositioning}.
+     * Defines the way text is retrieved from ocr engine output using {@link TextPositioning}.
      *
      * @return the way text is retrieved
      */
@@ -58,6 +58,7 @@ public TextPositioning getTextPositioning() {
      * using {@link TextPositioning}.
      *
      * @param textPositioning the way text is retrieved
+     *
      * @return the {@link OnnxTrEngineProperties} instance
      */
     public OnnxTrEngineProperties setTextPositioning(TextPositioning textPositioning) {