Layout Parser

https://layout-parser.readthedocs.io/en/latest/
Admin
Layout Parser is a Python library for detecting and parsing the layout of documents including text...
Tokens:56,695
Snippets:445
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Base LayoutParser Library

Source: https://layout-parser.readthedocs.io/en/latest/notes/installation.html

Installs the core LayoutParser library with support for data structures, visualization, and data loading/exporting.

```bash
pip install layoutparser
```

--------------------------------

### Install LayoutParser with PaddleDetection Support

Source: https://layout-parser.readthedocs.io/en/latest/notes/installation.html

Installs the base LayoutParser library along with dependencies for PaddleDetection-based layout detection models.

```bash
pip install "layoutparser[paddledetection]"
```

--------------------------------

### Install LayoutParser with EfficientDet Support

Source: https://layout-parser.readthedocs.io/en/latest/notes/installation.html

Installs the base LayoutParser library along with dependencies required for EfficientDet-based layout detection models.

```bash
pip install "layoutparser[effdet]"
```

--------------------------------

### Install LayoutParser with OCR Support

Source: https://layout-parser.readthedocs.io/en/latest/notes/installation.html

Installs the base LayoutParser library and dependencies for performing OCR tasks. This command is also used for downgrading google-cloud-vision if needed.

```bash
pip install "layoutparser[ocr]"
```

--------------------------------

### Install pycocotools

Source: https://layout-parser.readthedocs.io/en/latest/example/load_coco/index.html

Install the pycocotools library for handling COCO data format.

```bash
pip install pycocotools

```

--------------------------------

### Example TextBlock Structure

Source: https://layout-parser.readthedocs.io/en/latest/example/deep_layout_parsing/index.html

An example of a `TextBlock` object, showing its bounding box, type, and confidence score.

```python
TextBlock(block=Rectangle(x_1=646.4182739257812, y_1=1420.1715087890625, x_2=1132.8687744140625, y_2=1479.7222900390625), text=, id=None, type=Text, parent=None, next=None, score=0.9996440410614014)
```

--------------------------------

### Install LayoutParser with Detectron2 Support

Source: https://layout-parser.readthedocs.io/en/latest/notes/installation.html

Installs the base LayoutParser library and dependencies for Detectron2-based layout detection models. This command is for Mac OS and Linux users.

```bash
pip install layoutparser torchvision && pip install "git+https://github.com/facebookresearch/detectron2.git@v0.5#egg=detectron2"
```

--------------------------------

### Install Detectron2 for Mac OS and Linux

Source: https://layout-parser.readthedocs.io/en/latest/notes/installation.html

Installs LayoutParser, torchvision, and a specific version of Detectron2 from source for Mac OS and Linux users. This may take time as it compiles the library.

```bash
pip install layoutparser torchvision && pip install "detectron2@git+https://github.com/facebookresearch/detectron2.git@v0.5#egg=detectron2"
```

--------------------------------

### Initialize Tesseract OCR Agent

Source: https://layout-parser.readthedocs.io/en/latest/example/deep_layout_parsing/index.html

Initializes the Tesseract OCR engine for text recognition. Ensure OCR components are installed via 'pip install layoutparser[ocr]'.

```python
ocr_agent = lp.TesseractAgent(languages='eng')
    # Initialize the tesseract ocr engine. You might need
    # to install the OCR components in layoutparser:
    # pip install layoutparser[ocr]

```

--------------------------------

### Layout Iteration and Length

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout.html

Getting the number of elements and iterating over the Layout object.

```APIDOC
## __len__()

### Description
Returns the number of layout elements in the Layout.
```

```APIDOC
## __iter__()

### Description
Returns an iterator over the layout elements in the Layout.
```

--------------------------------

### Perform OCR and Return Full Response

Source: https://layout-parser.readthedocs.io/en/latest/example/parse_ocr/index.html

Use the OCR agent to detect text in an image. Set `return_response=True` to get the full response from the OCR engine, which includes detailed annotations.

```python
res = ocr_agent.detect(image, return_response=True)

# Alternative
# res = ocr_agent.detect('data/example-table.jpeg', return_response=True)
```

--------------------------------

### Initialize Detectron2LayoutModel

Source: https://layout-parser.readthedocs.io/en/latest/api_doc/models.html

Instantiate a Detectron2-based layout detection model using a configuration path. The model can then be used to detect layouts in images.

```python
import layoutparser as lp
model = lp.Detectron2LayoutModel('lp://HJDataset/faster_rcnn_R_50_FPN_3x/config')
```

--------------------------------

### Load and Use a Pre-trained Detectron2 Layout Model

Source: https://layout-parser.readthedocs.io/en/latest/notes/modelzoo.html

Instantiate a Detectron2-based layout model using a configuration path from the model catalog and a custom label map. The `extra_config` parameter allows for fine-tuning detection thresholds.

```python
import layoutparser as lp
model = lp.Detectron2LayoutModel(
            config_path ='lp://PubLayNet/faster_rcnn_R_50_FPN_3x/config', # In model catalog
            label_map   ={0: "Text", 1: "Title", 2: "List", 3:"Table", 4:"Figure"}, # In model`label_map`
            extra_config=["MODEL.ROI_HEADS.SCORE_THRESH_TEST", 0.8] # Optional
        )
model.detect(image)
```

--------------------------------

### Detectron2LayoutModel Initialization

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/models/detectron2/layoutmodel.html

