Documentation – Developer's reference

Python: Preparing content for recognition

Fri, 25 Aug 2023 00:00:00 +0000

Aspose.OCR for Python via .NET provides a versatile way to prepare your content for OCR. A package of recognized files/folders/URLs, regardless of their number and type, is constructed as OcrInput object. With this approach, you can easily process a single image or a large number of images from an auto-feed scanner in a single API call.

The object constructor takes the type of the provided content and optional processing filters that will be applied to all images in a batch.

Supported content types

You can only pack sources of the same type into one OcrInput object. The type is specified in the constructor and cannot be changed later.

Source content type	Supported file formats
`InputType.SINGLE_IMAGE`	One or more GIF, PNG, JPEG, BMP, or single-page TIFF images. The images can be provided by their absolute or relative paths, as `MemoryStream` objects, or as arrays of pixels. You can add images of different types in a single batch.
`InputType.PDF`	One or more PDF documents, containing scanned pages. The files can be provided by their absolute or relative paths or as `MemoryStream` objects.
`InputType.TIFF`	One or more multi-page TIFF images. The files can be provided by their absolute or relative paths or as `MemoryStream` objects.
`InputType.DJVU`	One or more DjVu files, provided by their absolute or relative paths or as `MemoryStream` objects.
`InputType.URL`	One or more web links to GIF, PNG, JPEG, BMP, or single-page TIFF images. Aspose.OCR for Python via .NET will download them automatically before processing. Limitations: Aspose.OCR for Python via .NET does not support authentication and can only work with public URLs. The URL must point directly to the image. Aspose.OCR for Python via .NET cannot extract images from HTML pages.
`InputType.DIRECTORY`	Absolute or relative paths to one or more folders containing GIF, PNG, JPEG, BMP, or single-page TIFF images. Unless specifically configured, all nested images will be recognized. Subfolders and nested archives will not be processed!
`InputType.ZIP`	Absolute or relative paths to one or more ZIP archives containing GIF, PNG, JPEG, BMP, or single-page TIFF images. Unless specifically configured, all archived images will be recognized. Nested archives and folders will not be processed!
`InputType.BASE64`	One or more GIF, PNG, JPEG, BMP, or single-page TIFF images provided as Base64-encoded strings.

Combination of different content types (for example, images and PDF documents) within one OcrInput object is not supported.

Adding source content

To manage a batch of images, scanned PDFs, URLs, folders, and other OCR content, use the following methods of the OcrInput class:

Method	Purpose
`add(string)`	Adds an absolute or relative path to a file/folder, or a URL to an image file on the web.
`add(string, int, int)`	Adds an absolute or relative path to a multi-page image, PDF document, ZIP archive or folder, specifying the images/pages for recognition.
`add(stream)`	Adds a stream, containing a file to be recognized.
`add(stream, int, int)`	Adds a stream, containing a milti-page image, PDF document, or ZIP archive, specifying the images/pages for recognition.
`add(Color[], int, int)`	Adds an image provided as an array of pixels. You must specify the width and height.
`add(byte[], int, int, PixelType)`	Adds an image provided as an array of pixels. You must specify the width, height and color model.
`add_base64(string)`	Adds an image encoded as Base64 string.

To get the number of items in the batch, use count() method.

Removing source content

To remove all sources from a batch, use clear() method.

Applying image processing filters

The accuracy and reliability of text recognition is highly dependent on the quality of the original image. Aspose.OCR for Python via .NET offers a large number of fully automated and manual image processing filters that enhance an image before it is sent to the OCR engine.

To apply processing filters to all images in the batch, provide them in the OcrInput object constructor, or later using replace_filters() method.

To remove all processing filters from a batch, use clear_filters() method.

Examples

The following code samples demonstrates how to prepare content for recognition:

Provide multiple images

input = OcrInput(InputType.SINGLE_IMAGE)
input.add("page1.png")
input.add("page2.png")

Provide scanned PDF

input = OcrInput(InputType.PDF)
# Recognize pages 2 to 8
input.add("contract.pdf", 1, 7)

Apply processing filters

# Automatically deskew all images
filters = PreprocessingFilter()
filters.add(PreprocessingFilter.auto_skew())
# Prepare batch
input = OcrInput(InputType.SINGLE_IMAGE, filters)
input.add("page1.png")
input.add("page2.png")

