API Reference

This section provides detailed documentation for all the classes and methods in Natural PDF.

Core Classes

natural_pdf

Natural PDF - A more intuitive interface for working with PDFs.

Classes

natural_pdf.ClassificationError

Error during classification operations.

Raised when: - Classification model loading fails - Classification inference fails - Invalid classification configuration

natural_pdf.ConfigSection

A configuration section that holds key-value option pairs.

natural_pdf.ConfigurationError

Error in configuration or options.

Raised when: - Invalid option values provided - Required configuration missing - Incompatible options combination

natural_pdf.ExportError

Error during export operations.

Raised when: - Export format not supported - Export writing fails - Required data missing for export

natural_pdf.Flow

Defines a logical flow or sequence of physical Page or Region objects.

A Flow represents a continuous logical document structure that spans across multiple pages or regions, enabling operations on content that flows across boundaries. This is essential for handling multi-page tables, articles that span columns, or any content that requires reading order across segments.

Flows specify arrangement (vertical/horizontal) and alignment rules to create a unified coordinate system for element extraction and text processing. They enable natural-pdf to treat fragmented content as a single continuous area for analysis and extraction operations.

The Flow system is particularly useful for: - Multi-page tables that break across page boundaries - Multi-column articles with complex reading order - Forms that span multiple pages - Any content requiring logical continuation across segments

Attributes:

Name	Type	Description
segments	List[Region]	List of Page or Region objects in flow order.
arrangement	Literal['vertical', 'horizontal']	Primary flow direction ('vertical' or 'horizontal').
alignment	Literal['start', 'center', 'end', 'top', 'left', 'bottom', 'right']	Cross-axis alignment for segments of different sizes.
segment_gap	float	Virtual gap between segments in PDF points.

Example

Multi-page table flow:

pdf = npdf.PDF("multi_page_table.pdf")

# Create flow for table spanning pages 2-4
table_flow = Flow(
    segments=[pdf.pages[1], pdf.pages[2], pdf.pages[3]],
    arrangement='vertical',
    alignment='left',
    segment_gap=10.0
)

# Extract table as if it were continuous
table_data = table_flow.extract_table()
text_content = table_flow.extract_text()

Multi-column article flow:

page = pdf.pages[0]
left_column = page.region(0, 0, 300, page.height)
right_column = page.region(320, 0, page.width, page.height)

# Create horizontal flow for columns
article_flow = Flow(
    segments=[left_column, right_column],
    arrangement='horizontal',
    alignment='top'
)

# Read in proper order
article_text = article_flow.extract_text()

Note

Flows create virtual coordinate systems that map element positions across segments, enabling spatial navigation and element selection to work seamlessly across boundaries.

Functions

natural_pdf.Flow.__init__(segments, arrangement, alignment='start', segment_gap=0.0)

Initializes a Flow object.

Parameters:

Name	Type	Description	Default
segments	Union[Sequence[SupportsSections], PageCollection]	An ordered sequence of objects implementing SupportsSections (e.g., Page, Region) that constitute the flow, or a PageCollection containing pages.	required
arrangement	Literal['vertical', 'horizontal']	The primary direction of the flow. - "vertical": Segments are stacked top-to-bottom. - "horizontal": Segments are arranged left-to-right.	required
alignment	Literal['start', 'center', 'end', 'top', 'left', 'bottom', 'right']	How segments are aligned on their cross-axis if they have differing dimensions. For a "vertical" arrangement: - "left" (or "start"): Align left edges. - "center": Align centers. - "right" (or "end"): Align right edges. For a "horizontal" arrangement: - "top" (or "start"): Align top edges. - "center": Align centers. - "bottom" (or "end"): Align bottom edges.	'start'
segment_gap	float	The virtual gap (in PDF points) between segments.	0.0

natural_pdf.Flow.apply_ocr(engine=None, *, options=None, languages=None, min_confidence=None, device=None, resolution=None, detect_only=False, apply_exclusions=True, replace=True, model=None, client=None, instructions=None, **kwargs)

Apply OCR across every segment in the flow.

Parameters:

Name	Type	Description	Default
engine	Optional[str]	OCR engine — "easyocr", "surya", "paddle", "paddlevl", "doctr", or "vlm".	None
options	Optional[Any]	Engine-specific option object.	None
languages	Optional[List[str]]	Language codes, e.g. ["en", "fr"].	None
min_confidence	Optional[float]	Discard results below this confidence (0–1).	None
device	Optional[str]	Compute device, e.g. "cpu" or "cuda".	None
resolution	Optional[int]	DPI for the image sent to the engine.	None
detect_only	bool	Detect text regions without recognizing characters.	False
apply_exclusions	bool	Mask exclusion zones before OCR.	True
replace	bool	Remove existing OCR elements first.	True
model	Optional[str]	VLM model name — switches to VLM OCR pipeline.	None
client	Optional[Any]	OpenAI-compatible client — switches to VLM OCR pipeline.	None
instructions	Optional[str]	Additional instructions appended to the VLM prompt.	None
**kwargs	Any	Extra engine-specific parameters.	{}

Returns:

Type	Description
Flow	Self for chaining.

natural_pdf.Flow.clear_text_layer()

Clear the underlying text layers (words/chars) for every segment page.

natural_pdf.Flow.create_text_elements_from_ocr(ocr_results, scale_x=None, scale_y=None, *, offset_x=0.0, offset_y=0.0)

Utility for constructing text elements from OCR output.

natural_pdf.Flow.extract_ocr_elements(*args, **kwargs)

Extract OCR-derived text elements from all segments.

natural_pdf.Flow.extract_table(*args, **kwargs)

Extract table from the flow, delegating to the analysis region.

natural_pdf.Flow.extract_tables(*args, **kwargs)

Extract tables from the flow, delegating to the analysis region.

natural_pdf.Flow.extract_text(**kwargs)

Extract text from the flow, concatenating text from all segments.

natural_pdf.Flow.get_sections(start_elements=None, end_elements=None, new_section_on_page_break=False, include_boundaries='both', orientation='vertical')

Extract logical sections from the Flow based on start and end boundary elements, mirroring the behaviour of PDF/PageCollection.get_sections().

This implementation is a thin wrapper that converts the Flow into a temporary PageCollection (constructed from the unique pages that the Flow spans) and then delegates the heavy‐lifting to that existing implementation. Any FlowElement / FlowElementCollection inputs are automatically unwrapped to their underlying physical elements so that PageCollection can work with them directly.

Parameters:

Name	Type	Description	Default
start_elements		Elements or selector string that mark the start of sections (optional).	None
end_elements		Elements or selector string that mark the end of sections (optional).	None
new_section_on_page_break	bool	Whether to start a new section at page boundaries (default: False).	False
include_boundaries	str	How to include boundary elements: 'start', 'end', 'both', or 'none' (default: 'both').	'both'
orientation	str	'vertical' (default) or 'horizontal' - determines section direction.	'vertical'

Returns:

Type	Description
ElementCollection	ElementCollection of Region/FlowRegion objects representing the
ElementCollection	extracted sections.

natural_pdf.Flow.highlights(show=False)

Create a highlight context for accumulating highlights.

This allows for clean syntax to show multiple highlight groups:

Example

with flow.highlights() as h: h.add(flow.find_all('table'), label='tables', color='blue') h.add(flow.find_all('text:bold'), label='bold text', color='red') h.show()

Or with automatic display

with flow.highlights(show=True) as h: h.add(flow.find_all('table'), label='tables') h.add(flow.find_all('text:bold'), label='bold') # Automatically shows when exiting the context

Parameters:

Name	Type	Description	Default
show	bool	If True, automatically show highlights when exiting context	False

Returns:

Type	Description
	HighlightContext for accumulating highlights

natural_pdf.Flow.remove_ocr_elements()

Remove OCR elements that were previously added to constituent pages.

natural_pdf.Flow.show(*, resolution=None, width=None, color=None, labels=True, label_format=None, highlights=None, legend_position='right', annotate=None, layout=None, stack_direction=None, gap=5, columns=6, crop=False, crop_bbox=None, in_context=None, separator_color=None, separator_thickness=2, **kwargs)

Generate a preview image with highlights.

By default, Flow.show stacks multiple segments in the order of the flow arrangement so you can see them as a single continuous surface. Set in_context=False to revert to the traditional page-highlighting behavior. You can also pass in_context=True explicitly to force the stacked visualization.

Parameters:

Name	Type	Description	Default
resolution	Optional[float]	DPI for rendering (default from global settings)	None
width	Optional[int]	Target width in pixels (overrides resolution)	None
color	Optional[Union[str, Tuple[int, int, int]]]	Default highlight color	None
labels	bool	Whether to show labels for highlights	True
label_format	Optional[str]	Format string for labels	None
highlights	Optional[Union[List[Dict[str, Any]], bool]]	Additional highlight groups to show	None
layout	Optional[Literal['stack', 'grid', 'single']]	How to arrange multiple pages/regions	None
stack_direction	Optional[Literal['vertical', 'horizontal']]	Direction for stack layout	None
gap	int	Pixels between stacked images	5
columns	Optional[int]	Number of columns for grid layout	6
crop	Union[bool, int, str, Region, Literal['wide']]	Whether to crop	False
crop_bbox	Optional[Tuple[float, float, float, float]]	Explicit crop bounds	None
in_context	Optional[bool]	If True, use special Flow visualization with separators	None
separator_color	Optional[Tuple[int, int, int]]	RGB color for separator lines (default: red)	None
separator_thickness	int	Thickness of separator lines	2
**kwargs		Additional parameters passed to rendering	{}

Returns:

Type	Description
Optional[Image]	PIL Image object or None if nothing to render

natural_pdf.FlowRegion

Represents a selected area within a Flow, potentially composed of multiple physical Region objects (constituent_regions) that might span across different original pages or disjoint physical regions defined in the Flow.

A FlowRegion is the result of a directional operation (e.g., .below(), .above()) on a FlowElement.

Attributes

natural_pdf.FlowRegion.bbox property

The bounding box that encloses all constituent regions.

For single-page FlowRegions this is a true geometric union. For multi-page FlowRegions the result is a merge_bboxes over all constituent regions regardless of page — useful for sorting and size estimates, but not a physically meaningful rectangle.

Returns None only when there are no constituent regions.

natural_pdf.FlowRegion.is_empty property

True when this FlowRegion contains no constituent regions.

natural_pdf.FlowRegion.normalized_type property

Return the normalized type for selector compatibility. This allows FlowRegion to be found by selectors like 'table'.

natural_pdf.FlowRegion.page property

Return the primary page for this region (first page when multi-page).

natural_pdf.FlowRegion.pages property

Return the distinct pages covered by this flow region.

natural_pdf.FlowRegion.parts property

Alias for constituent_regions — the physical region parts of this FlowRegion.

natural_pdf.FlowRegion.type property

Return the type attribute for selector compatibility. This is an alias for normalized_type.

Functions

natural_pdf.FlowRegion.__init__(flow, constituent_regions, source_flow_element=None, boundary_element_found=None)

Initializes a FlowRegion.

Parameters:

Name	Type	Description	Default
flow	'Flow'	The Flow instance this region belongs to.	required
constituent_regions	List['PhysicalRegion']	A list of physical natural_pdf.elements.region.Region objects that make up this FlowRegion.	required
source_flow_element	Optional['FlowElement']	The FlowElement that created this FlowRegion.	None
boundary_element_found	Optional[Union['PhysicalElement', 'PhysicalRegion']]	The physical element that stopped an 'until' search, if applicable.	None

natural_pdf.FlowRegion.apply_ocr(engine=None, *, options=None, languages=None, min_confidence=None, device=None, resolution=None, detect_only=False, apply_exclusions=True, replace=True, model=None, client=None, instructions=None, **kwargs)

Apply OCR across all constituent regions.

Parameters:

Name	Type	Description	Default
engine	Optional[str]	OCR engine — "easyocr", "surya", "paddle", "paddlevl", "doctr", or "vlm".	None
options	Optional[Any]	Engine-specific option object.	None
languages	Optional[List[str]]	Language codes, e.g. ["en", "fr"].	None
min_confidence	Optional[float]	Discard results below this confidence (0–1).	None
device	Optional[str]	Compute device, e.g. "cpu" or "cuda".	None
resolution	Optional[int]	DPI for the image sent to the engine.	None
detect_only	bool	Detect text regions without recognizing characters.	False
apply_exclusions	bool	Mask exclusion zones before OCR.	True
replace	bool	Remove existing OCR elements first.	True
model	Optional[str]	VLM model name — switches to VLM OCR pipeline.	None
client	Optional[Any]	OpenAI-compatible client — switches to VLM OCR pipeline.	None
instructions	Optional[str]	Additional instructions appended to the VLM prompt.	None
**kwargs	Any	Extra engine-specific parameters.	{}

Returns:

Type	Description
'FlowRegion'	Self for chaining.

natural_pdf.FlowRegion.elements(apply_exclusions=True)

Collects all unique physical elements from all constituent physical regions.

Parameters:

Name	Type	Description	Default
apply_exclusions	bool	Whether to respect PDF exclusion zones within each constituent physical region when gathering elements.	True

Returns:

Type	Description
'ElementCollection'	An ElementCollection containing all unique elements.

natural_pdf.FlowRegion.expand(amount=None, *, left=0, right=0, top=0, bottom=0, width_factor=1.0, height_factor=1.0, apply_exclusions=True)

expand(amount: float, *, apply_exclusions: bool = True) -> 'FlowRegion'

expand(*, left: Union[float, bool, str] = 0, right: Union[float, bool, str] = 0, top: Union[float, bool, str] = 0, bottom: Union[float, bool, str] = 0, width_factor: float = 1.0, height_factor: float = 1.0, apply_exclusions: bool = True) -> 'FlowRegion'

Create a new FlowRegion with all constituent regions expanded.

Parameters:

Name	Type	Description	Default
left	Union[float, bool, str]	Amount to expand left edge (positive value expands leftwards)	0
right	Union[float, bool, str]	Amount to expand right edge (positive value expands rightwards)	0
top	Union[float, bool, str]	Amount to expand top edge (positive value expands upwards)	0
bottom	Union[float, bool, str]	Amount to expand bottom edge (positive value expands downwards)	0
width_factor	float	Factor to multiply width by (applied after absolute expansion)	1.0
height_factor	float	Factor to multiply height by (applied after absolute expansion)	1.0

Returns:

Type	Description
'FlowRegion'	New FlowRegion with expanded constituent regions

natural_pdf.FlowRegion.extract_ocr_elements(*args, **kwargs)

Extract OCR elements from each constituent region and flatten the results.

natural_pdf.FlowRegion.extract_text(apply_exclusions=True, **kwargs)

Concatenate text from constituent regions while preserving flow order.

natural_pdf.FlowRegion.get_highlight_specs()

Get highlight specifications for all constituent regions.

This implements the highlighting protocol for FlowRegions, returning specs for each constituent region so they can be highlighted on their respective pages.

Returns:

Type	Description
List[Dict[str, Any]]	List of highlight specification dictionaries, one for each
List[Dict[str, Any]]	constituent region.

natural_pdf.FlowRegion.get_highlighter()

Resolve a highlighting service from the constituent regions.

natural_pdf.FlowRegion.get_sections(start_elements=None, end_elements=None, new_section_on_page_break=False, include_boundaries='both', orientation='vertical', **kwargs)

Extract logical sections from this FlowRegion based on start/end boundary elements.

This delegates to the parent Flow's get_sections() method, but only operates on the segments that are part of this FlowRegion.

Parameters:

Name	Type	Description	Default
start_elements		Elements or selector string that mark the start of sections	None
end_elements		Elements or selector string that mark the end of sections	None
new_section_on_page_break	bool	Whether to start a new section at page boundaries	False
include_boundaries	str	How to include boundary elements: 'start', 'end', 'both', or 'none'	'both'
orientation	str	'vertical' (default) or 'horizontal' - determines section direction	'vertical'

Returns:

Type	Description
'ElementCollection'	ElementCollection of FlowRegion objects representing the extracted sections

Example

Split a multi-page table region by headers

table_region = flow.find("text:contains('Table 4')").below(until="text:contains('Table 5')") sections = table_region.get_sections(start_elements="text:bold")

natural_pdf.FlowRegion.highlight(label=None, color=None, **kwargs)

Highlights all constituent physical regions on their respective pages.

Parameters:

Name	Type	Description	Default
label	Optional[str]	A base label for the highlights. Each constituent region might get an indexed label.	None
color	Optional[Union[Tuple, str]]	Color for the highlight.	None
**kwargs		Additional arguments for the underlying highlight method.	{}

Returns:

Type	Description
Optional['PIL_Image']	Image generated by the underlying highlight call, or None if no highlights were added.

natural_pdf.FlowRegion.highlights(show=False)

Create a highlight context for accumulating highlights.

This allows for clean syntax to show multiple highlight groups:

Example

with flow_region.highlights() as h: h.add(flow_region.find_all('table'), label='tables', color='blue') h.add(flow_region.find_all('text:bold'), label='bold text', color='red') h.show()

Or with automatic display

with flow_region.highlights(show=True) as h: h.add(flow_region.find_all('table'), label='tables') h.add(flow_region.find_all('text:bold'), label='bold') # Automatically shows when exiting the context

Parameters:

Name	Type	Description	Default
show	bool	If True, automatically show highlights when exiting context	False

Returns:

Type	Description
'HighlightContext'	HighlightContext for accumulating highlights

natural_pdf.FlowRegion.map_parts(fn)

Apply fn to each constituent region and return the results.

natural_pdf.FlowRegion.save_pdf(path, method='crop')

Save this FlowRegion as a PDF. Each constituent region becomes a page.

Parameters:

Name	Type	Description	Default
path	str	Output file path for the PDF.	required
method	str	'crop' (default) or 'whiteout'.	'crop'

Returns:

Type	Description
'FlowRegion'	Self for method chaining.

Raises:

Type	Description
ValueError	If there are no constituent regions or method is invalid.
ImportError	If pikepdf is not installed.

natural_pdf.FlowRegion.split(by=None, page_breaks=True, **kwargs)

Split this FlowRegion into sections.

This is a convenience method that wraps get_sections() with common splitting patterns.

Parameters:

Name	Type	Description	Default
by	Optional[str]	Selector string for elements that mark section boundaries (e.g., "text:bold")	None
page_breaks	bool	Whether to also split at page boundaries (default: True)	True
**kwargs		Additional arguments passed to get_sections()	{}

Returns:

Type	Description
'ElementCollection'	ElementCollection of FlowRegion objects representing the sections

Example

Split by bold headers

sections = flow_region.split(by="text:bold")

Split only by specific text pattern, ignoring page breaks

sections = flow_region.split( by="text:contains('Section')", page_breaks=False )

natural_pdf.FlowRegion.to_images(resolution=150, **kwargs)

Generates and returns a list of cropped PIL Images, one for each constituent physical region of this FlowRegion.

natural_pdf.Guides

Manages vertical and horizontal guide lines for table extraction and layout analysis.

Guides are collections of coordinates that can be used to define table boundaries, column positions, or general layout structures. They can be created through various detection methods or manually specified.

Attributes:

Name	Type	Description
verticals		List of x-coordinates for vertical guide lines
horizontals		List of y-coordinates for horizontal guide lines
context		Optional Page/Region that these guides relate to
bounds	Optional[Bounds]	Optional bounding box (x0, y0, x1, y1) for relative coordinate conversion
snap_behavior		How to handle failed snapping operations ('warn', 'ignore', 'raise')

Attributes

natural_pdf.Guides.cells property

Access cells by index like guides.cells[row][col] or guides.cells[row, col].

natural_pdf.Guides.columns property

Access columns by index like guides.columns[0].

natural_pdf.Guides.horizontal property writable

Get horizontal guide coordinates.

natural_pdf.Guides.n_cols property

Number of columns defined by vertical guides.

natural_pdf.Guides.n_rows property

Number of rows defined by horizontal guides.

natural_pdf.Guides.rows property

Access rows by index like guides.rows[0].

natural_pdf.Guides.vertical property writable

Get vertical guide coordinates.

Functions

natural_pdf.Guides.__add__(other)

Combine two guide sets.

Returns:

Type	Description
Guides	New Guides object with combined coordinates

natural_pdf.Guides.__init__(verticals=None, horizontals=None, context=None, bounds=None, relative=False, snap_behavior='warn')

Initialize a Guides object.

Parameters:

Name	Type	Description	Default
verticals	Optional[Union[Iterable[float], GuidesContext]]	Iterable of x-coordinates for vertical guides, or a context object shorthand	None
horizontals	Optional[Iterable[float]]	Iterable of y-coordinates for horizontal guides	None
context	Optional[GuidesContext]	Object providing spatial context (page, region, flow, etc.)	None
bounds	Optional[Tuple[float, float, float, float]]	Bounding box (x0, top, x1, bottom) if context not provided	None
relative	bool	Whether coordinates are relative (0-1) or absolute	False
snap_behavior	Literal['raise', 'warn', 'ignore']	How to handle snapping conflicts ('raise', 'warn', or 'ignore')	'warn'

natural_pdf.Guides.__repr__()

String representation of the guides.

natural_pdf.Guides.above(guide_index, obj=None)

Get a region above a horizontal guide.

Parameters:

Name	Type	Description	Default
guide_index	int	Horizontal guide index	required
obj	Optional[Union[Page, Region]]	Page or Region to create the region on (uses self.context if None)	None

Returns:

Type	Description
Region	Region above the specified guide

natural_pdf.Guides.add_content(axis='vertical', markers=None, obj=None, align='left', outer=True, tolerance=5, apply_exclusions=True)

Instance method: Add guides from content, allowing chaining. This allows: Guides.new(page).add_content(axis='vertical', markers=[...])

Parameters:

Name	Type	Description	Default
axis	Literal['vertical', 'horizontal']	Which axis to create guides for	'vertical'
markers	Union[str, List[str], ElementCollection, None]	Content to search for. Can be: - str: single selector or literal text - List[str]: list of selectors or literal text strings - ElementCollection: collection of elements to extract text from - None: no markers	None
obj	Optional[Union[Page, Region]]	Page or Region to search (uses self.context if None)	None
align	Literal['left', 'right', 'center', 'between']	How to align guides relative to found elements	'left'
outer	OuterBoundaryMode	Whether to add outer boundary guides. Can be: - bool: True/False to add/not add both - "first": To add boundary before the first element - "last": To add boundary before the last element	True
tolerance	float	Tolerance for snapping to element edges	5
apply_exclusions	bool	Whether to apply exclusion zones when searching for text	True

Returns:

Type	Description
Guides	Self for method chaining

natural_pdf.Guides.add_horizontal(y)

Add a horizontal guide at the specified y-coordinate.

natural_pdf.Guides.add_lines(axis='both', obj=None, threshold='auto', source_label=None, max_lines_h=None, max_lines_v=None, outer=False, detection_method='vector', resolution=192, **detect_kwargs)

Instance method: Add guides from lines, allowing chaining. This allows: Guides.new(page).add_lines(axis='horizontal')

Parameters:

Name	Type	Description	Default
axis	Literal['vertical', 'horizontal', 'both']	Which axis to detect lines for	'both'
obj	Optional[Union[Page, Region]]	Page or Region to search (uses self.context if None)	None
threshold	Union[float, str]	Line detection threshold ('auto' or float 0.0-1.0)	'auto'
source_label	Optional[str]	Filter lines by source label (vector) or label for detected lines (pixels)	None
max_lines_h	Optional[int]	Maximum horizontal lines to use	None
max_lines_v	Optional[int]	Maximum vertical lines to use	None
outer	bool	Whether to add outer boundary guides	False
detection_method	str	'vector', 'pixels', or 'auto' (default). 'auto' uses vector line information when available and falls back to pixel detection otherwise.	'vector'
resolution	int	DPI for pixel-based detection (default: 192)	192
**detect_kwargs		Additional parameters for pixel detection (see from_lines)	{}

Returns:

Type	Description
Guides	Self for method chaining

natural_pdf.Guides.add_vertical(x)

Add a vertical guide at the specified x-coordinate.

natural_pdf.Guides.add_whitespace(axis='both', obj=None, min_gap=10)

Instance method: Add guides from whitespace, allowing chaining. This allows: Guides.new(page).add_whitespace(axis='both')

Parameters:

Name	Type	Description	Default
axis	Literal['vertical', 'horizontal', 'both']	Which axis to create guides for	'both'
obj	Optional[Union[Page, Region]]	Page or Region to search (uses self.context if None)	None
min_gap	float	Minimum gap size to consider	10

Returns:

Type	Description
Guides	Self for method chaining

natural_pdf.Guides.below(guide_index, obj=None)

Get a region below a horizontal guide.

Parameters:

Name	Type	Description	Default
guide_index	int	Horizontal guide index	required
obj	Optional[Union[Page, Region]]	Page or Region to create the region on (uses self.context if None)	None

Returns:

Type	Description
Region	Region below the specified guide

natural_pdf.Guides.between_horizontal(start_index, end_index, obj=None)

Get a region between two horizontal guides.

Parameters:

Name	Type	Description	Default
start_index	int	Starting horizontal guide index	required
end_index	int	Ending horizontal guide index	required
obj	Optional[Union[Page, Region]]	Page or Region to create the region on (uses self.context if None)	None

Returns:

Type	Description
Region	Region between the specified guides

natural_pdf.Guides.between_vertical(start_index, end_index, obj=None)

Get a region between two vertical guides.

Parameters:

Name	Type	Description	Default
start_index	int	Starting vertical guide index	required
end_index	int	Ending vertical guide index	required
obj	Optional[Union[Page, Region]]	Page or Region to create the region on (uses self.context if None)	None

Returns:

Type	Description
Region	Region between the specified guides

natural_pdf.Guides.build_grid(target=None, source='guides', cell_padding=0.5, include_outer_boundaries=False, *, multi_page='auto')

Create table structure (table, rows, columns, cells) from guide coordinates.

Parameters:

Name	Type	Description	Default
target	Optional[GuidesContext]	Page or Region to create regions on (uses self.context if None)	None
source	str	Source label for created regions (for identification)	'guides'
cell_padding	float	Internal padding for cell regions in points	0.5
include_outer_boundaries	bool	Whether to add boundaries at edges if missing	False
multi_page	Literal['auto', True, False]	Controls multi-region table creation for FlowRegions. - "auto": (default) Creates a unified grid if there are multiple regions or guides span pages. - True: Forces creation of a unified multi-region grid. - False: Creates separate grids for each region.	'auto'

Returns:

Type	Description
Dict[str, Any]	Dictionary with 'counts' and 'regions' created.

natural_pdf.Guides.cell(row, col, obj=None)

Get a cell region from the guides.

Parameters:

Name	Type	Description	Default
row	int	Row index (0-based)	required
col	int	Column index (0-based)	required
obj	Optional[Union[Page, Region]]	Page or Region to create the cell on (uses self.context if None)	None

Returns:

Type	Description
Region	Region representing the specified cell

Raises:

Type	Description
IndexError	If row or column index is out of range

natural_pdf.Guides.column(index, obj=None)

Get a column region from the guides.

Parameters:

Name	Type	Description	Default
index	int	Column index (0-based)	required
obj	Optional[Union[Page, Region]]	Page or Region to create the column on (uses self.context if None)	None

Returns:

Type	Description
Region	Region representing the specified column

Raises:

Type	Description
IndexError	If column index is out of range

natural_pdf.Guides.divide(obj, n=None, cols=None, rows=None, axis='both') classmethod

Create guides by evenly dividing an object.

Parameters:

Name	Type	Description	Default
obj	Union[Page, Region, Tuple[float, float, float, float]]	Object to divide (Page, Region, or bbox tuple)	required
n	Optional[int]	Number of divisions (creates n+1 guides). Used if cols/rows not specified.	None
cols	Optional[int]	Number of columns (creates cols+1 vertical guides)	None
rows	Optional[int]	Number of rows (creates rows+1 horizontal guides)	None
axis	Literal['vertical', 'horizontal', 'both']	Which axis to divide along	'both'

Returns:

Type	Description
Guides	New Guides object with evenly spaced lines

Examples:

Divide into 3 columns

guides = Guides.divide(page, cols=3)

Divide into 5 rows

guides = Guides.divide(region, rows=5)

Divide both axes

guides = Guides.divide(page, cols=3, rows=5)

natural_pdf.Guides.extract_table(target=None, source='guides_temp', cell_padding=0.5, include_outer_boundaries=False, method=None, table_settings=None, use_ocr=False, ocr_config=None, text_options=None, cell_extraction_func=None, show_progress=False, content_filter=None, apply_exclusions=True, *, multi_page='auto', header='first', skip_repeating_headers=None, structure_engine=None)

Extract table data directly from guides without leaving temporary regions.

This method: 1. Creates table structure using build_grid() 2. Extracts table data from the created table region 3. Cleans up all temporary regions 4. Returns the TableResult

When passed a collection (PageCollection, ElementCollection, or list), this method will extract tables from each element and combine them into a single result.

Parameters:

Name	Type	Description	Default
target	Optional[Union[Page, Region, PageCollection, ElementCollection, List[Union[Page, Region]]]]	Page, Region, or collection of Pages/Regions to extract from (uses self.context if None)	None
source	str	Source label for temporary regions (will be cleaned up)	'guides_temp'
cell_padding	float	Internal padding for cell regions in points	0.5
include_outer_boundaries	bool	Whether to add boundaries at edges if missing	False
method	Optional[str]	Table extraction method ('tatr', 'pdfplumber', 'text', etc.)	None
table_settings	Optional[dict]	Settings for pdfplumber table extraction	None
use_ocr	bool	Whether to use OCR for text extraction	False
ocr_config	Optional[dict]	OCR configuration parameters	None
text_options	Optional[Dict]	Dictionary of options for the 'text' method	None
cell_extraction_func	Optional[Callable[[Region], Optional[str]]]	Optional callable for custom cell text extraction	None
show_progress	bool	Controls progress bar for text method	False
content_filter	Optional[Union[str, Callable[[str], bool], List[str]]]	Content filtering function or patterns	None
apply_exclusions	bool	Whether to apply exclusion regions during text extraction (default: True)	True
multi_page	Literal['auto', True, False]	Controls multi-region table creation for FlowRegions	'auto'
header	Union[str, List[str], None]	How to handle headers when extracting from collections: - "first": Use first row of first element as headers (default) - "all": Expect headers on each element, use from first element - None: No headers, use numeric indices - List[str]: Custom column names	'first'
skip_repeating_headers	Optional[bool]	Whether to remove duplicate header rows when extracting from collections. Defaults to True when header is "first" or "all", False otherwise.	None
structure_engine	Optional[str]	Optional structure detection engine name passed to the underlying region extraction to leverage provider-backed table structure results.	None

Returns:

Name	Type	Description
TableResult	TableResult	Extracted table data

Raises:

Type	Description
ValueError	If no table region is created from the guides

Example

from natural_pdf.analyzers import Guides

# Single page extraction
guides = Guides.from_lines(page, source_label="detected")
table_data = guides.extract_table()
df = table_data.to_df()

# Multiple page extraction
guides = Guides(pages[0])
guides.vertical.from_content(['Column 1', 'Column 2'])
table_result = guides.extract_table(pages, header=['Col1', 'Col2'])
df = table_result.to_df()

# Region collection extraction
regions = pdf.find_all('region[type=table]')
guides = Guides(regions[0])
guides.vertical.from_lines(n=3)
table_result = guides.extract_table(regions)

natural_pdf.Guides.from_content(obj, axis='vertical', markers=None, align='left', outer=True, tolerance=5, apply_exclusions=True) classmethod

Create guides based on text content positions.

Parameters:

Name	Type	Description	Default
obj	GuidesContext	Page, Region, or FlowRegion to search for content	required
axis	Literal['vertical', 'horizontal']	Whether to create vertical or horizontal guides	'vertical'
markers	Union[str, List[str], ElementCollection, None]	Content to search for. Can be: - str: single selector (e.g., 'text:contains("Name")') or literal text - List[str]: list of selectors or literal text strings - ElementCollection: collection of elements to extract text from - None: no markers	None
align	Union[Literal['left', 'right', 'center', 'between'], Literal['top', 'bottom']]	Where to place guides relative to found text: - For vertical guides: 'left', 'right', 'center', 'between' - For horizontal guides: 'top', 'bottom', 'center', 'between'	'left'
outer	OuterBoundaryMode	Whether to add guides at the boundaries	True
tolerance	float	Maximum distance to search for text	5
apply_exclusions	bool	Whether to apply exclusion zones when searching for text	True

Returns:

Type	Description
Guides	New Guides object aligned to text content

natural_pdf.Guides.from_headers(obj, axis='vertical', headers=None, method='min_crossings', min_width=None, max_width=None, margin=0.5, row_stabilization=True, num_samples=400) classmethod

Create vertical guides by analyzing header elements.

natural_pdf.Guides.from_lines(obj, axis='both', threshold='auto', source_label=None, max_lines_h=None, max_lines_v=None, outer=False, detection_method='auto', resolution=192, **detect_kwargs) classmethod

Create guides from detected line elements.

Parameters:

Name	Type	Description	Default
obj	GuidesContext	Page, Region, or FlowRegion to detect lines from	required
axis	Literal['vertical', 'horizontal', 'both']	Which orientations to detect	'both'
threshold	Union[float, str]	Detection threshold ('auto' or float 0.0-1.0) - used for pixel detection	'auto'
source_label	Optional[str]	Filter for line source (vector method) or label for detected lines (pixel method)	None
max_lines_h	Optional[int]	Maximum number of horizontal lines to keep	None
max_lines_v	Optional[int]	Maximum number of vertical lines to keep	None
outer	bool	Whether to add outer boundary guides	False
detection_method	str	'vector', 'pixels' (default), or 'auto' for hybrid detection.	'auto'
resolution	int	DPI for pixel-based detection (default: 192)	192
**detect_kwargs		Additional parameters for pixel-based detection: - min_gap_h: Minimum gap between horizontal lines (pixels) - min_gap_v: Minimum gap between vertical lines (pixels) - binarization_method: 'adaptive' or 'otsu' - morph_op_h/v: Morphological operations ('open', 'close', 'none') - smoothing_sigma_h/v: Gaussian smoothing sigma - method: 'projection' (default) or 'lsd' (requires opencv)	{}

Returns:

Type	Description
Guides	New Guides object with detected line positions

natural_pdf.Guides.from_stripes(obj, axis='horizontal', stripes=None, color=None) classmethod

Create guides from zebra stripes or colored bands.

natural_pdf.Guides.from_whitespace(obj, axis='both', min_gap=10) classmethod

Create guides by detecting whitespace gaps (divide + snap placeholder).

natural_pdf.Guides.get_cells()

Get all cell bounding boxes from guide intersections.

Returns:

Type	Description
List[Tuple[float, float, float, float]]	List of (x0, y0, x1, y1) tuples for each cell

natural_pdf.Guides.left_of(guide_index, obj=None)

Get a region to the left of a vertical guide.

Parameters:

Name	Type	Description	Default
guide_index	int	Vertical guide index	required
obj	Optional[Union[Page, Region]]	Page or Region to create the region on (uses self.context if None)	None

Returns:

Type	Description
Region	Region to the left of the specified guide

natural_pdf.Guides.new(context=None) classmethod

Create a new empty Guides object, optionally with a context.

This provides a clean way to start building guides through chaining: guides = Guides.new(page).add_content(axis='vertical', markers=[...])

Parameters:

Name	Type	Description	Default
context	Optional[Union[Page, Region]]	Optional Page or Region to use as default context for operations	None

Returns:

Type	Description
Guides	New empty Guides object

natural_pdf.Guides.remove_horizontal(index)

Remove a horizontal guide by index.

natural_pdf.Guides.remove_vertical(index)

Remove a vertical guide by index.

natural_pdf.Guides.right_of(guide_index, obj=None)

Get a region to the right of a vertical guide.

Parameters:

Name	Type	Description	Default
guide_index	int	Vertical guide index	required
obj	Optional[Union[Page, Region]]	Page or Region to create the region on (uses self.context if None)	None

Returns:

Type	Description
Region	Region to the right of the specified guide

natural_pdf.Guides.row(index, obj=None)

Get a row region from the guides.

Parameters:

Name	Type	Description	Default
index	int	Row index (0-based)	required
obj	Optional[Union[Page, Region]]	Page or Region to create the row on (uses self.context if None)	None

Returns:

Type	Description
Region	Region representing the specified row

Raises:

Type	Description
IndexError	If row index is out of range

natural_pdf.Guides.shift(index, offset, axis='vertical')

Move a specific guide by a offset amount.

Parameters:

Name	Type	Description	Default
index	int	Index of the guide to move	required
offset	float	Amount to move (positive = right/down)	required
axis	Literal['vertical', 'horizontal']	Which guide list to modify	'vertical'

Returns:

Type	Description
Guides	Self for method chaining

natural_pdf.Guides.show(on=None, **kwargs)

Display the guides overlaid on a page or region.

Parameters:

Name	Type	Description	Default
on		Page, Region, PIL Image, or string to display guides on. If None, uses self.context (the object guides were created from). If string 'page', uses the page from self.context.	None
**kwargs		Additional arguments passed to render() if applicable.	{}

Returns:

Type	Description
	PIL Image with guides drawn on it.

natural_pdf.Guides.snap_to_whitespace(axis='vertical', min_gap=10.0, detection_method='pixels', threshold='auto', on_no_snap='warn')

Snap guides to nearby whitespace gaps (troughs) using optimal assignment. Modifies this Guides object in place.

Parameters:

Name	Type	Description	Default
axis	str	Direction to snap ('vertical' or 'horizontal')	'vertical'
min_gap	float	Minimum gap size to consider as a valid trough	10.0
detection_method	str	Method for detecting troughs: 'pixels' - use pixel-based density analysis (default) 'text' - use text element spacing analysis	'pixels'
threshold	Union[float, str]	Threshold for what counts as a trough: - float (0.0-1.0): areas with this fraction or less of max density count as troughs - 'auto': automatically find threshold that creates enough troughs for guides (only applies when detection_method='pixels')	'auto'
on_no_snap	str	Action when snapping fails ('warn', 'ignore', 'raise')	'warn'

Returns:

Type	Description
Guides	Self for method chaining.

