Skip to main content

Working with Images

PDFDancer allows you to work with images in PDFs - add new images, select existing ones, move them, and delete them.

Selecting Images​

All Images​

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    # Get all images across the document
    all_images = pdf.select_images()

    # Get all images on a specific page
    page_images = pdf.page(1).select_images()

    for img in page_images:
        print(f"Image ID: {img.internal_id}")
        print(f"Position: {img.position.bounding_rect}")

Images at Coordinates​

with PDFDancer.open("document.pdf") as pdf:
    # Find images at specific coordinates
    images = pdf.page(2).select_images_at(x=120, y=300)

    for img in images:
        print(f"Found image at position: {img.position}")

Adding Images​

From File Path​

from pathlib import Path
from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    # Add image from file
    pdf.new_image() \
        .from_file(Path("logo.png")) \
        .at(page=1, x=48, y=700) \
        .add()

    pdf.save("output.pdf")

From Bytes​

info

The Python SDK does not have a from_bytes() method. If you have image bytes, write them to a temporary file first, then use from_file().

import tempfile
from pathlib import Path
from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    # Load image bytes
    image_bytes = Path("logo.png").read_bytes()

    # Write bytes to temporary file
    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as temp_file:
        temp_path = Path(temp_file.name)
        temp_path.write_bytes(image_bytes)

    try:
        # Add image from temporary file
        pdf.new_image() \
            .from_file(temp_path) \
            .at(page=1, x=100, y=600) \
            .add()

        pdf.save("output.pdf")
    finally:
        # Clean up temporary file
        temp_path.unlink()

Moving Images​

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    images = pdf.page(1).select_images()

    if images:
        # Move image to new position
        images[0].move_to(x=200, y=350)

    pdf.save("output.pdf")

Clearing Image Clipping​

If an image is present in the PDF but rendered through a clipping path that hides part or all of it, you can detach that clipping before saving. This is especially useful when reusing artwork that was originally masked into a smaller region.

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    image = pdf.page(1).select_images()[0]

    # Remove the clipping path attached to this image
    image.clear_clipping()

    pdf.save("output.pdf")

Deleting Images​

info

For a comprehensive guide on deletion operations across all content types, see Deleting Content.

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    images = pdf.page(1).select_images()

    # Delete all images on page 1
    for image in images:
        image.delete()

    pdf.save("output.pdf")

Transforming Images​

PDFDancer provides powerful image transformation capabilities to modify existing images in-place.

Scaling Images​

Scale an image by a factor or to a specific size.

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    images = pdf.page(1).select_images()

    if images:
        # Scale to half size
        images[0].scale(0.5)

        # Scale to double size
        images[1].scale(2.0)

        # Scale to specific dimensions (preserving aspect ratio)
        images[2].scale_to(width=200, height=150, preserve_aspect_ratio=True)

        # Scale to exact dimensions (ignoring aspect ratio)
        images[0].scale_to(width=100, height=100, preserve_aspect_ratio=False)

    pdf.save("output.pdf")

Rotating Images​

Rotate images by a specified angle in degrees.

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    images = pdf.page(1).select_images()

    if images:
        # Rotate 90 degrees clockwise
        images[0].rotate(90)

        # Rotate 180 degrees
        images[1].rotate(180)

        # Rotate 45 degrees
        images[2].rotate(45)

    pdf.save("output.pdf")

Cropping Images​

Crop images by trimming pixels from each edge.

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    images = pdf.page(1).select_images()

    if images:
        # Crop 10 pixels from each edge
        images[0].crop(left=10, top=10, right=10, bottom=10)

        # Crop only from the left side
        images[1].crop(left=50, top=0, right=0, bottom=0)

    pdf.save("output.pdf")

Setting Image Opacity​

Adjust the transparency of an image.

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    images = pdf.page(1).select_images()

    if images:
        # Set to 50% opacity (semi-transparent)
        images[0].set_opacity(0.5)

        # Set to 25% opacity (mostly transparent)
        images[1].set_opacity(0.25)

        # Set to fully opaque
        images[2].set_opacity(1.0)

    pdf.save("output.pdf")

Flipping Images​

Flip images horizontally, vertically, or both.

from pdfdancer import PDFDancer, ImageFlipDirection

with PDFDancer.open("document.pdf") as pdf:
    images = pdf.page(1).select_images()

    if images:
        # Flip horizontally (mirror left-right)
        images[0].flip(ImageFlipDirection.HORIZONTAL)

        # Flip vertically (mirror top-bottom)
        images[1].flip(ImageFlipDirection.VERTICAL)

        # Flip both horizontally and vertically
        images[2].flip(ImageFlipDirection.BOTH)

    pdf.save("output.pdf")

Replacing Images​

Replace an existing image with a new one while keeping the same position.

from pdfdancer import PDFDancer, Image

with PDFDancer.open("document.pdf") as pdf:
    images = pdf.page(1).select_images()

    if images:
        # Create a new image from file data
        with open("new-logo.png", "rb") as f:
            image_data = f.read()

        new_image = Image(
            format="PNG",
            width=100,
            height=100,
            data=image_data
        )

        # Replace the first image
        images[0].replace(new_image)

    pdf.save("output.pdf")

Filling Image Regions​

Fill a rectangular pixel region of an image with a solid color. This is useful for masking parts of an image, adding colored overlays, or blanking out sections.

from pdfdancer import PDFDancer, Color

with PDFDancer.open("document.pdf") as pdf:
    images = pdf.page(1).select_images()

    if images:
        # Fill a 50x30 pixel region starting at (10, 10) with black
        images[0].fill_region(10, 10, 50, 30, Color(0, 0, 0))

        # Fill a region with red
        images[0].fill_region(0, 0, 5, 5, Color(255, 0, 0))

        # Fill a region with white
        images[0].fill_region(20, 20, 10, 10, Color(255, 255, 255))

    pdf.save("output.pdf")

The fillRegion method takes the following parameters:

ParameterTypeDescription
xnumber / intX coordinate of the top-left corner of the region (pixels)
ynumber / intY coordinate of the top-left corner of the region (pixels)
widthnumber / intWidth of the region in pixels (must be positive)
heightnumber / intHeight of the region in pixels (must be positive)
colorColorThe fill color

Next Steps​