Adicionar Quadros de Imagem a Apresentações com Python

Introdução

Quadros de imagem no Aspose.Slides para Python permitem que você posicione e gerencie imagens raster e vetoriais como formas nativas de slide. Você pode inserir imagens a partir de arquivos ou streams, posicionar e redimensionar com coordenadas precisas, aplicar rotação, definir transparência e controlar a ordem Z juntamente com outras formas. A API também oferece suporte a recorte, manutenção de proporções, definição de bordas e efeitos, e substituição da imagem subjacente sem reconstruir o layout. Como os quadros de imagem se comportam como formas regulares, você pode adicionar animações, hyperlinks e texto alternativo, facilitando a criação de apresentações visualmente ricas e acessíveis.

Criar Quadros de Imagem

Esta seção mostra como inserir uma imagem em um slide criando um PictureFrame com Aspose.Slides para Python. Você aprenderá como carregar a imagem, posicioná‑la precisamente no slide e controlar seu tamanho e formatação.

Crie uma instância da classe Presentation.
Obtenha um slide pelo seu índice.
Crie um PPImage adicionando a imagem à ImageCollection da apresentação. Essa imagem será usada para preencher a forma.
Especifique a largura e a altura do quadro.
Crie um PictureFrame desse tamanho usando o método add_picture_frame.
Salve a apresentação como um arquivo PPTX.

O código Python a seguir mostra como criar um quadro de imagem:

import aspose.slides as slides

# Instanciar a classe Presentation para representar um arquivo PPTX.
with slides.Presentation() as presentation:
    # Obter o primeiro slide.
    slide = presentation.slides[0]

    # Adicionar a imagem à apresentação.
    with open("image.jpeg", "rb") as image_stream:
        image = presentation.images.add_image(image_stream)

        # Adicionar um quadro de imagem com tamanho da imagem.
        picture_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 50, 50, image.width, image.height, image)

        # Salvar a apresentação como PPTX.
        presentation.save("picture_frame.pptx", slides.export.SaveFormat.PPTX)

Quadros de imagem permitem que você crie rapidamente slides de apresentação a partir de imagens. Ao combinar quadros de imagem com as opções de salvamento do Aspose.Slides, você pode controlar as operações de E/S para converter imagens de um formato para outro. Você pode querer ver estas páginas: converter imagem para JPG; converter JPG para imagem; converter JPG para PNG; converter PNG para JPG; converter PNG para SVG; converter SVG para PNG.

Criar Quadros de Imagem com Escala Relativa

Esta seção demonstra a colocação de uma imagem em tamanho fixo e, em seguida, a aplicação de escala baseada em percentual independentemente na largura e altura. Como os percentuais podem ser diferentes, a proporção pode mudar. O dimensionamento é realizado em relação às dimensões originais da imagem.

Crie uma instância da classe Presentation.
Obtenha um slide pelo seu índice.
Crie um PPImage adicionando a imagem à ImageCollection da apresentação.
Adicione um PictureFrame ao slide.
Defina a largura e a altura relativas do quadro de imagem.
Salve a apresentação como um arquivo PPTX.

O código Python a seguir mostra como criar um quadro de imagem com escala relativa:

import aspose.slides as slides

# Instanciar a classe Presentation para representar um arquivo PPTX.
with slides.Presentation() as presentation:
    # Obter o primeiro slide.
    slide = presentation.slides[0]

    # Adicionar a imagem à coleção de imagens da apresentação.
    with open("image.jpeg", "rb") as image_stream:
        image = presentation.images.add_image(image_stream)

        # Adicionar um quadro de imagem ao slide.
        picture_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 50, 50, 100, 100, image)

        # Definir a largura e altura de escala relativa.
        picture_frame.relative_scale_height = 0.8
        picture_frame.relative_scale_width = 1.35

        # Salvar a apresentação.
        presentation.save("relative_scaling.pptx", slides.export.SaveFormat.PPTX)

Extrair Imagens Raster de Quadros de Imagem