Initializes a Detectron2-based layout detection model. Users can specify configuration paths, model weights, label maps, and device settings.

```APIDOC
## class Detectron2LayoutModel

### Description
Create a Detectron2-based Layout Detection Model

### Parameters
#### `config_path` (str)
 The path to the configuration file.
#### `model_path` (str, optional)
 The path to the saved weights of the model. If set, overwrite the weights in the configuration file. Defaults to `None`.
#### `label_map` (dict, optional)
 The map from the model prediction (ids) to real word labels (strings). If the config is from one of the supported datasets, Layout Parser will automatically initialize the label_map. Defaults to `None`.
#### `device` (str, optional)
 Whether to use cuda or cpu devices. If not set, LayoutParser will automatically determine the device to initialize the models on.
#### `extra_config` (list, optional)
 Extra configuration passed to the Detectron2 model configuration. The argument will be used in the `merge_from_list` function. Defaults to `[]`.

### Example
```python
import layoutparser as lp
model = lp.Detectron2LayoutModel('lp://HJDataset/faster_rcnn_R_50_FPN_3x/config')
model.detect(image)
```
```

--------------------------------

### Initialize GCVAgent with Language Hints

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/ocr/gcv_agent.html

Instantiate the GCVAgent, optionally providing a list of language codes to enhance OCR accuracy. The image format for sending to GCV can also be specified.

```python
agent = GCVAgent(languages=['en', 'zh-Hans'], ocr_image_decode_type=".png")
```

--------------------------------

### Get Quadrilateral Coordinates

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Returns the coordinates of the upper-left and lower-right corners of the bounding box that circumscribes the quadrilateral.

```python
@property
def coordinates(self):
        """
        Return the coordinates of the upper left and lower right corners points that
        define the circumscribed rectangle.

        Returns
            :obj:`Tuple(numeric)`: Output the numeric values of the coordinates in a Tuple of size four.
        """

        return cvt_points_to_coordinates(self.points)
```

--------------------------------

### Get Text from Layout Elements

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout.html

Extracts and returns a list of all text content from elements that have a 'text' attribute.

```python
return [ele.text for ele in self if hasattr(ele, "text")]
```

--------------------------------

### TesseractAgent.with_tesseract_executable

Source: https://layout-parser.readthedocs.io/en/latest/api_doc/ocr.html

Class method to initialize TesseractAgent with a specific Tesseract executable path.

```APIDOC
## with_tesseract_executable

### Description
Initializes the Tesseract OCR Agent with a specified Tesseract executable path.

### Parameters
- **tesseract_cmd_path** - Path to the Tesseract executable.
- **kwargs** - Additional keyword arguments to pass to the TesseractAgent constructor.
```

--------------------------------

### Get Attribute Information from Layout Elements

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout.html

Retrieves a list of values for a specified attribute from all elements that possess that attribute.

```python
return [getattr(ele, attr_name) for ele in self if hasattr(ele, attr_name)]
```

--------------------------------

### Get Quadrilateral Width

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Retrieves the width of the quadrilateral. Returns a user-defined width if provided, otherwise calculates it from the circumscribed rectangle.

```python
@property
def width(self):
        """
        Return the user defined width, otherwise the width of its circumscribed rectangle.

        Returns:
            :obj:`numeric`: Output the numeric value of the width.
        """

        if self._width is not None:
            return self._width
        return self.points[:, 0].max() - self.points[:, 0].min()
```

--------------------------------

### TesseractAgent Initialization

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/ocr/tesseract_agent.html

Initialize the TesseractAgent with specified languages and optional configurations.

```APIDOC
## TesseractAgent(languages="eng", **kwargs)

### Description
Create a Tesseract OCR Agent.

### Args
- **languages** (:obj:`list` or :obj:`str`, optional):
    You can specify the language code(s) of the documents to detect to improve accuracy. The supported language and their code can be found on `its github repo <https://github.com/tesseract-ocr/langdata>`_.
    It supports two formats: 1) you can pass in the languages code as a string of format like `"eng+fra"`, or 2) you can pack them as a list of strings `["eng", "fra"]`.
    Defaults to 'eng'.
```

--------------------------------

### Initializing a Layout Object

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout.html

Instantiate a Layout object with a list of blocks and optional page data. If no blocks are provided, an empty list is used.

```python
from layoutparser import Layout

# Initialize with blocks and page data
layout = Layout([block1, block2], page_data={'height': 100, 'width': 200})

# Initialize with an empty list of blocks
empty_layout = Layout()
```

--------------------------------

### Get Quadrilateral Height

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Retrieves the height of the quadrilateral. Returns a user-defined height if provided, otherwise calculates it from the circumscribed rectangle.

```python
@property
def height(self):
        """
        Return the user defined height, otherwise the height of its circumscribed rectangle.

        Returns:
            :obj:`numeric`: Output the numeric value of the height.
        """

        if self._height is not None:
            return self._height
        return self.points[:, 1].max() - self.points[:, 1].min()
```

--------------------------------

### Get Homogeneous Blocks

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout.html

Converts all elements in the layout to a common block type based on a predefined type casting hierarchy.

```python
return List[BaseLayoutElement]
```

--------------------------------

### Initialize TesseractAgent with Languages

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/ocr/tesseract_agent.html

Instantiate the TesseractAgent, specifying the language(s) for OCR. Languages can be provided as a single string (e.g., 'eng+fra') or a list of strings (e.g., ['eng', 'fra']).

```python
agent = TesseractAgent(languages="eng+fra")
```

--------------------------------

### Perform OCR and Get Only Text

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/ocr/tesseract_agent.html

Extract only the recognized text from an image using the detect method with return_only_text set to True.

```python
text = agent.detect(image, return_only_text=True)
```

--------------------------------

### Interval Class

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Represents the coordinate system of an interval, a block defined by a pair of start and end points on a designated axis.

```APIDOC
## class Interval(BaseCoordElement)

### Description
This class describes the coordinate system of an interval, a block defined by a pair of start and end point
on the designated axis and same length as the base canvas on the other axis.

### Args
- **start** (:obj:`numeric`): The coordinate of the start point on the designated axis.
- **end** (:obj:`numeric`): The end coordinate on the same axis as start.
- **axis** (:obj:`str`): The designated axis that the end points belong to.
- **canvas_height** (:obj:`numeric`, `optional`, defaults to 0): The height of the canvas that the interval is on.
- **canvas_width** (:obj:`numeric`, `optional`, defaults to 0): The width of the canvas that the interval is on.

### Methods
#### height
Calculate the height of the interval. If the interval is along the x-axis, the height will be the
height of the canvas, otherwise, it will be the difference between the start and end point.

Returns:
    :obj:`numeric`: Output the numeric value of the height.

#### width
Calculate the width of the interval. If the interval is along the y-axis, the width will be the
width of the canvas, otherwise, it will be the difference between the start and end point.

Returns:
    :obj:`numeric`: Output the numeric value of the width.

#### coordinates
This method considers an interval as a rectangle and calculates the coordinates of the upper left
and lower right corners to define the interval.

Returns:
    :obj:`Tuple(numeric)`:
        Output the numeric values of the coordinates in a Tuple of size four.

#### points
Return the coordinates of all four corners of the interval in a clockwise fashion
starting from the upper left.

Returns:
```

--------------------------------

### Load and Preprocess Image

Source: https://layout-parser.readthedocs.io/en/latest/example/deep_layout_parsing/index.html

Load an image using OpenCV and convert it from BGR to RGB format for processing.

```python
image = cv2.imread("data/paper-image.jpg")
image = image[..., ::-1]
    # Convert the image from BGR (cv2 default loading style)
    # to RGB
```

--------------------------------

### Interval Padding

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Applies padding to an Interval. Padding on axes not defined for the Interval will issue a warning. `safe_mode` ensures the padded start is not less than 0.

```python
def pad(self, left=0, right=0, top=0, bottom=0, safe_mode=True):

        if self.axis == "x":
            start = self.start - left
            end = self.end + right
            if top or bottom:
                warnings.warn(
                    f"Invalid padding top/bottom for an x axis {self.__class__.__name__}"
                )
        else:
            start = self.start - top
            end = self.end + bottom
            if left or right:
                warnings.warn(
                    f"Invalid padding right/left for a y axis {self.__class__.__name__}"
                )

        if safe_mode:
            start = max(0, start)

        return self.set(start=start, end=end)
```

--------------------------------

### Initialize Google Cloud Vision OCR Agent

Source: https://layout-parser.readthedocs.io/en/latest/example/parse_ocr/index.html

Initialize the GCVAgent with your Google Cloud Vision credentials and specify the languages for OCR. Ensure the credential path is correct.

```python
ocr_agent = lp.GCVAgent.with_credential("<path/to/your/credential>",
                                       languages = ['en'])
```

--------------------------------

### Layout Initialization

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout.html

Initializes a Layout object with a list of blocks and optional page data.

```APIDOC
## Layout(blocks: Optional[List] = None, *, page_data: Dict = None)

### Description
Initializes a Layout object. It stores layout elements in a list and related page data, providing APIs for batch processing.

### Parameters
#### Path Parameters
- **blocks** (list, optional): A list of layout element blocks. Defaults to None.
- **page_data** (Dict, optional): A dictionary storing page-related information like height and width. Defaults to None.
```

--------------------------------

### Interval Width Calculation

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Calculates the width of an interval. If the interval is along the y-axis, it returns the canvas width; otherwise, it returns the difference between the end and start points.

```python
if self.axis == "y":
    return self.canvas_width
else:
    return self.end - self.start
```

--------------------------------

### Interval Height Calculation

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Calculates the height of an interval. If the interval is along the x-axis, it returns the canvas height; otherwise, it returns the difference between the end and start points.

```python
if self.axis == "x":
    return self.canvas_height
else:
    return self.end - self.start
```

--------------------------------

### Specify Google Cloud Vision Credentials

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/ocr/gcv_agent.html

Use the `with_credential` class method to set the path to your Google Cloud service account key file before initializing the agent.

```python
GCVAgent.with_credential("/path/to/your/credential.json", languages=['en'])