Python: Recognition languages

Thu, 21 Nov 2024 00:00:00 +0000

To recognize text in certain languages, you must install additional recognition models:

Cyrillic text recognition: aspose-ocr-cyrillic-v1
Chinese text recognition: aspose-ocr-chinese-v2
Indic (Devanagari) text recognition: aspose-ocr-hindi-v2
Arabic text recognition: aspose-ocr-arabic-v1
Persian (Farsi) text recognition: aspose-ocr-arabic-v1
Uyghur text recognition: aspose-ocr-arabic-v1
Urdu text recognition: aspose-ocr-arabic-v1
Japanese text recognition: aspose-ocr-japanese-v1
Korean text recognition: aspose-ocr-korean-v1
Kannada text recognition: aspose-ocr-kannada-v1
Tamil text recognition: aspose-ocr-tamil-v1
Telugu text recognition: aspose-ocr-telugu-v1
Mixed-language Cyrillic/English recognition: aaspose-ocr-cyrillic-v2
Mongolian text recognition: aspose-ocr-cyrillic-v1

Aspose.OCR for Python via .NET can recognize a text in a large number of languages and all popular writing scripts, including texts with mixed languages.

To specify a language for recognition, provide one of the following values in language property of recognition settings:

Mixed-language Cyrillic/English text recognition is experimental. If you are absolutely sure about the text language (for example, Ukrainian), it is recommended to specify the language directly.

Value	Alphabet
`Language.MULTILANGUAGE` `Aspose.OCR.Language.AUTO` `Aspose.OCR.Language.UNIVERSAL`	Automatically detects the language. Supports multiple language families, including Latin, Cyrillic, Arabic, Chinese and more.
`Language.EXT_LATIN`	Auto-detect all supported Latin characters and diacritics
`Language.CYRILLIC`	Auto-detect all supported Cyrillic characters
`Language.CHINESE`	All Chinese languages. Mixed-language Chinese/English texts also supported.
`Language.DEVANAGARI` `Language.INDIC`	Indic texts based on Devanagari script, including mixed Devanagari/English texts.
`Language.EUROPEAN`	Mixed-language Cyrillic/English texts (experimental).
`Language.PERSO_ARABIC` `Language.ISLAMIC`	Mixed-language texts with Arabic, Persian and English.

If this parameter is omitted, the OCR engine will assume that the text is written in extended Latin.

Make sure you specify the correct language for the image. If you try to recognize Cyrillic text using Language.ENG, only the characters that look the same in both languages (for example, с and c) will be correctly recognized. Other characters will be replaced with similar-looking alternatives.

Example

The following code sample demonstrates how to specify the recognition language:

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition batch
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source.png")
# Recognize Ukrainian text
recognitionSettings = RecognitionSettings()
recognitionSettings.language = Language.UKR
# Recognize the image
result = api.recognize(input, recognitionSettings)
# Print recognition result
print(result[0].recognition_text)
input("Press Enter to continue...")

Python: Image processing

Mon, 21 Aug 2023 00:00:00 +0000

Each filter increases recognition time. The approximate amount of additional time required for preprocessing (as a percentage of the minimum OCR pipeline) is listed in the Performance Impact column.

Filter	Action	Performance impact	Usage scenarios
Skew correction	Automatically straighten images aligned at a slight angle to the horizontal.	12%	Skewed images
Rotation	Manually rotate severely skewed images.	7.5%	Rotated images
Noise removal	Automatically remove dirt, spots, scratches, glare, unwanted gradients, and other noise from photos and scans.	175% extra time; 38% more memory ⁽¹⁾	Photos Old books Newspapers Postcards Documents with stains and dirt
Contrast correction	Automatically adjust the image contrast.	7.5%	Photos Old papers Text on a background
Resizing	Proportionally scale images up / down, or manually define the width and height of the image.	up to 100% ⁽²⁾	Medication guides Food labels Full-sized photos from modern cameras and smartphones Scanned images at very high DPI
Binarization	Convert images to black and white automatically or manually adjust the criteria that determines whether a pixel is considered black or white.	0.9%	Always used for text detection and most automatic image corrections
Conversion to grayscale	Discard color information from images and leave only shades of gray.	0.5%	Photos Scanned ID cards Full-color scans
Color inversion	Swap image colors so that light areas appear dark and dark areas appear light.	0.25%	White text on black background Advertisements Business cards Screenshots
Dilation	Increase the thickness of characters in an image by adding pixels to the edges of high-contrast objects, such as letters.	3.1%	Receipts Printouts with very thin font
Median filter	Blur noisy images while preserving the edges of high-contrast objects like letters.	6.25%	Photos taken in low light conditions Poor quality printouts Highly compressed JPEG’s
Dewarping	Straighten page curvature and fix camera lens distortion for page photos. This method requires significant resources and time! Consider using it only if the image has geometric distortions preventing accurate recognition.	30-40 seconds; Up to 4 times more memory ⁽³⁾	Photos of curved pages Ultra wide-angle and fisheye photos Photos from entry-level smartphones