natural_pdf.Guides.to_absolute(bounds)

Convert relative coordinates to absolute coordinates.

Parameters:

Name	Type	Description	Default
bounds	Tuple[float, float, float, float]	Target bounding box (x0, y0, x1, y1)	required

Returns:

Type	Description
Guides	New Guides object with absolute coordinates

natural_pdf.Guides.to_dict()

Convert to dictionary format suitable for pdfplumber table_settings.

Returns:

Type	Description
Dict[str, Any]	Dictionary with explicit_vertical_lines and explicit_horizontal_lines

natural_pdf.Guides.to_relative()

Convert absolute coordinates to relative (0-1) coordinates.

Returns:

Type	Description
Guides	New Guides object with relative coordinates

natural_pdf.InvalidOptionError

Raised when an option value is invalid (wrong type, out of range, etc.).

natural_pdf.Judge

Visual classifier for regions using simple image metrics.

Requires class labels to be specified. For binary classification, requires at least one example of each class before making decisions.

Examples:

Checkbox detection:

judge = Judge("checkboxes", labels=["unchecked", "checked"])
judge.add(empty_box, "unchecked")
judge.add(marked_box, "checked")

result = judge.decide(new_box)
if result.label == "checked":
    print("Box is checked!")

Signature detection:

judge = Judge("signatures", labels=["unsigned", "signed"])
judge.add(blank_area, "unsigned")
judge.add(signature_area, "signed")

result = judge.decide(new_region)
print(f"Classification: {result.label} (confidence: {result.score})")

Functions

natural_pdf.Judge.__init__(name, labels, base_dir=None, target_prior=None)

Initialize a Judge for visual classification.

Parameters:

Name	Type	Description	Default
name	str	Name for this judge (used for folder name)	required
labels	List[str]	Class labels (required, typically 2 for binary classification)	required
base_dir	Optional[Union[str, Path]]	Base directory for storage. Defaults to current directory	None
target_prior	Optional[float]	Target prior probability for the FIRST label in the labels list. - 0.5 (default) = neutral, treats both classes equally - >0.5 = favors labels[0] - <0.5 = favors labels[1] Example: Judge("cb", ["checked", "unchecked"], target_prior=0.6) favors detecting "checked" checkboxes.	None

natural_pdf.Judge.add(region, label=None)

Add a region to the judge's dataset.

Parameters:

Name	Type	Description	Default
region	SupportsRender	Region object to add	required
label	Optional[str]	Class label. If None, added to unlabeled for later teaching	None

Raises:

Type	Description
JudgeError	If label is not in allowed labels

natural_pdf.Judge.count(target_label, regions)

Count how many regions match the target label.

Parameters:

Name	Type	Description	Default
target_label	str	The class label to count	required
regions	Iterable[SupportsRender]	List of regions to check	required

Returns:

Type	Description
int	Number of regions classified as target_label

natural_pdf.Judge.decide(regions)

Classify one or more regions.

Parameters:

Name	Type	Description	Default
regions	Union[SupportsRender, Iterable[SupportsRender]]	Single region or list of regions to classify	required

Returns:

Type	Description
Union[Decision, List[Decision]]	Decision or list of Decisions with label and score

Raises:

Type	Description
JudgeError	If not enough training examples

natural_pdf.Judge.forget(region=None, delete=False)

Clear training data, delete all files, or move a specific region to unlabeled.

Parameters:

Name	Type	Description	Default
region	Optional[SupportsRender]	If provided, move this specific region to unlabeled	None
delete	bool	If True, permanently delete all files	False

natural_pdf.Judge.info()

Show configuration and training information for this Judge.

natural_pdf.Judge.inspect(preview=True)

Inspect all stored examples, showing their true labels and predicted labels/scores. Useful for debugging classification issues.

Parameters:

Name	Type	Description	Default
preview	bool	If True (default), display images inline in HTML tables (requires IPython/Jupyter). If False, use text-only output.	True

natural_pdf.Judge.load(path) classmethod

Load a judge from a saved configuration.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	Path to the saved judge.json file or the judge directory	required

Returns:

Type	Description
Judge	Loaded Judge instance

natural_pdf.Judge.lookup(region)

Look up a region and return its hash and image if found in training data.

Parameters:

Name	Type	Description	Default
region	SupportsRender	Region to look up	required

Returns:

Type	Description
Optional[Tuple[str, Image]]	Tuple of (hash, image) if found, None if not found

natural_pdf.Judge.pick(target_label, regions, labels=None)

Pick which region best matches the target label.

Parameters:

Name	Type	Description	Default
target_label	str	The class label to look for	required
regions	Iterable[SupportsRender]	List of regions to choose from	required
labels	Optional[Sequence[str]]	Optional human-friendly labels for each region	None

Returns:

Type	Description
PickResult	PickResult with winning region, index, label (if provided), and score

Raises:

Type	Description
JudgeError	If target_label not in allowed labels

natural_pdf.Judge.save(path=None)

Save the judge configuration (auto-retrains first).

Parameters:

Name	Type	Description	Default
path	Optional[Union[str, Path]]	Optional path to save to. Defaults to judge.json in root directory	None

natural_pdf.Judge.show(max_per_class=10, size=(100, 100))

Display a grid showing examples from each category.

Parameters:

Name	Type	Description	Default
max_per_class	int	Maximum number of examples to show per class	10
size	Tuple[int, int]	Size of each image in pixels (width, height)	(100, 100)

natural_pdf.Judge.teach(labels=None, review=False)

Interactive teaching interface using IPython widgets.

Parameters:

Name	Type	Description	Default
labels	Optional[List[str]]	Labels to use for teaching. Defaults to self.labels	None
review	bool	If True, review already labeled images for re-classification	False

natural_pdf.JudgeError

Raised when Judge operations fail.

natural_pdf.LayoutEngineNotAvailableError

Raised when a requested layout engine is not installed or available.

natural_pdf.LayoutError

Error during layout detection.

Raised when: - Layout detector initialization fails - Model loading fails - Detection processing fails

natural_pdf.NaturalPDFError

Base exception for all Natural PDF errors.

All domain-specific exceptions should inherit from this class. This allows users to catch all Natural PDF errors with a single handler:

try:
    pdf.apply_ocr()
except NaturalPDFError as e:
    handle_error(e)

natural_pdf.OCREngineNotAvailableError

Raised when a requested OCR engine is not installed or available.

natural_pdf.OCRError

Error during OCR processing.

Raised when: - OCR engine initialization fails - Image processing fails - Text recognition fails - Engine is not available

natural_pdf.Options

Global options for natural-pdf, similar to pandas options.

natural_pdf.PDF

Enhanced PDF wrapper built on top of pdfplumber.

This class provides a fluent interface for working with PDF documents, with improved selection, navigation, and extraction capabilities. It integrates OCR, layout analysis, and AI-powered data extraction features while maintaining compatibility with the underlying pdfplumber API.

The PDF class supports loading from files, URLs, or streams, and provides spatial navigation, element selection with CSS-like selectors, and advanced document processing workflows including multi-page content flows.

Attributes:

Name	Type	Description
pages	PageCollection	Lazy-loaded list of Page objects for document pages.
path		Resolved path to the PDF file or source identifier.
source_path		Original path, URL, or stream identifier provided during initialization.
highlighter	HighlightingService	Service for rendering highlighted visualizations of document content.

Example

Basic usage:

import natural_pdf as npdf

pdf = npdf.PDF("document.pdf")
page = pdf.pages[0]
text_elements = page.find_all('text:contains("Summary")')

Advanced usage with OCR:

pdf = npdf.PDF("scanned_document.pdf")
pdf.apply_ocr(engine="easyocr", resolution=144)
tables = pdf.pages[0].find_all('table')

Attributes

natural_pdf.PDF.metadata property

Access PDF metadata as a dictionary.

Returns document metadata such as title, author, creation date, and other properties embedded in the PDF file. The exact keys available depend on what metadata was included when the PDF was created.

Returns:

Type	Description
Dict[str, Any]	Dictionary containing PDF metadata. Common keys include 'Title',
Dict[str, Any]	'Author', 'Subject', 'Creator', 'Producer', 'CreationDate', and
Dict[str, Any]	'ModDate'. May be empty if no metadata is available.

Example

pdf = npdf.PDF("document.pdf")
print(pdf.metadata.get('Title', 'No title'))
print(f"Created: {pdf.metadata.get('CreationDate')}")

natural_pdf.PDF.pages property

Access pages as a PageCollection object.

Provides access to individual pages of the PDF document through a collection interface that supports indexing, slicing, and iteration. Pages are lazy-loaded to minimize memory usage.

Returns:

Type	Description
PageCollection	PageCollection object that provides list-like access to PDF pages.

Raises:

Type	Description
AttributeError	If PDF pages are not yet initialized.

Example

pdf = npdf.PDF("document.pdf")

# Access individual pages
first_page = pdf.pages[0]
last_page = pdf.pages[-1]

# Slice pages
first_three = pdf.pages[0:3]

# Iterate over pages
for page in pdf.pages:
    print(f"Page {page.index} has {len(page.chars)} characters")

Functions

natural_pdf.PDF.__enter__()

Context manager entry.

natural_pdf.PDF.__exit__(exc_type, exc_val, exc_tb)

Context manager exit.

natural_pdf.PDF.__getitem__(key)

Access pages by index or slice.

natural_pdf.PDF.__init__(path_or_url_or_stream, reading_order=True, font_attrs=None, keep_spaces=True, text_tolerance=None, auto_text_tolerance=True, text_layer=True, context=None)

Initialize the enhanced PDF object.

Parameters:

Name	Type	Description	Default
path_or_url_or_stream		Path to the PDF file (str/Path), a URL (str), or a file-like object (stream). URLs must start with 'http://' or 'https://'.	required
reading_order	bool	If True, use natural reading order for text extraction. Defaults to True.	True
font_attrs	Optional[List[str]]	List of font attributes for grouping characters into words. Common attributes include ['fontname', 'size']. Defaults to None.	None
keep_spaces	bool	If True, include spaces in word elements during text extraction. Defaults to True.	True
text_tolerance	Optional[dict]	PDFplumber-style tolerance settings for text grouping. Dictionary with keys like 'x_tolerance', 'y_tolerance'. Defaults to None.	None
auto_text_tolerance	bool	If True, automatically scale text tolerance based on font size and document characteristics. Defaults to True.	True
text_layer	bool	If True, preserve existing text layer from the PDF. If False, removes all existing text elements during initialization, useful for OCR-only workflows. Defaults to True.	True

Raises:

Type	Description
TypeError	If path_or_url_or_stream is not a valid type.
IOError	If the PDF file cannot be opened or read.
ValueError	If URL download fails.

Example

# From file path
pdf = npdf.PDF("document.pdf")

# From URL
pdf = npdf.PDF("https://example.com/document.pdf")

# From stream
with open("document.pdf", "rb") as f:
    pdf = npdf.PDF(f)

# With custom settings
pdf = npdf.PDF("document.pdf",
              reading_order=False,
              text_layer=False,  # For OCR-only processing
              font_attrs=['fontname', 'size', 'flags'])

natural_pdf.PDF.__len__()

Return the number of pages in the PDF.

natural_pdf.PDF.__repr__()

Return a string representation of the PDF object.

natural_pdf.PDF.add_exclusion(exclusion_func, label=None, method='region')

Add an exclusion function to the PDF.

Exclusion functions define regions of each page that should be ignored during text extraction and analysis operations. This is useful for filtering out headers, footers, watermarks, or other administrative content that shouldn't be included in the main document processing.

Parameters:

Name	Type	Description	Default
exclusion_func		A function that takes a Page object and returns a Region to exclude from processing, or None if no exclusion should be applied to that page. The function is called once per page.	required
label	Optional[str]	Optional descriptive label for this exclusion rule, useful for debugging and identification.	None
method	str	Exclusion method - 'region' (default) converts to region, 'element' matches individual elements by bbox.	'region'

Returns:

Type	Description
PDF	Self for method chaining.

Raises:

Type	Description
AttributeError	If PDF pages are not yet initialized.

Example

pdf = npdf.PDF("document.pdf")

# Exclude headers (top 50 points of each page)
pdf.add_exclusion(
    lambda page: page.region(0, 0, page.width, 50),
    label="header_exclusion"
)

# Exclude any text containing "CONFIDENTIAL"
pdf.add_exclusion(
    lambda page: page.find('text:contains("CONFIDENTIAL")').above(include_source=True)
    if page.find('text:contains("CONFIDENTIAL")') else None,
    label="confidential_exclusion"
)

# Chain multiple exclusions
pdf.add_exclusion(header_func).add_exclusion(footer_func)

natural_pdf.PDF.add_region(region_func, name=None)

Add a region function to the PDF.

Parameters:

Name	Type	Description	Default
region_func	Callable[[Page], Optional[Region]]	A function that takes a Page and returns a Region, or None	required
name	Optional[str]	Optional name for the region	None

Returns:

Type	Description
PDF	Self for method chaining

natural_pdf.PDF.analyze_layout(*args, **kwargs)

Analyzes the layout of all pages in the PDF.

This is a convenience method that calls analyze_layout on the PDF's page collection.

Parameters:

Name	Type	Description	Default
*args		Positional arguments passed to pages.analyze_layout().	()
**kwargs		Keyword arguments passed to pages.analyze_layout().	{}

Returns:

Type	Description
ElementCollection[Region]	An ElementCollection of all detected Region objects.

natural_pdf.PDF.apply_ocr(engine=None, languages=None, min_confidence=None, device=None, resolution=None, apply_exclusions=True, detect_only=False, replace=True, options=None, pages=None)

Apply OCR to specified pages of the PDF using batch processing.

Performs optical character recognition on the specified pages, converting image-based text into searchable and extractable text elements. This method supports multiple OCR engines and provides batch processing for efficiency.

Parameters:

Name	Type	Description	Default
engine	Optional[str]	OCR engine — "rapidocr" (default), "easyocr", "surya", "paddle", "paddlevl", "doctr", or "vlm" (requires model=/client= or a default client via natural_pdf.set_default_client()). If None, uses the global default from natural_pdf.options.ocr.engine.	None
languages	Optional[List[str]]	List of language codes for OCR recognition (e.g., ['en', 'es']). If None, uses the global default from natural_pdf.options.ocr.languages.	None
min_confidence	Optional[float]	Minimum confidence threshold (0.0-1.0) for accepting OCR results. Text with lower confidence will be filtered out. If None, uses the global default.	None
device	Optional[str]	Device to run OCR on ('cpu', 'cuda', 'mps'). Engine-specific availability varies. If None, uses engine defaults.	None
resolution	Optional[int]	DPI resolution for rendering pages to images before OCR. Higher values improve accuracy but increase processing time and memory. Typical values: 150 (fast), 300 (balanced), 600 (high quality).	None
apply_exclusions	bool	If True, mask excluded regions before OCR to prevent processing of headers, footers, or other unwanted content.	True
detect_only	bool	If True, only detect text bounding boxes without performing character recognition. Useful for layout analysis workflows.	False
replace	bool	If True, replace any existing OCR elements on the pages. If False, append new OCR results to existing elements.	True
options	Optional[Any]	Engine-specific options object (e.g., EasyOCROptions, SuryaOptions). Allows fine-tuning of engine behavior beyond common parameters.	None
pages	Optional[Union[Iterable[int], range, slice]]	Page indices to process. Can be: - None: Process all pages - slice: Process a range of pages (e.g., slice(0, 10)) - Iterable[int]: Process specific page indices (e.g., [0, 2, 5])	None

Returns:

Type	Description
PDF	Self for method chaining.

Raises:

Type	Description
ValueError	If invalid page index is provided.
TypeError	If pages parameter has invalid type.
RuntimeError	If OCR engine is not available or fails.

Example

pdf = npdf.PDF("scanned_document.pdf")

# Basic OCR on all pages
pdf.apply_ocr()

# High-quality OCR with specific settings
pdf.apply_ocr(
    engine='easyocr',
    languages=['en', 'es'],
    resolution=300,
    min_confidence=0.8
)

# OCR specific pages only
pdf.apply_ocr(pages=[0, 1, 2])  # First 3 pages
pdf.apply_ocr(pages=slice(5, 10))  # Pages 5-9

# Detection-only workflow for layout analysis
pdf.apply_ocr(detect_only=True, resolution=150)

Note

OCR processing can be time and memory intensive, especially at high resolutions. Consider using exclusions to mask unwanted regions and processing pages in batches for large documents.

natural_pdf.PDF.ask(question, *, pages=None, min_confidence=0.1, model=None, client=None, using='text', engine=None, **kwargs)

Ask a single question about the document content.

Routes through page-level .ask() which delegates to .extract() internally, returning :class:StructuredDataResult.

Parameters:

Name	Type	Description	Default
question	str	Question string.	required
pages	Optional[Union[int, Iterable[int], range]]	Specific pages to query (default: all).	None
min_confidence	float	Minimum confidence for extractive QA.	0.1
model	Optional[str]	Model name for QA / VLM / LLM engine.	None
client	Optional[Any]	OpenAI-compatible client for LLM-backed QA.	None
using	str	'text' or 'vision'.	'text'
engine	Optional[str]	None (auto), 'doc_qa', 'vlm'.	None

Returns:

Type	Description
StructuredDataResult	class:StructuredDataResult with an answer field.

natural_pdf.PDF.ask_batch(questions, *, pages=None, min_confidence=0.1, model=None, client=None, using='text', engine=None, **kwargs)

Ask multiple questions about the document content.

Resolves pages once and creates a single :class:PageCollection, then routes each question through it, returning a list of :class:StructuredDataResult objects.

natural_pdf.PDF.ask_pages(question, *, pages=None, min_confidence=0.1, model=None, client=None, using='text', engine=None, **kwargs)

Ask a question across a set of pages and return per-page responses.

Returns a list of :class:StructuredDataResult, one per page.

natural_pdf.PDF.classify(labels, model=None, using=None, min_confidence=0.0, analysis_key='classification', multi_label=False, **kwargs)

Delegate classification to the classification service and return the result.

natural_pdf.PDF.classify_pages(labels, model=None, pages=None, analysis_key='classification', using=None, min_confidence=0.0, multi_label=False, batch_size=8, progress_bar=True, **kwargs)

Classifies specified pages of the PDF.

Parameters:

Name	Type	Description	Default
labels	List[str]	List of category names	required
model	Optional[str]	Model identifier ('text', 'vision', or specific HF ID)	None
pages	Optional[Union[Iterable[int], range, slice]]	Page indices, slice, or None for all pages	None
analysis_key	str	Key to store results in page's analyses dict	'classification'
using	Optional[str]	Processing mode ('text' or 'vision')	None
**kwargs		Additional arguments forwarded to the classification engine	{}

Returns:

Type	Description
PDF	Self for method chaining

natural_pdf.PDF.clear_exclusions()

Clear all exclusion functions from the PDF.

Removes all previously added exclusion functions that were used to filter out unwanted content (like headers, footers, or administrative text) from text extraction and analysis operations.

Returns:

Type	Description
PDF	Self for method chaining.

Raises:

Type	Description
AttributeError	If PDF pages are not yet initialized.

Example

pdf = npdf.PDF("document.pdf")
pdf.add_exclusion(lambda page: page.find('text:contains("CONFIDENTIAL")').above())

