OCR Options Reference

Typed option dataclasses from natural_pdf/ocr/ocr_options.py. Pass an instance via page.apply_ocr(engine="...", options=...). Subclass tables list only the fields each class adds; every class also accepts the shared BaseOCROptions fields.

BaseOCROptions (shared)

Base class for OCR engine options.

Fields shared by every engine’s options class. extra_args is passed through to the underlying engine.

Option	Type	Default	Description
extra_args	Dict[str, Any]	{}

ChandraOCROptions

Specific options for the Chandra OCR engine (VLM-based document OCR). Install: pip install chandra-ocr[hf]

Used by engine(s): chandra2.

Option	Type	Default	Description
method	str	'hf'	Inference backend: "hf" for local HuggingFace, "vllm" for remote vLLM server.
vllm_url	Optional[str]	None	URL for the vLLM server when method="vllm".
max_output_tokens	int	12384	Maximum number of tokens to generate per page.

DoctrOCROptions

Specific options for the doctr engine.

Used by engine(s): doctr.

Option	Type	Default	Description
det_arch	str	'db_resnet50'
reco_arch	str	'crnn_vgg16_bn'
pretrained	bool	True
assume_straight_pages	bool	True	Faster if pages are straight
export_as_straight_boxes	bool	False	Output straight boxes even if rotated text is detected
symmetric_pad	bool	True
preserve_aspect_ratio	bool	True
batch_size	int	1
bin_thresh	Optional[float]	None	Default is usually 0.3
box_thresh	Optional[float]	None	Default is usually 0.1
use_orientation_predictor	bool	False	Whether to use page orientation predictor

EasyOCROptions

Specific options for the EasyOCR engine.

Used by engine(s): easyocr.

Option	Type	Default	Description
model_storage_directory	Optional[str]	None
user_network_directory	Optional[str]	None
recog_network	str	'english_g2'
detect_network	str	'craft'
download_enabled	bool	True
detector	bool	True
recognizer	bool	True
verbose	bool	True
quantize	bool	True
cudnn_benchmark	bool	False
detail	int	1
decoder	str	'greedy'
beamWidth	int	5
batch_size	int	1
workers	int	0
allowlist	Optional[str]	None
blocklist	Optional[str]	None
paragraph	bool	False
min_size	int	10
contrast_ths	float	0.1
adjust_contrast	float	0.5
filter_ths	float	0.0
text_threshold	float	0.7
low_text	float	0.4
link_threshold	float	0.4
canvas_size	int	2560
mag_ratio	float	1.0
slope_ths	float	0.1
ycenter_ths	float	0.5
height_ths	float	0.5
width_ths	float	0.5
y_ths	float	0.5
x_ths	float	1.0
add_margin	float	0.1
output_format	str	'standard'

PaddleOCROptions

Specific options for the PaddleOCR engine, reflecting the paddleocr>=3.0.0 API. See: https://paddlepaddle.github.io/PaddleOCR/latest/en/version3.x/pipeline_usage/OCR.html

Used by engine(s): paddle.

Option	Type	Default	Description
doc_orientation_classify_model_name	Optional[str]	None
doc_orientation_classify_model_dir	Optional[str]	None
doc_unwarping_model_name	Optional[str]	None
doc_unwarping_model_dir	Optional[str]	None
text_detection_model_name	Optional[str]	None
text_detection_model_dir	Optional[str]	None
textline_orientation_model_name	Optional[str]	None
textline_orientation_model_dir	Optional[str]	None
text_recognition_model_name	Optional[str]	None
text_recognition_model_dir	Optional[str]	None
use_doc_orientation_classify	Optional[bool]	False
use_doc_unwarping	Optional[bool]	False
use_textline_orientation	Optional[bool]	False
textline_orientation_batch_size	Optional[int]	None
text_recognition_batch_size	Optional[int]	None
text_det_limit_side_len	Optional[int]	736	WAITING FOR FIX
text_det_limit_type	Optional[str]	'max'	WAITING FOR FIX
text_det_thresh	Optional[float]	None
text_det_box_thresh	Optional[float]	None
text_det_unclip_ratio	Optional[float]	None
text_det_input_shape	Optional[Tuple[int, int]]	None
text_rec_score_thresh	Optional[float]	None
text_rec_input_shape	Optional[Tuple[int, int, int]]	None
lang	Optional[str]	None
ocr_version	Optional[str]	None
device	Optional[str]	None
enable_hpi	Optional[bool]	None
use_tensorrt	Optional[bool]	None
precision	Optional[str]	None
enable_mkldnn	Optional[bool]	False	https://github.com/PaddlePaddle/PaddleOCR/issues/15294
cpu_threads	Optional[int]	None
paddlex_config	Optional[str]	None

PaddleOCRVLOptions

Specific options for the PaddleOCR-VL engine (VLM-based document understanding). See: https://paddlepaddle.github.io/PaddleOCR/latest/en/version3.x/pipeline_usage/PP-ChatOCRv4.html

Used by engine(s): paddlevl.

Option	Type	Default	Description
pipeline_version	Optional[str]	None
use_layout_detection	Optional[bool]	None
use_chart_recognition	Optional[bool]	None
use_seal_recognition	Optional[bool]	None
use_doc_orientation_classify	Optional[bool]	None
use_doc_unwarping	Optional[bool]	None
format_block_content	Optional[bool]	None
max_new_tokens	Optional[int]	None
temperature	Optional[float]	None
top_p	Optional[float]	None
repetition_penalty	Optional[float]	None

RapidOCROptions

Specific options for the RapidOCR engine. RapidOCR uses PaddleOCR models converted to ONNX format, providing the same accuracy with simpler installation (~15MB vs ~500MB).

Used by engine(s): rapidocr.

Option	Type	Default	Description
det_model_type	str	'mobile'	“mobile” or “server”
rec_model_type	str	'mobile'	“mobile” or “server”
config_path	Optional[str]	None	Path to custom config.yaml
use_det	bool	True
use_cls	bool	True
use_rec	bool	True
return_word_box	bool	False	Split lines into individual word boxes
return_single_char_box	bool	False	Return per-character boxes
text_score	Optional[float]	None	Text confidence filter (default 0.5)
box_thresh	Optional[float]	None	Detection box threshold (default 0.5)
unclip_ratio	Optional[float]	None	Box expansion ratio (default 1.6)

SuryaOCROptions

Specific options for the Surya OCR engine.

Used by engine(s): surya.

Option	Type	Default	Description
strip_math	bool	True	Remove <math>…</math> tags and their content from OCR output. HTML formatting tags (<b>, etc.) are always stripped.

Engines without a typed options class

chandra, dots, glm_ocr, vlm — configure these through apply_ocr() keyword arguments (e.g. model=) instead of an options dataclass.