```

--------------------------------

### Sort Layout Elements

Source: https://layout-parser.readthedocs.io/en/latest/api_doc/elements.html

Sorts the list of blocks within a Layout object based on a specified key and order. Use this to reorder elements, for example, by their vertical position.

```python
>>> import layoutparser as lp
>>> i = lp.Interval(4, 5, axis="y")
>>> l = lp.Layout([i, i.shift(2)])
>>> l.sort(key=lambda x: x.coordinates[1], reverse=True)
```

--------------------------------

### Initialize Quadrilateral with Points

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Initializes a Quadrilateral object with its four corner points. Supports various input formats for points, including numpy arrays and lists.

```python
def __init__(self, points: Union[np.ndarray, List, List[List]], height=None, width=None):

        if isinstance(points, np.ndarray):
            if points.shape != (4, 2):
                raise ValueError(f"Invalid points shape: {points.shape}.")
        elif isinstance(points, list):
            if len(points) == 8:
                points = np.array(points).reshape(4, 2)
            elif len(points) == 4 and isinstance(points[0], list):
                points = np.array(points)
            else:
                raise ValueError(
                    f"Invalid number of points element {len(points)}. Should be 8."
                )
        else:
            raise ValueError(
                f"Invalid input type for points {type(points)}."
                "Please make sure it is a list of np.ndarray."
            )

        self._points = points
        self._width = width
        self._height = height
```

--------------------------------

### Interval Class Initialization

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Initializes an Interval object representing a coordinate system on a specific axis. Ensures start is less than or equal to end and the axis is valid ('x' or 'y').

```python
assert start <= end, f"Invalid input for start and end. Start must <= end."
self.start = start
self.end = end

assert axis in ["x", "y"], f"Invalid axis {axis}. Axis must be in 'x' or 'y'"
self.axis = axis

self.canvas_height = canvas_height or 0
self.canvas_width = canvas_width or 0
```

--------------------------------

### Rectangle Properties and Methods

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Demonstrates accessing properties like height, width, coordinates, points, center, and area of a Rectangle object. Also shows methods for conditional positioning and relative positioning.

```python
rect = Rectangle(x_1=10, y_1=20, x_2=100, y_2=200)
print(rect.height)
print(rect.width)
print(rect.coordinates)
print(rect.points)
print(rect.center)
print(rect.area)
```

```python
interval = Interval(0, 10, axis='x')
new_rect = rect.condition_on(interval)
print(new_rect.coordinates)
```

```python
other_rect = Rectangle(50, 50, 150, 150)
new_rect = rect.condition_on(other_rect)
print(new_rect.coordinates)
```

```python
interval = Interval(0, 10, axis='x')
new_rect = rect.relative_to(interval)
print(new_rect.coordinates)
```

```python
other_rect = Rectangle(50, 50, 150, 150)
new_rect = rect.relative_to(other_rect)
print(new_rect.coordinates)
```

--------------------------------

### Sort and Assign IDs to Text Blocks

Source: https://layout-parser.readthedocs.io/en/latest/example/deep_layout_parsing/index.html

Sort text blocks based on their vertical position and assign sequential IDs. This example sorts blocks into left and right columns.

```python
h, w = image.shape[:2]

left_interval = lp.Interval(0, w/2*1.05, axis='x').put_on_canvas(image)

left_blocks = text_blocks.filter_by(left_interval, center=True)
left_blocks.sort(key = lambda b:b.coordinates[1], inplace=True)

right_blocks = [b for b in text_blocks if b not in left_blocks]
right_blocks.sort(key = lambda b:b.coordinates[1], inplace=True)

# And finally combine the two list and add the index
# according to the order
text_blocks = lp.Layout([b.set(id = idx) for idx, b in enumerate(left_blocks + right_blocks)])
```

--------------------------------

### Detectron2LayoutModel

Source: https://layout-parser.readthedocs.io/en/latest/api_doc/models.html

Initializes a Detectron2-based layout detection model. This class allows users to load pre-trained Detectron2 models for layout analysis.

```APIDOC
## class layoutparser.models.Detectron2LayoutModel

### Description
Create a Detectron2-based Layout Detection Model.

### Parameters
* **config_path** (str) – The path to the configuration file.
* **model_path** (str, None) – The path to the saved weights of the model. If set, overwrite the weights in the configuration file. Defaults to None.
* **label_map** (dict, optional) – The map from the model prediction (ids) to real word labels (strings). If the config is from one of the supported datasets, Layout Parser will automatically initialize the label_map. Defaults to None.
* **device** (str, optional) – Whether to use cuda or cpu devices. If not set, LayoutParser will automatically determine the device to initialize the models on.
* **extra_config** (list, optional) – Extra configuration passed to the Detectron2 model configuration. The argument will be used in the merge_from_list function. Defaults to [].

### Example
```python
>>> import layoutparser as lp
>>> model = lp.Detectron2LayoutModel('lp://HJDataset/faster_rcnn_R_50_FPN_3x/config')
>>> model.detect(image)
```
```

--------------------------------

### Load a pre-trained Detectron2 layout model

Source: https://layout-parser.readthedocs.io/en/latest/example/load_coco/index.html

Loads a Detectron2-based layout detection model from LayoutParser, specifying a confidence threshold and a custom label map.

```python
model = lp.Detectron2LayoutModel('lp://PubLayNet/faster_rcnn_R_50_FPN_3x/config',
                                 extra_config=["MODEL.ROI_HEADS.SCORE_THRESH_TEST", 0.8],
                                 label_map={0: "text", 1: "title", 2: "list", 3:"table", 4:"figure"})

```

--------------------------------

### Perform OCR and Get Raw Response

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/ocr/tesseract_agent.html

Use the detect method to send an image for OCR and retrieve the full response from Tesseract, including text and bounding box data.

```python
response = agent.detect(image, return_response=True)
```

--------------------------------

### GCVAgent Initialization

Source: https://layout-parser.readthedocs.io/en/latest/api_doc/ocr.html

Initializes a GCVAgent for Google Cloud Vision OCR. Supports specifying languages for improved accuracy and an image decode type for preprocessing.

```APIDOC
## GCVAgent