# Later, remove all exclusions
pdf.clear_exclusions()

natural_pdf.PDF.close()

Close the underlying PDF file and clean up any temporary files.

natural_pdf.PDF.describe(**kwargs)

Describe the PDF content using the describe service.

natural_pdf.PDF.deskew(pages=None, resolution=300, angle=None, detection_resolution=72, force_overwrite=False, engine=None, **deskew_kwargs)

Creates a new, in-memory PDF object containing deskewed versions of the specified pages from the original PDF.

This method renders each selected page, detects and corrects skew, and then combines the resulting images into a new PDF using 'img2pdf'. The new PDF object is returned directly.

Important: The returned PDF is image-based. Any existing text, OCR results, annotations, or other elements from the original pages will not be carried over.

Parameters:

Name	Type	Description	Default
pages	Optional[Union[Iterable[int], range, slice]]	Page indices/slice to include (0-based). If None, processes all pages.	None
resolution	int	DPI resolution for rendering the output deskewed pages.	300
angle	Optional[float]	The specific angle (in degrees) to rotate by. If None, detects automatically.	None
detection_resolution	int	DPI resolution used for skew detection if angles are not already cached on the page objects.	72
force_overwrite	bool	If False (default), raises a ValueError if any target page already contains processed elements (text, OCR, regions) to prevent accidental data loss. Set to True to proceed anyway.	False
engine	Optional[str]	Engine name — "projection" (default), "hough", or "standard".	None
**deskew_kwargs		Additional keyword arguments forwarded to the deskew engine during automatic detection (e.g., num_peaks for Hough).	{}

Returns:

Type	Description
PDF	A new PDF object representing the deskewed document.

Raises:

Type	Description
ImportError	If 'img2pdf' library is not installed.
ValueError	If force_overwrite is False and target pages contain elements.
FileNotFoundError	If the source PDF cannot be read (if file-based).
IOError	If creating the in-memory PDF fails.
RuntimeError	If rendering or deskewing individual pages fails.

natural_pdf.PDF.export_ocr_correction_task(output_zip_path, *, overwrite=False, suggest=None, resolution=300)

Exports OCR results from this PDF into a correction task package. Exports OCR results from this PDF into a correction task package.

Parameters:

Name	Type	Description	Default
output_zip_path	str	The path to save the output zip file.	required
overwrite	bool	When True, replace any existing archive at output_zip_path.	False
suggest		Optional callable that can provide OCR suggestions per region.	None
resolution	int	DPI used when rendering page images for the package.	300

natural_pdf.PDF.export_training_data(output_dir, **kwargs)

Export cropped text images and labels for OCR model training.

Creates a HuggingFace ImageFolder-compatible directory with cropped text-element images and metadata (JSONL or CSV).

Parameters:

Name	Type	Description	Default
output_dir	str	Destination directory.	required
**kwargs		Forwarded to :func:~natural_pdf.exporters.training_data.export_training_data.	{}

Returns:

Type	Description
dict	Summary dict with images, skipped, and output_dir keys.

natural_pdf.PDF.extract(schema, client=None, analysis_key='structured', prompt=None, using='text', model=None, engine=None, overwrite=True, **kwargs)

Run structured extraction on the entire PDF.

Accepts the same arguments as :meth:Page.extract. Pass citations=True to get per-field source citations that map extracted values back to their source elements across pages. Pass confidence=True for per-field confidence scores, and instructions="..." for domain-specific LLM guidance.

Returns:

Type	Description
	class:StructuredDataResult

natural_pdf.PDF.extract_pages(schema, *, client=None, pages=None, analysis_key='structured', overwrite=True, **kwargs)

Run structured extraction across multiple pages.

natural_pdf.PDF.extract_tables(selector=None, merge_across_pages=False, method=None, table_settings=None)

Extract tables from the document or matching elements.

Parameters:

Name	Type	Description	Default
selector	Optional[str]	Optional selector to filter tables (not yet implemented).	None
merge_across_pages	bool	Whether to merge tables that span across pages (not yet implemented).	False
method	Optional[str]	Extraction strategy to prefer. Mirrors Page.extract_tables.	None
table_settings	Optional[dict]	Per-method configuration forwarded to Page.extract_tables.	None

Returns:

Type	Description
List[Any]	List of extracted tables

natural_pdf.PDF.extract_text(selector=None, preserve_whitespace=True, preserve_line_breaks=True, page_separator='\n', use_exclusions=True, debug_exclusions=False, *, layout=True, x_density=None, y_density=None, x_tolerance=None, y_tolerance=None, line_dir=None, char_dir=None, strip_final=False, strip_empty=False, return_textmap=False)

Extract text from the entire document or matching elements.

Parameters:

Name	Type	Description	Default
selector	Optional[str]	Optional selector to filter elements	None
preserve_whitespace	bool	Whether to keep blank characters	True
preserve_line_breaks	bool	When False, collapse newlines in each page's text.	True
page_separator	Optional[str]	String inserted between page texts when combining results.	'\n'
use_exclusions	bool	Whether to apply exclusion regions	True
debug_exclusions	bool	Whether to output detailed debugging for exclusions	False
layout	bool	Whether to enable layout-aware spacing (default: True).	True
x_density	Optional[float]	Horizontal character density override.	None
y_density	Optional[float]	Vertical line density override.	None
x_tolerance	Optional[float]	Horizontal clustering tolerance.	None
y_tolerance	Optional[float]	Vertical clustering tolerance.	None
line_dir	Optional[str]	Line reading direction override.	None
char_dir	Optional[str]	Character reading direction override.	None
strip_final	bool	When True, strip trailing whitespace from the combined text.	False
strip_empty	bool	When True, drop empty lines from the output.	False

Returns:

Type	Description
str	Extracted text as string

natural_pdf.PDF.extracted(analysis_key=None)

Retrieve the stored result from a previous .extract() call.

natural_pdf.PDF.from_images(images, resolution=300, apply_ocr=True, ocr_engine=None, **pdf_options) classmethod

Create a PDF from image(s).

Parameters:

Name	Type	Description	Default
images	Union[Image, List[Image], str, List[str], Path, List[Path]]	Single image, list of images, or path(s)/URL(s) to image files	required
resolution	int	DPI for the PDF (default: 300, good for OCR and viewing)	300
apply_ocr	bool	Apply OCR to make searchable (default: True)	True
ocr_engine	Optional[str]	OCR engine to use (default: auto-detect)	None
**pdf_options		Options passed to PDF constructor	{}

Returns:

Type	Description
PDF	PDF object containing the images as pages

Example

# Simple scan to searchable PDF
pdf = PDF.from_images("scan.jpg")

# From URL
pdf = PDF.from_images("https://example.com/image.png")

# Multiple pages (mix of local and URLs)
pdf = PDF.from_images(["page1.png", "https://example.com/page2.jpg"])

# Without OCR
pdf = PDF.from_images(images, apply_ocr=False)

# With specific engine
pdf = PDF.from_images(images, ocr_engine='surya')

natural_pdf.PDF.get_id()

Get unique identifier for this PDF.

natural_pdf.PDF.get_sections(start_elements=None, end_elements=None, new_section_on_page_break=False, include_boundaries='both', orientation='vertical')

Extract sections from the entire PDF based on start/end elements.

This method delegates to the PageCollection.get_sections() method, providing a convenient way to extract document sections across all pages.

Parameters:

Name	Type	Description	Default
start_elements		Elements or selector string that mark the start of sections (optional)	None
end_elements		Elements or selector string that mark the end of sections (optional)	None
new_section_on_page_break		Whether to start a new section at page boundaries (default: False)	False
include_boundaries		How to include boundary elements: 'start', 'end', 'both', or 'none' (default: 'both')	'both'
orientation		'vertical' (default) or 'horizontal' - determines section direction	'vertical'

Returns:

Type	Description
ElementCollection	ElementCollection of Region objects representing the extracted sections

Example

Extract sections between headers:

pdf = npdf.PDF("document.pdf")

# Get sections between headers
sections = pdf.get_sections(
    start_elements='text[size>14]:bold',
    end_elements='text[size>14]:bold'
)

# Get sections that break at page boundaries
sections = pdf.get_sections(
    start_elements='text:contains("Chapter")',
    new_section_on_page_break=True
)

Note

You can provide only start_elements, only end_elements, or both. - With only start_elements: sections go from each start to the next start (or end of document) - With only end_elements: sections go from beginning of document to each end - With both: sections go from each start to the corresponding end

natural_pdf.PDF.highlights(show=False)

Create a highlight context for accumulating highlights.

This allows for clean syntax to show multiple highlight groups:

Example

with pdf.highlights() as h: h.add(pdf.find_all('table'), label='tables', color='blue') h.add(pdf.find_all('text:bold'), label='bold text', color='red') h.show()

Or with automatic display

with pdf.highlights(show=True) as h: h.add(pdf.find_all('table'), label='tables') h.add(pdf.find_all('text:bold'), label='bold') # Automatically shows when exiting the context

Parameters:

Name	Type	Description	Default
show	bool	If True, automatically show highlights when exiting context	False

Returns:

Type	Description
HighlightContext	HighlightContext for accumulating highlights

natural_pdf.PDF.inspect(limit=30, **kwargs)

Inspect the PDF content using the describe service.

natural_pdf.PDF.save_pdf(output_path, ocr=False, original=False, apply_exclusions=False, dpi=300)

Saves the PDF object (all its pages) to a new file.

Choose one saving mode: - ocr=True: Creates a new, image-based PDF using OCR results from all pages. Text generated during the natural-pdf session becomes searchable, but original vector content is lost. Requires 'ocr-export' extras. - original=True: Saves a copy of the original PDF file this object represents. Any OCR results or analyses from the natural-pdf session are NOT included. If the PDF was opened from an in-memory buffer, this mode may not be suitable. Requires 'ocr-export' extras. - apply_exclusions=True: Saves the original PDF with exclusion zones whited out. Exclusion regions added via add_exclusion() are covered with white rectangles, preserving the rest of the original vector content. Cannot be combined with ocr=True.

Parameters:

Name	Type	Description	Default
output_path	Union[str, Path]	Path to save the new PDF file.	required
ocr	bool	If True, save as a searchable, image-based PDF using OCR data.	False
original	bool	If True, save the original source PDF content.	False
apply_exclusions	bool	If True, save with exclusion zones whited out.	False
dpi	int	Resolution (dots per inch) used only when ocr=True.	300

Raises:

Type	Description
ValueError	If the PDF has no pages, or if the mode flags are invalid.
ImportError	If required libraries are not installed for the chosen mode.
RuntimeError	If an unexpected error occurs during saving.

natural_pdf.PDF.save_searchable(output_path, dpi=300)

DEPRECATED: Use save_pdf(..., ocr=True) instead. Saves the PDF with an OCR text layer, making content searchable.

Requires optional dependencies. Install with: pip install "natural-pdf[export]"

Parameters:

Name	Type	Description	Default
output_path	Union[str, Path]	Path to save the searchable PDF	required
dpi	int	Resolution for rendering and OCR overlay.	300

natural_pdf.PDF.search(query, *, top_k=5, model=None)

Semantic search across pages in this PDF.

Finds the pages most relevant to the query using sentence-transformers embeddings. Embeddings are cached so repeated searches are fast.

Parameters:

Name	Type	Description	Default
query	str	Text to search for.	required
top_k	int	Number of pages to return.	5
model	Optional[str]	Embedding model name (default: all-MiniLM-L6-v2).	None

Returns:

Type	Description
PageCollection	PageCollection of the most relevant pages, ordered by relevance.
PageCollection	Each page has a _search_score attribute with the similarity score.

natural_pdf.PDF.split(divider, *, include_boundaries='start', orientation='vertical', new_section_on_page_break=False)

Divide the PDF into sections based on the provided divider elements.

Parameters:

Name	Type	Description	Default
divider		Elements or selector string that mark section boundaries	required
include_boundaries	str	How to include boundary elements (default: 'start').	'start'
orientation	str	'vertical' or 'horizontal' (default: 'vertical').	'vertical'
new_section_on_page_break	bool	Whether to split at page boundaries (default: False).	False

Returns:

Type	Description
ElementCollection	ElementCollection of Region objects representing the sections

Example

Split a PDF by chapter titles

chapters = pdf.split("text[size>20]:contains('Chapter')")

Export each chapter to a separate file

for i, chapter in enumerate(chapters): chapter_text = chapter.extract_text() with open(f"chapter_{i+1}.txt", "w") as f: f.write(chapter_text)

Split by horizontal rules/lines

sections = pdf.split("line[orientation=horizontal]")

Split only by page breaks (no divider elements)

pages = pdf.split(None, new_section_on_page_break=True)

natural_pdf.PDF.to_markdown(*, pages=None, separator='\n\n---\n\n', **kwargs)

Convert PDF pages to Markdown using a VLM.

Falls back to extract_text() per-page when no model is configured.

Parameters:

Name	Type	Description	Default
pages	Optional[List[int]]	Optional list of 0-based page indices. Defaults to all pages.	None
separator	str	String inserted between page results.	'\n\n---\n\n'
**kwargs		Passed to each page's to_markdown().	{}

Returns:

Type	Description
str	Combined Markdown string.

natural_pdf.PDF.update_ocr(transform, *, apply_exclusions=False, pages=None, max_workers=None, progress_callback=None)

Convenience wrapper for updating only OCR-derived text elements.

natural_pdf.PDF.update_text(transform, *, selector='text', apply_exclusions=False, pages=None, max_workers=None, progress_callback=None)

Applies corrections to text elements using a callback function.

Parameters:

Name	Type	Description	Default
transform	Callable[[Any], Optional[str]]	Function that takes an element and returns corrected text or None	required
selector	str	Selector to apply corrections to (default: "text")	'text'
apply_exclusions	bool	Whether to honour exclusion regions while selecting text.	False
pages	Optional[Union[Iterable[int], range, slice]]	Optional page indices/slice to limit the scope of correction	None
max_workers	Optional[int]	Maximum number of threads to use for parallel execution	None
progress_callback	Optional[Callable[[], None]]	Optional callback function for progress updates	None

Returns:

Type	Description
PDF	Self for method chaining

natural_pdf.PDFCollection

Attributes

natural_pdf.PDFCollection.pdfs property

Returns the list of PDF objects held by the collection.

Functions

natural_pdf.PDFCollection.__init__(source, recursive=True, **pdf_options)

Initializes a collection of PDF documents from various sources.

Parameters:

Name	Type	Description	Default
source	Union[str, Iterable[Union[str, PDF]]]	The source of PDF documents. Can be: - An iterable (e.g., list) of existing PDF objects. - An iterable (e.g., list) of file paths/URLs/globs (strings). - A single file path/URL/directory/glob string.	required
recursive	bool	If source involves directories or glob patterns, whether to search recursively (default: True).	True
**pdf_options	Any	Keyword arguments passed to the PDF constructor.	{}

natural_pdf.PDFCollection.apply_ocr(engine=None, languages=None, min_confidence=None, device=None, resolution=None, apply_exclusions=True, detect_only=False, replace=True, options=None, pages=None, max_workers=None)

Apply OCR to all PDFs in the collection, potentially in parallel.

Parameters:

Name	Type	Description	Default
engine	Optional[str]	OCR engine to use (e.g., 'easyocr', 'paddleocr', 'surya')	None
languages	Optional[List[str]]	List of language codes for OCR	None
min_confidence	Optional[float]	Minimum confidence threshold for text detection	None
device	Optional[str]	Device to use for OCR (e.g., 'cpu', 'cuda')	None
resolution	Optional[int]	DPI resolution for page rendering	None
apply_exclusions	bool	Whether to apply exclusion regions	True
detect_only	bool	If True, only detect text regions without extracting text	False
replace	bool	If True, replace existing OCR elements	True
options	Optional[Any]	Engine-specific options	None
pages	Optional[Union[slice, List[int]]]	Specific pages to process (None for all pages)	None
max_workers	Optional[int]	Maximum number of threads to process PDFs concurrently. If None or 1, processing is sequential. (default: None)	None

Returns:

Type	Description
PDFCollection	Self for method chaining

natural_pdf.PDFCollection.categorize(labels, **kwargs)

Categorizes PDFs in the collection based on content or features.

natural_pdf.PDFCollection.classify_all(labels, using=None, model=None, analysis_key='classification', min_confidence=0.0, multi_label=False, batch_size=8, progress_bar=True, **kwargs)

Classify each PDF document in the collection using provider-backed batch processing.

natural_pdf.PDFCollection.correct_ocr(correction_callback, max_workers=None, progress_callback=None)

Apply OCR correction to all relevant elements across all pages and PDFs in the collection using a single progress bar.

Parameters:

Name	Type	Description	Default
correction_callback	Callable[[Any], Optional[str]]	Function to apply to each OCR element. It receives the element and should return the corrected text (str) or None.	required
max_workers	Optional[int]	Max threads to use for parallel execution within each page.	None
progress_callback	Optional[Callable[[], None]]	Optional callback function to call after processing each element.	None

Returns:

Type	Description
PDFCollection	Self for method chaining.

natural_pdf.PDFCollection.describe(**kwargs)

Describe the PDF collection content using the describe service.

natural_pdf.PDFCollection.export_ocr_correction_task(output_zip_path, **kwargs)

Exports OCR results from all PDFs in this collection into a single correction task package (zip file).

Parameters:

Name	Type	Description	Default
output_zip_path	str	The path to save the output zip file.	required
**kwargs		Additional arguments passed to create_correction_task_package (e.g., image_render_scale, overwrite).	{}

natural_pdf.PDFCollection.export_training_data(output_dir, **kwargs)

Export cropped text images and labels for OCR model training.

Creates a HuggingFace ImageFolder-compatible directory with cropped text-element images and metadata (JSONL or CSV).

Parameters:

Name	Type	Description	Default
output_dir	str	Destination directory.	required
**kwargs		Forwarded to :func:~natural_pdf.exporters.training_data.export_training_data.	{}

Returns:

Type	Description
dict	Summary dict with images, skipped, and output_dir keys.

natural_pdf.PDFCollection.from_directory(directory_path, recursive=True, **pdf_options) classmethod

Creates a PDFCollection explicitly from PDF files within a directory.

natural_pdf.PDFCollection.from_glob(pattern, recursive=True, **pdf_options) classmethod

Creates a PDFCollection explicitly from a single glob pattern.

natural_pdf.PDFCollection.from_globs(patterns, recursive=True, **pdf_options) classmethod

Creates a PDFCollection explicitly from a list of glob patterns.

natural_pdf.PDFCollection.from_paths(paths_or_urls, **pdf_options) classmethod

Creates a PDFCollection explicitly from a list of file paths or URLs.

natural_pdf.PDFCollection.inspect(limit=30, **kwargs)

Inspect the PDF collection content using the describe service.

natural_pdf.PDFCollection.search(query, *, top_k=5, model=None)

Semantic search across pages in all PDFs in this collection.

Finds the pages most relevant to the query using sentence-transformers embeddings. Pages from all PDFs are ranked together.

Parameters:

Name	Type	Description	Default
query	str	Text to search for.	required
top_k	int	Number of pages to return.	5
model	Optional[str]	Embedding model name (default: all-MiniLM-L6-v2).	None

Returns:

Type	Description
PageCollection	PageCollection of the most relevant pages, ordered by relevance.
PageCollection	Each page has a _search_score attribute with the similarity score.

natural_pdf.PDFCollection.show(limit=30, per_pdf_limit=10, **kwargs)

Display all PDFs in the collection with labels.

Each PDF is shown with its pages in a grid layout (6 columns by default), and all PDFs are stacked vertically with labels.

Parameters:

Name	Type	Description	Default
limit	Optional[int]	Maximum total pages to show across all PDFs (default: 30)	30
per_pdf_limit	Optional[int]	Maximum pages to show per PDF (default: 10)	10
**kwargs		Additional arguments passed to each PDF's show() method (e.g., columns, exclusions, resolution, etc.)	{}

Returns:

Type	Description
	Displayed image in Jupyter or None

natural_pdf.Page

Enhanced Page wrapper built on top of pdfplumber.Page.

This class provides a fluent interface for working with PDF pages, with improved selection, navigation, extraction, and question-answering capabilities. It integrates multiple analysis capabilities through mixins and provides spatial navigation with CSS-like selectors.

The Page class serves as the primary interface for document analysis, offering: - Element selection and spatial navigation - OCR and layout analysis integration - Table detection and extraction - AI-powered classification and data extraction - Visual debugging with highlighting and cropping - Text style analysis and structure detection

Attributes:

Name	Type	Description
index	int	Zero-based index of this page in the PDF.
number	int	One-based page number (index + 1).
width	float	Page width in points.
height	float	Page height in points.
bbox	float	Bounding box tuple (x0, top, x1, bottom) of the page.
chars	List[Any]	Collection of character elements on the page.
words	List[Any]	Collection of word elements on the page.
lines	List[Any]	Collection of line elements on the page.
rects	List[Any]	Collection of rectangle elements on the page.
images	List[Any]	Collection of image elements on the page.
metadata	Dict[str, Any]	Dictionary for storing analysis results and custom data.

Example

Basic usage:

pdf = npdf.PDF("document.pdf")
page = pdf.pages[0]

# Find elements with CSS-like selectors
headers = page.find_all('text[size>12]:bold')
summaries = page.find('text:contains("Summary")')

# Spatial navigation
content_below = summaries.below(until='text[size>12]:bold')

# Table extraction
tables = page.extract_table()

Advanced usage:

# Apply OCR if needed
page.apply_ocr(engine='easyocr', resolution=300)

# Layout analysis
page.analyze_layout(engine='yolo')

# AI-powered extraction
data = page.extract_structured_data(MySchema)

# Visual debugging
page.find('text:contains("Important")').show()

Attributes

natural_pdf.Page.chars property

Get all character elements on this page.

natural_pdf.Page.height property

Get page height.

natural_pdf.Page.images property

Get all embedded raster images on this page.

natural_pdf.Page.index property

Get page index (0-based).

natural_pdf.Page.layout_analyzer property

Get or create the layout analyzer for this page.

natural_pdf.Page.lines property

Get all line elements on this page.

natural_pdf.Page.number property

Get page number (1-based).

natural_pdf.Page.page_number property

Get page number (1-based).

natural_pdf.Page.pdf property

Provides public access to the parent PDF object.

natural_pdf.Page.rects property

Get all rectangle elements on this page.

natural_pdf.Page.size property

Get the size of the page in points.

natural_pdf.Page.skew_angle property

Get the detected skew angle for this page (if calculated).

natural_pdf.Page.text_style_labels property

Get a sorted list of unique text style labels found on the page.

Runs text style analysis with default options if it hasn't been run yet. To use custom options, call analyze_text_styles(options=...) explicitly first.

Returns:

Type	Description
List[str]	A sorted list of unique style label strings.

natural_pdf.Page.width property

Get page width.

natural_pdf.Page.words property

Get all word elements on this page.

Functions

natural_pdf.Page.__init__(page, parent, index, font_attrs=None, load_text=True, context=None)

Initialize a page wrapper.

Creates an enhanced Page object that wraps a pdfplumber page with additional functionality for spatial navigation, analysis, and AI-powered extraction.

Parameters:

Name	Type	Description	Default
page	Page	The underlying pdfplumber page object that provides raw PDF data.	required
parent	PDF	Parent PDF object that contains this page and provides access to managers and global settings.	required
index	int	Zero-based index of this page in the PDF document.	required
font_attrs		List of font attributes to consider when grouping characters into words. Common attributes include ['fontname', 'size', 'flags']. If None, uses default character-to-word grouping rules.	None
load_text	bool	If True, load and process text elements from the PDF's text layer. If False, skip text layer processing (useful for OCR-only workflows).	True

Note

This constructor is typically called automatically when accessing pages through the PDF.pages collection. Direct instantiation is rarely needed.

Example

# Pages are usually accessed through the PDF object
pdf = npdf.PDF("document.pdf")
page = pdf.pages[0]  # Page object created automatically

# Direct construction (advanced usage)
import pdfplumber
with pdfplumber.open("document.pdf") as plumber_pdf:
    plumber_page = plumber_pdf.pages[0]
    page = Page(plumber_page, pdf, 0, load_text=True)

natural_pdf.Page.__repr__()

String representation of the page.

natural_pdf.Page.add_element(element, element_type='words')

Add an element to the backing collection.

natural_pdf.Page.add_exclusion(exclusion, label=None, method='region')

Register an exclusion on the host via the exclusion service.

natural_pdf.Page.add_highlight(bbox=None, color=None, label=None, use_color_cycling=False, element=None, annotate=None, existing='append')

Add a highlight to a bounding box or the entire page. Delegates to the central HighlightingService.

Parameters:

Name	Type	Description	Default
bbox	Optional[Tuple[float, float, float, float]]	Bounding box (x0, top, x1, bottom). If None, highlight entire page.	None
color	Optional[Union[Tuple, str]]	RGBA color tuple/string for the highlight.	None
label	Optional[str]	Optional label for the highlight.	None
use_color_cycling	bool	If True and no label/color, use next cycle color.	False
element	Optional[Any]	Optional original element being highlighted (for attribute extraction).	None
annotate	Optional[List[str]]	List of attribute names from 'element' to display.	None
existing	str	How to handle existing highlights ('append' or 'replace').	'append'

Returns:

Type	Description
Page	Self for method chaining.

natural_pdf.Page.add_highlight_polygon(polygon, color=None, label=None, use_color_cycling=False, element=None, annotate=None, existing='append')

Highlight a polygon shape on the page. Delegates to the central HighlightingService.

Parameters:

Name	Type	Description	Default
polygon	List[Tuple[float, float]]	List of (x, y) points defining the polygon.	required
color	Optional[Union[Tuple, str]]	RGBA color tuple/string for the highlight.	None
label	Optional[str]	Optional label for the highlight.	None
use_color_cycling	bool	If True and no label/color, use next cycle color.	False
element	Optional[Any]	Optional original element being highlighted (for attribute extraction).	None
annotate	Optional[List[str]]	List of attribute names from 'element' to display.	None
existing	str	How to handle existing highlights ('append' or 'replace').	'append'

Returns:

Type	Description
Page	Self for method chaining.

natural_pdf.Page.add_region(region, name=None, *, source=None)

Add a region to the page.

Parameters:

Name	Type	Description	Default
region	Region	Region object to add	required
name	Optional[str]	Optional name for the region	None
source	Optional[str]	Optional provenance label; if provided it will be recorded on the region.	None

Returns:

Type	Description
Page	Self for method chaining

natural_pdf.Page.add_regions(regions, prefix=None, *, source=None)

Add multiple regions to the page.

Parameters:

Name	Type	Description	Default
regions	List[Region]	List of Region objects to add	required
prefix	Optional[str]	Optional prefix for automatic naming (regions will be named prefix_1, prefix_2, etc.)	None
source	Optional[str]	Optional provenance label applied to each region.	None

Returns:

Type	Description
Page	Self for method chaining

natural_pdf.Page.analyze_layout(engine=None, *, options=None, confidence=None, classes=None, exclude_classes=None, device=None, existing='replace', model_name=None, client=None, show_progress=None)

Delegate layout analysis to the configured layout service.

natural_pdf.Page.analyze_text_styles(options=None)

Analyze text elements by style, adding attributes directly to elements.

This method uses TextStyleAnalyzer to process text elements (typically words) on the page. It adds the following attributes to each processed element: - style_label: A descriptive or numeric label for the style group. - style_key: A hashable tuple representing the style properties used for grouping. - style_properties: A dictionary containing the extracted style properties.

Parameters:

Name	Type	Description	Default
options	Optional[TextStyleOptions]	Optional TextStyleOptions to configure the analysis. If None, the analyzer's default options are used.	None

Returns:

Type	Description
ElementCollection	ElementCollection containing all processed text elements with added style attributes.

natural_pdf.Page.annotate_checkboxes(resolution=150)

Open an interactive widget for manual checkbox annotation.

Draw rectangles on the page image to mark checkbox locations. Call get_regions() on the returned annotator to retrieve results.

Parameters:

Name	Type	Description	Default
resolution	int	DPI for rendering the page image.	150

Returns:

Type	Description
	CheckboxAnnotator instance.

natural_pdf.Page.apply_custom_ocr(*, ocr_function, source_label='custom-ocr', replace=True, confidence=None, add_to_page=True)

Apply a custom OCR function via the shared OCR service.

natural_pdf.Page.apply_ocr(engine=None, *, options=None, languages=None, min_confidence=None, device=None, resolution=None, detect_only=False, apply_exclusions=True, replace=True, model=None, client=None, instructions=None, function=None, **kwargs)

Apply OCR to the entire page.

Parameters:

Name	Type	Description	Default
engine	Optional[str]	OCR engine — "rapidocr" (default), "easyocr", "surya", "paddle", "paddlevl", "doctr", "vlm", "dots" (dots.mocr), "glm_ocr", or "chandra". "dots", "glm_ocr", and "chandra" auto-select MLX on Apple Silicon, HF transformers elsewhere. Use engine="vlm" with model= and/or client= for VLM-based OCR.	None
options	Optional[Any]	Engine-specific option object.	None
languages	Optional[List[str]]	Language codes, e.g. ["en", "fr"].	None
min_confidence	Optional[float]	Discard results below this confidence (0–1).	None
device	Optional[str]	Compute device, e.g. "cpu" or "cuda".	None
resolution	Optional[int]	DPI for the page image sent to the engine.	None
detect_only	bool	Detect text regions without recognizing characters.	False
apply_exclusions	bool	Mask exclusion zones before OCR.	True
replace	bool	Remove existing OCR elements first.	True
model	Optional[str]	VLM model name — switches to VLM OCR pipeline.	None
client	Optional[Any]	OpenAI-compatible client — switches to VLM OCR pipeline.	None
instructions	Optional[str]	Additional instructions appended to the VLM prompt. Ignored when prompt is passed directly via **kwargs.	None
function	Optional[Callable]	Custom OCR callable that receives a Region and returns text.	None
**kwargs		Extra engine-specific parameters. Notable kwargs: layout (bool | str): Controls layout detection for VLM engines. True uses PP-DocLayout-V3 (block-level). A string like "rapidocr" or "paddle" uses that classic engine in detect-only mode for line-level boxes. False disables layout (full-page prompt). None (default) auto-detects based on model family. prompt (str): Custom VLM prompt. max_new_tokens (int): Max generation tokens for VLM.	{}

Returns:

Type	Description
Page	Self for chaining.

natural_pdf.Page.ask(question, min_confidence=0.1, model=None, debug=False, *, client=None, using='text', engine=None, **kwargs)

Ask a question about the page content.

Parameters:

Name	Type	Description	Default
question	Any	Question string or list of question strings.	required
min_confidence	float	Minimum confidence for extractive QA.	0.1
model	Optional[str]	Model name for the QA / VLM engine.	None
debug	bool	Enable debug output.	False
client	Any	OpenAI-compatible client for LLM-backed QA.	None
using	str	Content mode — 'text' or 'vision'.	'text'
engine	Optional[str]	Extraction engine — None (auto), 'doc_qa', 'vlm'.	None

Returns:

Type	Description
StructuredDataResult	class:StructuredDataResult with an answer field.

natural_pdf.Page.classify(labels, model=None, using=None, min_confidence=0.0, analysis_key='classification', multi_label=False, **kwargs)

Delegate classification to the classification service and return the result.

natural_pdf.Page.clear_detected_layout_regions()

Removes all regions from this page that were added by layout analysis (i.e., regions where source attribute is 'detected').

This clears the regions both from the page's internal _regions['detected'] list and from the ElementManager's internal list of regions.

Returns:

Type	Description
Page	Self for method chaining.

natural_pdf.Page.clear_exclusions()

Clear all exclusions from the page.

natural_pdf.Page.clear_highlights()

Clear all highlights from this specific page via HighlightingService.

Returns:

Type	Description
Page	Self for method chaining

natural_pdf.Page.clear_text_layer(*args, **kwargs)

Clear the underlying word/char layers for this page.

natural_pdf.Page.compare_ocr(engines, *, normalize='collapse', strategy='auto', resolution=150, languages=None, min_confidence=None, device=None, engine_options=None, **kwargs)

Compare multiple OCR engines on this page.

Runs each engine and produces a comparison without modifying the page's element store. Use .apply(engine=...) on the result to persist the chosen engine's output.

Parameters:

Name	Type	Description	Default
engines	List	Engine specs to compare. Each can be a string (e.g. "easyocr") or a dict with "engine" key plus overrides (e.g. {"engine": "rapidocr", "resolution": 72}).	required
normalize	str	Text normalization — "collapse" (default), "strict", or "ignore" (strip spaces).	'collapse'
strategy	str	Alignment — "auto" (default), "rows", "tiles".	'auto'
resolution	int	Render DPI (default 150).	150
languages	Optional[List[str]]	Language codes for OCR.	None
min_confidence	Optional[float]	Minimum confidence filter.	None
device	Optional[str]	"cpu", "cuda", or "mps".	None
engine_options	Optional[Dict[str, Any]]	Per-engine overrides (deprecated — use dict specs).	None

Returns:

Type	Description
	class:~natural_pdf.ocr.comparison.OcrComparison with
	.summary(), .show(), .heatmap(), .diff(),
	and .apply(engine=...).

natural_pdf.Page.create_region(x0, top, x1, bottom)

Create a region on this page with the specified coordinates.

Parameters:

Name	Type	Description	Default
x0	float	Left x-coordinate	required
top	float	Top y-coordinate	required
x1	float	Right x-coordinate	required
bottom	float	Bottom y-coordinate	required

Returns:

Type	Description
Any	Region object for the specified coordinates

natural_pdf.Page.create_text_elements_from_ocr(*args, **kwargs)

Proxy for ElementManager.create_text_elements_from_ocr.

natural_pdf.Page.crop(bbox=None, **kwargs)

Crop the page to the specified bounding box.

This is a direct wrapper around pdfplumber's crop method.

Parameters:

Name	Type	Description	Default
bbox	Optional[Bounds]	Bounding box (x0, top, x1, bottom) or None	None
**kwargs	Any	Additional parameters (top, bottom, left, right)	{}

Returns:

Type	Description
Any	Cropped page object (pdfplumber.Page)

natural_pdf.Page.describe(**kwargs)

Describe the page content using the describe service.

natural_pdf.Page.deskew(resolution=300, angle=None, detection_resolution=72, engine=None, **deskew_kwargs)

Creates and returns a deskewed PIL image of the page.

If angle is not provided, it will first try to detect the skew angle using detect_skew_angle (or use the cached angle if available).

Parameters:

Name	Type	Description	Default
resolution	int	DPI resolution for the output deskewed image.	300
angle	Optional[float]	The specific angle (in degrees) to rotate by. If None, detects automatically.	None
detection_resolution	int	DPI resolution used for detection if angle is None.	72
engine	Optional[str]	Engine name — "projection" (default), "hough", or "standard".	None
**deskew_kwargs		Additional keyword arguments passed to the detection engine if automatic detection is performed.	{}

Returns:

Type	Description
Optional[Image]	A deskewed PIL.Image.Image object.

Raises:

Type	Description
Exception	Any errors raised by the configured deskew provider.

natural_pdf.Page.detect_skew_angle(resolution=72, grayscale=True, force_recalculate=False, engine=None, **deskew_kwargs)

Detect the skew angle of this page using the deskew provider.

Parameters:

Name	Type	Description	Default
resolution	int	DPI resolution for rendering before detection.	72
grayscale	bool	Whether to convert to grayscale before detection.	True
force_recalculate	bool	Re-detect even if a cached angle exists.	False
engine	Optional[str]	Engine name — "projection" (default), "hough", or "standard".	None
**deskew_kwargs		Extra arguments forwarded to the detection engine.	{}

natural_pdf.Page.ensure_elements_loaded()

Force the underlying element manager to load elements.

natural_pdf.Page.extract(schema, client=None, analysis_key='structured', prompt=None, using='text', model=None, engine=None, overwrite=True, **kwargs)

Run structured extraction and return the result.

Parameters:

Name	Type	Description	Default
schema	Union[Type[Any], Sequence[str]]	A Pydantic BaseModel class or list of field name strings.	required
client	Any	An OpenAI-compatible client instance (required for LLM engine).	None
analysis_key	str	Key to store results under in self.analyses.	'structured'
prompt	Optional[str]	Custom system prompt for the LLM.	None
using	str	Content mode — 'text' (layout text) or 'vision' (rendered image).	'text'
model	Optional[str]	Model identifier passed to the LLM client.	None
engine	Optional[str]	'llm', 'doc_qa', or None (auto-detect from client).	None
overwrite	bool	Re-run if results already exist for analysis_key.	True
**kwargs	Any	Extra arguments forwarded to the extraction engine. citations (bool): When True, each field's result includes source citations mapping the value back to PDF elements. confidence: Per-field confidence scoring. Accepts True or 'range' for 0.0–1.0 scale, a list of categorical levels, or a dict mapping values to descriptions. instructions (str): Domain-specific guidance appended to the LLM prompt, affecting all reasoning.	{}

Returns:

Type	Description
	class:StructuredDataResult with attribute, item, and iteration access:

.. code-block:: python

result = page.extract(MySchema, client=client, citations=True)

result.site                    # "Chicago" (attribute access)
result["site"].value           # "Chicago" (item access)
result["site"].citations       # ElementCollection of source elements
result["site"].citations.show()
result["site"].confidence      # 0.95 (when confidence= is set)
result.confidences             # {"site": 0.95, ...}
result.to_dict()               # {"site": "Chicago", ...}
result.show()                  # highlight all citations on page

natural_pdf.Page.extract_ocr_elements(*args, **kwargs)

Extract OCR results without mutating the page.

natural_pdf.Page.extract_structured_data(*args, **kwargs)

Alias for :meth:extract.

natural_pdf.Page.extract_table(method=None, table_settings=None, use_ocr=False, ocr_config=None, text_options=None, cell_extraction_func=None, show_progress=False, content_filter=None, apply_exclusions=True, verticals=None, horizontals=None, outer=False, structure_engine=None)

Call the table service with the canonical extract_table signature.

natural_pdf.Page.extract_tables(method=None, table_settings=None)

Call the table service to extract every table for the host.