Notes

Automatic noise removal uses a specialized neural network that consumes significant computing resources and RAM. Use it with care.
Resizing takes between 6% and 100% more time than the minimum processing pipeline, depending on the original image size.
Due to the high complexity of the underlying neural network, dewarping is resource- and time-intensive. Actual numbers may vary greatly depending on the performance of the computer and the characteristics of the original image.

Chaining processing filters

Multiple processing filters can be applied to the same image to further improve the recognition quality. The filters are applied one by one in the order they are added to PreprocessingFilter object.

Note that each filter requires additional time and resources on the computer running the application. Do not add extra filters if you are satisfied with the recognition accuracy, especially when developing web applications.

Set binarization threshold

Correct skew

Rotate

Remove noise

Adjust contrast

Scale

Resize

Convert to grayscale

Invert colors

Dilate

Apply median filter

filters = PreprocessingFilter()
filters.add(PreprocessingFilter.threshold({THRESHOLD}))
filters.add(PreprocessingFilter.auto_skew())
filters.add(PreprocessingFilter.rotate({ANGLE}))
filters.add(PreprocessingFilter.auto_denoising())
filters.add(PreprocessingFilter.contrast_correction_filter())
filters.add(PreprocessingFilter.scale({RATIO}))
filters.add(PreprocessingFilter.resize({WIDTH}, {HEIGHT}))
filters.add(PreprocessingFilter.to_grayscale())
filters.add(PreprocessingFilter.invert())
filters.add(PreprocessingFilter.dilate())
filters.add(PreprocessingFilter.median())

Approximate increase of processing time: 0%

Previewing and saving processed images

Aspose.OCR for Python via .NET offers an easy way to access or save processed images using the methods of the ImageProcessing class:

Method	Return value	Description
`render()`	`OcrInput`	Applies processing filters to all images in a batch and returns a new batch with processed images. This batch can later be submitted for recognition or used for optimization.
`save()`	`OcrInput`	Applies processing filters to all images in batch and saves the resulting images in the specified folder. That method also returns a new batch with processed images, that can be later submitted for the recognition.

You can use these methods to analyze the effectiveness of processing filters, exclude unnecessary filters that consume resources without affecting the result, or show the result of image processing in the user interface.

Processing filters are applied to all images in the batch, including those without text.
PDF documents can contain more than one image per page. Therefore, the resulting OcrInput object can contain more images than the number of pages in the document.

# Set processing filters
filters = PreprocessingFilter()
filters.add(PreprocessingFilter.auto_dewarping())
filters.add(PreprocessingFilter.contrast_correction_filter())
# Add all pages from a scanned PDF to OcrInput object and apply processing filters
input = OcrInput(InputType.PDF, filters)
input.add("source.pdf")
# Save processed images from the provided PDF to the "images" folder
ImageProcessing.save(input, "images")

Python: Language detecton

Mon, 03 Mar 2025 00:00:00 +0000

To use language detection, install (aspose-ocr-language-classification-v1) advanced OCR model to your project.

Aspose.OCR for .NET can automatically identify the following languages and language families used on the provided image using detect_languages method:

Latin
Cyrillic
Arabic
Chinese
Japanese
Korean
Hindi
Tamil
Telugu
Kannada

The method accepts the collection of images in any of the supported formats and returns them as an array of LanguageDetectionOutput objects with the following properties:

Property	Type	Description
`source`	`string`	The full path or URL of the source file. If the file is provided as a `MemoryStream` object, an array of pixels, or a Base64 string, this value will be empty.
`page`	`int`	Page number. When working with single-page images, this value is always 0.
`languages`	Array of `DetectedLanguage` objects	Lists the recognition languages detected in the image along with their probabilities.

DetectedLanguage objects contain the following properties:

Property	Type	Description
`language`	`Language`	Detected language
`accuracy`	`float`	The confidence level of the language detection, which can be used to assess the accuracy.

Example

The following code sample demonstrates how to detect the image languages:

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition batch
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source.png")
# Detect languages
result = api.detect_languages(input)
for lang in result[0].languages:
    print(lang.language)
    print(lang.accuracy)

The following code sample demonstrates how to detect the image languages and recognize multilanguage image:

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition batch
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source.png")
# Set language detection
set = RecognitionSettings()
set.language = Language.AUTO
set.language_detection_level = LanguageDetectionLevel.BY_WORD
# Detect languages and recognize image     
results = api.recognize(input, set)
for result in results:
    print(result.recognition_text)

Python: Layout detecton

Mon, 03 Mar 2025 00:00:00 +0000

To use language detection, install (aspose-ocr-document-structure-detection-v1.ocr) advanced OCR model to your project.

Aspose.OCR for .NET can automatically analyze image content and identify the different types of layout blocks within it.

Pass one or more images as aspose.ocr.OcrInput object to aspose.ocr.detect_document_layout method and get the layout blocks as aspose.ocr.LayoutOutput object.

The method accepts the collection of images in any of the supported formats and returns them as an array of LayoutOutput objects with the following properties:

`aspose.ocr.LayoutOutput`

This class stores a layout block detected in an image.

Property	Type	Description
`source`	`string`	The full path to the file or URL, if applicable. Empty for images provided as a stream, byte array, or Base64.
`page`	`int`	Page number for multi-page images.
`paragraphs`	Array of `ContentArea`	Detected paragraphs.
`images`	Array of `ContentArea`	Detected illustrations.
`headers`	Array of `ContentArea`	Detected headers.
`tables`	Array of `ContentArea`	Detected tables.
`lists`	Array of `ContentArea`	Detected lists.
`captions`	Array of `ContentArea`	Detected captions.
`equations`	Array of `ContentArea`	Detected equations.

`Aspose.OCR.ContentArea`

This class stores a layout block detected in an image.

Property	Type	Description
`index`	`int`	The sequential index of the content area, unique within the entire image.
`rectangle`	`aspose.ocr.Rectangle`	The bounding rectangle of the content area.

Example

The following code sample demonstrates how to detect the image layout:

### Detect layout on the image

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition batch
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source.png")
# Detect layout
results = api.detect_document_layout(input)
# Print result
for result in results:
    print("paragraphs:" + str(len(result.paragraphs)))
    print("images:" + str(len(result.images)))
    print("tables:" + str(len(result.tables)))
    print("headers:" + str(len(result.headers)))
    print("lists:" + str(len(result.lists)))
    print("captions:" + str(len(result.captions)))
    print("equations:" + str(len(result.equations)))

# Recognize only headers
# Set rectangles for recognition
set = RecognitionSettings()
set.recognition_areas = [area.rectangle for area in result.headers] # use paragraphs or any other areas
# Recognize areas (rectangles)
results = api.recognize(input, set)
for result in results:
    print(result.recognition_text)

Python: Defining recognized characters

Sat, 26 Aug 2023 00:00:00 +0000

Aspose.OCR for Python via .NET supports a large list of extended Latin, Cyrillic and Asian characters. However, a typical image contains no more than half of these characters. You can greatly improve the accuracy and performance of recognition by specifying which characters the OCR engine will look for.

The full workflow is as follows:

Identifying the characters on an image.
Aspose.OCR provides detailed information about the characters found in the image and their possible alternatives.
Defining the whitelist of characters.
Limit the set of characters Aspose.OCR engine will look for.
Defining the blacklist of characters.
Explicitly ignore certain image defects that may be incorrectly recognized as characters.

Python: Recognition settings

Wed, 30 Aug 2023 00:00:00 +0000

Aspose.OCR for Python via .NET provides good recognition accuracy and performance by default. However, there will inevitably be cases where the default settings cannot provide reliable recognition results.