Você pode extrair imagens raster de objetos PictureFrame e salvá‑las em PNG, JPG e outros formatos. O exemplo de código abaixo demonstra como extrair uma imagem do documento “sample.pptx” e salvá‑la no formato PNG.

import aspose.slides as slides

with slides.Presentation("sample.pptx") as presentation:
    first_slide = presentation.slides[0]
    first_shape = first_slide.shapes[0]

    if isinstance(first_shape, slides.PictureFrame):
        image = first_shape.picture_format.picture.image.image
        image.save("slide_1_shape_1.png", slides.ImageFormat.PNG)

Extrair Imagens SVG de Quadros de Imagem

Quando uma apresentação contém gráficos SVG inseridos dentro de formas PictureFrame, o Aspose.Slides para Python via .NET permite recuperar as imagens vetoriais originais com total fidelidade. Percorrendo a coleção de formas do slide, você pode identificar cada PictureFrame, verificar se o PPImage subjacente contém conteúdo SVG e, então, salvar essa imagem no disco ou em um stream no seu formato SVG nativo.

O exemplo de código a seguir demonstra como extrair uma imagem SVG de um quadro de imagem:

import aspose.slides as slides

with slides.Presentation("sample.pptx") as presentation:
    slide = presentation.slides[0]
    shape = slide.shapes[0]

    if isinstance(shape, slides.PictureFrame):
        svg_image = shape.picture_format.picture.image.svg_image

        if svg_image is not None:
            with open("output.svg", "w", encoding="utf-8") as svg_stream:
                svg_stream.write(svg_image.svg_content)

Obter Transparência da Imagem

Aspose.Slides permite que você recupere o efeito de transparência aplicado a uma imagem. Este código Python demonstra a operação:

import aspose.slides as slides

with slides.Presentation("sample.pptx") as presentation:
    picture_frame = presentation.slides[0].shapes[0]
    image_transform = picture_frame.picture_format.picture.image_transform
    for effect in image_transform:
        if isinstance(effect, slides.effects.AlphaModulateFixed):
            transparency_value = 100 - effect.amount
            print("Picture transparency: " + str(transparency_value))

Todos os efeitos aplicados a imagens podem ser encontrados em aspose.slides.effects.

Obter Brilho e Contraste de uma Imagem

Aspose.Slides permite que você recupere o efeito de brilho e contraste aplicado a uma imagem. A classe Luminance representa esse efeito de transformação de imagem.

Este código Python demonstra como obter as configurações de brilho e contraste de um quadro de imagem:

import aspose.slides as slides

with slides.Presentation("sample.pptx") as presentation:
    slide = presentation.slides[0]
    shape = slide.shapes[0]
    picture_frame = shape

    image_transform = picture_frame.picture_format.picture.image_transform
    for effect in image_transform:
        if isinstance(effect, slides.effects.Luminance):
            luminance = effect.get_effective()
            brightness = luminance.brightness
            contrast = luminance.contrast

            print("Brightness: " + str(brightness))
            print("Contrast: " + str(contrast))

Formatação de Quadros de Imagem

Aspose.Slides oferece muitas opções de formatação que você pode aplicar a um quadro de imagem. Com essas opções, você pode ajustar um quadro de imagem para atender a requisitos específicos.

Crie uma instância da classe Presentation.
Obtenha um slide pelo seu índice.
Crie um PPImage adicionando a imagem à ImageCollection da apresentação. Essa imagem será usada para preencher a forma.
Especifique a largura e a altura do quadro.
Crie um PictureFrame desse tamanho usando o método add_picture_frame da slide.
Defina a cor da linha do quadro de imagem.
Defina a espessura da linha do quadro de imagem.
Gire o quadro de imagem fornecendo um valor positivo (horário) ou negativo (anti‑horário).
Salve a apresentação modificada como um arquivo PPTX.

O código Python a seguir demonstra o processo de formatação do quadro de imagem:

import aspose.slides as slides
import aspose.pydrawing as draw

