OcrSettings

Settings for Ocr. Values fall back through three levels: document → SDK → built-in default. Writes target the document only when set on a document’s settings, otherwise the SDK globally when set on SdkSettings.

Tags: Vision, Advanced

from nutrient_sdk import OcrSettings

Construction

# Per-document override
with Document.open("input.pdf") as doc:
    settings = doc.settings.ocr_settings
    settings.some_field = new_value          # mutate fields directly

# SDK-wide default (applies to all documents)
SdkSettings.ocr_settings.some_field = new_value

Settings are configured by writing to fields on the returned object. The settings property itself cannot be reassigned — doc.settings.ocr_settings = other_settings is rejected.

Properties

default_languages

@property
def default_languages(self) -> str

@default_languages.setter
def default_languages(self, value: str) -> None

Default OCR languages to use (comma-separated language codes).

Type: str

Default: "eng"

detect_language_favor_accuracy

@property
def detect_language_favor_accuracy(self) -> bool

@detect_language_favor_accuracy.setter
def detect_language_favor_accuracy(self, value: bool) -> None

Indicates whether the automatic language-detection pass favors recognition accuracy over speed. The text this pass recognizes is never returned to the caller — it only feeds the language identifier, which reads word shape and character n-grams and tolerates per-character noise. Favoring accuracy therefore runs extra recognition passes refining glyph detail that nothing downstream reads. Enable it for the small share of pages whose language is identified from marginal text, at roughly a quarter more detection time. This is independent of FavorAccuracy, which governs the OCR whose text is returned.

Type: bool

Default: false

detect_language_once_per_document

@property
def detect_language_once_per_document(self) -> bool

@detect_language_once_per_document.setter
def detect_language_once_per_document(self, value: bool) -> None

Indicates whether automatic language detection (the "auto" OCR language) runs once for the whole document instead of once per page. When enabled, the first page that needs a language runs the detection and every other page of the same document reuses that result, so a document pays the detection cost once rather than once per page. Disable it to detect every page independently — what a document whose pages are in different languages needs — at the cost of a full page recognition pass per page.

Type: bool

Default: true

detect_language_page_fraction

@property
def detect_language_page_fraction(self) -> float

@detect_language_page_fraction.setter
def detect_language_page_fraction(self, value: float) -> None

The share of a page (0.0 to 1.0) the automatic language-detection pass reads text from — a centered band of the page, full width. Identifying a language needs a couple of paragraphs, while the pass otherwise recognizes the whole page, and recognition cost scales with the amount of text read. A band that yields too little text falls back to the whole page, so this trades a rare second read for a much cheaper common case. Orientation and script detection always read the whole page. Set to 0 to read text from the whole page.

Type: float

Default: 0.5

enable_orientation_detection

@property
def enable_orientation_detection(self) -> bool

@enable_orientation_detection.setter
def enable_orientation_detection(self, value: bool) -> None

Indicates whether the OCR engine detects and compensates page orientation (90°/180°/270°) during recognition. The recognized text layout carries the correction; the source image or page is not rotated.

Type: bool

Default: false

enable_preprocessing

@property
def enable_preprocessing(self) -> bool

@enable_preprocessing.setter
def enable_preprocessing(self, value: bool) -> None

Indicates whether to enable image preprocessing before OCR.

Type: bool

Default: true

enable_skew_detection

@property
def enable_skew_detection(self) -> bool

@enable_skew_detection.setter
def enable_skew_detection(self, value: bool) -> None

Indicates whether to enable automatic skew detection and correction.

Type: bool

Default: true

enable_table_detection

@property
def enable_table_detection(self) -> bool

@enable_table_detection.setter
def enable_table_detection(self, value: bool) -> None

Indicates whether to detect and extract tables from OCR output.

Type: bool

Default: true

favor_accuracy

@property
def favor_accuracy(self) -> bool

@favor_accuracy.setter
def favor_accuracy(self, value: bool) -> None

Indicates whether to favor accuracy over speed in OCR processing. When enabled, the recognizer runs additional passes (inverted-text detection and layout refinement) that improve results on difficult scans at the cost of processing time. Disable to favor speed, for example in high-volume batch OCR.

Type: bool

Default: true

max_languages

@property
def max_languages(self) -> int

@max_languages.setter
def max_languages(self, value: int) -> None

Maximum number of languages to report from offline language detection. The default, 1, reports only the dominant language (no language mixing). Raise it (e.g. 2) to detect multiple languages in one document, including two languages that share a script (such as English + French).

Type: int

Default: 1

max_scripts

@property
def max_scripts(self) -> int

@max_scripts.setter
def max_scripts(self, value: int) -> None

Maximum number of writing scripts to recognize on a page during offline language detection (and the “auto” OCR path). The default, 1, recognizes only the dominant script (no script mixing) — fastest, and the original behavior. Raise it (e.g. 2) to handle cross-script documents such as Cyrillic + Han, where the page is OCR’d with each detected script’s model.

Type: int

Default: 1

max_threads

@property
def max_threads(self) -> int

@max_threads.setter
def max_threads(self, value: int) -> None

The maximum number of pages processed concurrently when a document-level OCR operation (such as making a document searchable) runs over multiple pages. Set to 0 to use one thread per available processor. Values below 1 (other than 0) are treated as 1.

Type: int

Default: 1

min_language_vote_fraction

@property
def min_language_vote_fraction(self) -> float

@min_language_vote_fraction.setter
def min_language_vote_fraction(self, value: float) -> None

Consensus control for multi-language detection (only applies when MaxLanguages is greater than 1). A secondary language that is not present in the whole-page reading is reported only if the regions that detect it make up at least this fraction (0.0 to 1.0) of all regions. Works together with MinLanguageVotes to keep the extra language from being inferred from a negligible share of a long document.

Type: float

Default: 0.2

min_language_votes

@property
def min_language_votes(self) -> int

@min_language_votes.setter
def min_language_votes(self, value: int) -> None

Consensus control for multi-language detection (only applies when MaxLanguages is greater than 1). A secondary language that is not present in the whole-page reading is reported only if it is detected in at least this many text regions. Raising it improves precision — it suppresses a spurious extra language inferred from a single noisy region — at a small cost to recall of a genuine minority language that appears in only one region.

Type: int

Default: 2

min_script_ratio

@property
def min_script_ratio(self) -> float

@min_script_ratio.setter
def min_script_ratio(self, value: float) -> None

Minimum share of a page (0.0 to 1.0) a secondary writing script must occupy before the page is also read with that script’s model (only applies when MaxScripts is greater than 1). Raising it improves precision: it stops a faint, spurious script — often lookalike letters a second script’s model misreads from the dominant script — from being read at all, which is a common source of a wrongly reported extra language. The dominant script is always read.

Type: float

Default: 0.2