To configure Aspose.OCR for Python via .NET recognition settings, specify an optional parameter for the recognition method. The parameter type depends on the recognition method.

Parameter type	Applicable to
`RecognitionSettings`	Extracting text from images, scanned PDFs, DjVu files and other content provided as `OcrInput` object.
`ReceiptRecognitionSettings`	Extracting text from receipts.
`IDCardRecognitionSettings`	Extracting text from ID cards.
`PassportRecognitionSettings`	Extracting text from passports.
`CarPlateRecognitionSettings`	Extracting text from vehicle license plates.
`InvoiceRecognitionSettings`	Extracting text from invoices.

Python: Table recognition

Thu, 27 Nov 2025 00:00:00 +0000

Aspose.OCR for Python via .NET now provides a dedicated API for detecting table layout and recognizing table data in images, scanned documents, screenshots, or photos. To extract table text, simply call the universal aspose.ocr.AsposeOcr.recognize method with DetectAreasMode.TABLE settings.

This method accepts an OcrInput object and optional recognition settings.

Recognition results are returned as a list of aspose.ocr.RecognitionResult objects. Each result contains extracted table data, detected regions, and allows exporting to various formats. Additionally, you can retrieve the table’s row and column structure using the get_table_data() method.

Example

The following code example shows how to extract text from table and get rows and columns structure:

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source1.png")

# Set areas detection mode
recognitionSettings = RecognitionSettings()
recognitionSettings.detect_areas_mode = DetectAreasMode.TABLE
# Recognize the image
results = api.recognize(input, recognitionSettings)

# Print recognition result
for result in results:
    print(result.recognition_text)

# Print table rows cloumns
 table =  results.get_table_data()
        for page in table.pages:
            print("page:" + str(page.page_index))
            for row in page.rows:
                print("row:" + str(row.row_index))
                for cell in row.cells:
                    print("cell:" + str(cell.column_index)+": "+cell.text)

Python: Formula recognition

Thu, 27 Nov 2025 00:00:00 +0000

Aspose.OCR for Python via .NET now provides a dedicated API for detecting and recognizing mathematical formulas in images, scanned documents, screenshots, or photos. To extract formula text, simply call the universal aspose.ocr.AsposeOcr.recognize_formula method.

This method accepts an OcrInput object and optional recognition settings. Internally, formula detection uses the DetectAreasMode.FORMULA mode to locate mathematical expressions before recognition.

Recognition results are returned as a list of aspose.ocr.RecognitionResult objects. Each result contains extracted formula text, detected regions, and allows exporting to various formats.

DetectAreasMode.FORMULA

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source1.png")

# Set areas detection mode
recognitionSettings = RecognitionSettings()
recognitionSettings.detect_areas_mode = DetectAreasMode.FORMULA
# Recognize the image
results = api.recognize(input, recognitionSettings)

# Print recognition result
for result in results:
    print(result.recognition_text)

RecognizeFormula(OcrInput images, bool detectAreas = true)

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source1.png")

# Recognize formulas with areas detection
results = api.recognize_formula(input, True)
# Parameter bool detectAreas - if set to true, automatically detects and isolates formula regions before performing recognition. If false, processes the entire image as a formula.

# Print recognition result
for result in results:
    print(result.recognition_text)

Live demo

recognitionEngine.recognize_formula(input, True)

x_{c} ( t )=\\sin\left( 2 \\pi( 1 0 0 ) t \right)
T=1 / 4 0 0
x [ n ]
x [ n ]
x [ n ]=\\cos\left( {\\frac{\\pi} {4}} n \right) , \\qquad-\\infty< n < \\infty.

Live demo

recognitionEngine.recognize_formula(input, False)

x [ n ]=\\cos\left( \\frac{\\pi} {4} n \right) . \\qquad-\\infty< n < \\infty.

Python: Content areas detection

Fri, 18 Oct 2024 00:00:00 +0000

A scanned image or photograph of a text document may contain a large number of blocks of various content - text paragraphs, tables, illustrations, formulas, and the like. Detecting, ordering, and classifying areas of interest on a page is the cornerstone of successful and accurate OCR. This process is called content areas detection.

Aspose.OCR offers several content areas detection algorithms, allowing you to choose the one that works best for your specific content.