### Description
A wrapper for Google Cloud Vision (GCV) Text Detection APIs.

### Parameters
* **languages** (list, optional) – You can specify the language code of the documents to detect to improve accuracy. Defaults to None.
* **ocr_image_decode_type** (str, optional) – The format to convert the input image to before sending for GCV OCR. Defaults to ".png".
    * ".png" is suggested as it does not compress the image.
    * But ".jpg" could also be a good choice if the input image is very large.

### Class Method: with_credential

#### Description
Specifiy the credential to use for the GCV OCR API.

#### Parameters
* **credential_path** (str) – The path to the credential file
```

--------------------------------

### Interval Class

Source: https://layout-parser.readthedocs.io/en/latest/api_doc/elements.html

The Interval class represents a coordinate system for a block defined by start and end points on a designated axis. It includes properties for dimensions and methods for geometric operations.

```APIDOC
## Interval Class

### Description
This class describes the coordinate system of an interval, a block defined by a pair of start and end point on the designated axis and same length as the base canvas on the other axis.

### Parameters
* **start** (`numeric`) – The coordinate of the start point on the designated axis.
* **end** (`numeric`) – The end coordinate on the same axis as start.
* **axis** (`str`) – The designated axis that the end points belong to.
* **canvas_height** (`numeric`, optional, defaults to 0) – The height of the canvas that the interval is on.
* **canvas_width** (`numeric`, optional, defaults to 0) – The width of the canvas that the interval is on.

### Properties
* **height** (`numeric`) – Calculate the height of the interval. If the interval is along the x-axis, the height will be the height of the canvas, otherwise, it will be the difference between the start and end point.
* **width** (`numeric`) – Calculate the width of the interval. If the interval is along the y-axis, the width will be the width of the canvas, otherwise, it will be the difference between the start and end point.
* **coordinates** (`Tuple(numeric)`) – This method considers an interval as a rectangle and calculates the coordinates of the upper left and lower right corners to define the interval.
* **points** (`Numpy array`) – Return the coordinates of all four corners of the interval in a clockwise fashion starting from the upper left.
* **center** (`Tuple(numeric)`) – Calculate the mid-point between the start and end point.
* **area** (`numeric`) – Return the area of the covered region of the interval. The area is bounded to the canvas. If the interval is put on a canvas, the area equals to interval width * canvas height (axis=’x’) or interval height * canvas width (axis=’y’). Otherwise, the area is zero.

### Methods
* **put_on_canvas** (`Interval`) – Set the height and the width of the canvas that the interval is on.
  * Parameters:
    * **canvas** (`Numpy array` or `BaseCoordElement` or `PIL.Image.Image`) – The base element that the interval is on. The numpy array should be the format of [height, width].
* **condition_on** (`BaseCoordElement`) – Given the current element in relative coordinates to another element which is in absolute coordinates, generate a new element of the current element in absolute coordinates.
  * Parameters:
    * **other** (`BaseCoordElement`) – The other layout element involved in the geometric operations.
  * Raises:
    * **Exception** – Raise error when the input type of the other element is invalid.
* **relative_to** (`BaseCoordElement`) – Given the current element and another element both in absolute coordinates, generate a new element of the current element in relative coordinates to the other element.
  * Parameters:
    * **other** (`BaseCoordElement`) – The other layout element involved in the geometric operations.
  * Raises:
    * **Exception** – Raise error when the input type of the other element is invalid.
* **is_in** (`bool`) – Identify whether the current element is within another element.
  * Parameters:
    * **other** (`BaseCoordElement`) – The other layout element involved in the geometric operations.
    * **soft_margin** (`dict`, optional, defaults to {})
    * **center** (`bool`, optional, defaults to False)
* **intersect** (`layoutparser.elements.base.BaseCoordElement`) – Intersect the current shape with the other object, with operations defined in Shape Operations.
  * Parameters:
    * **other** (`layoutparser.elements.base.BaseCoordElement`)
    * **strict** (`bool`, optional, defaults to True)
* **union** (`layoutparser.elements.base.BaseCoordElement`) – Union the current shape with the other object, with operations defined in Shape Operations.
  * Parameters:
    * **other** (`layoutparser.elements.base.BaseCoordElement`)
    * **strict** (`bool`, optional, defaults to True)
```

--------------------------------

### Load and Display Image

Source: https://layout-parser.readthedocs.io/en/latest/example/parse_ocr/index.html

Load an image using OpenCV and display it using Matplotlib. This step is for visualizing the input image before OCR processing.

```python
image = cv2.imread('data/example-table.jpeg')
plt.imshow(image);
```

--------------------------------

### Group Rows by Hard-coded Parameters

Source: https://layout-parser.readthedocs.io/en/latest/example/parse_ocr/index.html

Iterates through rows to fetch row-based information using predefined parameters like start y-coordinate, number of rows, and height. This method is suitable when the row structure is consistent and known.

```python
y_0 = 307
n_rows = 13
height = 41
y_1 = y_0+n_rows*height

row = []
for y in range(y_0, y_1, height):

    interval = lp.Interval(y,y+height, axis='y')
    residence_row = filtered_residence.
        filter_by(interval).
        get_texts()

    lotno_row = filter_lotno.
        filter_by(interval).
        get_texts()

    row.append([''.join(residence_row), ''.join(lotno_row)])

```

```python
row

```

```python
[['LosAngeles', 'E6037'],
 ['LosAngeles', 'E6037'],
 ['LosAngeles', 'E6037'],
 ['Oakland', '?'],
 ['Riverside', 'E5928'],
 ['LosAngeles', 'E6037'],
 ['LongBeach', '?E6038'],
 ['LongBeach', '11'],
 ['Maricopa', '?E5928'],
 ['FallsChurch', '8122-649334'],
 ['ChaseCity', '8122-64933?'],
 ['Houston', '7078-649343'],
 ['Scott', '7078-649342']]

```

--------------------------------

### TextBlock Initialization with BaseCoordElement

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Initializes a TextBlock with a BaseCoordElement and optional text, ID, type, parent, next, and score. Ensures the block is an instance of BaseCoordElement.

```python
assert isinstance(block, BaseCoordElement)
self.block = block

self.text = text
self.id = id
self.type = type
self.parent = parent
self.next = next
self.score = score
```

--------------------------------

### lp.load_pdf

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/io/pdf.html

Loads text and optionally images from a PDF file. It can extract tokens from each page and, if `load_images` is True, also renders and returns the page images. The DPI can be specified for image rendering, which also affects the scaling of the extracted layout to match the image dimensions.

```APIDOC
## lp.load_pdf

### Description
Loads text and optionally images from a PDF file. It can extract tokens from each page and, if `load_images` is True, also renders and returns the page images. The DPI can be specified for image rendering, which also affects the scaling of the extracted layout to match the image dimensions.

### Parameters
- **filename** (str): Path to the PDF file.
- **load_images** (bool, optional): If True, also loads and returns page images. Defaults to False.
- **extra_attrs** (List[str], optional): List of extra attributes to extract for each word. Defaults to `["fontname", "size"]`.
- **dpi** (int, optional): DPI for rendering images when `load_images` is True. Defaults to `DEFAULT_PDF_DPI=72`.

### Returns
- **List[Layout]**: A list where each element contains all tokens for a single page, ordered by page.
- **Tuple[List[Layout], List["Image.Image"]]**: If `load_images` is True, returns the list of layouts and a list of corresponding page images.

### Examples
```python
import layoutparser as lp

# Load only text tokens
pdf_layout = lp.load_pdf("path/to/pdf")
print(pdf_layout[0]) # Layout for page 0

# Load text tokens and images
pdf_layout, pdf_images = lp.load_pdf("path/to/pdf", load_images=True)
# Draw a box on the first page image using its layout
lp.draw_box(pdf_images[0], pdf_layout[0])
```
```

--------------------------------

### Process and visualize annotations for a random image

Source: https://layout-parser.readthedocs.io/en/latest/example/load_coco/index.html

Selects a random image, loads its annotations, reads the image, converts annotations to LayoutParser objects, and visualizes the bounding boxes.

```python
color_map = {
    'text':   'red',
    'title':  'blue',
    'list':   'green',
    'table':  'purple',
    'figure': 'pink',
}


for image_id in random.sample(coco.imgs.keys(), 1):
    image_info = coco.imgs[image_id]
    annotations = coco.loadAnns(coco.getAnnIds([image_id]))

    image = cv2.imread(f'{COCO_IMG_PATH}/{image_info["file_name"]}')
    layout = load_coco_annotations(annotations, coco)

    viz = lp.draw_box(image, layout, color_map=color_map)
    display(viz) # show the results

```

--------------------------------

### layoutparser.elements.Layout Methods

Source: https://layout-parser.readthedocs.io/en/latest/genindex.html

Methods available for Layout objects in layoutparser.elements.

```APIDOC
## sort()

### Description
Sorts the elements within a Layout.

### Method
`sort()`

### Parameters
(No specific parameters documented in the source for this method.)

### Request Example
(No request example provided in the source.)

### Response
(No specific response details documented in the source.)
```

```APIDOC
## to_dataframe()

### Description
Converts a Layout to a pandas DataFrame.

### Method
`to_dataframe()`

### Parameters
(No specific parameters documented in the source for this method.)

### Request Example
(No request example provided in the source.)

### Response
(No specific response details documented in the source.)
```

```APIDOC
## to_dict()

### Description
Converts a Layout to a dictionary.

### Method
`to_dict()`

### Parameters
(No specific parameters documented in the source for this method.)

### Request Example
(No request example provided in the source.)

### Response
(No specific response details documented in the source.)
```

--------------------------------

### Initialize COCO object and load annotations

Source: https://layout-parser.readthedocs.io/en/latest/example/load_coco/index.html

Initialize the COCO object with the path to the annotations file and load annotations into memory.

```python
COCO_ANNO_PATH = 'data/publaynet/annotations/val.json'
COCO_IMG_PATH  = 'data/publaynet/val'

coco = COCO(COCO_ANNO_PATH)

