Skip to content

Commit

Permalink
docs/page.rst: insert_image(): improved docs.
Browse files Browse the repository at this point in the history
Wordwrap text.
List args alphabetically.
Moved "Changed in v..." to end of section.

Added args `height` and `width`.
Clarify keyword-only args.
Fixed link to `RecipesImages_O` 'How to Add Images to a PDF Page'.
Removed broken link to https://github.com/pymupdf/PyMuPDF-Utilities/tree/master/demo/fitz-logo.py.
  • Loading branch information
julian-smith-artifex-com committed Dec 14, 2023
1 parent 4076edd commit cc498a8
Showing 1 changed file with 92 additions and 41 deletions.
133 changes: 92 additions & 41 deletions docs/page.rst
Original file line number Diff line number Diff line change
Expand Up @@ -930,47 +930,52 @@ In a nutshell, this is what you can do with PyMuPDF:
pair: oc; insert_image
pair: xref; insert_image

.. method:: insert_image(rect, filename=None, pixmap=None, stream=None, mask=None, rotate=0, alpha=-1, oc=0, xref=0, keep_proportion=True, overlay=True)
.. method:: insert_image(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)

PDF only: Put an image inside the given rectangle. The image may already exist in the PDF or be taken from a pixmap, a file, or a memory area.

* Changed in v1.14.1: By default, the image keeps its aspect ratio.
* Changed in v1.14.13: The image is now always placed **centered** in the rectangle, i.e. the centers of image and rectangle are equal.
* Changed in v1.17.6: Insertion rectangle no longer needs to have a non-empty intersection with the page's :attr:`Page.cropbox` [#f5]_.
* Changed in v1.18.13: Allow providing the image as the xref of an existing one.
PDF only: Put an image inside the given rectangle. The image may already
exist in the PDF or be taken from a pixmap, a file, or a memory area.

:arg rect_like rect: where to put the image. Must be finite and not empty.
:arg str filename: name of an image file (all formats supported by MuPDF -- see :ref:`ImageFiles`).
:arg bytes,bytearray,io.BytesIO stream: image in memory (all formats supported by MuPDF -- see :ref:`ImageFiles`).

Changed in v1.14.13: *io.BytesIO* is now also supported.

:arg int alpha: deprecated and ignored.
:arg str filename:
name of an image file (all formats supported by MuPDF -- see
:ref:`ImageFiles`).
:arg int height:
:arg bool keep_proportion:
maintain the aspect ratio of the image.
:arg bytes,bytearray,io.BytesIO mask:
image in memory -- to be used as image mask (alpha values) for the base
image. When specified, the base image must be provided as a filename or
a stream -- and must not be an image that already has a mask.
:arg int oc:
(:data:`xref`) make image visibility dependent on this :data:`OCG`
or :data:`OCMD`. Ignored after the first of multiple insertions. The
property is stored with the generated PDF image object and therefore
controls the image's visibility throughout the PDF.
:arg overlay: see :ref:`CommonParms`.
:arg pixmap: a pixmap containing the image.
:type pixmap: :ref:`Pixmap`

:arg bytes,bytearray,io.BytesIO mask: *(new in version v1.18.1)* image in memory -- to be used as image mask (alpha values) for the base image. When specified, the base image must be provided as a filename or a stream -- and must not be an image that already has a mask.

:arg int xref: *(New in v1.18.13)* the :data:`xref` of an image already present in the PDF. If given, parameters `filename`, `pixmap`, `stream`, `alpha` and `mask` are ignored. The page will simply receive a reference to the existing image.

:arg int alpha: *(Changed in v1.19.3)* deprecated. No longer needed -- ignored when given.

:arg int rotate: *(new in version v1.14.11)* rotate the image.
:arg int rotate: rotate the image.
Must be an integer multiple of 90 degrees.
Positive values rotate anti-clockwise.
If you need a rotation by an arbitrary angle,
consider converting the image to a PDF
(:meth:`Document.convert_to_pdf`)
first and then use :meth:`Page.show_pdf_page` instead.
:arg bytes,bytearray,io.BytesIO stream:
image in memory (all formats supported by MuPDF -- see :ref:`ImageFiles`).
:arg int width:
:arg int xref:
the :data:`xref` of an image already present in the PDF. If given,
parameters `filename`, `pixmap`, `stream`, `alpha` and `mask` are
ignored. The page will simply receive a reference to the existing
image.