natural_pdf.Page.extract_text(preserve_whitespace=True, preserve_line_breaks=True, use_exclusions=True, debug_exclusions=False, content_filter=None, *, layout=False, x_density=None, y_density=None, x_tolerance=None, y_tolerance=None, line_dir=None, char_dir=None, strip_final=False, strip_empty=False, bidi=True, return_textmap=False)

extract_text(preserve_whitespace: bool = ..., preserve_line_breaks: bool = ..., use_exclusions: bool = ..., debug_exclusions: bool = ..., content_filter: Any = ..., *, layout: bool = ..., x_density: Optional[float] = ..., y_density: Optional[float] = ..., x_tolerance: Optional[float] = ..., y_tolerance: Optional[float] = ..., line_dir: Optional[str] = ..., char_dir: Optional[str] = ..., strip_final: bool = ..., strip_empty: bool = ..., bidi: bool = ..., return_textmap: Literal[False] = ...) -> str

extract_text(preserve_whitespace: bool = ..., preserve_line_breaks: bool = ..., use_exclusions: bool = ..., debug_exclusions: bool = ..., content_filter: Any = ..., *, layout: bool = ..., x_density: Optional[float] = ..., y_density: Optional[float] = ..., x_tolerance: Optional[float] = ..., y_tolerance: Optional[float] = ..., line_dir: Optional[str] = ..., char_dir: Optional[str] = ..., strip_final: bool = ..., strip_empty: bool = ..., bidi: bool = ..., return_textmap: Literal[True] = ...) -> Tuple[str, Any]

Extract text from this page, respecting exclusions and using pdfplumber's layout engine (chars_to_textmap) if layout arguments are provided or default.

Parameters:

Name	Type	Description	Default
preserve_line_breaks	bool	When False, collapse newlines into spaces for a flattened string.	True
use_exclusions	bool	Whether to apply exclusion regions (default: True). Note: Filtering logic is now always applied if exclusions exist.	True
debug_exclusions	bool	Whether to output detailed exclusion debugging info (default: False).	False
content_filter		Optional content filter to exclude specific text patterns. Can be: - A regex pattern string (characters matching the pattern are EXCLUDED) - A callable that takes text and returns True to KEEP the character - A list of regex patterns (characters matching ANY pattern are EXCLUDED)	None
layout	bool	Whether to enable layout-aware spacing (default: False).	False
x_density	Optional[float]	Horizontal character density override.	None
y_density	Optional[float]	Vertical line density override.	None
x_tolerance	Optional[float]	Horizontal clustering tolerance.	None
y_tolerance	Optional[float]	Vertical clustering tolerance.	None
line_dir	Optional[str]	Line reading direction override.	None
char_dir	Optional[str]	Character reading direction override.	None
strip_final	bool	When True, strip trailing whitespace from the combined text.	False
strip_empty	bool	When True, drop entirely blank lines from the output.	False
bidi	bool	Whether to apply bidi reordering when RTL text is detected (default: True).	True

Returns:

Type	Description
Union[str, Tuple[str, Any]]	Extracted text as string, potentially with layout-based spacing.

natural_pdf.Page.extracted(analysis_key=None)

Retrieve the stored result from a previous .extract() call.

Returns the same :class:StructuredDataResult that .extract() returned, or None if the extraction failed.

natural_pdf.Page.filter_elements(elements, selector, **kwargs)

Filter a list of elements based on a selector.

Parameters:

Name	Type	Description	Default
elements	List[Element]	List of elements to filter	required
selector	str	CSS-like selector string	required
**kwargs		Additional filter parameters	{}

Returns:

Type	Description
List[Element]	List of elements that match the selector

natural_pdf.Page.get_all_elements_raw()

Return all elements without applying exclusions.

natural_pdf.Page.get_elements(apply_exclusions=True, debug_exclusions=False)

Get all elements on this page.

Parameters:

Name	Type	Description	Default
apply_exclusions		Whether to apply exclusion regions (default: True).	True
debug_exclusions	bool	Whether to output detailed exclusion debugging info (default: False).	False

Returns:

Type	Description
List[Element]	List of all elements on the page, potentially filtered by exclusions.

natural_pdf.Page.get_elements_by_type(element_type)

Return the elements for a specific backing collection (e.g. 'words').

natural_pdf.Page.get_highlighter()

Expose the page-level HighlightingService for Visualizable consumers.

natural_pdf.Page.get_section_between(start_element=None, end_element=None, include_boundaries='both', orientation='vertical')

Get a section between two elements on this page.

Parameters:

Name	Type	Description	Default
start_element		Element marking the start of the section	None
end_element		Element marking the end of the section	None
include_boundaries		How to include boundary elements: 'start', 'end', 'both', or 'none'	'both'
orientation		'vertical' (default) or 'horizontal' - determines section direction	'vertical'

Returns:

Type	Description
Region	Region representing the section

Raises:

Type	Description
ValueError	Propagated from Region.get_section_between for invalid inputs.

natural_pdf.Page.get_sections(start_elements=None, end_elements=None, include_boundaries='start', y_threshold=5.0, bounding_box=None, orientation='vertical', **kwargs)

Delegate section extraction to the Region implementation.

natural_pdf.Page.has_element_cache()

Return True if the element manager currently holds any elements.

natural_pdf.Page.highlights(show=False)

Create a highlight context for accumulating highlights.

This allows for clean syntax to show multiple highlight groups:

Example

with page.highlights() as h: h.add(page.find_all('table'), label='tables', color='blue') h.add(page.find_all('text:bold'), label='bold text', color='red') h.show()

Or with automatic display

with page.highlights(show=True) as h: h.add(page.find_all('table'), label='tables') h.add(page.find_all('text:bold'), label='bold') # Automatically shows when exiting the context

Parameters:

Name	Type	Description	Default
show	bool	If True, automatically show highlights when exiting context	False

Returns:

Type	Description
HighlightContext	HighlightContext for accumulating highlights

natural_pdf.Page.inspect(limit=30, **kwargs)

Inspect the page content using the describe service.

natural_pdf.Page.invalidate_element_cache()

Invalidate the cached elements so they are reloaded on next access.

natural_pdf.Page.iter_regions()

Return a list of regions currently registered with the page.

natural_pdf.Page.region(left=None, top=None, right=None, bottom=None, width=None, height=None)

Create a region on this page with more intuitive named parameters, allowing definition by coordinates or by coordinate + dimension.

Parameters:

Name	Type	Description	Default
left	Optional[float]	Left x-coordinate (default: 0 if width not used).	None
top	Optional[float]	Top y-coordinate (default: 0 if height not used).	None
right	Optional[float]	Right x-coordinate (default: page width if width not used).	None
bottom	Optional[float]	Bottom y-coordinate (default: page height if height not used).	None
width	Union[str, float, None]	Width definition. Can be: - Numeric: The width of the region in points. Cannot be used with both left and right. - String 'full': Sets region width to full page width (overrides left/right). - String 'element' or None (default): Uses provided/calculated left/right, defaulting to page width if neither are specified.	None
height	Optional[float]	Numeric height of the region. Cannot be used with both top and bottom.	None

Returns:

Type	Description
Any	Region object for the specified coordinates

Raises:

Type	Description
ValueError	If conflicting arguments are provided (e.g., top, bottom, and height) or if width is an invalid string.

Examples:

>>> page.region(top=100, height=50)  # Region from y=100 to y=150, default width
>>> page.region(left=50, width=100)   # Region from x=50 to x=150, default height
>>> page.region(bottom=500, height=50) # Region from y=450 to y=500
>>> page.region(right=200, width=50)  # Region from x=150 to x=200
>>> page.region(top=100, bottom=200, width="full") # Explicit full width

natural_pdf.Page.remove_element(element, element_type=None)

Remove an element from the backing collection.

natural_pdf.Page.remove_elements_by_source(element_type, source)

Remove all elements of a given type whose source matches.

natural_pdf.Page.remove_ocr_elements(*args, **kwargs)

Remove OCR-derived elements from the backing element manager.

natural_pdf.Page.remove_regions(*, source=None, region_type=None, predicate=None)

Remove regions from the page based on optional filters.

Parameters:

Name	Type	Description	Default
source	Optional[str]	Match regions whose region.source equals this string.	None
region_type	Optional[str]	Match regions whose region.region_type equals this string.	None
predicate	Optional[Callable[[Region], bool]]	Additional callable that returns True when a region should be removed.	None

Returns:

Type	Description
int	The number of regions removed.

natural_pdf.Page.remove_regions_by_source(source)

Remove all registered regions that match the requested source.

natural_pdf.Page.remove_text_layer()

Remove all text elements from this page.

This removes all text elements (words and characters) from the page, effectively clearing the text layer.

Returns:

Type	Description
Page	Self for method chaining

natural_pdf.Page.rotate(angle=90, direction='clockwise')

Return a rotated view of this page without mutating the original.

Rotations are limited to right angles and are applied before pdfplumber processes layout, so all downstream extraction (text, tables, etc.) sees the content in the new orientation.

Parameters:

Name	Type	Description	Default
angle	int	Magnitude of rotation in degrees (0/90/180/270).	90
direction	Literal['clockwise', 'counterclockwise']	Direction of rotation; defaults to clockwise.	'clockwise'

Returns:

Type	Description
Page	A new Page instance backed by a rotated pdfplumber.Page.

natural_pdf.Page.save_image(filename, width=None, labels=True, legend_position='right', render_ocr=False, include_highlights=True, resolution=144, **kwargs)

Save the page image to a file, rendering highlights via HighlightingService.

Parameters:

Name	Type	Description	Default
filename	str	Path to save the image to.	required
width	Optional[int]	Optional width for the output image.	None
labels	bool	Whether to include a legend.	True
legend_position	str	Position of the legend.	'right'
render_ocr	bool	Whether to render OCR text.	False
include_highlights	bool	Whether to render highlights.	True
resolution	float	Resolution in DPI for base image rendering (default: 144 DPI, equivalent to previous scale=2.0).	144
**kwargs		Additional args for rendering.	{}

Returns:

Type	Description
Page	Self for method chaining.

natural_pdf.Page.save_searchable(output_path, dpi=300)

Saves the PDF page with an OCR text layer, making content searchable.

Requires optional dependencies. Install with: pip install "natural-pdf[export]"

OCR must have been applied to the pages beforehand

(e.g., pdf.apply_ocr()).

Parameters:

Name	Type	Description	Default
output_path	Union[str, Path]	Path to save the searchable PDF.	required
dpi	int	Resolution for rendering and OCR overlay (default 300).	300

natural_pdf.Page.split(divider, **kwargs)

Divide the page into sections based on the provided divider elements.

natural_pdf.Page.to_markdown(*, model=None, client=None, resolution=144, render_kwargs=None, max_new_tokens=None, prompt=None)

Convert this page to Markdown using a VLM.

Falls back to extract_text() when no model is configured.

Recommended models (olmOCR-bench scores):

• Local (HuggingFace): "rednote-hilab/dots.mocr" (83.9) — 3B, needs GPU. "lightonai/LightOnOCR-2-1B" (83.2) — 1B, runs on CPU/MPS/GPU. Install: pip install transformers>=5.0.0 "Qwen/Qwen2.5-VL-7B-Instruct" (65.5) — 7B, needs GPU.

• Remote (via client=): "gpt-4o" (69.9), "gemini-2.0-flash" (63.8).

Parameters:

Name	Type	Description	Default
model	Optional[str]	HuggingFace model ID or remote model name.	None
client	Optional[Any]	OpenAI-compatible client for remote inference.	None
resolution	int	DPI for rendering the page image.	144
render_kwargs	Optional[Dict[str, Any]]	Extra kwargs for render().	None
max_new_tokens	Optional[int]	Maximum tokens for the VLM to generate.	None
prompt	Optional[str]	Custom prompt override.	None

Returns:

Type	Description
str	Markdown string.

natural_pdf.Page.to_region()

Return a Region covering the full page.

natural_pdf.Page.until(selector, include_endpoint=True, *, text=None, apply_exclusions=True, regex=False, case=True, text_tolerance=None, auto_text_tolerance=None, reading_order=True)

Select content from the top of the page until matching selector.

Parameters:

Name	Type	Description	Default
selector	str	CSS-like selector string	required
include_endpoint	bool	Whether to include the endpoint element in the region	True
**kwargs		Additional selection parameters	required

Returns:

Type	Description
Any	Region object representing the selected content

Examples:

>>> page.until('text:contains("Conclusion")')  # Select from top to conclusion
>>> page.until('line[width>=2]', include_endpoint=False)  # Select up to thick line

natural_pdf.Page.viewer()

Creates and returns an interactive ipywidget for exploring elements on this page.

Uses InteractiveViewerWidget.from_page() to create the viewer.

Returns:

Type	Description
Any	An InteractiveViewerWidget instance ready for display in Jupyter.

Raises:

Type	Description
ImportError	If required dependencies (ipywidgets) are missing.
ValueError	If image rendering or data preparation fails within from_page.

natural_pdf.Page.without_exclusions()

Context manager that temporarily disables exclusion processing.

This prevents infinite recursion when exclusion callables themselves use find() operations. While in this context, all find operations will skip exclusion filtering.

Example

# This exclusion would normally cause infinite recursion:
page.add_exclusion(lambda p: p.find("text:contains('Header')").expand())

# But internally, it's safe because we use:
with page.without_exclusions():
    region = exclusion_callable(page)

Yields:

Type	Description
	The page object with exclusions temporarily disabled.

natural_pdf.PageCollection

Represents a collection of Page objects, often from a single PDF document. Provides methods for batch operations on these pages.

Attributes

natural_pdf.PageCollection.elements property

Alias to expose pages for APIs expecting an elements attribute.

Functions

natural_pdf.PageCollection.__getitem__(idx)

__getitem__(idx: int) -> 'Page'

__getitem__(idx: slice) -> 'PageCollection'

Support indexing and slicing.

natural_pdf.PageCollection.__init__(pages, *, context=None)

Initialize a page collection.

Parameters:

Name	Type	Description	Default
pages	Sequence['Page'] | Iterable['Page']	List or sequence of Page objects (can be lazy)	required

natural_pdf.PageCollection.__iter__()

Support iteration.

natural_pdf.PageCollection.__len__()

Return the number of pages in the collection.

natural_pdf.PageCollection.__repr__()

Return a string representation showing the page count.

natural_pdf.PageCollection.apply_ocr(engine=None, *, options=None, languages=None, min_confidence=None, device=None, resolution=None, detect_only=False, apply_exclusions=True, replace=True, model=None, client=None, instructions=None, **kwargs)

Apply OCR uniformly across all pages in the collection.

Parameters:

Name	Type	Description	Default
engine	Optional[str]	OCR engine — "easyocr", "surya", "paddle", "paddlevl", "doctr", or "vlm".	None
options	Optional[Any]	Engine-specific option object.	None
languages	Optional[List[str]]	Language codes, e.g. ["en", "fr"].	None
min_confidence	Optional[float]	Discard results below this confidence (0–1).	None
device	Optional[str]	Compute device, e.g. "cpu" or "cuda".	None
resolution	Optional[int]	DPI for the image sent to the engine.	None
detect_only	bool	Detect text regions without recognizing characters.	False
apply_exclusions	bool	Mask exclusion zones before OCR.	True
model	Optional[str]	VLM model name — switches to VLM OCR pipeline.	None
client	Optional[Any]	OpenAI-compatible client — switches to VLM OCR pipeline.	None
instructions	Optional[str]	Additional instructions appended to the VLM prompt.	None
**kwargs		Extra engine-specific parameters.	{}

Returns:

Type	Description
	Self for chaining.

natural_pdf.PageCollection.deskew(resolution=300, detection_resolution=72, force_overwrite=False, engine=None, **deskew_kwargs)

Creates a new, in-memory PDF object containing deskewed versions of the pages in this collection.

This method delegates the actual processing to the parent PDF object's deskew method.

Important: The returned PDF is image-based. Any existing text, OCR results, annotations, or other elements from the original pages will not be carried over.

Parameters:

Name	Type	Description	Default
resolution	int	DPI resolution for rendering the output deskewed pages.	300
detection_resolution	int	DPI resolution used for skew detection if angles are not already cached on the page objects.	72
force_overwrite	bool	If False (default), raises a ValueError if any target page already contains processed elements (text, OCR, regions) to prevent accidental data loss. Set to True to proceed anyway.	False
engine	Optional[str]	Engine name — "projection" (default), "hough", or "standard".	None
**deskew_kwargs		Additional keyword arguments forwarded to the deskew engine during automatic detection.	{}

Returns:

Type	Description
'PDF'	A new PDF object representing the deskewed document.

Raises:

Type	Description
ImportError	If 'deskew' or 'img2pdf' libraries are not installed (raised by PDF.deskew).
ValueError	If force_overwrite is False and target pages contain elements (raised by PDF.deskew), or if the collection is empty.
RuntimeError	If pages lack a parent PDF reference, or the parent PDF lacks the deskew method.

natural_pdf.PageCollection.extract_text(separator='\n', apply_exclusions=True, **kwargs)

Extract text from all pages in the collection.

Parameters:

Name	Type	Description	Default
keep_blank_chars		Whether to keep blank characters (default: True)	required
apply_exclusions	bool	Whether to apply exclusion regions (default: True)	True
strip		Whether to strip whitespace from the extracted text.	required
**kwargs		Additional extraction parameters	{}

Returns:

Type	Description
str	Combined text from all pages

natural_pdf.PageCollection.get_sections(start_elements=None, end_elements=None, new_section_on_page_break=False, include_boundaries='both', orientation='vertical')

Extract logical sections across this collection of pages.

This delegates to :class:natural_pdf.flows.flow.Flow, which already implements the heavy lifting for cross-segment section extraction and returns either :class:Region or :class:FlowRegion objects as appropriate. The arrangement is chosen based on the requested orientation so that horizontal sections continue to work for rotated content.

natural_pdf.PageCollection.groupby(by, *, show_progress=True)

Group pages by selector text or callable result.

Parameters:

Name	Type	Description	Default
by	Union[str, Callable]	CSS selector string or callable function	required
show_progress	bool	Whether to show progress bar during computation (default: True)	True

Returns:

Type	Description
'PageGroupBy'	PageGroupBy object supporting iteration and dict-like access

Examples:

Group by header text

for title, pages in pdf.pages.groupby('text[size=16]'): print(f"Section: {title}")

Group by callable

for city, pages in pdf.pages.groupby(lambda p: p.find('text:contains("CITY")').extract_text()): process_city_pages(pages)

Quick exploration with indexing

grouped = pdf.pages.groupby('text[size=16]') grouped.info() # Show all groups first_section = grouped[0] # First group last_section = grouped[-1] # Last group

Dict-like access by name

madison_pages = grouped.get('CITY OF MADISON') madison_pages = grouped['CITY OF MADISON'] # Alternative

Disable progress bar for small collections

grouped = pdf.pages.groupby('text[size=16]', show_progress=False)

natural_pdf.PageCollection.highlights(show=False)

Create a highlight context for accumulating highlights.

This allows for clean syntax to show multiple highlight groups:

Example

with pages.highlights() as h: h.add(pages.find_all('table'), label='tables', color='blue') h.add(pages.find_all('text:bold'), label='bold text', color='red') h.show()

Or with automatic display

