custom-layoutparser 0.1.0__py3-none-any.whl

layoutparser/elements/layout_elements.py

@@ -0,0 +1,1352 @@
+# Copyright 2021 The Layout Parser team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import List, Union, Dict, Dict, Any, Optional, Tuple
+from collections.abc import Iterable
+from copy import copy
+from inspect import getmembers, isfunction
+import warnings
+import functools
+
+import numpy as np
+import pandas as pd
+from PIL import Image
+from cv2 import getPerspectiveTransform as _getPerspectiveTransform
+from cv2 import warpPerspective as _warpPerspective
+
+from .base import BaseCoordElement, BaseLayoutElement
+from .utils import (
+    cvt_coordinates_to_points,
+    cvt_points_to_coordinates,
+    perspective_transformation,
+    vertice_in_polygon,
+    polygon_area,
+)
+from .errors import NotSupportedShapeError, InvalidShapeError
+
+
+def mixin_textblock_meta(func):
+    @functools.wraps(func)
+    def wrap(self, *args, **kwargs):
+        out = func(self, *args, **kwargs)
+        if isinstance(out, BaseCoordElement):
+            self = copy(self)
+            self.block = out
+            return self
+
+    return wrap
+
+
+def inherit_docstrings(cls=None, *, base_class=None):
+
+    # Refer to https://stackoverflow.com/a/17393254
+    if cls is None:
+        return functools.partial(inherit_docstrings, base_class=base_class)
+
+    for name, func in getmembers(cls, isfunction):
+        if func.__doc__:
+            continue
+        if base_class == None:
+            for parent in cls.__mro__[1:]:
+                if hasattr(parent, name):
+                    func.__doc__ = getattr(parent, name).__doc__
+                    break
+        else:
+            if hasattr(base_class, name):
+                func.__doc__ = getattr(base_class, name).__doc__
+
+    return cls
+
+
+def support_textblock(func):
+    @functools.wraps(func)
+    def wrap(self, other, *args, **kwargs):
+        if isinstance(other, TextBlock):
+            other = other.block
+        out = func(self, other, *args, **kwargs)
+        return out
+
+    return wrap
+
+
+@inherit_docstrings
+class Interval(BaseCoordElement):
+    """
+    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.
+    """
+
+    _name = "interval"
+    _features = ["start", "end", "axis", "canvas_height", "canvas_width"]
+
+    def __init__(self, start, end, axis, canvas_height=None, canvas_width=None):
+
+        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
+
+    @property
+    def height(self):
+        """
+        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.
+        """
+
+        if self.axis == "x":
+            return self.canvas_height
+        else:
+            return self.end - self.start
+
+    @property
+    def width(self):
+        """
+        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.
+        """
+
+        if self.axis == "y":
+            return self.canvas_width
+        else:
+            return self.end - self.start
+
+    @property
+    def coordinates(self):
+        """
+        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.
+        """
+
+        if self.axis == "x":
+            coords = (self.start, 0, self.end, self.canvas_height)
+        else:
+            coords = (0, self.start, self.canvas_width, self.end)
+
+        return coords
+
+    @property
+    def points(self):
+        """
+        Return the coordinates of all four corners of the interval in a clockwise fashion
+        starting from the upper left.
+
+        Returns:
+            :obj:`Numpy array`: A Numpy array of shape 4x2 containing the coordinates.
+        """
+
+        return cvt_coordinates_to_points(self.coordinates)
+
+    @property
+    def center(self):
+        """
+        Calculate the mid-point between the start and end point.
+
+        Returns:
+            :obj:`Tuple(numeric)`: Returns of coordinate of the center.
+        """
+
+        return (self.start + self.end) / 2.0
+
+    @property
+    def area(self):
+        """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.
+        """
+        return self.height * self.width
+
+    def put_on_canvas(self, canvas):
+        """
+        Set the height and the width of the canvas that the interval is on.
+
+        Args:
+            canvas (:obj:`Numpy array` or :obj:`BaseCoordElement` or :obj:`PIL.Image.Image`):
+                The base element that the interval is on. The numpy array should be the
+                format of `[height, width]`.
+
+        Returns:
+            :obj:`Interval`:
+                A copy of the current Interval with its canvas height and width set to
+                those of the input canvas.
+        """
+
+        if isinstance(canvas, np.ndarray):
+            h, w = canvas.shape[:2]
+        elif isinstance(canvas, BaseCoordElement):
+            h, w = canvas.height, canvas.width
+        elif isinstance(canvas, Image.Image):
+            w, h = canvas.size
+        else:
+            raise NotImplementedError
+
+        return self.set(canvas_height=h, canvas_width=w)
+
+    @support_textblock
+    def condition_on(self, other):
+
+        if isinstance(other, Interval):
+            if other.axis == self.axis:
+                d = other.start
+                # Reset the canvas size in the absolute coordinates
+                return self.__class__(self.start + d, self.end + d, self.axis)
+            else:
+                return copy(self)
+
+        elif isinstance(other, Rectangle):
+
+            return self.put_on_canvas(other).to_rectangle().condition_on(other)
+
+        elif isinstance(other, Quadrilateral):
+
+            return self.put_on_canvas(other).to_quadrilateral().condition_on(other)
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def relative_to(self, other):
+
+        if isinstance(other, Interval):
+            if other.axis == self.axis:
+                d = other.start
+                # Reset the canvas size in the absolute coordinates
+                return self.__class__(self.start - d, self.end - d, self.axis)
+            else:
+                return copy(self)
+
+        elif isinstance(other, Rectangle):
+
+            return self.put_on_canvas(other).to_rectangle().relative_to(other)
+
+        elif isinstance(other, Quadrilateral):
+
+            return self.put_on_canvas(other).to_quadrilateral().relative_to(other)
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def is_in(self, other, soft_margin={}, center=False):
+
+        other = other.pad(**soft_margin)
+
+        if isinstance(other, Interval):
+            if self.axis != other.axis:
+                return False
+            else:
+                if not center:
+                    return other.start <= self.start <= self.end <= other.end
+                else:
+                    return other.start <= self.center <= other.end
+
+        elif isinstance(other, Rectangle) or isinstance(other, Quadrilateral):
+            x_1, y_1, x_2, y_2 = other.coordinates
+
+            if center:
+                if self.axis == "x":
+                    return x_1 <= self.center <= x_2
+                else:
+                    return y_1 <= self.center <= y_2
+            else:
+                if self.axis == "x":
+                    return x_1 <= self.start <= self.end <= x_2
+                else:
+                    return y_1 <= self.start <= self.end <= y_2
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def intersect(self, other: BaseCoordElement, strict: bool = True):
+        """"""
+
+        if isinstance(other, Interval):
+            if self.axis != other.axis:
+                if self.axis == "x" and other.axis == "y":
+                    return Rectangle(self.start, other.start, self.end, other.end)
+                else:
+                    return Rectangle(other.start, self.start, other.end, self.end)
+            else:
+                return self.__class__(
+                    max(self.start, other.start),
+                    min(self.end, other.end),
+                    self.axis,
+                    self.canvas_height,
+                    self.canvas_width,
+                )
+
+        elif isinstance(other, Rectangle):
+            x_1, y_1, x_2, y_2 = other.coordinates
+            if self.axis == "x":
+                return Rectangle(max(x_1, self.start), y_1, min(x_2, self.end), y_2)
+            elif self.axis == "y":
+                return Rectangle(x_1, max(y_1, self.start), x_2, min(y_2, self.end))
+
+        elif isinstance(other, Quadrilateral):
+            if strict:
+                raise NotSupportedShapeError(
+                    "The intersection between an Interval and a Quadrilateral might generate Polygon shapes that are not supported in the current version of layoutparser. You can pass `strict=False` in the input that converts the Quadrilateral to Rectangle to avoid this Exception."
+                )
+            else:
+                warnings.warn(
+                    f"With `strict=False`, the other of shape {other.__class__} will be converted to {Rectangle} for obtaining the intersection"
+                )
+                return self.intersect(other.to_rectangle())
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def union(self, other: BaseCoordElement, strict: bool = True):
+        """"""
+        if isinstance(other, Interval):
+            if self.axis != other.axis:
+                raise InvalidShapeError(
+                    f"Unioning two intervals of different axes is not allowed."
+                )
+            else:
+                return self.__class__(
+                    min(self.start, other.start),
+                    max(self.end, other.end),
+                    self.axis,
+                    self.canvas_height,
+                    self.canvas_width,
+                )
+
+        elif isinstance(other, Rectangle):
+            x_1, y_1, x_2, y_2 = other.coordinates
+            if self.axis == "x":
+                return Rectangle(min(x_1, self.start), y_1, max(x_2, self.end), y_2)
+            elif self.axis == "y":
+                return Rectangle(x_1, min(y_1, self.start), x_2, max(y_2, self.end))
+
+        elif isinstance(other, Quadrilateral):
+            if strict:
+                raise NotSupportedShapeError(
+                    "The intersection between an Interval and a Quadrilateral might generate Polygon shapes that are not supported in the current version of layoutparser. You can pass `strict=False` in the input that converts the Quadrilateral to Rectangle to avoid this Exception."
+                )
+            else:
+                warnings.warn(
+                    f"With `strict=False`, the other of shape {other.__class__} will be converted to {Rectangle} for obtaining the intersection"
+                )
+                return self.union(other.to_rectangle())
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    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)
+
+    def shift(self, shift_distance):
+        """
+        Shift the interval by a user specified amount along the same axis that the interval is defined on.
+
+        Args:
+            shift_distance (:obj:`numeric`): The number of pixels used to shift the interval.
+
+        Returns:
+            :obj:`BaseCoordElement`: The shifted Interval object.
+        """
+
+        if isinstance(shift_distance, Iterable):
+            shift_distance = (
+                shift_distance[0] if self.axis == "x" else shift_distance[1]
+            )
+            warnings.warn(
+                f"Input shift for multiple axes. Only use the distance for the {self.axis} axis"
+            )
+
+        start = self.start + shift_distance
+        end = self.end + shift_distance
+        return self.set(start=start, end=end)
+
+    def scale(self, scale_factor):
+        """
+        Scale the layout element by a user specified amount the same axis that the interval is defined on.
+
+        Args:
+            scale_factor (:obj:`numeric`): The amount for downscaling or upscaling the element.
+
+        Returns:
+            :obj:`BaseCoordElement`: The scaled Interval object.
+        """
+
+        if isinstance(scale_factor, Iterable):
+            scale_factor = scale_factor[0] if self.axis == "x" else scale_factor[1]
+            warnings.warn(
+                f"Input scale for multiple axes. Only use the factor for the {self.axis} axis"
+            )
+
+        start = self.start * scale_factor
+        end = self.end * scale_factor
+        return self.set(start=start, end=end)
+
+    def crop_image(self, image):
+        x_1, y_1, x_2, y_2 = self.put_on_canvas(image).coordinates
+        return image[int(y_1) : int(y_2), int(x_1) : int(x_2)]
+
+    def to_rectangle(self):
+        """
+        Convert the Interval to a Rectangle element.
+
+        Returns:
+            :obj:`Rectangle`: The converted Rectangle object.
+        """
+        return Rectangle(*self.coordinates)
+
+    def to_quadrilateral(self):
+        """
+        Convert the Interval to a Quadrilateral element.
+
+        Returns:
+            :obj:`Quadrilateral`: The converted Quadrilateral object.
+        """
+        return Quadrilateral(self.points)
+
+
+@inherit_docstrings
+class Rectangle(BaseCoordElement):
+    """
+    This class describes the coordinate system of an axial rectangle box using two points as indicated below::
+
+            (x_1, y_1) ----
+            |             |
+            |             |
+            |             |
+            ---- (x_2, y_2)
+
+    Args:
+        x_1 (:obj:`numeric`):
+            x coordinate on the horizontal axis of the upper left corner of the rectangle.
+        y_1 (:obj:`numeric`):
+            y coordinate on the vertical axis of the upper left corner of the rectangle.
+        x_2 (:obj:`numeric`):
+            x coordinate on the horizontal axis of the lower right corner of the rectangle.
+        y_2 (:obj:`numeric`):
+            y coordinate on the vertical axis of the lower right corner of the rectangle.
+    """
+
+    _name = "rectangle"
+    _features = ["x_1", "y_1", "x_2", "y_2"]
+
+    def __init__(self, x_1, y_1, x_2, y_2):
+
+        self.x_1 = x_1
+        self.y_1 = y_1
+        self.x_2 = x_2
+        self.y_2 = y_2
+
+    @property
+    def height(self):
+        """
+        Calculate the height of the rectangle.
+
+        Returns:
+            :obj:`numeric`: Output the numeric value of the height.
+        """
+
+        return self.y_2 - self.y_1
+
+    @property
+    def width(self):
+        """
+        Calculate the width of the rectangle.
+
+        Returns:
+            :obj:`numeric`: Output the numeric value of the width.
+        """
+
+        return self.x_2 - self.x_1
+
+    @property
+    def coordinates(self):
+        """
+        Return the coordinates of the two points that define the rectangle.
+
+        Returns:
+            :obj:`Tuple(numeric)`: Output the numeric values of the coordinates in a Tuple of size four.
+        """
+
+        return (self.x_1, self.y_1, self.x_2, self.y_2)
+
+    @property
+    def points(self):
+        """
+        Return the coordinates of all four corners of the rectangle in a clockwise fashion
+        starting from the upper left.
+
+        Returns:
+            :obj:`Numpy array`: A Numpy array of shape 4x2 containing the coordinates.
+        """
+
+        return cvt_coordinates_to_points(self.coordinates)
+
+    @property
+    def center(self):
+        """
+        Calculate the center of the rectangle.
+
+        Returns:
+            :obj:`Tuple(numeric)`: Returns of coordinate of the center.
+        """
+
+        return (self.x_1 + self.x_2) / 2.0, (self.y_1 + self.y_2) / 2.0
+
+    @property
+    def area(self):
+        """
+        Return the area of the rectangle.
+        """
+        return self.width * self.height
+
+    @support_textblock
+    def condition_on(self, other):
+
+        if isinstance(other, Interval):
+            if other.axis == "x":
+                dx, dy = other.start, 0
+            else:
+                dx, dy = 0, other.start
+
+            return self.__class__(
+                self.x_1 + dx, self.y_1 + dy, self.x_2 + dx, self.y_2 + dy
+            )
+
+        elif isinstance(other, Rectangle):
+            dx, dy, _, _ = other.coordinates
+
+            return self.__class__(
+                self.x_1 + dx, self.y_1 + dy, self.x_2 + dx, self.y_2 + dy
+            )
+
+        elif isinstance(other, Quadrilateral):
+            transformed_points = perspective_transformation(
+                other.perspective_matrix, self.points, is_inv=True
+            )
+
+            return other.__class__(transformed_points, self.height, self.width)
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def relative_to(self, other):
+        if isinstance(other, Interval):
+            if other.axis == "x":
+                dx, dy = other.start, 0
+            else:
+                dx, dy = 0, other.start
+
+            return self.__class__(
+                self.x_1 - dx, self.y_1 - dy, self.x_2 - dx, self.y_2 - dy
+            )
+
+        elif isinstance(other, Rectangle):
+            dx, dy, _, _ = other.coordinates
+
+            return self.__class__(
+                self.x_1 - dx, self.y_1 - dy, self.x_2 - dx, self.y_2 - dy
+            )
+
+        elif isinstance(other, Quadrilateral):
+            transformed_points = perspective_transformation(
+                other.perspective_matrix, self.points, is_inv=False
+            )
+
+            return other.__class__(transformed_points, self.height, self.width)
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def is_in(self, other, soft_margin={}, center=False):
+
+        other = other.pad(**soft_margin)
+
+        if isinstance(other, Interval):
+            if not center:
+                if other.axis == "x":
+                    start, end = self.x_1, self.x_2
+                else:
+                    start, end = self.y_1, self.y_2
+                return other.start <= start <= end <= other.end
+            else:
+                c = self.center[0] if other.axis == "x" else self.center[1]
+                return other.start <= c <= other.end
+
+        elif isinstance(other, Rectangle):
+            x_interval = other.to_interval(axis="x")
+            y_interval = other.to_interval(axis="y")
+            return self.is_in(x_interval, center=center) and self.is_in(
+                y_interval, center=center
+            )
+
+        elif isinstance(other, Quadrilateral):
+
+            if not center:
+                # This is equivalent to determine all the points of the
+                # rectangle is in the quadrilateral.
+                is_vertice_in = [
+                    vertice_in_polygon(vertice, other.points) for vertice in self.points
+                ]
+                return all(is_vertice_in)
+            else:
+                center = np.array(self.center)
+                return vertice_in_polygon(center, other.points)
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def intersect(self, other: BaseCoordElement, strict: bool = True):
+        """"""
+
+        if isinstance(other, Interval):
+            return other.intersect(self)
+
+        elif isinstance(other, Rectangle):
+
+            return self.__class__(
+                max(self.x_1, other.x_1),
+                max(self.y_1, other.y_1),
+                min(self.x_2, other.x_2),
+                min(self.y_2, other.y_2),
+            )
+
+        elif isinstance(other, Quadrilateral):
+            if strict:
+                raise NotSupportedShapeError(
+                    "The intersection between a Rectangle and a Quadrilateral might generate Polygon shapes that are not supported in the current version of layoutparser. You can pass `strict=False` in the input that converts the Quadrilateral to Rectangle to avoid this Exception."
+                )
+            else:
+                warnings.warn(
+                    f"With `strict=False`, the other of shape {other.__class__} will be converted to {Rectangle} for obtaining the intersection"
+                )
+                return self.intersect(other.to_rectangle())
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def union(self, other: BaseCoordElement, strict: bool = True):
+        """"""
+        if isinstance(other, Interval):
+            return other.intersect(self)
+
+        elif isinstance(other, Rectangle):
+            return self.__class__(
+                min(self.x_1, other.x_1),
+                min(self.y_1, other.y_1),
+                max(self.x_2, other.x_2),
+                max(self.y_2, other.y_2),
+            )
+
+        elif isinstance(other, Quadrilateral):
+            if strict:
+                raise NotSupportedShapeError(
+                    "The intersection between an Interval and a Quadrilateral might generate Polygon shapes that are not supported in the current version of layoutparser. You can pass `strict=False` in the input that converts the Quadrilateral to Rectangle to avoid this Exception."
+                )
+            else:
+                warnings.warn(
+                    f"With `strict=False`, the other of shape {other.__class__} will be converted to {Rectangle} for obtaining the intersection"
+                )
+                return self.union(other.to_rectangle())
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    def pad(self, left=0, right=0, top=0, bottom=0, safe_mode=True):
+
+        x_1 = self.x_1 - left
+        y_1 = self.y_1 - top
+        x_2 = self.x_2 + right
+        y_2 = self.y_2 + bottom
+
+        if safe_mode:
+            x_1 = max(0, x_1)
+            y_1 = max(0, y_1)
+
+        return self.__class__(x_1, y_1, x_2, y_2)
+
+    def shift(self, shift_distance=0):
+
+        if not isinstance(shift_distance, Iterable):
+            shift_x = shift_distance
+            shift_y = shift_distance
+        else:
+            assert (
+                len(shift_distance) == 2
+            ), "shift_distance should have 2 elements, one for x dimension and one for y dimension"
+            shift_x, shift_y = shift_distance
+
+        x_1 = self.x_1 + shift_x
+        y_1 = self.y_1 + shift_y
+        x_2 = self.x_2 + shift_x
+        y_2 = self.y_2 + shift_y
+        return self.__class__(x_1, y_1, x_2, y_2)
+
+    def scale(self, scale_factor=1):
+
+        if not isinstance(scale_factor, Iterable):
+            scale_x = scale_factor
+            scale_y = scale_factor
+        else:
+            assert (
+                len(scale_factor) == 2
+            ), "scale_factor should have 2 elements, one for x dimension and one for y dimension"
+            scale_x, scale_y = scale_factor
+
+        x_1 = self.x_1 * scale_x
+        y_1 = self.y_1 * scale_y
+        x_2 = self.x_2 * scale_x
+        y_2 = self.y_2 * scale_y
+        return self.__class__(x_1, y_1, x_2, y_2)
+
+    def crop_image(self, image):
+        x_1, y_1, x_2, y_2 = self.coordinates
+        return image[int(y_1) : int(y_2), int(x_1) : int(x_2)]
+
+    def to_interval(self, axis, **kwargs):
+        if axis == "x":
+            start, end = self.x_1, self.x_2
+        else:
+            start, end = self.y_1, self.y_2
+
+        return Interval(start, end, axis=axis, **kwargs)
+
+    def to_quadrilateral(self):
+        return Quadrilateral(self.points)
+
+
+@inherit_docstrings
+class Quadrilateral(BaseCoordElement):
+    """
+    This class describes the coodinate system of a four-sided polygon. A quadrilateral is defined by
+    the coordinates of its 4 corners in a clockwise order starting with the upper left corner (as shown below)::
+
+        points[0] -...- points[1]
+        |                      |
+        .                      .
+        .                      .
+        .                      .
+        |                      |
+        points[3] -...- points[2]
+
+    Args:
+        points (:obj:`Numpy array` or `list`):
+            A `np.ndarray` of shape 4x2  for four corner coordinates
+            or a list of length 8 for in the format of
+            `[p0_x, p0_y, p1_x, p1_y, p2_x, p2_y, p3_x, p3_y]`
+            or a list of length 4 in the format of
+            `[[p0_x, p0_y], [p1_x, p1_y], [p2_x, p2_y], [p3_x, p3_y]]`.
+        height (:obj:`numeric`, `optional`, defaults to `None`):
+            The height of the quadrilateral. This is to better support the perspective
+            transformation from the OpenCV library.
+        width (:obj:`numeric`, `optional`, defaults to `None`):
+            The width of the quadrilateral. Similarly as height, this is to better support the perspective
+            transformation from the OpenCV library.
+    """
+
+    _name = "quadrilateral"
+    _features = ["points", "height", "width"]
+
+    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
+
+    @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()
+
+    @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()
+
+    @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)
+
+    @property
+    def points(self):
+        """
+        Return the coordinates of all four corners of the quadrilateral in a clockwise fashion
+        starting from the upper left.
+
+        Returns:
+            :obj:`Numpy array`: A Numpy array of shape 4x2 containing the coordinates.
+        """
+
+        return self._points
+
+    @property
+    def center(self):
+        """
+        Calculate the center of the quadrilateral.
+
+        Returns:
+            :obj:`Tuple(numeric)`: Returns of coordinate of the center.
+        """
+
+        return tuple(self.points.mean(axis=0).tolist())
+
+    @property
+    def area(self):
+        """
+        Return the area of the quadrilateral.
+        """
+        return polygon_area(self.points[:, 0], self.points[:, 1])
+
+    @property
+    def mapped_rectangle_points(self):
+
+        x_map = {0: 0, 1: 0, 2: self.width, 3: self.width}
+        y_map = {0: 0, 1: 0, 2: self.height, 3: self.height}
+
+        return self.map_to_points_ordering(x_map, y_map)
+
+    @property
+    def perspective_matrix(self):
+        return _getPerspectiveTransform(
+            self.points.astype("float32"),
+            self.mapped_rectangle_points.astype("float32"),
+        )
+
+    def map_to_points_ordering(self, x_map, y_map):
+
+        points_ordering = self.points.argsort(axis=0).argsort(axis=0)
+        # Ref: https://github.com/numpy/numpy/issues/8757#issuecomment-355126992
+
+        return np.vstack(
+            [
+                np.vectorize(x_map.get)(points_ordering[:, 0]),
+                np.vectorize(y_map.get)(points_ordering[:, 1]),
+            ]
+        ).T
+
+    @support_textblock
+    def condition_on(self, other):
+
+        if isinstance(other, Interval):
+
+            if other.axis == "x":
+                return self.shift([other.start, 0])
+            else:
+                return self.shift([0, other.start])
+
+        elif isinstance(other, Rectangle):
+
+            return self.shift([other.x_1, other.y_1])
+
+        elif isinstance(other, Quadrilateral):
+
+            transformed_points = perspective_transformation(
+                other.perspective_matrix, self.points, is_inv=True
+            )
+            return self.__class__(transformed_points, self.height, self.width)
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def relative_to(self, other):
+
+        if isinstance(other, Interval):
+
+            if other.axis == "x":
+                return self.shift([-other.start, 0])
+            else:
+                return self.shift([0, -other.start])
+
+        elif isinstance(other, Rectangle):
+
+            return self.shift([-other.x_1, -other.y_1])
+
+        elif isinstance(other, Quadrilateral):
+
+            transformed_points = perspective_transformation(
+                other.perspective_matrix, self.points, is_inv=False
+            )
+            return self.__class__(transformed_points, self.height, self.width)
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def is_in(self, other, soft_margin={}, center=False):
+
+        other = other.pad(**soft_margin)
+
+        if isinstance(other, Interval):
+            if not center:
+                if other.axis == "x":
+                    start, end = self.coordinates[0], self.coordinates[2]
+                else:
+                    start, end = self.coordinates[1], self.coordinates[3]
+                return other.start <= start <= end <= other.end
+            else:
+                c = self.center[0] if other.axis == "x" else self.center[1]
+                return other.start <= c <= other.end
+
+        elif isinstance(other, Rectangle):
+            x_interval = other.to_interval(axis="x")
+            y_interval = other.to_interval(axis="y")
+            return self.is_in(x_interval, center=center) and self.is_in(
+                y_interval, center=center
+            )
+
+        elif isinstance(other, Quadrilateral):
+
+            if not center:
+                # This is equivalent to determine all the points of the
+                # rectangle is in the quadrilateral.
+                is_vertice_in = [
+                    vertice_in_polygon(vertice, other.points) for vertice in self.points
+                ]
+                return all(is_vertice_in)
+            else:
+                center = np.array(self.center)
+                return vertice_in_polygon(center, other.points)
+
+        else:
+            raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def intersect(self, other: BaseCoordElement, strict: bool = True):
+        """"""
+
+        if strict:
+            raise NotSupportedShapeError(
+                "The intersection between a Quadrilateral and other objects might generate Polygon shapes that are not supported in the current version of layoutparser. You can pass `strict=False` in the input that converts the Quadrilateral to Rectangle to avoid this Exception."
+            )
+        else:
+            if isinstance(other, Interval) or isinstance(other, Rectangle):
+                warnings.warn(
+                    f"With `strict=False`, the current Quadrilateral object will be converted to {Rectangle} for obtaining the intersection"
+                )
+                return other.intersect(self.to_rectangle())
+            elif isinstance(other, Quadrilateral):
+                warnings.warn(
+                    f"With `strict=False`, both input Quadrilateral objects will be converted to {Rectangle} for obtaining the intersection"
+                )
+                return self.to_rectangle().intersect(other.to_rectangle())
+            else:
+                raise Exception(f"Invalid input type {other.__class__} for other")
+
+    @support_textblock
+    def union(self, other: BaseCoordElement, strict: bool = True):
+        """"""
+        if strict:
+            raise NotSupportedShapeError(
+                "The intersection between a Quadrilateral and other objects might generate Polygon shapes that are not supported in the current version of layoutparser. You can pass `strict=False` in the input that converts the Quadrilateral to Rectangle to avoid this Exception."
+            )
+        else:
+            if isinstance(other, Interval) or isinstance(other, Rectangle):
+                warnings.warn(
+                    f"With `strict=False`, the current Quadrilateral object will be converted to {Rectangle} for obtaining the intersection"
+                )
+                return other.union(self.to_rectangle())
+            elif isinstance(other, Quadrilateral):
+                warnings.warn(
+                    f"With `strict=False`, both input Quadrilateral objects will be converted to {Rectangle} for obtaining the intersection"
+                )
+                return self.to_rectangle().union(other.to_rectangle())
+            else:
+                raise Exception(f"Invalid input type {other.__class__} for other")
+
+    def pad(self, left=0, right=0, top=0, bottom=0, safe_mode=True):
+
+        x_map = {0: -left, 1: -left, 2: right, 3: right}
+        y_map = {0: -top, 1: -top, 2: bottom, 3: bottom}
+
+        padding_mat = self.map_to_points_ordering(x_map, y_map)
+
+        points = self.points + padding_mat
+        if safe_mode:
+            points = np.maximum(points, 0)
+
+        return self.set(points=points)
+
+    def shift(self, shift_distance=0):
+
+        if not isinstance(shift_distance, Iterable):
+            shift_mat = [shift_distance, shift_distance]
+        else:
+            assert (
+                len(shift_distance) == 2
+            ), "shift_distance should have 2 elements, one for x dimension and one for y dimension"
+            shift_mat = shift_distance
+
+        points = self.points + np.array(shift_mat)
+
+        return self.set(points=points)
+
+    def scale(self, scale_factor=1):
+
+        if not isinstance(scale_factor, Iterable):
+            scale_mat = [scale_factor, scale_factor]
+        else:
+            assert (
+                len(scale_factor) == 2
+            ), "scale_factor should have 2 elements, one for x dimension and one for y dimension"
+            scale_mat = scale_factor
+
+        points = self.points * np.array(scale_mat)
+
+        return self.set(points=points)
+
+    def crop_image(self, image):
+        """
+        Crop the input image using the points of the quadrilateral instance.
+
+        Args:
+            image (:obj:`Numpy array`): The array of the input image.
+
+        Returns:
+            :obj:`Numpy array`: The array of the cropped image.
+        """
+
+        return _warpPerspective(
+            image, self.perspective_matrix, (int(self.width), int(self.height))
+        )
+
+    def to_interval(self, axis, **kwargs):
+
+        x_1, y_1, x_2, y_2 = self.coordinates
+        if axis == "x":
+            start, end = x_1, x_2
+        else:
+            start, end = y_1, y_2
+
+        return Interval(start, end, axis=axis, **kwargs)
+
+    def to_rectangle(self):
+        return Rectangle(*self.coordinates)
+
+    def __eq__(self, other):
+        if other.__class__ is not self.__class__:
+            return False
+        return np.isclose(self.points, other.points).all()
+
+    def __repr__(self):
+        keys = ["points", "width", "height"]
+        info_str = ", ".join([f"{key}={getattr(self, key)}" for key in keys])
+        return f"{self.__class__.__name__}({info_str})"
+
+    def to_dict(self) -> Dict[str, Any]:
+
+        """
+        Generate a dictionary representation of the current object::
+
+            {
+                "block_type": "quadrilateral",
+                "points": [
+                    p[0,0], p[0,1],
+                    p[1,0], p[1,1],
+                    p[2,0], p[2,1],
+                    p[3,0], p[3,1]
+                ],
+                "height": value,
+                "width": value
+            }
+        """
+        data = super().to_dict()
+        data["points"] = data["points"].reshape(-1).tolist()
+        return data
+
+
+ALL_BASECOORD_ELEMENTS = [Interval, Rectangle, Quadrilateral]
+
+BASECOORD_ELEMENT_NAMEMAP = {ele._name: ele for ele in ALL_BASECOORD_ELEMENTS}
+BASECOORD_ELEMENT_INDEXMAP = {
+    ele._name: idx for idx, ele in enumerate(ALL_BASECOORD_ELEMENTS)
+}
+
+
+@inherit_docstrings(base_class=BaseCoordElement)
+class TextBlock(BaseLayoutElement):
+    """
+    This class constructs content-related information of a layout element in addition to its coordinate definitions
+    (i.e. Interval, Rectangle or Quadrilateral).
+
+    Args:
+        block (:obj:`BaseCoordElement`):
+            The shape-specific coordinate systems that the text block belongs to.
+        text (:obj:`str`, `optional`, defaults to None):
+            The ocr'ed text results within the boundaries of the text block.
+        id (:obj:`int`, `optional`, defaults to `None`):
+            The id of the text block.
+        type (:obj:`int`, `optional`, defaults to `None`):
+            The type of the text block.
+        parent (:obj:`int`, `optional`, defaults to `None`):
+            The id of the parent object.
+        next (:obj:`int`, `optional`, defaults to `None`):
+            The id of the next block.
+        score (:obj:`numeric`, defaults to `None`):
+            The prediction confidence of the block
+    """
+
+    _name = "textblock"
+    _features = ["text", "id", "type", "parent", "next", "score"]
+
+    def __init__(
+        self, block, text=None, id=None, type=None, parent=None, next=None, score=None
+    ):
+
+        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
+
+    @property
+    def height(self):
+        """
+        Return the height of the shape-specific block.
+
+        Returns:
+            :obj:`numeric`: Output the numeric value of the height.
+        """
+
+        return self.block.height
+
+    @property
+    def width(self):
+        """
+        Return the width of the shape-specific block.
+
+        Returns:
+            :obj:`numeric`: Output the numeric value of the width.
+        """
+
+        return self.block.width
+
+    @property
+    def coordinates(self):
+        """
+        Return the coordinates of the two corner points that define the shape-specific block.
+
+        Returns:
+            :obj:`Tuple(numeric)`: Output the numeric values of the coordinates in a Tuple of size four.
+        """
+
+        return self.block.coordinates
+
+    @property
+    def points(self):
+        """
+        Return the coordinates of all four corners of the shape-specific block in a clockwise fashion
+        starting from the upper left.
+
+        Returns:
+            :obj:`Numpy array`: A Numpy array of shape 4x2 containing the coordinates.
+        """
+
+        return self.block.points
+
+    @property
+    def area(self):
+        """
+        Return the area of associated block.
+        """
+        return self.block.area
+
+    @mixin_textblock_meta
+    def condition_on(self, other):
+        return self.block.condition_on(other)
+
+    @mixin_textblock_meta
+    def relative_to(self, other):
+        return self.block.relative_to(other)
+
+    def is_in(self, other, soft_margin={}, center=False):
+        return self.block.is_in(other, soft_margin, center)
+
+    @mixin_textblock_meta
+    def union(self, other: BaseCoordElement, strict: bool = True):
+        return self.block.union(other, strict=strict)
+
+    @mixin_textblock_meta
+    def intersect(self, other: BaseCoordElement, strict: bool = True):
+        return self.block.intersect(other, strict=strict)
+
+    @mixin_textblock_meta
+    def shift(self, shift_distance):
+        return self.block.shift(shift_distance)
+
+    @mixin_textblock_meta
+    def pad(self, left=0, right=0, top=0, bottom=0, safe_mode=True):
+        return self.block.pad(left, right, top, bottom, safe_mode)
+
+    @mixin_textblock_meta
+    def scale(self, scale_factor):
+        return self.block.scale(scale_factor)
+
+    def crop_image(self, image):
+        return self.block.crop_image(image)
+
+    def to_interval(self, axis: Optional[str] = None, **kwargs):
+        if isinstance(self.block, Interval):
+            return self
+        else:
+            if not axis:
+                raise ValueError(
+                    f"Please provide valid `axis` values {'x' or 'y'} as the input"
+                )
+            return self.set(block=self.block.to_interval(axis=axis, **kwargs))
+
+    def to_rectangle(self):
+        if isinstance(self.block, Rectangle):
+            return self
+        else:
+            return self.set(block=self.block.to_rectangle())
+
+    def to_quadrilateral(self):
+        if isinstance(self.block, Quadrilateral):
+            return self
+        else:
+            return self.set(block=self.block.to_quadrilateral())
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Generate a dictionary representation of the current textblock of the format::
+
+            {
+                "block_type": <name of self.block>,
+                <attributes of self.block combined with
+                    non-empty self._features>
+            }
+        """
+        base_dict = self.block.to_dict()
+        for f in self._features:
+            val = getattr(self, f)
+            if val is not None:
+                base_dict[f] = getattr(self, f)
+        return base_dict
+
+    @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})