:arg int oc: *(new in v1.18.3)* (:data:`xref`) make image visibility dependent on this :data:`OCG` or :data:`OCMD`. Ignored after the first of multiple insertions. The property is stored with the generated PDF image object and therefore controls the image's visibility throughout the PDF.
:arg bool keep_proportion: *(new in version v1.14.11)* maintain the aspect ratio of the image.

For a description of *overlay* see :ref:`CommonParms`.

*Changed in v1.18.13:* Return xref of stored image.

:rtype: int
:returns: The xref of the embedded image. This can be used as the `xref` argument for very significant performance boosts, if the image is inserted again.
:type pixmap: :ref:`Pixmap`

:returns:
The xref of the embedded image. This can be used as the `xref` argument
for very significant performance boosts, if the image is inserted
again.

This example puts the same image on every page of a document::

Expand All @@ -986,17 +991,63 @@ In a nutshell, this is what you can do with PyMuPDF:

.. note::

1. The method detects multiple insertions of the same image (like in above example) and will store its data only on the first execution. This is even true (although less performant), if using the default `xref=0`.

2. The method cannot detect if the same image had already been part of the file before opening it.

3. You can use this method to provide a background or foreground image for the page, like a copyright or a watermark. Please remember, that watermarks require a transparent image if put in foreground ...

4. The image may be inserted uncompressed, e.g. if a *Pixmap* is used or if the image has an alpha channel. Therefore, consider using *deflate=True* when saving the file. In addition, there exist effective ways to control the image size -- even if transparency comes into play. Have a look at `this <https://pymupdf.readthedocs.io/en/latest/faq.html#how-to-add-images-to-a-pdf-page>`_ section of the documentation.

5. The image is stored in the PDF in its original quality. This may be much better than what you ever need for your display. Consider **decreasing the image size** before insertion -- e.g. by using the pixmap option and then shrinking it or scaling it down (see :ref:`Pixmap` chapter). The PIL method *Image.thumbnail()* can also be used for that purpose. The file size savings can be very significant.

6. Another efficient way to display the same image on multiple pages is another method: :meth:`show_pdf_page`. Consult :meth:`Document.convert_to_pdf` for how to obtain intermediary PDFs usable for that method. Demo script `fitz-logo.py <https://github.com/pymupdf/PyMuPDF-Utilities/tree/master/demo/fitz-logo.py>`_ implements a fairly complete approach.
1.
The method detects multiple insertions of the same image (like in
above example) and will store its data only on the first execution.
This is even true (although less performant), if using the default
`xref=0`.
2.
The method cannot detect if the same image had already been part of
the file before opening it.

3.
You can use this method to provide a background or foreground image
for the page, like a copyright or a watermark. Please remember, that
watermarks require a transparent image if put in foreground ...

4.
The image may be inserted uncompressed, e.g. if a *Pixmap* is used
or if the image has an alpha channel. Therefore, consider using
*deflate=True* when saving the file. In addition, there exist
effective ways to control the image size -- even if transparency
comes into play. Have a look at :ref:`RecipesImages_O`.

5.
The image is stored in the PDF in its original quality. This may
be much better than what you ever need for your display. Consider
**decreasing the image size** before insertion -- e.g. by using
the pixmap option and then shrinking it or scaling it down (see
:ref:`Pixmap` chapter). The PIL method *Image.thumbnail()* can
also be used for that purpose. The file size savings can be very
significant.

6.
Another efficient way to display the same image on multiple
pages is another method: :meth:`show_pdf_page`. Consult
:meth:`Document.convert_to_pdf` for how to obtain intermediary PDFs
usable for that method.

* Changed in v1.14.1: By default, the image keeps its aspect ratio.
* Changed in v1.14.11: Added args `keep_proportion`, `rotate`.
* Changed in v1.14.13:

*
The image is now always placed **centered** in the rectangle, i.e.
the centers of image and rectangle are equal.
* Added support for `stream` as `io.BytesIO`.

* Changed in v1.17.6:
Insertion rectangle no longer needs to have a non-empty intersection
with the page's :attr:`Page.cropbox` [#f5]_.
* Changed in v1.18.1: Added `mask` arg.
* Changed in v1.18.3: Added `oc` arg.
* Changed in v1.18.13:

* Allow providing the image as the xref of an existing one.
* Added `xref` arg.
* Return xref of stored image.

* Changed in v1.19.3: deprecate and ignore `alpha` arg.


.. index::
Expand Down

0 comments on commit cc498a8

Please sign in to comment.