Area detection modes

You can manually override the default content areas detection method if you are unhappy with the results or get unwanted artifacts.

Document structure analysis algorithm is specified in an optional DetectAreasMode parameter of recognition settings.

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition batch
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source.png")
# Set document areas detection mode
recognitionSettings = RecognitionSettings()
recognitionSettings.detect_areas_mode = DetectAreasMode.MULTICOLUMN
# Recognize the image
result = api.recognize(input, recognitionSettings)
# Print recognition result
print(result[0].recognition_text)
input("Press Enter to continue...")

Aspose.OCR for Python via .NET supports the following document structure analysis methods provided in DetectAreasMode enumeration:

Name	Description	Use cases
`DetectAreasMode.UNIVERSAL`	Detects all blocks of text in the image, including sparse and irregular text on street photos. Used by default. See DetectAreasMode.UNIVERSAL for additional details.	Photos Screenshots Advertisements Datasheets Street photos Price tags Food labels
`DetectAreasMode.MULTICOLUMN`	Detects large blocks of text formatted in several columns. See DetectAreasMode.MULTICOLUMN for additional details.	Contracts Books Articles Newspapers
`DetectAreasMode.LEAN`	Do not analyze document structure. Prioritizes speed and reduces resource consumption by omitting support for complex layouts.	Simple images containing a few lines of text without illustrations or formatting. Applications requiring maximum recognition speed Web applications
`DetectAreasMode.TABLE`	Detects cells in tabular structures. See DetectAreasMode.TABLE for additional details.	Tables Invoices
`DetectAreasMode.CURVED_TEXT`	Auto-straightens curved lines and finds text blocks inside the resulting image. See DetectAreasMode.CURVED_TEXT for additional details.	Photos of books, magazine articles, and other curved pages.

Python: AsposeAI class

Sun, 14 Sep 2025 00:00:00 +0000

The AsposeAI class provides the bridge between LLM models and the OCR engine.

🛠 Constructors

AsposeAI()
AsposeAI(logging)

You can also pass optional logging and customization callbacks.

Configuration

⚙️ AsposeAIModelConfig

Property	Type	Description
`allow_auto_download`	`string`	If true, the model will be automatically downloaded if not available locally.
`directory_model_path`	`string`	Optional path where downloaded or processed models will be cached. If not set, a default system location will be used.
`file_model_path`	`string`	Local path to the folder containing the model files. If specified, this will be used instead of downloading. Default empty.
`hugging_face_quantization`	`string`	Optional quantization type to use when downloading from HuggingFace. Examples: “int8”, “fp16”, “none”. Default q4_k_m.
`hugging_face_repo_id`	`string`	ID of the model on HuggingFace (e.g., “openai/gpt2”). If specified, the model will be downloaded from HuggingFace. Default bartowski/Qwen2.5-3B-Instruct-GGUF.
`context_size`	`int`	Defines the maximum number of tokens the LLM can use as context during inference. If null, the default context size defined by the model will be used. Larger values allow the model to consider more text but may require more memory.
`gpu_layers`	`int`	Number of GPU layers to use for the model. If not specified, the default value (40) will be used. Set to 0 to run entirely on the CPU.

🧠 AsposeAI Class – Core Methods

Method	Description
`set_post_processor(processor, custom_settings)`	Adds a custom AI postprocessor to enhance OCR results.
`run_postprocessor(res)`	Enhances plain recognized text strings using registered AI modules.
`run_postprocessor(res)`	Enhances structured OCR output using registered AI modules.
`free_resources()`	Explicitly unloads AI models and clears memory.
`list_local()`	Lists all local AI models available in the configured folder.
`get_local_path()`	Returns the directory path of the current model location.
`is_initialized()`	Checks if the AI engine and model are ready to use.

Python: Recognition

Mon, 27 Jan 2025 00:00:00 +0000

Reading text from any content in Aspose.OCR for Python via .NET is as easy as calling a universal recognize() method.

This method takes OcrInput object and optional recognition settings.

Recognition results are returned as a OcrOutput object, that allow you to perform advanced manipulations with recognition results, including automatic spelling correction and saving results in various formats.

Example

