Function insert_image

src_classic/utils.py:291–423

Insert an image for display in a rectangle. Args: rect: (rect_like) position of image on the page. alpha: (int, optional) set to 0 if image has no transparency. filename: (str, Path, file object) image filename. keep_proportion: (bool) keep width / height ratio (

(page, rect, **kwargs)

def insert_image(page, rect, **kwargs):
    """Insert an image for display in a rectangle.

    Args:
        rect: (rect_like) position of image on the page.
        alpha: (int, optional) set to 0 if image has no transparency.
        filename: (str, Path, file object) image filename.
        keep_proportion: (bool) keep width / height ratio (default).
        mask: (bytes, optional) image consisting of alpha values to use.
        oc: (int) xref of OCG or OCMD to declare as Optional Content.
        overlay: (bool) put in foreground (default) or background.
        pixmap: (Pixmap) use this as image.
        rotate: (int) rotate by 0, 90, 180 or 270 degrees.
        stream: (bytes) use this as image.
        xref: (int) use this as image.

    'page' and 'rect' are positional, all other parameters are keywords.

    If 'xref' is given, that image is used. Other input options are ignored.
    Else, exactly one of pixmap, stream or filename must be given.

    'alpha=0' for non-transparent images improves performance significantly.
    Affects stream and filename only.

    Optimum transparent insertions are possible by using filename / stream in
    conjunction with a 'mask' image of alpha values.

    Returns:
        xref (int) of inserted image. Re-use as argument for multiple insertions.
    """
    CheckParent(page)
    doc = page.parent
    if not doc.is_pdf:
        raise ValueError("is no PDF")

    valid_keys = {
        "alpha",
        "filename",
        "height",
        "keep_proportion",
        "mask",
        "oc",
        "overlay",
        "pixmap",
        "rotate",
        "stream",
        "width",
        "xref",
    }
    s = set(kwargs.keys()).difference(valid_keys)
    if s != set():
        raise ValueError(f"bad key argument(s): {s}.")
    filename = kwargs.get("filename")
    pixmap = kwargs.get("pixmap")
    stream = kwargs.get("stream")
    mask = kwargs.get("mask")
    rotate = int(kwargs.get("rotate", 0))
    width = int(kwargs.get("width", 0))