ImageCollection / PPImage

ImageCollection and PPImage — Aspose.Slides FOSS Python API Reference

Images in a presentation are stored in the ppt/media/ part of the .pptx package. The ImageCollection (accessed via prs.images) manages them. Each stored image is represented by a PPImage. Shapes that display images use a PictureFrame and a PictureFillFormat.

Package: aspose.slides_foss

PPImage

PPImage represents a single embedded image in the presentation package.

PPImage Properties

Property	Type	Access	Description
`content_type`	`str`	Read	MIME type of the image (e.g. `"image/png"`, `"image/jpeg"`).
`width`	`int`	Read	Image width in pixels.
`height`	`int`	Read	Image height in pixels.
`x`	`int`	Read	X-offset (always `0`).
`y`	`int`	Read	Y-offset (always `0`).
`binary_data`	`list[int]`	Read	A copy of the raw image bytes as a list of integers.
`image`	`Image`	Read	An `Image` wrapper around the raw bytes.

PPImage Methods

Method	Signature	Description
`replace_image`	`(new_image) -> None`	Replace the stored image with new bytes. Accepts `bytes`, `bytearray`, `list[int]`, a `PPImage`, or an `Image` object.

ImageCollection

ImageCollection (accessed via prs.images) holds all PPImage objects embedded in the presentation.

ImageCollection Methods

Method	Signature	Description
`add_image`	`(source) -> PPImage`	Add an image from `bytes`, `bytearray`, `list[int]`, a file-like stream, an existing `PPImage`, or an `Image` object. Returns the existing `PPImage` if the same data is already embedded.
`__getitem__`	`[index: int] -> PPImage`	Return the image at zero-based `index`.
`__len__`	`() -> int`	Total number of embedded images.
`__iter__`	N/A	Iterate over all images.

Images (static factory)

Images provides static helpers for creating Image objects from disk or streams. The resulting Image can then be passed to prs.images.add_image().

Images Static Methods

Method	Signature	Description
`Images.from_file`	`(filename: str) -> Image`	Load image bytes from a file path.
`Images.from_stream`	`(stream) -> Image`	Load image bytes from a binary stream.

PictureFillFormat

PictureFillFormat controls how an image fills a shape (stretch or tile). Access it via picture_frame.picture_format or via shape.fill_format.picture_fill_format when fill_type == FillType.PICTURE.

PictureFillFormat Properties

Property	Type	Access	Description
`picture_fill_mode`	`PictureFillMode`	Read/Write	`STRETCH` (default) or `TILE`.
`picture`	`SlidesPicture`	Read	The embedded picture reference.
`dpi`	`int`	Read/Write	DPI used for filling. Default `-1` (unset).
`crop_left`	`float`	Read/Write	Percentage cropped from the left edge.
`crop_top`	`float`	Read/Write	Percentage cropped from the top edge.
`crop_right`	`float`	Read/Write	Percentage cropped from the right edge.
`crop_bottom`	`float`	Read/Write	Percentage cropped from the bottom edge.
`stretch_offset_left`	`float`	Read/Write	Left inset/outset when stretching.
`stretch_offset_top`	`float`	Read/Write	Top inset/outset when stretching.
`stretch_offset_right`	`float`	Read/Write	Right inset/outset when stretching.
`stretch_offset_bottom`	`float`	Read/Write	Bottom inset/outset when stretching.
`tile_offset_x`	`float`	Read/Write	Horizontal tile offset in points (tile mode).
`tile_offset_y`	`float`	Read/Write	Vertical tile offset in points (tile mode).
`tile_scale_x`	`float`	Read/Write	Horizontal scale percentage for tile mode.
`tile_scale_y`	`float`	Read/Write	Vertical scale percentage for tile mode.
`tile_alignment`	`RectangleAlignment`	Read/Write	Alignment anchor for tile mode.
`tile_flip`	`TileFlip`	Read/Write	Flip mode: `NO_FLIP`, `FLIP_X`, `FLIP_Y`, `FLIP_BOTH`.

PictureFrame

PictureFrame is the shape that displays an embedded image. Add one via slide.shapes.add_picture_frame().

PictureFrame Properties

Property	Type	Access	Description
`picture_format`	`PictureFillFormat`	Read	Fill format for the embedded image.
`shape_type`	`ShapeType`	Read/Write	Shape outline type (defaults to `RECTANGLE`).
`picture_frame_lock`	`PictureFrameLock`	Read	Lock settings for this picture frame.
`relative_scale_height`	`float`	Read/Write	Height scale relative to original image size. `1.0` = 100%.
`relative_scale_width`	`float`	Read/Write	Width scale relative to original image size. `1.0` = 100%.
`is_cameo`	`bool`	Read	Always `False` in this implementation.

PictureFrame also inherits the standard shape properties (x, y, width, height, name, fill_format, line_format, effect_format) from GeometryShape.

Code Examples

Add an Image to a Slide

import aspose.slides_foss as slides
from aspose.slides_foss import ShapeType
from aspose.slides_foss.export import SaveFormat

with slides.Presentation() as prs:
    slide = prs.slides[0]

    with open("logo.png", "rb") as f:
        image_data = f.read()

    pp_img = prs.images.add_image(image_data)
    frame = slide.shapes.add_picture_frame(
        ShapeType.RECTANGLE, 50, 50, 300, 200, pp_img
    )
    prs.save("with-image.pptx", SaveFormat.PPTX)

Load Image Using Images Factory

import aspose.slides_foss as slides
from aspose.slides_foss import Images, ShapeType
from aspose.slides_foss.export import SaveFormat

with slides.Presentation() as prs:
    slide = prs.slides[0]

    img = Images.from_file("photo.jpg")
    pp_img = prs.images.add_image(img)
    slide.shapes.add_picture_frame(ShapeType.RECTANGLE, 100, 100, 400, 300, pp_img)

    prs.save("photo-slide.pptx", SaveFormat.PPTX)

Crop an Image in a PictureFrame

import aspose.slides_foss as slides
from aspose.slides_foss import ShapeType
from aspose.slides_foss.export import SaveFormat

with slides.Presentation("deck.pptx") as prs:
    slide = prs.slides[0]

    with open("banner.png", "rb") as f:
        pp_img = prs.images.add_image(f.read())

    frame = slide.shapes.add_picture_frame(
        ShapeType.RECTANGLE, 50, 50, 600, 200, pp_img
    )
    # Crop 10% from left and right to focus on centre
    frame.picture_format.crop_left = 10.0
    frame.picture_format.crop_right = 10.0

    prs.save("cropped.pptx", SaveFormat.PPTX)

Iterate Over All Embedded Images

import aspose.slides_foss as slides

with slides.Presentation("deck.pptx") as prs:
    print(f"Total images: {len(prs.images)}")
    for i, img in enumerate(prs.images):
        print(f"  [{i}] {img.content_type}  {img.width}x{img.height}px")

Replace an Embedded Image

import aspose.slides_foss as slides
from aspose.slides_foss.export import SaveFormat

with slides.Presentation("deck.pptx") as prs:
    if len(prs.images) > 0:
        with open("new-logo.png", "rb") as f:
            new_data = f.read()
        prs.images[0].replace_image(new_data)
    prs.save("deck-updated.pptx", SaveFormat.PPTX)