with pages.highlights(show=True) as h: h.add(pages.find_all('table'), label='tables') h.add(pages.find_all('text:bold'), label='bold') # Automatically shows when exiting the context

Parameters:

Name	Type	Description	Default
show	bool	If True, automatically show highlights when exiting context	False

Returns:

Type	Description
'HighlightContext'	HighlightContext for accumulating highlights

natural_pdf.PageCollection.save_pdf(output_path, ocr=False, original=False, apply_exclusions=False, dpi=300)

Saves the pages in this collection to a new PDF file.

Choose one saving mode: - ocr=True: Creates a new, image-based PDF using OCR results. This makes the text generated during the natural-pdf session searchable, but loses original vector content. Requires 'ocr-export' extras. - original=True: Extracts the original pages from the source PDF, preserving all vector content, fonts, and annotations. OCR results from the natural-pdf session are NOT included. Requires 'ocr-export' extras. - apply_exclusions=True: Saves the original pages with exclusion zones whited out. Cannot be combined with ocr=True.

Parameters:

Name	Type	Description	Default
output_path	Union[str, Path]	Path to save the new PDF file.	required
ocr	bool	If True, save as a searchable, image-based PDF using OCR data.	False
original	bool	If True, save the original, vector-based pages.	False
apply_exclusions	bool	If True, save with exclusion zones whited out.	False
dpi	int	Resolution (dots per inch) used only when ocr=True for rendering page images and aligning the text layer.	300

Raises:

Type	Description
ValueError	If the collection is empty, if neither or both 'ocr' and 'original' are True, or if 'original=True' and pages originate from different PDFs.
ImportError	If required libraries ('pikepdf', 'Pillow') are not installed for the chosen mode.
RuntimeError	If an unexpected error occurs during saving.

natural_pdf.PageCollection.split(divider, *, include_boundaries='start', orientation='vertical', new_section_on_page_break=False)

Divide this page collection into sections based on the provided divider elements.

Parameters:

Name	Type	Description	Default
divider	BoundarySource	Elements or selector string that mark section boundaries	required
include_boundaries	str	How to include boundary elements (default: 'start').	'start'
orientation	str	'vertical' or 'horizontal' (default: 'vertical').	'vertical'
new_section_on_page_break	bool	Whether to split at page boundaries (default: False).	False

Returns:

Type	Description
'ElementCollection[Region]'	ElementCollection of Region objects representing the sections

Example

Split a PDF by chapter titles

chapters = pdf.pages.split("text[size>20]:contains('CHAPTER')")

Split by page breaks

page_sections = pdf.pages.split(None, new_section_on_page_break=True)

Split multi-page document by section headers

sections = pdf.pages[10:20].split("text:bold:contains('Section')")

natural_pdf.PageCollection.to_flow(arrangement='vertical', alignment='start', segment_gap=0.0)

Convert this PageCollection to a Flow for cross-page operations.

This enables treating multiple pages as a continuous logical document structure, useful for multi-page tables, articles spanning columns, or any content requiring reading order across page boundaries.

Parameters:

Name	Type	Description	Default
arrangement	Literal['vertical', 'horizontal']	Primary flow direction ('vertical' or 'horizontal'). 'vertical' stacks pages top-to-bottom (most common). 'horizontal' arranges pages left-to-right.	'vertical'
alignment	Literal['start', 'center', 'end', 'top', 'left', 'bottom', 'right']	Cross-axis alignment for pages of different sizes: For vertical: 'left'/'start', 'center', 'right'/'end' For horizontal: 'top'/'start', 'center', 'bottom'/'end'	'start'
segment_gap	float	Virtual gap between pages in PDF points (default: 0.0).	0.0

Returns:

Type	Description
'Flow'	Flow object that can perform operations across all pages in sequence.

Example

Multi-page table extraction:

pdf = npdf.PDF("multi_page_report.pdf")

# Create flow for pages 2-4 containing a table
table_flow = pdf.pages[1:4].to_flow()

# Extract table as if it were continuous
table_data = table_flow.extract_table()
df = table_data.df

Cross-page element search:

# Find all headers across multiple pages
headers = pdf.pages[5:10].to_flow().find_all('text[size>12]:bold')

# Analyze layout across pages
regions = pdf.pages.to_flow().analyze_layout(engine='yolo')

natural_pdf.PageCollection.to_markdown(*, separator='\n\n---\n\n', **kwargs)

Convert all pages in the collection to Markdown.

Parameters:

Name	Type	Description	Default
separator	str	String inserted between page results.	'\n\n---\n\n'
**kwargs		Passed to each page's to_markdown().	{}

Returns:

Type	Description
str	Combined Markdown string.

natural_pdf.PageCollection.update_ocr(transform, *, apply_exclusions=False, **kwargs)

Shortcut for updating only OCR text across the collection.

natural_pdf.PageCollection.update_text(transform, *, selector='text', apply_exclusions=False, **kwargs)

Apply text corrections across every page in the collection.

natural_pdf.QAError

Error during document Q&A operations.

Raised when: - Q&A model initialization fails - Question answering fails - Context extraction fails

natural_pdf.Region

Represents a rectangular region on a page.

Regions are fundamental building blocks in natural-pdf that define rectangular areas of a page for analysis, extraction, and navigation. They can be created manually or automatically through spatial navigation methods like .below(), .above(), .left(), and .right() from elements or other regions.

Regions integrate multiple analysis capabilities through mixins and provide: - Element filtering and collection within the region boundary - OCR processing for the region area - Table detection and extraction - AI-powered classification and structured data extraction - Visual rendering and debugging capabilities - Text extraction with spatial awareness

The Region class supports both rectangular and polygonal boundaries, making it suitable for complex document layouts and irregular shapes detected by layout analysis algorithms.

Attributes:

Name	Type	Description
page	'Page'	Reference to the parent Page object.
bbox	Tuple[float, float, float, float]	Bounding box tuple (x0, top, x1, bottom) in PDF coordinates.
x0	float	Left x-coordinate.
top	float	Top y-coordinate (minimum y).
x1	float	Right x-coordinate.
bottom	float	Bottom y-coordinate (maximum y).
width	float	Region width (x1 - x0).
height	float	Region height (bottom - top).
polygon	List[Tuple[float, float]]	List of coordinate points for non-rectangular regions.
label		Optional descriptive label for the region.
metadata	Dict[str, Any]	Dictionary for storing analysis results and custom data.

Example

Creating regions:

pdf = npdf.PDF("document.pdf")
page = pdf.pages[0]

# Manual region creation
header_region = page.region(0, 0, page.width, 100)

# Spatial navigation from elements
summary_text = page.find('text:contains("Summary")')
content_region = summary_text.below(until='text[size>12]:bold')

# Extract content from region
tables = content_region.extract_table()
text = content_region.get_text()

Advanced usage:

# OCR processing
region.apply_ocr(engine='easyocr', resolution=300)

# AI-powered extraction
data = region.extract_structured_data(MySchema)

# Visual debugging
region.show(highlights=['tables', 'text'])

Attributes

natural_pdf.Region.bbox property

Get the bounding box as (x0, top, x1, bottom).

natural_pdf.Region.bottom property

Get the bottom coordinate.

natural_pdf.Region.endpoint property

Get the boundary element that matched the 'until' selector.

When a region is created using directional navigation with an 'until' parameter (e.g., element.above(until='text[size>10]')), this property returns the element that matched the selector and defined the boundary.

Returns:

Type	Description
Optional['Element']	The element that matched the 'until' selector, or None if no
Optional['Element']	'until' was specified or no match was found.

Example

# Find the header above a price element
region = price.above(until='text[size>14]')
header = region.endpoint  # The text element that matched

natural_pdf.Region.has_polygon property

Check if this region has polygon coordinates.

natural_pdf.Region.height property

Get the height of the region.

natural_pdf.Region.origin property

The element/region that created this region (if it was created via directional method).

natural_pdf.Region.page property

Get the parent page.

natural_pdf.Region.polygon property

Get polygon coordinates if available, otherwise return rectangle corners.

natural_pdf.Region.top property

Get the top coordinate.

natural_pdf.Region.type property

Element type.

natural_pdf.Region.width property

Get the width of the region.

natural_pdf.Region.x0 property

Get the left coordinate.

natural_pdf.Region.x1 property

Get the right coordinate.

Functions

natural_pdf.Region.__add__(other)

Add regions/elements together to create an ElementCollection.

This allows intuitive combination of regions using the + operator:

complainant = section.find("text:contains(Complainant)").right(until='text')
dob = section.find("text:contains(DOB)").right(until='text')
combined = complainant + dob  # Creates ElementCollection with both regions

Parameters:

Name	Type	Description	Default
other	Union['Element', 'Region', 'ElementCollection']	Another Region, Element or ElementCollection to combine	required

Returns:

Type	Description
'ElementCollection'	ElementCollection containing all elements

natural_pdf.Region.__init__(page, bbox, polygon=None, parent=None, label=None)

Initialize a region.

Creates a Region object that represents a rectangular or polygonal area on a page. Regions are used for spatial navigation, content extraction, and analysis operations.

Parameters:

Name	Type	Description	Default
page	'Page'	Parent Page object that contains this region and provides access to document elements and analysis capabilities.	required
bbox	Tuple[float, float, float, float]	Bounding box coordinates as (x0, top, x1, bottom) tuple in PDF coordinate system (points, with origin at bottom-left).	required
polygon	Optional[List[Tuple[float, float]]]	Optional list of coordinate points [(x1,y1), (x2,y2), ...] for non-rectangular regions. If provided, the region will use polygon-based intersection calculations instead of simple rectangle overlap.	None
parent	Optional['Region']	Optional parent region for hierarchical document structure. Useful for maintaining tree-like relationships between regions.	None
label	Optional[str]	Optional descriptive label for the region, useful for debugging and identification in complex workflows.	None

Example

pdf = npdf.PDF("document.pdf")
page = pdf.pages[0]

# Rectangular region
header = Region(page, (0, 0, page.width, 100), label="header")

# Polygonal region (from layout detection)
table_polygon = [(50, 100), (300, 100), (300, 400), (50, 400)]
table_region = Region(page, (50, 100, 300, 400),
                    polygon=table_polygon, label="table")

Note

Regions are typically created through page methods like page.region() or spatial navigation methods like element.below(). Direct instantiation is used mainly for advanced workflows or layout analysis integration.

natural_pdf.Region.__radd__(other)

Right-hand addition to support ElementCollection + Region.

natural_pdf.Region.__repr__()

String representation of the region.

natural_pdf.Region.above(height=None, width='full', include_source=False, until=None, include_endpoint=True, offset=None, apply_exclusions=True, multipage=None, within=None, anchor='start', **kwargs)

Select region above this region.

Parameters:

Name	Type	Description	Default
height	Optional[float]	Height of the region above, in points	None
width	str	Width mode - "full" for full page width or "element" for element width	'full'
include_source	bool	Whether to include this region in the result (default: False)	False
until	Optional[str]	Optional selector string to specify an upper boundary element	None
include_endpoint	bool	Whether to include the boundary element in the region (default: True)	True
offset	Optional[float]	Pixel offset when excluding source/endpoint (default: None, uses natural_pdf.options.layout.directional_offset)	None
multipage	Optional[bool]	Override global multipage behaviour; defaults to None meaning use global option.	None
**kwargs		Additional parameters	{}

Returns:

Type	Description
Optional[Union['Region', 'FlowRegion']]	Region object representing the area above, or None if within constraint has no overlap

natural_pdf.Region.add_child(child)

Add a child region to this region.

Used for hierarchical document structure when using models like Docling that understand document hierarchy.

Parameters:

Name	Type	Description	Default
child		Region object to add as a child	required

Returns:

Type	Description
	Self for method chaining

natural_pdf.Region.analyze_text_table_structure(snap_tolerance=10, join_tolerance=3, min_words_vertical=3, min_words_horizontal=1, intersection_tolerance=3, expand_bbox=None, **kwargs)

Analyzes the text elements within the region (or slightly expanded area) to find potential table structure (lines, cells) using text alignment logic adapted from pdfplumber.

Parameters:

Name	Type	Description	Default
snap_tolerance	int	Tolerance for snapping parallel lines.	10
join_tolerance	int	Tolerance for joining collinear lines.	3
min_words_vertical	int	Minimum words needed to define a vertical line.	3
min_words_horizontal	int	Minimum words needed to define a horizontal line.	1
intersection_tolerance	int	Tolerance for detecting line intersections.	3
expand_bbox	Optional[Dict[str, int]]	Optional dictionary to expand the search area slightly beyond the region's exact bounds (e.g., {'left': 5, 'right': 5}).	None
**kwargs		Additional keyword arguments passed to find_text_based_tables (e.g., specific x/y tolerances).	{}

Returns:

Type	Description
Optional[Dict]	A dictionary containing 'horizontal_edges', 'vertical_edges', 'cells' (list of dicts),
Optional[Dict]	and 'intersections', or None if pdfplumber is unavailable or an error occurs.

natural_pdf.Region.apply_ocr(engine=None, *, options=None, languages=None, min_confidence=None, device=None, resolution=None, detect_only=False, apply_exclusions=True, replace=True, model=None, client=None, instructions=None, function=None, **kwargs)

Apply OCR to this region.

Parameters:

Name	Type	Description	Default
engine	Optional[str]	OCR engine — "rapidocr" (default), "easyocr", "surya", "paddle", "paddlevl", "doctr", "vlm", "dots" (dots.mocr), "glm_ocr", or "chandra". "dots", "glm_ocr", and "chandra" auto-select MLX on Apple Silicon, HF transformers elsewhere. Use engine="vlm" with model= and/or client= for VLM-based OCR.	None
options	Optional[Any]	Engine-specific option object.	None
languages	Optional[List[str]]	Language codes, e.g. ["en", "fr"].	None
min_confidence	Optional[float]	Discard results below this confidence (0–1).	None
device	Optional[str]	Compute device, e.g. "cpu" or "cuda".	None
resolution	Optional[int]	DPI for the region image sent to the engine.	None
detect_only	bool	Detect text regions without recognizing characters.	False
apply_exclusions	bool	Mask exclusion zones before OCR.	True
replace	bool	Remove existing OCR elements first.	True
model	Optional[str]	VLM model name — switches to VLM OCR pipeline.	None
client	Optional[Any]	OpenAI-compatible client — switches to VLM OCR pipeline.	None
instructions	Optional[str]	Additional instructions appended to the VLM prompt. Ignored when prompt is passed directly via **kwargs.	None
function	Optional[Callable]	Custom OCR callable that receives this Region and returns text.	None
**kwargs		Extra engine-specific parameters. Notable kwargs: layout (bool | str): Controls layout detection for VLM engines. True uses PP-DocLayout-V3 (block-level). A string like "rapidocr" or "paddle" uses that classic engine in detect-only mode for line-level boxes. False disables layout (full-page prompt). None (default) auto-detects based on model family. prompt (str): Custom VLM prompt. max_new_tokens (int): Max generation tokens for VLM.	{}

Returns:

Type	Description
'Region'	Self for chaining.

natural_pdf.Region.attr(name)

Get an attribute value from this region.

This method provides a consistent interface for attribute access that works on both individual regions/elements and collections. When called on a single region, it simply returns the attribute value. When called on collections, it extracts the attribute from all items.

Parameters:

Name	Type	Description	Default
name	str	The attribute name to retrieve (e.g., 'text', 'width', 'height')	required

Returns:

Type	Description
Any	The attribute value, or None if the attribute doesn't exist

Examples:

On a single region

region = page.find('text:contains("Title")').expand(10) width = region.attr('width') # Same as region.width

Consistent API across elements and regions

obj = page.find('*:contains("Title")') # Could be element or region text = obj.attr('text') # Works for both

natural_pdf.Region.below(height=None, width='full', include_source=False, until=None, include_endpoint=True, offset=None, apply_exclusions=True, multipage=None, within=None, anchor='start', **kwargs)

Select region below this region.

Parameters:

Name	Type	Description	Default
height	Optional[float]	Height of the region below, in points	None
width	str	Width mode - "full" for full page width or "element" for element width	'full'
include_source	bool	Whether to include this region in the result (default: False)	False
until	Optional[str]	Optional selector string to specify a lower boundary element	None
include_endpoint	bool	Whether to include the boundary element in the region (default: True)	True
offset	Optional[float]	Pixel offset when excluding source/endpoint (default: None, uses natural_pdf.options.layout.directional_offset)	None
multipage	Optional[bool]	Override global multipage behaviour; defaults to None meaning use global option.	None
**kwargs		Additional parameters	{}

Returns:

Type	Description
Optional[Union['Region', 'FlowRegion']]	Region object representing the area below, or None if within constraint has no overlap

natural_pdf.Region.clear_text_layer(*args, **kwargs)

Clear OCR results from the underlying managers and return totals.

natural_pdf.Region.clip(obj=None, left=None, top=None, right=None, bottom=None)

Clip this region to specific bounds, either from another object with bbox or explicit coordinates.

The clipped region will be constrained to not exceed the specified boundaries. You can provide either an object with bounding box properties, specific coordinates, or both. When both are provided, explicit coordinates take precedence.

Parameters:

Name	Type	Description	Default
obj	Optional[Any]	Optional object with bbox properties (Region, Element, TextElement, etc.)	None
left	Optional[float]	Optional left boundary (x0) to clip to	None
top	Optional[float]	Optional top boundary to clip to	None
right	Optional[float]	Optional right boundary (x1) to clip to	None
bottom	Optional[float]	Optional bottom boundary to clip to	None

Returns:

Type	Description
'Region'	New Region with bounds clipped to the specified constraints

Examples:

Clip to another region's bounds

clipped = region.clip(container_region)

Clip to any element's bounds

clipped = region.clip(text_element)

Clip to specific coordinates

clipped = region.clip(left=100, right=400)

Mix object bounds with specific overrides

clipped = region.clip(obj=container, bottom=page.height/2)

natural_pdf.Region.create_cells()

Create cell regions for a detected table by intersecting its row and column regions, and add them to the page.

Assumes child row and column regions are already present on the page.

Returns:

Type	Description
	Self for method chaining.

natural_pdf.Region.create_region(left, top, right, bottom, *, relative=True, label=None)

Create a child region anchored to this region.

Parameters:

Name	Type	Description	Default
left	float	Left coordinate. Interpreted relative to this region when relative is True.	required
top	float	Top coordinate.	required
right	float	Right coordinate.	required
bottom	float	Bottom coordinate.	required
relative	bool	When True (default), coordinates are treated as offsets from this region's bounds. Set to False to provide absolute page coordinates.	True
label	Optional[str]	Optional label to assign to the new region.	None

Returns:

Type	Description
'Region'	The newly created child region.

natural_pdf.Region.create_text_elements_from_ocr(*args, **kwargs)

Delegate to the OCR service for text element creation.

natural_pdf.Region.describe(**kwargs)

Describe the region content using the describe service.

natural_pdf.Region.exclude()

Exclude this region from text extraction and other operations.

This excludes everything within the region's bounds.

natural_pdf.Region.extract(*args, **kwargs)

Run structured extraction on this region.

Accepts the same arguments as :meth:Page.extract. Pass citations=True for per-field source citations within this region, confidence=True for per-field confidence scores, and instructions="..." for domain-specific LLM guidance.

