Document procedure to remove an image

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/topics/images.rst b/docs/topics/images.rst
index 19ec2e8..487d625 100644
--- a/docs/topics/images.rst
+++ b/docs/topics/images.rst
@@ -143,3 +143,33 @@ Notes on this example:
 
 * This example would replace all occurrences of the image if it were used
   multiple times in a PDF.
+
+Removing an image
+-----------------
+
+The easy way to remove an image is to replace it with a 1x1 pixel transparent image.
+A transparent image can be created by setting the ``/ImageMask`` to true.
+
+Note that, if an image is referenced on multiple pages, this procedure only updates
+the occurrence on one page. If all references to the image are deleted, it should
+not be included in the output file.
+
+.. ipython::
+
+In [1]: pdf = pikepdf.open('tests/resources/sandwich.pdf')
+
+In [1]: page = pdf.pages[0]
+
+In [1]: image_name, image = next(page.images.items())
+
+In [1]: new_image = pdf.make_stream(b'\xff')
+
+In [1]: new_image.Width, new_image.Height = 1, 1
+
+In [1]: new_image.BitsPerComponent = 1
+
+In [1]: new_image.ImageMask = True
+
+In [1]: new_image.Decode = [0, 1]
+
+In [1]: page.Resources.XObject[image_name] = new_image