# Instanciar a classe Presentation para representar um arquivo PPTX.
with slides.Presentation() as presentation:
    # Obter o primeiro slide.
    slide = presentation.slides[0]

    # Adicionar a imagem à coleção de imagens da apresentação.
    with open("image.jpeg", "rb") as image_stream:
        image = presentation.images.add_image(image_stream)

        # Adicionar um quadro de imagem com tamanho da imagem.
        picture_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 50, 50, image.width, image.height, image)

        # Aplicar formatação ao quadro de imagem.
        picture_frame.line_format.fill_format.fill_type = slides.FillType.SOLID
        picture_frame.line_format.fill_format.solid_fill_color.color = draw.Color.blue
        picture_frame.line_format.width = 20
        picture_frame.rotation = 45

    # Salvar a apresentação como PPTX.
    presentation.save("picture_formatting.pptx", slides.export.SaveFormat.PPTX)

Tip

A Aspose desenvolveu um Collage Maker gratuito. Se precisar mesclar JPG/JPEG ou imagens PNG, ou criar grades de fotos, pode usar este serviço.

Adicionar Imagens como Links

Para manter os arquivos de apresentação pequenos, você pode adicionar imagens ou vídeos via links em vez de incorporar os arquivos diretamente nas apresentações. O código Python a seguir mostra como inserir uma imagem e um vídeo em um placeholder:

import aspose.slides as slides

with slides.Presentation("input.pptx") as presentation:
    slide = presentation.slides[0]

    shapes_to_remove = []

    for shape in slide.shapes:
        if shape.placeholder is None:
            continue

        if shape.placeholder.type == slides.PlaceholderType.PICTURE:
            picture_frame = slide.shapes.add_picture_frame(
                slides.ShapeType.RECTANGLE, shape.x, shape.y, shape.width, shape.height, None)

            picture_frame.picture_format.picture.link_path_long = \
                "https://upload.wikimedia.org/wikipedia/commons/3/3a/I.M_at_Old_School_Public_Broadcasting_in_October_2016_02.jpg"

            shapes_to_remove.append(shape)

        elif shape.placeholder.type == slides.PlaceholderType.MEDIA:
            video_frame = slide.shapes.add_video_frame(shape.X, shape.Y, shape.width, shape.height, "")

            video_frame.picture_format.picture.link_path_long = \
                "https://upload.wikimedia.org/wikipedia/commons/3/3a/I.M_at_Old_School_Public_Broadcasting_in_October_2016_02.jpg"

            video_frame.link_path_long = "https://youtu.be/t_1LYZ102RA"
            shapes_to_remove.append(shape)

    for shape in shapes_to_remove:
        slide.shapes.remove(shape)

    presentation.save("output.pptx", slides.export.SaveFormat.PPTX)

Recortar Imagens

Nesta seção, você aprenderá como recortar a área visível de uma imagem dentro de um quadro de imagem sem alterar o arquivo fonte. Você também aprenderá o método básico para aplicar margens de recorte e criar uma composição limpa e focada diretamente no slide.

O código Python a seguir mostra como recortar uma imagem em um slide:

import aspose.slides as slides

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

    # Adicionar a imagem à coleção de imagens da apresentação.
    with slides.Images.from_file("image.png") as source_image:
        image = presentation.images.add_image(source_image)

    # Adicionar um quadro de imagem ao slide.
    picture_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 100, 100, 420, 250, image)

    # Recortar a imagem (valores percentuais).
    picture_frame.picture_format.crop_left = 23.6
    picture_frame.picture_format.crop_right = 21.5
    picture_frame.picture_format.crop_top = 3
    picture_frame.picture_format.crop_bottom = 31

    # Salvar o resultado.
    presentation.save("cropped_image.pptx", slides.export.SaveFormat.PPTX)

Excluir Áreas Recortadas de Imagens

Se desejar excluir as áreas recortadas de uma imagem em um quadro, use o método delete_picture_cropped_areas. Esse método retorna a imagem recortada ou a imagem original se nenhum recorte for necessário.

O código Python a seguir demonstra a operação:

import aspose.slides as slides

