com.asprise.ocr

## Class Ocr

- java.lang.Object
- - com.asprise.ocr.Ocr

-     public class Ocr
      extends Object

  Represents an engine of Asprise OCR - a high performance OCR engine for Java/C#/VB.NET/C/C++ on Windows, Linux, Mac OS X and Unix.

  Click here to access the Asprise OCR developer's guide.

  The OCR engine is capable of recognizing text in 20+ languages (English, Spanish, French, German, Italian, Hungarian, Finnish, Swedish, Romanian, Polish, Malay, Arabic, Indonesian, and Russian) and 1-D/2-D barcode of most popular formats (EAN-8, EAN-13, UPC-A, UPC-E, ISBN-10, ISBN-13, Interleaved 2 of 5, Code 39, Code 128, PDF417, and QR Code.).

  An instance of this class should be used by one thread at a time. For multi-treading, please create multiple instance of this class.

  ### Basic code sample

      Ocr.setUp(); // one time setup
       Ocr ocr = new Ocr();
       ocr.startEngine("eng", Ocr.SPEED_FASTEST);
       String s = ocr.recognize(new File[] {new File("test.jpg")}, Ocr.RECOGNIZE_TYPE_ALL, Ocr.OUTPUT_FORMAT_PLAINTEXT, 0, null);
       System.out.println("RESULT: " + s);
       // do more recognition here ...
       ocr.stopEngine();

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Ocr.ImagePreProcessingType` Image pre-processing type
    `static class` | `Ocr.PageType` Page type hint
    `static class` | `Ocr.PropertyBuilder` Builder for configuring scan properties.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONFIG_PROP_KEY_VALUE_SEPARATOR` Do not change unless you are told so.
    `static String` | `CONFIG_PROP_SEPARATOR` Do not change unless you are told so.
    `static String` | `LANGUAGE_DEU` deu (German)
    `static String` | `LANGUAGE_ENG` eng (English)
    `static String` | `LANGUAGE_FRA` fra (French)
    `static String` | `LANGUAGE_POR` por (Portuguese)
    `static String` | `LANGUAGE_SPA` spa (Spanish)
    `static String` | `OUTPUT_FORMAT_PDF` Output recognition result as searchable PDF
    `static String` | `OUTPUT_FORMAT_PLAINTEXT` Output recognition result as plain text
    `static String` | `OUTPUT_FORMAT_XML` Output recognition result in XML format with additional information if coordination, confidence, runtime, etc.
    `static int` | `PAGES_ALL` Recognize all pages.
    `static String` | `PROP_IMG_PREPROCESS_CUSTOM_CMDS` Custom mage pre-processing command
    `static String` | `PROP_IMG_PREPROCESS_TYPE` Image pre-processing type
    `static String` | `PROP_IMG_PREPROCESS_TYPE_CUSTOM` Custom, need to set PROP_IMG_PREPROCESS_CUSTOM_CMDS
    `static String` | `PROP_IMG_PREPROCESS_TYPE_DEFAULT` Use system default
    `static String` | `PROP_IMG_PREPROCESS_TYPE_DEFAULT_WITH_ORIENTATION_DETECTION` Default + page orientation detection
    `static String` | `PROP_INPUT_PDF_DPI` The DPI to be used to render the PDF file; default is 300 if not specified
    `static String` | `PROP_LIMIT_TO_CHARSET` Recognizes only the specified list of characters.
    `static String` | `PROP_OUTPUT_SEPARATE_WORDS` Set to 'true' to set the output level as word instead of the default, line.
    `static String` | `PROP_PAGE_TYPE` Use this property to hint the OCR engine about page type.
    `static String` | `PROP_PAGE_TYPE_AUTO`
    `static String` | `PROP_PAGE_TYPE_SCATTERED`
    `static String` | `PROP_PAGE_TYPE_SINGLE_BLOCK`
    `static String` | `PROP_PAGE_TYPE_SINGLE_CHAR`
    `static String` | `PROP_PAGE_TYPE_SINGLE_COLUMN`
    `static String` | `PROP_PAGE_TYPE_SINGLE_LINE`
    `static String` | `PROP_PAGE_TYPE_SINGLE_WORD`
    `static String` | `PROP_PDF_OUTPUT_CONF_THRESHOLD` Valid value: 0 ~ 100 - text recognized below or above confidence will be highlighted in different colors.
    `static String` | `PROP_PDF_OUTPUT_FILE` PDF output file - required for PDF output.
    `static String` | `PROP_PDF_OUTPUT_FONT` Font to be used for PDF output.
    `static String` | `PROP_PDF_OUTPUT_IMAGE_DPI` The DPI of the images or '0' to auto-detect.
    `static String` | `PROP_PDF_OUTPUT_IMAGE_FORCE_BW` Convert images into black/white to reduce PDF output file size.
    `static String` | `PROP_PDF_OUTPUT_RETURN_TEXT_FORMAT` Return text in 'text' or 'xml' format when the output format is set to PDF.
    `static String` | `PROP_PDF_OUTPUT_RETURN_TEXT_FORMAT_PLAINTEXT`
    `static String` | `PROP_PDF_OUTPUT_RETURN_TEXT_FORMAT_XML`
    `static String` | `PROP_PDF_OUTPUT_TEXT_VISIBLE` Make text visible - for debugging and analysis purpose.
    `static String` | `PROP_SAVE_INTERMEDIATE_IMAGES_TO_DIR` Save intermediate images generated for debug purpose - don't specify or empty string to skip saving
    `static String` | `PROP_TABLE_MIN_SIDE_LENGTH` default is 31 if not specified
    `static String` | `PROP_TABLE_SKIP_DETECTION` table will be detected by default; set this property to true to skip detection.
    `static String` | `RECOGNIZE_TYPE_ALL` Recognize both text and barcode
    `static String` | `RECOGNIZE_TYPE_BARCODE` Recognize barcode
    `static String` | `RECOGNIZE_TYPE_TEXT` Recognize text
    `static String` | `SPEED_FAST` less speed, better accuracy
    `static String` | `SPEED_FASTEST` Highest speed, accuracy may suffer - default option
    `static String` | `SPEED_SLOW` lowest speed, best accuracy

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Ocr()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `getConsoleMode()` -1 unknow / 0 no / 1 yes
    `static String` | `getLibraryVersion()` The library version.
    `static String` | `getLibraryVersion(boolean verbose)` The library version.
    `boolean` | `isEngineRunning()` Returns true only if the engine has been started and has not been stopped yet.
    `static boolean` | `isSetupRequired()` Whether one-time setup is required.
    `static String[]` | `listSupportedLanguages()` Returns all supported languages.
    `static void` | `main(String[] args)` Displays the library version and optional performs OCR on the input file.
    `String` | `recognize(File[] files, String recognizeType, String outputFormat, Object... propSpec)` Performs text/barcode recognition on the given files with the specified output format.
    `String` | `recognize(RenderedImage img, String recognizeType, String outputFormat, Object... propSpec)` Performs text/barcode recognition on the given image with the specified output format.
    `String` | `recognize(String files, int pageIndex, int startX, int startY, int width, int height, String recognizeType, String outputFormat, Object... propSpec)` Performs OCR on the given input files.
    `String` | `recognize(URL[] sources, String recognizeType, String outputFormat, Object... propSpec)` Performs text/barcode recognition on the given files with the specified output format.
    `static boolean` | `saveAocrXslToDir(File dir, boolean overwrite)` Saves aocr.xsl to the specified directory
    `static void` | `setUp()` Performs one-time setup; does nothing if setup has already been done.
    `void` | `startEngine(String lang, String speed)` Starts the OCR engine; does nothing if the engine has already been started.
    `void` | `stopEngine()` Stops the OCR engine; does nothing if it has already been stopped.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SPEED_FASTEST

          public static final String SPEED_FASTEST

      Highest speed, accuracy may suffer - default option
      See Also:
        Constant Field Values

    - #### SPEED_FAST

          public static final String SPEED_FAST

      less speed, better accuracy
      See Also:
        Constant Field Values

    - #### SPEED_SLOW

          public static final String SPEED_SLOW

      lowest speed, best accuracy
      See Also:
        Constant Field Values

    - #### RECOGNIZE_TYPE_TEXT

          public static final String RECOGNIZE_TYPE_TEXT

      Recognize text
      See Also:
        Constant Field Values

    - #### RECOGNIZE_TYPE_BARCODE

          public static final String RECOGNIZE_TYPE_BARCODE

      Recognize barcode
      See Also:
        Constant Field Values

    - #### RECOGNIZE_TYPE_ALL

          public static final String RECOGNIZE_TYPE_ALL

      Recognize both text and barcode
      See Also:
        Constant Field Values

    - #### OUTPUT_FORMAT_PLAINTEXT

          public static final String OUTPUT_FORMAT_PLAINTEXT

      Output recognition result as plain text
      See Also:
        Constant Field Values

    - #### OUTPUT_FORMAT_XML

          public static final String OUTPUT_FORMAT_XML

      Output recognition result in XML format with additional information if coordination, confidence, runtime, etc.
      See Also:
        Constant Field Values

    - #### OUTPUT_FORMAT_PDF

          public static final String OUTPUT_FORMAT_PDF

      Output recognition result as searchable PDF
      See Also:
        Constant Field Values

    - #### LANGUAGE_ENG

          public static final String LANGUAGE_ENG

      eng (English)
      See Also:
        Constant Field Values

    - #### LANGUAGE_SPA

          public static final String LANGUAGE_SPA

      spa (Spanish)
      See Also:
        Constant Field Values

    - #### LANGUAGE_POR

          public static final String LANGUAGE_POR

      por (Portuguese)
      See Also:
        Constant Field Values

    - #### LANGUAGE_DEU

          public static final String LANGUAGE_DEU

      deu (German)
      See Also:
        Constant Field Values

    - #### LANGUAGE_FRA

          public static final String LANGUAGE_FRA

      fra (French)
      See Also:
        Constant Field Values

    - #### PROP_PAGE_TYPE

          public static final String PROP_PAGE_TYPE

      Use this property to hint the OCR engine about page type.
      See Also:
        Constant Field Values

    - #### PROP_PAGE_TYPE_AUTO

          public static final String PROP_PAGE_TYPE_AUTO

      See Also:
        Constant Field Values

    - #### PROP_PAGE_TYPE_SINGLE_BLOCK

          public static final String PROP_PAGE_TYPE_SINGLE_BLOCK

      See Also:
        Constant Field Values

    - #### PROP_PAGE_TYPE_SINGLE_COLUMN

          public static final String PROP_PAGE_TYPE_SINGLE_COLUMN

      See Also:
        Constant Field Values

    - #### PROP_PAGE_TYPE_SINGLE_LINE

          public static final String PROP_PAGE_TYPE_SINGLE_LINE

      See Also:
        Constant Field Values

    - #### PROP_PAGE_TYPE_SINGLE_WORD

          public static final String PROP_PAGE_TYPE_SINGLE_WORD

      See Also:
        Constant Field Values

    - #### PROP_PAGE_TYPE_SINGLE_CHAR

          public static final String PROP_PAGE_TYPE_SINGLE_CHAR

      See Also:
        Constant Field Values

    - #### PROP_PAGE_TYPE_SCATTERED

          public static final String PROP_PAGE_TYPE_SCATTERED

      See Also:
        Constant Field Values

    - #### PROP_LIMIT_TO_CHARSET

          public static final String PROP_LIMIT_TO_CHARSET

      Recognizes only the specified list of characters.
      See Also:
        Constant Field Values

    - #### PROP_OUTPUT_SEPARATE_WORDS

          public static final String PROP_OUTPUT_SEPARATE_WORDS

      Set to 'true' to set the output level as word instead of the default, line.
      See Also:
        Constant Field Values

    - #### PROP_INPUT_PDF_DPI

          public static final String PROP_INPUT_PDF_DPI

      The DPI to be used to render the PDF file; default is 300 if not specified
      See Also:
        Constant Field Values

    - #### PROP_IMG_PREPROCESS_TYPE

          public static final String PROP_IMG_PREPROCESS_TYPE

      Image pre-processing type
      See Also:
        Constant Field Values

    - #### PROP_IMG_PREPROCESS_TYPE_DEFAULT

          public static final String PROP_IMG_PREPROCESS_TYPE_DEFAULT

      Use system default
      See Also:
        Constant Field Values

    - #### PROP_IMG_PREPROCESS_TYPE_DEFAULT_WITH_ORIENTATION_DETECTION

          public static final String PROP_IMG_PREPROCESS_TYPE_DEFAULT_WITH_ORIENTATION_DETECTION

      Default + page orientation detection
      See Also:
        Constant Field Values

    - #### PROP_IMG_PREPROCESS_TYPE_CUSTOM

          public static final String PROP_IMG_PREPROCESS_TYPE_CUSTOM

      Custom, need to set PROP_IMG_PREPROCESS_CUSTOM_CMDS
      See Also:
        Constant Field Values

    - #### PROP_IMG_PREPROCESS_CUSTOM_CMDS

          public static final String PROP_IMG_PREPROCESS_CUSTOM_CMDS

      Custom mage pre-processing command
      See Also:
        Constant Field Values

    - #### PROP_TABLE_SKIP_DETECTION

          public static final String PROP_TABLE_SKIP_DETECTION

      table will be detected by default; set this property to true to skip detection.
      See Also:
        Constant Field Values

    - #### PROP_TABLE_MIN_SIDE_LENGTH

          public static final String PROP_TABLE_MIN_SIDE_LENGTH

      default is 31 if not specified
      See Also:
        Constant Field Values

    - #### PROP_SAVE_INTERMEDIATE_IMAGES_TO_DIR

          public static final String PROP_SAVE_INTERMEDIATE_IMAGES_TO_DIR

      Save intermediate images generated for debug purpose - don't specify or empty string to skip saving
      See Also:
        Constant Field Values

    - #### PROP_PDF_OUTPUT_FILE

          public static final String PROP_PDF_OUTPUT_FILE

      PDF output file - required for PDF output. Valid prop value: absolute path to the target output file.
      See Also:
        Constant Field Values

    - #### PROP_PDF_OUTPUT_IMAGE_DPI

          public static final String PROP_PDF_OUTPUT_IMAGE_DPI

      The DPI of the images or '0' to auto-detect. Optional. Valid prop value: 0(default: auto-detect), 300, 200, etc.
      See Also:
        Constant Field Values

    - #### PROP_PDF_OUTPUT_FONT

          public static final String PROP_PDF_OUTPUT_FONT

      Font to be used for PDF output. Optional. Valid values: "serif" (default), "sans".
      See Also:
        Constant Field Values

    - #### PROP_PDF_OUTPUT_TEXT_VISIBLE

          public static final String PROP_PDF_OUTPUT_TEXT_VISIBLE

      Make text visible - for debugging and analysis purpose. Optional. Valid prop values false(default), true.
      See Also:
        Constant Field Values

    - #### PROP_PDF_OUTPUT_IMAGE_FORCE_BW

          public static final String PROP_PDF_OUTPUT_IMAGE_FORCE_BW

      Convert images into black/white to reduce PDF output file size. Optional. Valid prop values: false(default), true.
      See Also:
        Constant Field Values

    - #### PROP_PDF_OUTPUT_CONF_THRESHOLD

          public static final String PROP_PDF_OUTPUT_CONF_THRESHOLD

      Valid value: 0 ~ 100 - text recognized below or above confidence will be highlighted in different colors.
      See Also:
        Constant Field Values

    - #### PROP_PDF_OUTPUT_RETURN_TEXT_FORMAT

          public static final String PROP_PDF_OUTPUT_RETURN_TEXT_FORMAT

      Return text in 'text' or 'xml' format when the output format is set to PDF.
      See Also:
        Constant Field Values

    - #### PROP_PDF_OUTPUT_RETURN_TEXT_FORMAT_PLAINTEXT

          public static final String PROP_PDF_OUTPUT_RETURN_TEXT_FORMAT_PLAINTEXT

      See Also:
        Constant Field Values

    - #### PROP_PDF_OUTPUT_RETURN_TEXT_FORMAT_XML

          public static final String PROP_PDF_OUTPUT_RETURN_TEXT_FORMAT_XML

      See Also:
        Constant Field Values

    - #### CONFIG_PROP_SEPARATOR

          public static String CONFIG_PROP_SEPARATOR

      Do not change unless you are told so.

    - #### CONFIG_PROP_KEY_VALUE_SEPARATOR

          public static String CONFIG_PROP_KEY_VALUE_SEPARATOR

      Do not change unless you are told so.

    - #### PAGES_ALL

          public static final int PAGES_ALL

      Recognize all pages.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Ocr

          public Ocr()

  - ### Method Detail

    - #### getLibraryVersion

          public static String getLibraryVersion()

      The library version.
      Returns:

    - #### getLibraryVersion

          public static String getLibraryVersion(boolean verbose)

      The library version.
      Returns:

    - #### isSetupRequired

          public static boolean isSetupRequired()

      Whether one-time setup is required.
      Returns:

    - #### setUp

          public static void setUp()

      Performs one-time setup; does nothing if setup has already been done.

    - #### listSupportedLanguages

          public static String[] listSupportedLanguages()

      Returns all supported languages.

    - #### startEngine

          public void startEngine(String lang,
                         String speed)

      Starts the OCR engine; does nothing if the engine has already been started.
      Parameters:
        `lang` - e.g., "eng" for English
        `speed` - valid values: SPEED_FASTEST, SPEED_FAST, SPEED_SLOW.

    - #### stopEngine

          public void stopEngine()

      Stops the OCR engine; does nothing if it has already been stopped.

    - #### isEngineRunning

          public boolean isEngineRunning()

      Returns true only if the engine has been started and has not been stopped yet.
      Returns:

    - #### recognize

          public String recognize(URL[] sources,
                         String recognizeType,
                         String outputFormat,
                         Object... propSpec)

      Performs text/barcode recognition on the given files with the specified output format.

      Supported file formats:

      - BMP
      - JPEG
      - PNG
      - TIFF
      - PNM
      - GIF
      Parameters:
        `sources` - input image files - can be local files or files on remote server
        `recognizeType` - valid values: RECOGNIZE_TYPE_TEXT, RECOGNIZE_TYPE_BARCODE or RECOGNIZE_TYPE_ALL.
        `outputFormat` - valid values: OUTPUT_FORMAT_PLAINTEXT, OUTPUT_FORMAT_XML or OUTPUT_FORMAT_PDF.
        `propSpec` - additional properties, can be a single Properties object or inline specification in pairs. Valid property names are defined in this class, etc.
      Returns:
        the recognition output in the specified format or

            null

        if there is no input file.

    - #### recognize

          public String recognize(File[] files,
                         String recognizeType,
                         String outputFormat,
                         Object... propSpec)

      Performs text/barcode recognition on the given files with the specified output format.

      Supported file formats:

      - BMP
      - JPEG
      - PNG
      - TIFF
      - PNM
      - GIF
      Parameters:
        `files` - input image files - files must exist and file name can not contain ','
        `recognizeType` - valid values: RECOGNIZE_TYPE_TEXT, RECOGNIZE_TYPE_BARCODE or RECOGNIZE_TYPE_ALL.
        `outputFormat` - valid values: OUTPUT_FORMAT_PLAINTEXT, OUTPUT_FORMAT_XML or OUTPUT_FORMAT_PDF.
        `propSpec` - additional properties, can be a single Properties object or inline specification in pairs. Valid property names are defined in this class, etc.
      Returns:
        the recognition output in the specified format or

            null

        if there is no input file.

    - #### recognize

          public String recognize(RenderedImage img,
                         String recognizeType,
                         String outputFormat,
                         Object... propSpec)

      Performs text/barcode recognition on the given image with the specified output format.
      Parameters:
        `img` - input image
        `recognizeType` - valid values: RECOGNIZE_TYPE_TEXT, RECOGNIZE_TYPE_BARCODE or RECOGNIZE_TYPE_ALL.
        `outputFormat` - valid values: OUTPUT_FORMAT_PLAINTEXT, OUTPUT_FORMAT_XML or OUTPUT_FORMAT_PDF.
        `propSpec` - additional properties, can be a single Properties object or inline specification in pairs. Valid property names are defined in this class, etc.
      Returns:
        the recognition output in the specified format or

            null

        if there is no input file.

    - #### recognize

          public String recognize(String files,
                         int pageIndex,
                         int startX,
                         int startY,
                         int width,
                         int height,
                         String recognizeType,
                         String outputFormat,
                         Object... propSpec)

      Performs OCR on the given input files.
      Parameters:
        `files` - comma ',' separated image file path (JPEG, BMP, PNG, TIFF)
        `pageIndex` - -1 for all pages or the specified page (first page is 1) for multi-page image format like TIFF
        `startX` - -1 for whole page or the starting x coordinate of the specified region
        `startY` - -1 for whole page or the starting y coordinate of the specified region
        `width` - -1 for whole page or the width of the specified region
        `height` - -1 for whole page or the height of the specified region
        `recognizeType` - valid values: RECOGNIZE_TYPE_TEXT, RECOGNIZE_TYPE_BARCODE or RECOGNIZE_TYPE_ALL.
        `outputFormat` - valid values: OUTPUT_FORMAT_PLAINTEXT or OUTPUT_FORMAT_XML.
        `propSpec` - additional properties, can be a single Properties object or inline specification in pairs. Valid property names are defined in this class, etc.
      Returns:
        text (plain text, xml) recognized for OUTPUT_FORMAT_PLAINTEXT, OUTPUT_FORMAT_XML; null for OUTPUT_FORMAT_PDF.

    - #### saveAocrXslToDir

          public static boolean saveAocrXslToDir(File dir,
                                 boolean overwrite)

      Saves aocr.xsl to the specified directory

    - #### getConsoleMode

          public static int getConsoleMode()

      -1 unknow / 0 no / 1 yes

    - #### main

          public static void main(String[] args)

      Displays the library version and optional performs OCR on the input file. Usage:

          Usage: java -jar aocr.jar INPUT_FILE [text|xml|pdf]

      Parameters:
        `args` -

Copyright © Asprise Software. All Rights Reserved. Please visit the product page at asprise.com