The following code example shows how to extract text from multiple images:

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition batch
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source1.png")
input.add("source2.png")
# Set recognition language
recognitionSettings = RecognitionSettings()
recognitionSettings.language = Language.UKR;
# Recognize the image
results = api.recognize(input, recognitionSettings)
# Print recognition result
for result in results:
    print(result.recognition_text)

Python: Defect detection

Thu, 30 May 2024 00:00:00 +0000

Image defects can significantly impact the accuracy of OCR. They can be caused by the quality of the image acquisition process, environmental conditions, and the hardware used to capture the image. To improve recognition accuracy, it is essential to preprocess and enhance images to mitigate these defects whenever possible.

Aspose.OCR for Python via .NET can automatically find potentially problematic areas of image and return the information on the type of defect and its coordinates. The following types of defects can be found:

Defect	Enumeration	Description	Impact	How to mitigate
Salt-and-pepper noise	`DefectType.SALT_PEPPER_NOISE`	Appears as random white and black pixels scattered across the area. Often occurs in digital photographs.	Some characters are misidentified Unnecessary dots or commas appear in recognition results	Apply median filter Use automatic noise removal
Low contrast between text and background	`DefectType.LOW_CONTRAST`	Highlights and shadows typically appear on curved pages.	Low recognition accuracy Text not recognized (ignored by OCR engine)	Automatically adjust contrast Convert to grayscale Binarize with high threshold
Blur	`DefectType.BLUR`	The entire image or some of its areas are out of focus. Important: This detection algorithm can only identify the entire image as blurry. Specific areas cannot be detected.	Characters are not recognized correctly Text not recognized (ignored by OCR engine)	Use automatic contrast correction Convert image to grayscale
Glare	`DefectType.GLARE`	Highlight areas in an image caused by uneven lighting, such as spot lights or flash.	Low recognition accuracy Text not recognized (ignored by OCR engine)	Automatically adjust contrast Convert to grayscale Binarize with high threshold
All supported defects	`DefectType.ALL`	All above-mentioned defects.	See the corresponding defect for details.	See the corresponding defect for details.

You can highlight problem areas when previewing an image and even OCR them using alternative recognition settings to get a better result.

Detecting defects

To find defects on images, provide the collection of images and specify the type of defect to detect_defects() method.

The method returns DefectOutput object with the following properties:

Property	Description
`source`	The full path to the file or URL, if any.
`page`	The page number for multi-page images and PDFs.
`defect_areas`	The list of image defects and areas where they were found.

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Add image to the recognition batch
input = OcrInput(InputType.SINGLE_IMAGE)
input.add("source.png")
# Find shadows and highlights
defects = api.detect_defects(input, DefectType.LOW_CONTRAST)
print(det[0].source)
print(det[0].defect_areas[0].defect_type)

Live demo

Python: Specialized recognition methods

Fri, 13 Oct 2023 00:00:00 +0000

Aspose.OCR for Python via .NET offers fine-tuned OCR methods for extracting text from certain types of images:

Extracting text from ID cards
Automatically read text from scanned or photographed ID cards.
Extracting text from passports
Digitize scans or photos of passports.
Extracting text from vehicle license plates
Reading vehicle license plates without manual retyping.
Extracting text from invoices
Digitizing scanned invoices without manual retyping.
Extracting text from receipts
Digitizing scanned receipts without manual retyping.
Extracting text from street photos
Extracting text from street photos, price tags, menus, catalogs and other images with sparse text and noisy/colored backgrounds.

Python: Performance optimization

Fri, 15 Sep 2023 00:00:00 +0000

Aspose.OCR for Python via .NET allows for very flexible balancing of recognition speed, quality, and resource usage for each use case:

Fast recognition for simple and clear images, such as high-quality scans. About twice as fast as regular recognition.
Extracting text from images which contain a single line of text. About 7 times faster than normal OCR.
Limiting the number of threads used by the recognition engine.
Fine-tuning image processing filters.
Customizing recognition accuracy, performance, and other settings.

Python: Comparing text in images

Thu, 31 Aug 2023 00:00:00 +0000

Aspose.OCR for Python via .NET can compare texts on two images, regardless of the font, text size, case, styles, and colors.

To compare texts in 2 images, use image_text_diff() method of AsposeOcr class. This method allows you to optionally customize recognition accuracy, performance, and other settings.