with slides.Presentation("sample.pptx") as presentation:
    slide = presentation.slides[0]

    # Obter o PictureFrame do primeiro slide.
    picture_frame = slides.shape[0]

    # Obter o PictureFrame do primeiro slide.
    cropped_image = picture_frame.picture_format.delete_picture_cropped_areas()

    # Salvar o resultado.
    presentation.save("deleted_cropped_areas.pptx", slides.export.SaveFormat.PPTX)

NOTE

O método delete_picture_cropped_areas adiciona a imagem recortada à coleção de imagens da apresentação. Se a imagem for usada apenas no PictureFrame processado, isso pode reduzir o tamanho da apresentação; caso contrário, o número de imagens na apresentação resultante pode aumentar.

Durante o recorte, este método converte arquivos metafile WMF/EMF em uma imagem PNG raster.

Compactar Imagens

Você pode compactar uma imagem em uma apresentação usando o método PictureFillFormat.compress_image. Esse método compacta uma imagem reduzindo seu tamanho com base no tamanho da forma e na resolução especificada, com a opção de excluir áreas recortadas.

Ele ajusta o tamanho e a resolução da imagem de forma semelhante ao recurso Picture Format -> Compress Pictures -> Resolution do PowerPoint.

Os exemplos Python a seguir demonstram como compactar uma imagem em uma apresentação especificando uma resolução alvo e, opcionalmente, removendo áreas recortadas:

import aspose.slides as slides

with slides.Presentation("demo.pptx") as presentation:
    slide = presentation.slides[0]
    picture_frame = slide.shapes[0]

    # Comprimir a imagem com resolução alvo de 150 DPI (resolução Web) e remover áreas recortadas.
    result = picture_frame.picture_format.compress_image(True, slides.export.PicturesCompression.DPI150)

    # Verificar o resultado da compressão.
    if result:
        print("Image successfully compressed.")
    else:
        print("Image compression failed or no changes were necessary.")

    presentation.save("compressed_image.pptx", slides.export.SaveFormat.PPTX)

Ou usando um valor DPI personalizado diretamente:

import aspose.slides as slides

with slides.Presentation("demo.pptx") as presentation:
    slide = presentation.slides[0]
    picture_frame = slide.shapes[0]

    # Comprimir a imagem para 150 DPI (resolução web), removendo áreas recortadas.
    picture_frame.picture_format.compress_image(True, 150)

    presentation.save("compressed_image.pptx", slides.export.SaveFormat.PPTX)

NOTE

O método converte a imagem para uma resolução inferior com base no tamanho da forma e no DPI fornecido. Regiões recortadas também podem ser excluídas para otimizar o tamanho do arquivo. Se a imagem for um metafile (WMF/EMF) ou SVG, a compactação não será aplicada. Além disso, a qualidade JPEG é preservada ou ligeiramente reduzida com base na resolução, de forma semelhante ao que o PowerPoint faz com JPEGs de alta resolução.

Bloquear a Proporção de Aspecto

Se desejar que uma forma que contém uma imagem mantenha sua proporção de aspecto após alterar as dimensões da imagem, defina a propriedade aspect_ratio_locked como True.

O código Python a seguir mostra como bloquear a proporção de aspecto de uma forma:

import aspose.slides as slides

with slides.Presentation("sample.pptx") as presentation:
    layout = presentation.layout_slides.get_by_type(slides.SlideLayoutType.CUSTOM)
    empty_slide = presentation.slides.add_empty_slide(layout)

    with slides.Images.from_file("image.png") as source_image:
        image = presentation.images.add_image(source_image)

    picture_frame = empty_slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 50, 50, image.width, image.height, image)

    # Travar a proporção de aspecto ao redimensionar.
    picture_frame.picture_frame_lock.aspect_ratio_locked = True

    presentation.save("aspect_ratio_locked.pptx", slides.export.SaveFormat.PPTX)

NOTE

Esta configuração Lock Aspect Ratio preserva apenas a proporção de aspecto da forma, não a proporção de aspecto da imagem dentro dela.

Usar Propriedades de Deslocamento de Alongamento

Usando as propriedades stretch_offset_left, stretch_offset_top, stretch_offset_right e stretch_offset_bottom da classe PictureFillFormat, você pode definir um retângulo de preenchimento.