Returns:

Type	Description
	class:StructuredDataResult

natural_pdf.Region.extract_ocr_elements(*, engine=None, options=None, languages=None, min_confidence=None, device=None, resolution=None)

Run OCR and return the resulting text elements without mutating this region.

Parameters:

Name	Type	Description	Default
engine	Optional[str]	OCR engine name (defaults follow the scope configuration).	None
options	Optional[Any]	Engine-specific options payload or dataclass.	None
languages	Optional[List[str]]	Optional list of language codes.	None
min_confidence	Optional[float]	Optional minimum confidence threshold.	None
device	Optional[str]	Preferred execution device.	None
resolution	Optional[int]	Explicit render DPI; falls back to config/context when omitted.	None

Returns:

Type	Description
List[Any]	List of text elements created from OCR (not added to the page).

natural_pdf.Region.extract_structured_data(*args, **kwargs)

Alias for :meth:extract.

natural_pdf.Region.extract_text(granularity='chars', apply_exclusions=True, debug=False, *, overlap='center', newlines=True, content_filter=None, return_textmap=False, **kwargs)

Extract text from this region, respecting page exclusions and using pdfplumber's layout engine (chars_to_textmap).

Parameters:

Name	Type	Description	Default
granularity	str	Level of text extraction - 'chars' (default) or 'words'. - 'chars': Character-by-character extraction (current behavior) - 'words': Word-level extraction with configurable overlap	'chars'
apply_exclusions	bool	Whether to apply exclusion regions defined on the parent page.	True
debug	bool	Enable verbose debugging output for filtering steps.	False
overlap	str	How to determine if words overlap with the region (only used when granularity='words'): - 'center': Word center point must be inside (default) - 'full': Word must be fully inside the region - 'partial': Any overlap includes the word	'center'
newlines	Union[bool, str]	Whether to strip newline characters from the extracted text.	True
content_filter		Optional content filter to exclude specific text patterns. Can be: - A regex pattern string (characters matching the pattern are EXCLUDED) - A callable that takes text and returns True to KEEP the character - A list of regex patterns (characters matching ANY pattern are EXCLUDED)	None
**kwargs		Additional layout parameters passed directly to pdfplumber's chars_to_textmap function (e.g., layout, x_density, y_density). See Page.extract_text docstring for more.	{}

Returns:

Type	Description
str	Extracted text as string, potentially with layout-based spacing.

natural_pdf.Region.get_children(selector=None)

Get immediate child regions, optionally filtered by selector.

Parameters:

Name	Type	Description	Default
selector		Optional selector to filter children	None

Returns:

Type	Description
	List of child regions matching the selector

natural_pdf.Region.get_descendants(selector=None)

Get all descendant regions (children, grandchildren, etc.), optionally filtered by selector.

Parameters:

Name	Type	Description	Default
selector		Optional selector to filter descendants	None

Returns:

Type	Description
	List of descendant regions matching the selector

natural_pdf.Region.get_elements(selector=None, apply_exclusions=True, **kwargs)

Get all elements within this region.

Parameters:

Name	Type	Description	Default
selector	Optional[str]	Optional selector to filter elements	None
apply_exclusions		Whether to apply exclusion regions	True
**kwargs		Additional parameters for element filtering	{}

Returns:

Type	Description
List['Element']	List of elements in the region

natural_pdf.Region.get_section_between(start_element=None, end_element=None, include_boundaries='both', orientation='vertical')

Get a section between two elements within this region.

Parameters:

Name	Type	Description	Default
start_element		Element marking the start of the section	None
end_element		Element marking the end of the section	None
include_boundaries		How to include boundary elements: 'start', 'end', 'both', or 'none'	'both'
orientation		'vertical' (default) or 'horizontal' - determines section direction	'vertical'

Returns:

Type	Description
	Region representing the section

natural_pdf.Region.get_sections(start_elements=None, end_elements=None, include_boundaries='both', orientation='vertical', **kwargs)

Get sections within this region based on start/end elements.

Parameters:

Name	Type	Description	Default
start_elements	Union[str, Sequence['Element'], 'ElementCollection', None]	Elements or selector string that mark the start of sections	None
end_elements	Union[str, Sequence['Element'], 'ElementCollection', None]	Elements or selector string that mark the end of sections	None
include_boundaries	str	How to include boundary elements: 'start', 'end', 'both', or 'none'	'both'
orientation	str	'vertical' (default) or 'horizontal' - determines section direction	'vertical'

Returns:

Type	Description
'ElementCollection[Region]'	List of Region objects representing the extracted sections

natural_pdf.Region.get_text_table_cells(snap_tolerance=10, join_tolerance=3, min_words_vertical=3, min_words_horizontal=1, intersection_tolerance=3, expand_bbox=None, **kwargs)

Analyzes text alignment to find table cells and returns them as temporary Region objects without adding them to the page.

Parameters:

Name	Type	Description	Default
snap_tolerance	int	Tolerance for snapping parallel lines.	10
join_tolerance	int	Tolerance for joining collinear lines.	3
min_words_vertical	int	Minimum words needed to define a vertical line.	3
min_words_horizontal	int	Minimum words needed to define a horizontal line.	1
intersection_tolerance	int	Tolerance for detecting line intersections.	3
expand_bbox	Optional[Dict[str, int]]	Optional dictionary to expand the search area slightly beyond the region's exact bounds (e.g., {'left': 5, 'right': 5}).	None
**kwargs		Additional keyword arguments passed to find_text_based_tables (e.g., specific x/y tolerances).	{}

Returns:

Type	Description
'ElementCollection[Region]'	An ElementCollection containing temporary Region objects for each detected cell,
'ElementCollection[Region]'	or an empty ElementCollection if no cells are found or an error occurs.

natural_pdf.Region.highlight(label=None, color=None, use_color_cycling=False, annotate=None, existing='append')

Highlight this region on the page.

Parameters:

Name	Type	Description	Default
label	Optional[str]	Optional label for the highlight	None
color	Optional[Union[Tuple, str]]	Color tuple/string for the highlight, or None to use automatic color	None
use_color_cycling	bool	Force color cycling even with no label (default: False)	False
annotate	Optional[List[str]]	List of attribute names to display on the highlight (e.g., ['confidence', 'type'])	None
existing	str	How to handle existing highlights ('append' or 'replace').	'append'

Returns:

Type	Description
None	None

natural_pdf.Region.inspect(limit=30, **kwargs)

Inspect the region content using the describe service.

natural_pdf.Region.left(width=None, height='element', include_source=False, until=None, include_endpoint=True, offset=None, apply_exclusions=True, multipage=None, within=None, anchor='start', **kwargs)

Select region to the left of this region.

Parameters:

Name	Type	Description	Default
width	Optional[float]	Width of the region to the left, in points	None
height	str	Height mode - "full" for full page height or "element" for element height	'element'
include_source	bool	Whether to include this region in the result (default: False)	False
until	Optional[str]	Optional selector string to specify a left boundary element	None
include_endpoint	bool	Whether to include the boundary element in the region (default: True)	True
offset	Optional[float]	Pixel offset when excluding source/endpoint (default: None, uses natural_pdf.options.layout.directional_offset)	None
multipage	Optional[bool]	Override global multipage behaviour; defaults to None meaning use global option.	None
**kwargs		Additional parameters	{}

Returns:

Type	Description
Optional[Union['Region', 'FlowRegion']]	Region object representing the area to the left, or None if within constraint has no overlap

natural_pdf.Region.region(left=None, top=None, right=None, bottom=None, width=None, height=None, relative=False)

Create a sub-region within this region using the same API as Page.region().

By default, coordinates are absolute (relative to the page), matching Page.region(). Set relative=True to use coordinates relative to this region's top-left corner.

Parameters:

Name	Type	Description	Default
left	Optional[float]	Left x-coordinate (absolute by default, or relative to region if relative=True)	None
top	Optional[float]	Top y-coordinate (absolute by default, or relative to region if relative=True)	None
right	Optional[float]	Right x-coordinate (absolute by default, or relative to region if relative=True)	None
bottom	Optional[float]	Bottom y-coordinate (absolute by default, or relative to region if relative=True)	None
width	Union[str, float, None]	Width definition (same as Page.region())	None
height	Optional[float]	Height of the region (same as Page.region())	None
relative	bool	If True, coordinates are relative to this region's top-left (0,0). If False (default), coordinates are absolute page coordinates.	False

Returns:

Type	Description
'Region'	Region object for the specified coordinates, clipped to this region's bounds

Examples:

Absolute coordinates (default) - same as page.region()

sub = region.region(left=100, top=200, width=50, height=30)

Relative to region's top-left

sub = region.region(left=10, top=10, width=50, height=30, relative=True)

Mix relative positioning with this region's bounds

sub = region.region(left=region.x0 + 10, width=50, height=30)

natural_pdf.Region.remove_ocr_elements(*args, **kwargs)

Remove OCR text from constituent regions.

natural_pdf.Region.right(width=None, height='element', include_source=False, until=None, include_endpoint=True, offset=None, apply_exclusions=True, multipage=None, within=None, anchor='start', **kwargs)

Select region to the right of this region.

Parameters:

Name	Type	Description	Default
width	Optional[float]	Width of the region to the right, in points	None
height	str	Height mode - "full" for full page height or "element" for element height	'element'
include_source	bool	Whether to include this region in the result (default: False)	False
until	Optional[str]	Optional selector string to specify a right boundary element	None
include_endpoint	bool	Whether to include the boundary element in the region (default: True)	True
offset	Optional[float]	Pixel offset when excluding source/endpoint (default: None, uses natural_pdf.options.layout.directional_offset)	None
multipage	Optional[bool]	Override global multipage behaviour; defaults to None meaning use global option.	None
**kwargs		Additional parameters	{}

Returns:

Type	Description
Optional[Union['Region', 'FlowRegion']]	Region object representing the area to the right, or None if within constraint has no overlap

natural_pdf.Region.rotate(angle=90, direction='clockwise')

Return a rotated view of this region as a new Region bound to a virtual page.

The rotation is applied to underlying pdfplumber objects (chars, rects, lines, images) before extraction, so text/tables are reprocessed in the new orientation. The original page/region are not mutated.

natural_pdf.Region.save(filename, resolution=None, labels=True, legend_position='right')

Save the page with this region highlighted to an image file.

Parameters:

Name	Type	Description	Default
filename	str	Path to save the image to	required
resolution	Optional[float]	Resolution in DPI for rendering (default: uses global options, fallback to 144 DPI)	None
labels	bool	Whether to include a legend for labels	True
legend_position	str	Position of the legend	'right'

Returns:

Type	Description
'Region'	Self for method chaining

natural_pdf.Region.save_image(filename, resolution=None, crop=False, include_highlights=True, **kwargs)

Save an image of just this region to a file.

Parameters:

Name	Type	Description	Default
filename	str	Path to save the image to	required
resolution	Optional[float]	Resolution in DPI for rendering (default: uses global options, fallback to 144 DPI)	None
crop	bool	If True, only crop the region without highlighting its boundaries	False
include_highlights	bool	Whether to include existing highlights (default: True)	True
**kwargs		Additional parameters for rendering	{}

Returns:

Type	Description
'Region'	Self for method chaining

natural_pdf.Region.save_pdf(path, method='crop')

Save this region as a PDF file. The region becomes a single page in the output.

Uses pikepdf to manipulate the original vector PDF, preserving selectable text.

Parameters:

Name	Type	Description	Default
path	str	Output file path for the PDF.	required
method	str	'crop' (default) sets CropBox to region bounds, producing a page sized to the region. 'whiteout' keeps the full page but draws white rectangles over areas outside the region.	'crop'

Returns:

Type	Description
'Region'	Self for method chaining.

Raises:

Type	Description
ImportError	If pikepdf is not installed.
ValueError	If method is not 'crop' or 'whiteout'.

Examples:

region = page.find('text:bold').below()
region.save_pdf("output.pdf")
region.save_pdf("whiteout.pdf", method="whiteout")

natural_pdf.Region.split(divider, **kwargs)

Divide this region into sections based on the provided divider elements.

Parameters:

Name	Type	Description	Default
divider		Elements or selector string that mark section boundaries	required
**kwargs		Additional parameters passed to get_sections() - include_boundaries: How to include boundary elements (default: 'start') - orientation: 'vertical' or 'horizontal' (default: 'vertical')	{}

Returns:

Type	Description
'ElementCollection[Region]'	ElementCollection of Region objects representing the sections

Example

Split a region by bold text

sections = region.split("text:bold")

Split horizontally by vertical lines

sections = region.split("line[orientation=vertical]", orientation="horizontal")

natural_pdf.Region.to_region()

Regions already satisfy the section surface; return self.

natural_pdf.Region.to_text_element(text_content=None, source_label='derived_from_region', object_type='word', default_font_size=10.0, default_font_name='RegionContent', confidence=None, add_to_page=False)

Creates a new TextElement object based on this region's geometry.

The text for the new TextElement can be provided directly, generated by a callback function, or left as None.

Parameters:

Name	Type	Description	Default
text_content	Optional[Union[str, Callable[['Region'], Optional[str]]]]	If a string, this will be the text of the new TextElement. If a callable, it will be called with this region instance and its return value (a string or None) will be the text. If None (default), the TextElement's text will be None.	None
source_label	str	The 'source' attribute for the new TextElement.	'derived_from_region'
object_type	str	The 'object_type' for the TextElement's data dict (e.g., "word", "char").	'word'
default_font_size	float	Placeholder font size if text is generated.	10.0
default_font_name	str	Placeholder font name if text is generated.	'RegionContent'
confidence	Optional[float]	Confidence score for the text. If text_content is None, defaults to 0.0. If text is provided/generated, defaults to 1.0 unless specified.	None
add_to_page	bool	If True, the created TextElement will be added to the region's parent page. (Default: False)	False

Returns:

Type	Description
'TextElement'	A new TextElement instance.

Raises:

Type	Description
ValueError	If the region does not have a valid 'page' attribute.

natural_pdf.Region.trim(padding=1, threshold=0.95, resolution=None, pre_shrink=0.5, method='any')

Trim whitespace from the edges of this region.

Similar to Python's string .strip() method. Stops at ANY non-white pixel by default.

Parameters:

Name	Type	Description	Default
padding	float	Padding to keep around content in PDF points (default: 1)	1
threshold	float	For pixel methods, threshold for whitespace detection (0.0-1.0, default: 0.95)	0.95
resolution	Optional[float]	Resolution for pixel-based methods in DPI (default: 144)	None
pre_shrink	float	For pixel methods, shrink before trim to avoid border artifacts (default: 0.5)	0.5
method	Literal['auto', 'elements', 'any', 'average']	Trimming strategy: - 'any' (default): Pixel-based, stop at ANY non-white pixel (like string.strip()) - 'auto': Use 'elements' if available, fall back to 'any' - 'elements': Use bounding boxes of text/elements (best for digital PDFs) - 'average': Pixel-based, use row/column averages (for noisy scans)	'any'

Returns:

Type	Description
'Region'	New Region with whitespace trimmed from all edges

Examples:

# Default: stop at any content pixel (like string.strip())
trimmed = region.trim()

# Use element bounding boxes (faster, but may include empty elements)
trimmed = region.trim(method='elements')

# For noisy scanned documents
trimmed = region.trim(method='average', threshold=0.9)

natural_pdf.Region.viewer(*, resolution=150, include_chars=False, include_attributes=None)

Create an interactive ipywidget viewer for this specific region.

The method renders the region to an image (cropped to the region bounds) and overlays all elements that intersect the region (optionally excluding noisy character-level elements). The resulting widget offers the same zoom / pan experience as :py:meth:Page.viewer but scoped to the region.

Parameters

resolution : int, default 150 Rendering resolution (DPI). This should match the value used by the page-level viewer so element scaling is accurate. include_chars : bool, default False Whether to include individual char elements in the overlay. These are often too dense for a meaningful visualisation so are skipped by default. include_attributes : list[str], optional Additional element attributes to expose in the info panel (on top of the default set used by the page viewer).

Returns

InteractiveViewerWidgetType | None The widget instance, or None if ipywidgets is not installed or an error occurred during creation.

natural_pdf.Region.within()

Context manager that constrains directional operations to this region.

When used as a context manager, all directional navigation operations (above, below, left, right) will be constrained to the bounds of this region.

Returns:

Name	Type	Description
RegionContext		A context manager that yields this region

Examples:

# Create a column region
left_col = page.region(right=page.width/2)

# All directional operations are constrained to left_col
with left_col.within() as col:
    header = col.find("text[size>14]")
    content = header.below(until="text[size>14]")
    # content will only include elements within left_col

# Operations outside the context are not constrained
full_page_below = header.below()  # Searches full page

natural_pdf.SearchError

Error during search operations.

natural_pdf.SelectorError

Error in selector parsing or matching.

Raised when: - Selector syntax is invalid - Selector matching fails - Referenced elements not found

natural_pdf.SelectorMatchError

Raised when selector matching encounters an error.

natural_pdf.SelectorParseError

Raised when a selector string cannot be parsed.

Functions

natural_pdf.configure_logging(level=logging.INFO, handler=None)

Configure logging for the natural_pdf package.

Parameters:

Name	Type	Description	Default
level		Logging level (e.g., logging.INFO, logging.DEBUG)	INFO
handler		Optional custom handler. Defaults to a StreamHandler.	None

natural_pdf.export_training_data(source, output_dir, *, selector='text', prompt='OCR this image. Return only the exact text.', resolution=150, padding=2, output_format='jsonl', overwrite=False, split=None, random_seed=42, include_metadata=True)

Export cropped text-element images and labels for OCR model training.

Parameters:

Name	Type	Description	Default
source	Union['PDF', 'PDFCollection', List['PDF']]	One or more PDFs to export from.	required
output_dir	str	Destination directory (created if needed).	required
selector	Optional[str]	CSS-like selector for which elements to crop (default "text").	'text'
prompt	str	Instruction string used in the conversations field.	'OCR this image. Return only the exact text.'
resolution	int	Render DPI for crop images.	150
padding	int	Points of padding around each element bbox.	2
output_format	Literal['jsonl', 'csv']	"jsonl" (ShareGPT + HF ImageFolder) or "csv".	'jsonl'
overwrite	bool	If False and output_dir already exists, raise FileExistsError.	False
split	Optional[float]	Train/validation split ratio (e.g. 0.9 for 90 % train). None means no split.	None
random_seed	int	Seed for reproducible train/val shuffling.	42
include_metadata	bool	Include source PDF path, page number, and bbox in output.	True

Returns:

Type	Description
dict	Summary dict: {"images": N, "skipped": M, "output_dir": path}.

natural_pdf.set_default_client(client, *, model=None)

Set a default OpenAI-compatible client (and optionally model) for VLM calls.

Parameters:

Name	Type	Description	Default
client	Any	An OpenAI-compatible client object.	required
model	Optional[str]	Optional model name to use with the client.	None

natural_pdf.set_option(name, value)

Set a global Natural PDF option.

Parameters:

Name	Type	Description	Default
name	str	Option name in dot notation (e.g., 'layout.auto_multipage')	required
value		New value for the option	required

Example

import natural_pdf as npdf npdf.set_option('layout.auto_multipage', True) npdf.set_option('ocr.engine', 'surya')