Show / Hide Table of Contents

# Class OCROptions

##### Inheritance

object
OptionsBase
OCROptions

##### Implements

IDisposable

##### Inherited Members

OptionsBase.mObjSet
OptionsBase.mDict
OptionsBase.ColorPtToNumber(ColorPt)
OptionsBase.ColorPtFromNumber(double)
OptionsBase.GetArray(string)
OptionsBase.PutNumber(string, double)
OptionsBase.PutBool(string, bool)
OptionsBase.PutText(string, string)
OptionsBase.PutRect(string, Rect)
OptionsBase.PushBackNumber(string, double)
OptionsBase.PushBackBool(string, bool)
OptionsBase.PushBackText(string, string)
OptionsBase.PushBackRect(string, Rect)
OptionsBase.RectFromArray(Obj)
OptionsBase.insertRectCollection(string, RectCollection, int)
OptionsBase.GetInternalObj()
OptionsBase.Dispose()
OptionsBase.Dispose(bool)
OptionsBase.Destroy()
object.Equals(object)
object.Equals(object, object)
object.GetHashCode()
object.GetType()
object.MemberwiseClone()
object.ReferenceEquals(object, object)
object.ToString()

###### Namespace: pdftron.PDF

###### Assembly: PDFTronDotNet.dll

##### Syntax

    public class OCROptions : OptionsBase, IDisposable

### Constructors

#### OCROptions()

Constructor.

##### Declaration

    public OCROptions()

### Methods

#### AddDPI(int)

Sets the value for DPI in the options object.

Knowing proper image resolution is important, as it enables the OCR engine to translate pixel heights of characters to their respective font sizes.

We do our best to retrieve resolution information from the input's metadata, however it occasionally can be corrupt or missing. Hence we allow manual override of source's resolution, which supersedes any metadata found (both explicit as in image metadata and implicit as in PDF).

If input is a PDF file, the SDK will render PDF page for OCR as a raster image with 300 DPI resolution. Otherwise, if input is an image, SDK will pass to OCR raster image in original resolution. Exceptionally, if the user, by using this method, suggests the resolution (say 300 DPI), the SDK will try do as suggested.

Here, some restrictions apply:

- New image size in pixels (Width X Height) cannot exceed 75 MP (Mega Pixels)
- Each image side (Width or Height), in pixels, cannot exceed 16 bits (65,535)

To achieve that, SDK will iteratively scale down the DPI till both conditions are met.

##### Declaration

    public OCROptions AddDPI(int dpi)

##### Parameters

Type | Name | Description
--- | --- | ---
int | dpi | The new value for DPI.

##### Returns

Type | Description
--- | ---
OCROptions | This object, for call chaining.

#### AddIgnoreZonesForPage(RectCollection, int)

Adds a zones to the IgnoreZones array.

It is an optional list of areas that will be excluded from analysis.

The meaning and handling of the passed region coordinates will vary depending on:

- Whether input is PDF (rather than an image), and
- Whether SetUsePDFPageCoords() is called with value true.

If either of above is true, then the region coordinates have to be given in PDF Points and coodinate space origin at bottom-left.

Otherwise:

- The input is a raster image,
- The coordinates has to be given in pixel units and with coordinate space origin at top-left

See also: ProcessPDF() ImageToPDF() SetUsePDFPageCoords() AddTextZonesForPage().

##### Declaration

    public OCROptions AddIgnoreZonesForPage(RectCollection regions, int pageNum)

##### Parameters

Type | Name | Description
--- | --- | ---
RectCollection | regions | The new zones to add to IgnoreZonesForPage.
int | pageNum | The page number the added regions belong to

##### Returns

Type | Description
--- | ---
OCROptions | This object, for call chaining.

#### AddLang(string)

Adds a language to the Langs array.

OCR engine is prepared for recognition of a predefined set of language scripts. Various scripts have differences in glyphs and it is recommended that OCR engine is instructed to use a correct glyph set to match the appropriate Unicode. At this moment, there are two avaliable engines for use. Let we refer them by their executable names: OCRModule and OCRModuleIRIS.

Here is a list of supported languages by their codes that may be passed as a parameter. One language per call to AddLang(). Use multiple calls to AddLang() to add additional languages.

Warning: Be aware that adding too many language codes at once may lead to wrong altertnatives regarding Latin characters with accents.