Quando o alongamento é especificado para uma imagem, o retângulo de origem é dimensionado para caber no retângulo de preenchimento. Cada borda do retângulo de preenchimento é definida por um deslocamento percentual em relação à borda correspondente da caixa delimitadora da forma. Um percentual positivo especifica um recuo, enquanto um percentual negativo especifica um avanço.

Crie uma instância da classe Presentation.
Obtenha uma referência a um slide pelo seu índice.
Adicione um AutoShape retangular.
Defina o tipo de preenchimento da forma.
Defina o modo de preenchimento de imagem da forma.
Carregue uma imagem.
Atribua a imagem para preencher a forma.
Especifique os deslocamentos da imagem em relação às bordas correspondentes da caixa delimitadora da forma.
Salve a apresentação como um arquivo PPTX.

O código Python a seguir demonstra como usar as propriedades de Deslocamento de Alongamento:

import aspose.slides as slides

# Instanciar a classe Presentation que representa um arquivo PPTX.
with slides.Presentation() as presentation:
    # Obter o primeiro slide.
    slide = presentation.slides[0]

    # Adicionar um AutoShape retangular.
    shape = slide.shapes.add_auto_shape(slides.ShapeType.RECTANGLE, 20, 20, 300, 300)

    # Definir o tipo de preenchimento da forma.
    shape.fill_format.fill_type = slides.FillType.PICTURE

    # Definir o modo de preenchimento de imagem da forma.
    shape.fill_format.picture_fill_format.picture_fill_mode = slides.PictureFillMode.STRETCH

    # Carregar a imagem e adicioná‑la à apresentação.
    with open("image.jpeg", "rb") as image_stream:
        image = presentation.images.add_image(image_stream)

    # Atribuir a imagem para preencher a forma.
    shape.fill_format.picture_fill_format.picture.image = image

    # Especificar deslocamentos da imagem a partir das bordas correspondentes da caixa delimitadora da forma.
    shape.fill_format.picture_fill_format.stretch_offset_left = 25
    shape.fill_format.picture_fill_format.stretch_offset_right = 25
    shape.fill_format.picture_fill_format.stretch_offset_top = -20
    shape.fill_format.picture_fill_format.stretch_offset_bottom = -10

    # Salvar o arquivo PPTX no disco.
    presentation.save("stretch_offset.pptx", slides.export.SaveFormat.PPTX)

Tip

A Aspose fornece conversores gratuitos—JPEG to PowerPoint e PNG to PowerPoint—que permitem criar rapidamente apresentações a partir de imagens.

FAQ

Como descobrir quais formatos de imagem são suportados para PictureFrame?

Aspose.Slides suporta tanto imagens raster (PNG, JPEG, BMP, GIF, etc.) quanto imagens vetoriais (por exemplo, SVG) via o objeto de imagem que é atribuído a um PictureFrame. A lista de formatos suportados geralmente se sobrepõe às capacidades do mecanismo de conversão de slides e imagens.

Como a adição de dezenas de imagens grandes afetará o tamanho e o desempenho do PPTX?

Incorporar imagens grandes aumenta o tamanho do arquivo e o uso de memória; vincular imagens ajuda a manter o tamanho da apresentação reduzido, mas requer que os arquivos externos permaneçam acessíveis. Aspose.Slides fornece a capacidade de adicionar imagens por link para reduzir o tamanho do arquivo.

Como bloquear um objeto de imagem para evitar movimentação/redimensionamento acidental?

Use shape locks para um PictureFrame (por exemplo, desativar movimentação ou redimensionamento). O mecanismo de bloqueio é descrito para formas em um artigo de proteção separado e é suportado para vários tipos de forma, incluindo PictureFrame.

O SVG vetor permanece fiel ao exportar uma apresentação para PDF/imagens?

Aspose.Slides permite extrair um SVG de um PictureFrame como o vetor original. Ao exportar para PDF ou formatos raster, o resultado pode ser rasterizado dependendo das configurações de exportação; o fato de o SVG original ser armazenado como vetor é confirmado pelo comportamento de extração.