```

--------------------------------

### Import Libraries for Layout Parsing

Source: https://layout-parser.readthedocs.io/en/latest/example/deep_layout_parsing/index.html

Import necessary libraries for layout parsing and image manipulation.

```python
import layoutparser as lp
import cv2
```

--------------------------------

### Initialize TextBlock from Dictionary

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Initializes a TextBlock from a dictionary representation. It determines the block type and attributes from the dictionary and loads associated features.

```python
@classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "TextBlock":
        """Initialize the textblock based on the dictionary representation.
        It generate the block based on the `block_type` and `block_attr`,
        and loads the textblock specific features from the dict.

        Args:
            data (:obj:`dict`): The dictionary representation of the object
        """
        assert (
            data["block_type"] in BASECOORD_ELEMENT_NAMEMAP
        ), f"Invalid block_type {data['block_type']}"

        block = BASECOORD_ELEMENT_NAMEMAP[data["block_type"]].from_dict(data)

        return cls(block, **{f: data.get(f, None) for f in cls._features})
```

--------------------------------

### Set Tesseract Executable Path

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/ocr/tesseract_agent.html

Configure the path to the Tesseract executable if it's not in the system's PATH. This class method should be called before initializing the agent.

```python
TesseractAgent.with_tesseract_executable(tesseract_cmd_path="/usr/bin/tesseract")
```

--------------------------------

### Load Detectron2 Layout Model

Source: https://layout-parser.readthedocs.io/en/latest/example/deep_layout_parsing/index.html

Load a pre-trained Detectron2 layout model from the layoutparser model zoo. Adjust the score threshold using extra_config.

```python
model = lp.Detectron2LayoutModel('lp://PubLayNet/faster_rcnn_R_50_FPN_3x/config',
                                 extra_config=["MODEL.ROI_HEADS.SCORE_THRESH_TEST", 0.8],
                                 label_map={0: "Text", 1: "Title", 2: "List", 3:"Table", 4:"Figure"})
    # Load the deep layout model from the layoutparser API
    # For all the supported model, please check the Model
    # Zoo Page: https://layout-parser.readthedocs.io/en/latest/notes/modelzoo.html
```

--------------------------------

### layoutparser.elements.Quadrilateral Methods

Source: https://layout-parser.readthedocs.io/en/latest/genindex.html

Methods available for Quadrilateral objects in layoutparser.elements.

```APIDOC
## to_interval()

### Description
Converts a Quadrilateral to an Interval.

### Method
`to_interval()`

### Parameters
(No specific parameters documented in the source for this method.)

### Request Example
(No request example provided in the source.)

### Response
(No specific response details documented in the source.)
```

--------------------------------

### Draw Detected Layout Boxes

Source: https://layout-parser.readthedocs.io/en/latest/example/deep_layout_parsing/index.html

Visualize the detected layout by drawing bounding boxes on the image.

```python
lp.draw_box(image, layout, box_width=3)
    # Show the detected layout of the input image
```

--------------------------------

### Load OCR Response from File

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/ocr/tesseract_agent.html

Loads an OCR response object from a specified file using pickle. Ensure the file exists and is a valid pickle file.

```python
    @staticmethod
    def load_response(filename):
        with open(filename, "rb") as fp:
            res = pickle.load(fp)
        return res
```

--------------------------------

### Image Loading and Conversion

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/models/detectron2/layoutmodel.html

Handles the loading and conversion of input images to a format suitable for the Detectron2 model, ensuring the image is in RGB format and represented as a numpy array.

```python
image = self.image_loader(image)
```

--------------------------------

### TesseractAgent Initialization

Source: https://layout-parser.readthedocs.io/en/latest/api_doc/ocr.html

Initializes the Tesseract OCR Agent. You can specify languages to improve accuracy. It supports language codes as a string (e.g., 'eng+fra') or a list of strings (e.g., ['eng', 'fra']).

```APIDOC
## TesseractAgent

### Description
A wrapper for Tesseract Text Detection APIs based on PyTesseract.

### Parameters
- **languages** (list or str, optional) – You can specify the language code(s) of the documents to detect to improve accuracy. The supported language and their code can be found on its github repo. It supports two formats: 1) you can pass in the languages code as a string of format like “eng+fra”, or 2) you can pack them as a list of strings [“eng”, “fra”]. Defaults to ‘eng’.

### Dependencies
- `pytesseract`
```

--------------------------------

### Check Layout Type

Source: https://layout-parser.readthedocs.io/en/latest/example/deep_layout_parsing/index.html

Verify the type of the detected layout object. It should be a `Layout` instance.

```python
type(layout)
```

--------------------------------

### layoutparser.elements.TextBlock Methods

Source: https://layout-parser.readthedocs.io/en/latest/genindex.html

Methods available for TextBlock objects in layoutparser.elements.

```APIDOC
## to_interval()

### Description
Converts a TextBlock to an Interval.

### Method
`to_interval()`

### Parameters
(No specific parameters documented in the source for this method.)

### Request Example
(No request example provided in the source.)

### Response
(No specific response details documented in the source.)
```

--------------------------------

### Load PDF Layout

Source: https://layout-parser.readthedocs.io/en/latest/api_doc/io.html

Load tokens for each page from a PDF file. Use `load_images=True` to also retrieve page screenshots.

```python
import layoutparser as lp
pdf_layout = lp.load_pdf("path/to/pdf")
pdf_layout[0] # the layout for page 0
```

```python
pdf_layout, pdf_images = lp.load_pdf("path/to/pdf", load_images=True)
lp.draw_box(pdf_images[0], pdf_layout[0])
```

--------------------------------

### load_dict

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/io/basic.html

Loads a dictionary or a list of dictionaries representing layout data and converts it into a BaseLayoutElement or Layout object.

```APIDOC
## load_dict