Language | Code | Language | Code
--- | --- | --- | ---
English | eng | Chinese Simpl. | chi_sim
French | fra | Chinese Trad. | chi_tra
German | deu | Japanese | jpn
Italian | ita | Korean | kor
Russian | rus |  |
Spanish | spa |  |

Here are the languages supported out of the box per engine:

Executable Name | Supported Codes
--- | ---
OCRModule | eng fra deu ita spa rus
OCRModuleIRIS | eng fra deu ita spa rus chi_sim chi_tra jpn kor

Note: OCRModuleIRIS allows mix of a single Asian language and just English.

##### Declaration

    public OCROptions AddLang(string lang)

##### Parameters

Type | Name | Description
--- | --- | ---
string | lang | The new language to add to Langs.

##### Returns

Type | Description
--- | ---
OCROptions | This object, for call chaining.

#### AddTextZonesForPage(RectCollection, int)

Adds a zones to the TextZones array.

It is as an optional list of known text zones that will be used to improve OCR quality.

See also: AddIgnoreZonesForPage().

##### Declaration

    public OCROptions AddTextZonesForPage(RectCollection regions, int pageNum)

##### Parameters

Type | Name | Description
--- | --- | ---
RectCollection | regions | The new zones to add to TextZonesForPage.
int | pageNum | The page number the added regions belong to.

##### Returns

Type | Description
--- | ---
OCROptions | This object, for call chaining.

#### GetAutoRotate()

Gets the value AutoRotate from the options object.

Default value is false. Setting to true will deskew the image before conducting OCR.

Note: This function doesn't apply to IRIS OCR module.

##### Declaration

    public bool GetAutoRotate()

##### Returns

Type | Description
--- | ---
bool | The current value for AutoRotate.

#### GetDPI()

Gets the value DPI from the options object.

Knowing proper image resolution is important, as it enables the OCR engine to translate pixel heights of characters to their respective font sizes.

We do our best to retrieve resolution information from the input's metadata, however it occasionally can be corrupt or missing. Hence we allow manual override of source's resolution, which supersedes any metadata found (both explicit as in image metadata and implicit as in PDF).

If input is a PDF file, the SDK will render PDF page for OCR as a raster image with 300 DPI resolution. Otherwise, if input is an image, SDK will pass to OCR raster image in original resolution. Exceptionally, if the user, by using this method, suggests the resolution (say 300 DPI), the SDK will try do as suggested.

Here, some restrictions apply:

- New image size in pixels (Width X Height) cannot exceed 75 MP (Mega Pixels)
- Each image side (Width or Height), in pixels, cannot exceed 16 bits (65,535)

To achieve that, SDK will iteratively scale down the DPI till both conditions are met.

##### Declaration

    public int GetDPI()

##### Returns

Type | Description
--- | ---
int | The current value for DPI.

#### GetIgnoreExistingText()

Gets the value IgnoreExistingText from the options object.

Default value is false, so that areas with existing text will be automatically skipped during OCR. Setting to true will cause a pre-existing text to be duplicated with the OCR-ed ones in the PDF document or in GetOCRJsonFromPDF() and GetOCRXmlFromPDF() results.

Deprecated! Use GetIncludeExistingText instead.

##### Declaration

    public bool GetIgnoreExistingText()

##### Returns

Type | Description
--- | ---
bool | The current value for IgnoreExistingText.

#### GetIncludeExistingText()

Gets the value IncludeExistingText from the options object.

Default value is false, so that areas with existing text will be automatically skipped during OCR. Setting to true will cause a pre-existing text to be duplicated with the OCR-ed ones in the PDF document or in GetOCRJsonFromPDF() and GetOCRXmlFromPDF() results.

##### Declaration

    public bool GetIncludeExistingText()

##### Returns

Type | Description
--- | ---
bool | The current value for IncludeExistingText.

#### GetOCREngine()

Gets the value OCREngine from the options object.

Options include 'default' or 'iris'. Chosen module must be present and correctly licensed.

##### Declaration

    public string GetOCREngine()

##### Returns

Type | Description
--- | ---
string | The current value for OCREngine.

#### GetUsePDFPageCoords()

Gets the value UsePDFPageCoords from the options object.

Defines the coordinate system, scaling and units. SDK and OCRModule will refer to this setting while dealing with potential input zone rectangle(s) (ignorable or text) and with the output result as well. The default value is false which corresponds to raster image input.