image_text_diff() returns a number representing how similar the compared images are. The return value is a floating point number from 0 to 1; the lower the number, the more different image texts are. 0 means that the texts are completely different; 1 means the texts are identical. Fonts and styles are ignored.

The difference between image texts is calculated as the Levenshtein distance. Simply put, it is the minimum number of changes required to transform one string into another by inserting, deleting or replacing a single character.

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Configure recognition settings
recognitionSettings = RecognitionSettings()
recognitionSettings.auto_denoising = true
# Case-insensitive comparison of image texts
if api.compare_image_texts("image1.png", "image2.png", recognitionSettings, true):
    # Percentage of similarity between texts
    distance = api.image_text_diff("image1.png", "image2.png", recognitionSettings, true)
    print("The image texts are {:.2%} similar".format(distance))
else:
    print("Images contain the same text")

Python: Finding text in an image

Thu, 31 Aug 2023 00:00:00 +0000

Aspose.OCR for Python via .NET makes searching for text in images as easy as finding the text fragment in a string. In a single line of code, you can search for a case-sensitive or case-insensitive string, and even validate an image text against a pattern.

To search for a text in an image, use image_has_text() method of AsposeOcr class. The method either takes a text fragment or a regular expression and returns true if the text is found or false if not.

image_has_text() method allows you to optionally customize recognition accuracy, performance, and other settings.

# Instantiate Aspose.OCR API
api = AsposeOcr()
# Configure recognition settings
recognitionSettings = RecognitionSettings()
recognitionSettings.auto_denoising = true
# Detect text
if api.image_has_text("source.png", "Aspose", recognitionSettings):
    print("The image contains the word \"Aspose\"")
else:
    print("The image doesn't contain the word \"Aspose\"")

Python: Working with image regions

Sat, 26 Aug 2023 00:00:00 +0000

Aspose.OCR for Python via .NET allows you to find and read only certain areas of an image, not all text. This is very useful for batch processing uniform documents such as ID cards, visas, driver’s licenses, applications, and so on.

Python: Spell checker

Sat, 02 Sep 2023 00:00:00 +0000

Although Aspose.OCR for Python via .NET provides high recognition accuracy, printing defects, dirt, or non-standard fonts may cause certain characters or words to be recognized incorrectly. To further improve recognition results, you can turn on spell checker, which finds and automatically corrects spelling errors.

Python: Saving recognition results

Fri, 01 Sep 2023 00:00:00 +0000

Aspose.OCR for Python via .NET can save recognition results in multiple formats so they can be shared, stored in a database, displayed, or analyzed:

Python: Debug mode - Save processing results

Sun, 15 Jun 2025 00:00:00 +0000

Aspose.OCR for Python via .NET provides a Debug Mode that allows you to visually inspect how the input image is transformed during recognition.

When debug mode is enabled, the library saves intermediate processing results as image files:

The preprocessed image after filters (e.g., binarization, noise removal, resizing).
The image with highlighted text regions, where red rectangles mark detected text lines or blocks.

This feature is especially useful for troubleshooting recognition errors and fine-tuning preprocessing filters.

Property	Description
`set_debug_mode`	Enables or disables debug image saving.
`set_debug_mode_save_directory`	Sets the target folder where images will be saved. If not set, the current working directory is used.

Enabling debug mode

Debug mode is activated using two methods of the AsposeOCR class:

Enable debug mode


from aspose.ocr import *
    api = AsposeOcr()
    api.set_debug_mode_save_directory("C:/output/debug")
    api.set_debug_mode(True)
    #  Recognize image
    input = OcrInput(InputType.PDF)
    input.add(file, 2, 3)

    set = RecognitionSettings()
    result = api.recognize(input, set)

Output examples

When enabled, you will see image files like:

Preprocessed0.png – image after applying preprocessing filters
DetectedTextLines0.png – the same image with red rectangles drawn around detected text areas

Each image corresponds to the input from OcrInput.addImage(…) or its index.

Notes

Debug images do not affect recognition accuracy.
This feature works with both automatic and manual preprocessing.
If a temporary license is used, debug mode still functions as expected.

Python: Monitoring

Sat, 02 Sep 2023 00:00:00 +0000

Aspose.OCR for Python via .NET provides flexible ways to track the recognition process, check for non-fatal problems, and identify recognition errors.