### Description
Loads a dict of list of dict representations of some layout data, automatically parse its type, and save it as any of BaseLayoutElement or Layout datatype.

### Arguments
- **data** (Union[Dict, List]): A dict of list of dict representations of the layout data.

### Raises
- ValueError: If the data format is incompatible with the layout-data-JSON format.
- ValueError: If any `block_type` name is not in the available list of layout element names.

### Returns
- Union[BaseLayoutElement, Layout]: Based on the dict format, it will automatically parse the type of the data and load it accordingly.
```

--------------------------------

### Quadrilateral Methods

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout_elements.html

Provides methods for geometric operations like intersection, union, padding, shifting, scaling, and conversion to other shapes.

```APIDOC
## Quadrilateral.intersect(other: BaseCoordElement, strict: bool = True)

### Description
Calculates the intersection between a Quadrilateral and another coordinate element. If `strict` is True, it raises an error for unsupported shapes. If `strict` is False, it converts Quadrilaterals to Rectangles for intersection calculation.

### Method
`intersect`

### Parameters
- **other** (BaseCoordElement) - The other coordinate element to intersect with.
- **strict** (bool) - If True, raises an error for unsupported shapes. Defaults to True.

### Response
Returns a new shape representing the intersection.

## Quadrilateral.union(other: BaseCoordElement, strict: bool = True)

### Description
Calculates the union between a Quadrilateral and another coordinate element. Similar to `intersect`, `strict` controls behavior with unsupported shapes.

### Method
`union`

### Parameters
- **other** (BaseCoordElement) - The other coordinate element to union with.
- **strict** (bool) - If True, raises an error for unsupported shapes. Defaults to True.

### Response
Returns a new shape representing the union.

## Quadrilateral.pad(left=0, right=0, top=0, bottom=0, safe_mode=True)

### Description
Applies padding to the Quadrilateral.

### Method
`pad`

### Parameters
- **left** (int) - Padding on the left side.
- **right** (int) - Padding on the right side.
- **top** (int) - Padding on the top side.
- **bottom** (int) - Padding on the bottom side.
- **safe_mode** (bool) - If True, ensures points do not go below 0. Defaults to True.

### Response
Returns a new Quadrilateral with applied padding.

## Quadrilateral.shift(shift_distance=0)

### Description
Shifts the Quadrilateral by a given distance.

### Method
`shift`

### Parameters
- **shift_distance** (int or Iterable) - The distance to shift. Can be a single value for both x and y, or a list/tuple of two values [x, y].

### Response
Returns a new Quadrilateral shifted by the specified distance.

## Quadrilateral.scale(scale_factor=1)

### Description
Scales the Quadrilateral by a given factor.

### Method
`scale`

### Parameters
- **scale_factor** (float or Iterable) - The factor to scale by. Can be a single value for both x and y, or a list/tuple of two values [x, y].

### Response
Returns a new Quadrilateral scaled by the specified factor.

## Quadrilateral.crop_image(image)

### Description
Crops an image using the Quadrilateral's points.

### Method
`crop_image`

### Parameters
- **image** (:obj:`Numpy array`) - The input image as a NumPy array.

### Response
- :obj:`Numpy array`: The cropped image.

## Quadrilateral.to_interval(axis, **kwargs)

### Description
Converts the Quadrilateral to an Interval along a specified axis.

### Method
`to_interval`

### Parameters
- **axis** (str) - The axis to convert to ('x' or 'y').
- **kwargs** - Additional keyword arguments to pass to the Interval constructor.

### Response
- :obj:`Interval`: An Interval object representing the Quadrilateral along the specified axis.

## Quadrilateral.to_rectangle()

### Description
Converts the Quadrilateral to a Rectangle.

### Method
`to_rectangle`

### Response
- :obj:`Rectangle`: A Rectangle object representing the Quadrilateral.

## Quadrilateral.to_dict() -> Dict[str, Any]

### Description
Generates a dictionary representation of the Quadrilateral object.

### Method
`to_dict`

### Response
- :obj:`Dict[str, Any]`: A dictionary containing the block type and points of the Quadrilateral.
```

--------------------------------

### Layout Copying

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/elements/layout.html

Creating a shallow copy of the Layout object.

```APIDOC
## copy()

### Description
Returns a shallow copy of the Layout object.
```

--------------------------------

### detect

Source: https://layout-parser.readthedocs.io/en/latest/api_doc/models.html

Detects the layout of a given image using the initialized model.

```APIDOC
## method detect

### Description
Detect the layout of a given image.

### Parameters
* **image** (np.ndarray or PIL.Image) – The input image to detect.

### Returns
The detected layout of the input image

### Return Type
`Layout`
```

--------------------------------

### Detect Method

Source: https://layout-parser.readthedocs.io/en/latest/_modules/layoutparser/models/detectron2/layoutmodel.html

Detects the layout of a given image using the initialized Detectron2 model.

```APIDOC
## Detectron2LayoutModel.detect

### Description
Detect the layout of a given image.

### Parameters
#### `image` (np.ndarray or PIL.Image)
 The input image to detect.

### Returns
#### :obj:`~layoutparser.Layout`
 The detected layout of the input image
```

--------------------------------

### Layout Instance Type

Source: https://layout-parser.readthedocs.io/en/latest/example/deep_layout_parsing/index.html

The detected layout is an instance of `layoutparser.elements.Layout`, which inherits from list.

```python
layoutparser.elements.Layout
```
Tokens:
Raw