Here are the meanings for value:

Value | Origin | +Y axis dir. | Unit | Size | Expected input
--- | --- | --- | --- | --- | ---
false | top-left | Downwards | Pixel | 1/DPI inches | Image
true | bottom-left | Upwards | Point | 1/72 inches | PDF

Note that, OCRModule backend has no notion about the SDK's real input. So, if not explicitelly instructed via this call and value, it will work by default and will report the coordinates as for false. This is important to know for cases when the call for OCR service comes from GetOCRJsonFromPDF() or GetOCRXmlFromPDF() where the results should be correct in JSON or XML format - and removes the need for user to do additional adjustments.

See also: AddIgnoreZonesForPage() AddTextZonesForPage() AddDPI() GetOCRJsonFromImage() GetOCRXmlFromImage().

##### Declaration

    public bool GetUsePDFPageCoords()

##### Returns

Type | Description
--- | ---
bool | The current value for UsePDFPageCoords.

#### SetAutoRotate(bool)

Sets the value for AutoRotate in the options object.

Default value is false. Setting to true will deskew the image before conducting OCR.

Note: This function doesn't apply to IRIS OCR module.

##### Declaration

    public OCROptions SetAutoRotate(bool value)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | value | The new value for AutoRotate.

##### Returns

Type | Description
--- | ---
OCROptions | This object, for call chaining.

#### SetIgnoreExistingText(bool)

Sets the value for IgnoreExistingText in the options object.

Default value is false, so that areas with existing text will be automatically skipped during OCR. Setting to true will cause a pre-existing text to be duplicated with the OCR-ed ones in the PDF document or in GetOCRJsonFromPDF() and GetOCRXmlFromPDF() results.

Deprecated! Use SetIncludeExistingText instead.

##### Declaration

    public OCROptions SetIgnoreExistingText(bool value)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | value | The new value for IgnoreExistingText.

##### Returns

Type | Description
--- | ---
OCROptions | This object, for call chaining.

#### SetIncludeExistingText(bool)

Sets the value for IncludeExistingText in the options object.

Default value is false, so that areas with existing text will be automatically skipped during OCR. Setting to true will cause a pre-existing text to be duplicated with the OCR-ed ones in the PDF document or in GetOCRJsonFromPDF() and GetOCRXmlFromPDF() results.

##### Declaration

    public OCROptions SetIncludeExistingText(bool value)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | value | The new value for IncludeExistingText.

##### Returns

Type | Description
--- | ---
OCROptions | This object, for call chaining.

#### SetOCREngine(string)

Sets the value for OCREngine in the options object.

Options include 'default' or 'iris'. Chosen module must be present and correctly licensed.

##### Declaration

    public OCROptions SetOCREngine(string value)

##### Parameters

Type | Name | Description
--- | --- | ---
string | value | The new value for OCREngine.

##### Returns

Type | Description
--- | ---
OCROptions | This object, for call chaining.

#### SetUsePDFPageCoords(bool)

Sets the value for UsePDFPageCoords in the options object.

Defines the coordinate system, scaling and units. SDK and OCRModule will refer to this setting while dealing with potential input zone rectangle(s) (ignorable or text) and with the output result as well. The default value is false which corresponds to raster image input.

Here are the meanings for value:

Value | Origin | +Y axis dir. | Unit | Size | Expected input
--- | --- | --- | --- | --- | ---
false | top-left | Downwards | Pixel | 1/DPI inches | Image
true | bottom-left | Upwards | Point | 1/72 inches | PDF

Note that, OCRModule backend has no notion about the SDK's real input. So, if not explicitelly instructed via this call and value, it will work by default and will report the coordinates as for false. This is important to know for cases when the call for OCR service comes from GetOCRJsonFromPDF() or GetOCRXmlFromPDF() where the results should be correct in JSON or XML format - and removes the need for user to do additional adjustments.

See also: AddIgnoreZonesForPage() AddTextZonesForPage() AddDPI() GetOCRJsonFromImage() GetOCRXmlFromImage().

##### Declaration

    public OCROptions SetUsePDFPageCoords(bool value)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | value | The new value for UsePDFPageCoords.

##### Returns

Type | Description
--- | ---
OCROptions | This object, for call chaining.

### Implements

IDisposable