Method insert_image

src/__init__.py:12431–12553

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. height: (int) keep_

(
            page,
            rect,
            *,
            alpha=-1,
            filename=None,
            height=0,
            keep_proportion=True,
            mask=None,
            oc=0,
            overlay=True,
            pixmap=None,
            rotate=0,
            stream=None,
            width=0,
            xref=0,
            )

        return spare_height, scale

    def insert_image(
            page,
            rect,
            *,
            alpha=-1,
            filename=None,
            height=0,
            keep_proportion=True,
            mask=None,
            oc=0,
            overlay=True,
            pixmap=None,
            rotate=0,
            stream=None,
            width=0,
            xref=0,
            ):
        """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.
            height: (int)
            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: (pymupdf.Pixmap) use this as image.
            rotate: (int) rotate by 0, 90, 180 or 270 degrees.
            stream: (bytes) use this as image.
            width: (int)
            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")

        if xref == 0 and (bool(filename) + bool(stream) + bool(pixmap) != 1):
            raise ValueError("xref=0 needs exactly one of filename, pixmap, stream")

        if filename:
            if type(filename) is str: