Skip to content
Back to top
View this page

# pdf2docx.common.Element module

Object with a bounding box, e.g. Block, Line, Span.

Based on `PyMuPDF`, the coordinates (e.g. bbox of `page.get_text('rawdict')`) are generally provided relative to the un-rotated page; while this `pdf2docx` library works under real page coordinate system, i.e. with rotation considered. So, any instances created by this Class are always applied a rotation matrix automatically.

Therefore, the bbox parameter used to create `Element` instance MUST be relative to un-rotated CS. If final coordinates are provided, should update it after creating an empty object:

    Element().update_bbox(final_bbox)

Note

An exception is `page.get_drawings()`, the coordinates are converted to real page CS already.

class pdf2docx.common.Element.Element(raw: dict = None, parent=None)

  Bases: `IText`

  Boundary box with attribute in fitz.Rect type.

  ROTATION_MATRIX = Matrix(1.0, 0.0, -0.0, 1.0, 0.0, 0.0)
  contains(e: Element, threshold: float = 1.0)

    Whether given element is contained in this instance, with margin considered.

    Args:

      e (Element): Target element threshold (float, optional): Intersection rate.

      > Defaults to 1.0. The larger, the stricter.

    Returns:

      bool: [description]

  copy()

    make a deep copy.

  get_expand_bbox(dt: float)

    Get expanded bbox with margin in both x- and y- direction.

    Args:

      dt (float): Expanding margin.

    Returns:

      fitz.Rect: Expanded bbox.

    Note

    This method creates a new bbox, rather than changing the bbox of itself.

  get_main_bbox(e, threshold: float = 0.95)

    If the intersection with `e` exceeds the threshold, return the union of these two elements; else return None.

    Args:

      e (Element): Target element. threshold (float, optional): Intersection rate. Defaults to 0.95.

    Returns:

      fitz.Rect: Union bbox or None.

  horizontally_align_with(e, factor: float = 0.0, text_direction: bool = True)

    Check whether two Element instances have enough intersection in horizontal direction, i.e. along the reading direction.

    Args:

      e (Element): Element to check with factor (float, optional): threshold of overlap ratio, the larger it is, the higher

      > probability the two bbox-es are aligned.

      text_direction (bool, optional): consider text direction or not. True by default.

    Examples:

        +--------------+
        |              | L1  +--------------------+
        +--------------+     |                    | L2
                             +--------------------+

    An enough intersection is defined based on the minimum width of two boxes:

        L1+L2-L>factor*min(L1,L2)

  in_same_row(e)

    Check whether in same row/line with specified Element instance. With text direction considered.

    > Taking horizontal text as an example:

    > - yes: the bottom edge of each box is lower than the centerline of the other one;

    > - otherwise, not in same row.

    Args:

      e (Element): Target object.

    Note

    The difference to method `horizontally_align_with`: they may not in same line, though aligned horizontally.

  property parent
  plot(page, stroke: tuple = (0, 0, 0), width: float = 0.5, fill: tuple = None, dashes: str = None)

    Plot bbox in PDF page for debug purpose.

  classmethod pure_rotation_matrix()

    Pure rotation matrix used for calculating text direction after rotation.

  classmethod set_rotation_matrix(rotation_matrix)

    Set global rotation matrix.

    Args:

      Rotation_matrix (fitz.Matrix): target matrix

  store()

    Store properties in raw dict.

  union_bbox(e)

    Update current bbox to the union with specified Element.

    Args:

      e (Element): The target to get union

    Returns:

      Element: self

  update_bbox(rect)

    Update current bbox to specified `rect`.

    Args:
      rect (fitz.Rect or list): bbox-like `(x0, y0, x1, y1)`,

        in real page CS (with rotation considered).

  vertically_align_with(e, factor: float = 0.0, text_direction: bool = True)

    Check whether two Element instances have enough intersection in vertical direction, i.e. perpendicular to reading direction.

    Args:

      e (Element): Object to check with factor (float, optional): Threshold of overlap ratio, the larger it is, the higher

      > probability the two bbox-es are aligned.

      text_direction (bool, optional): Consider text direction or not. True by default.

    Returns:

      bool: [description]

    Examples:

        +--------------+
        |              |
        +--------------+
                L1
                +-------------------+
                |                   |
                +-------------------+
                        L2

    An enough intersection is defined based on the minimum width of two boxes:

        L1+L2-L>factor*min(L1,L2)