Gerenciar efeitos de transformação de imagem em apresentações com Python

Sobre o que é esta página

Aplicar, encadear, inspecionar, remover e verificar efeitos de transformação de imagem para quadros de picture com Aspose.Slides para Python via .NET.

Visão geral

Aspose.Slides representa ajustes de imagem como uma coleção ordenada de operações de transformação de imagem. Para um quadro de imagem, comece com o Picture da moldura e acesse sua propriedade image_transform. A ImageTransformOperationCollection retornada permite que você anexe, enumere, inspecione, remova e limpe efeitos sem reescrever os bytes da imagem original.

Este artigo demonstra um fluxo de trabalho completo para brilho e contraste, transformações de cor, desfoque, transparência, cadeias de efeitos ordenadas, valores efetivos, remoção e verificação de ida e volta de PPTX.

Entender a propriedade do efeito e a reutilização de imagens

Um recurso de imagem e a picture que a exibe são objetos diferentes:

PPImage armazena ou referencia os dados de imagem de origem pertencentes à apresentação.
Picture pertence a um preenchimento de picture e refere‑se a um recurso de imagem enquanto armazena a coleção de transformações de imagem.
PictureFrame é a forma do slide que possui o preenchimento de picture relevante, geometria, configurações de recorte e outras formatações ao nível da moldura.

Portanto, as operações de transformação de imagem não modificam os bytes em PPImage. Quando o mesmo PPImage é passado para ShapeCollection.add_picture_frame mais de uma vez, cada novo quadro de imagem recebe seu próprio Picture e sua própria coleção de transformações. Aplicar escala de cinza a um quadro não deixa os outros quadros em escala de cinza, embora todos reutilizem o mesmo recurso de imagem incorporado.

O mesmo modelo Picture.image_transform também é usado por outros preenchimentos de picture, como um shape ou plano de fundo de slide. Os exemplos abaixo concentram‑se em quadros de picture.

Usar intervalos de parâmetros válidos e unidades

Os métodos demonstrados utilizam os seguintes intervalos semânticos e unidades. Mantenha os valores dentro desses intervalos mesmo que uma versão específica da biblioteca não rejeite imediatamente cada valor fora do intervalo; o formato de apresentação de destino pode normalizar, omitir ou rejeitar dados inválidos durante a gravação ou quando o PowerPoint abrir o arquivo.

Operação	Parâmetros	Intervalo válido e unidade
add_brightness_contrast_effect	`brightness`, `contrast`	`-100` até `100`, porcentagem; `0` deixa o componente inalterado.
add_gray_scale_effect	Nenhum	Sem parâmetros numéricos. Alfa permanece inalterado.
add_duotone_effect	`color1`, `color2`	Duas cores para pixels escuros e claros. Canais RGB e alfa usam `0` até `255`.
add_tint_effect	`hue`, `amount`	Matiz (`hue`) de `0` inclusive até `360` exclusivo, em graus; quantidade (`amount`) de `-100` até `100`, porcentagem.
add_hsl_effect	`hue`, `saturation`, `luminance`	Matiz (`hue`) de `0` inclusive até `360` exclusivo, em graus; saturação e luminância de `-100` até `100`, porcentagem.
add_color_replace_effect	`color`	A cor de substituição usa valores de canal de `0` até `255`. Valores alfa existentes permanecem inalterados.
add_blur_effect	`radius`, `grow`	Raio é não negativo e medido em pontos; `grow` é um Boolean que controla se o conteúdo desfocado pode se estender além dos limites originais.
add_alpha_modulate_fixed_effect	`amount`	Porcentagem não negativa. Use `0` até `100` para escala de opacidade comum: `0` é totalmente transparente e `100` preserva o alfa existente.
add_alpha_replace_effect	`alpha`	`0` até `100`, porcentagem de opacidade.
add_alpha_bi_level_effect	`threshold`	`0` até `100`, limiar alfa em porcentagem. Valores abaixo dele tornam‑se transparentes; valores iguais ou acima tornam‑se opacos.

Para modulação fixa de alfa, transparência e opacidade são complementares. Por exemplo, 35% de transparência corresponde a um valor de modulação alfa de 65%.

Aplicar Brilho e Contraste

ImageTransformOperationCollection.add_brightness_contrast_effect retorna uma operação BrightnessContrast. suas configurações escalares são fornecidas quando a operação é criada. BrightnessContrast.get_effective devolve valores calculados somente leitura que podem ser inspecionados ou registrados.

O exemplo a seguir aumenta o brilho em 15% e o contraste em 20%, então renderiza uma pré‑visualização sem modificar a imagem incorporada:

import aspose.slides as slides

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

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

    picture_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 50, 50, 400, 260, image)
    image_transform = picture_frame.picture_format.picture.image_transform
    brightness_contrast = image_transform.add_brightness_contrast_effect(15, 20)

    effective_values = brightness_contrast.get_effective()
    print("Brightness: " + str(effective_values.brightness) + "%")
    print("Contrast: " + str(effective_values.contrast) + "%")

    with slide.get_image() as preview:
        preview.save("brightness-contrast-preview.png")

BrightnessContrast é uma extensão de efeito de picture do Office 2010 e é menos portátil que o efeito padrão de luminância do DrawingML. Quando brilho e contraste precisam permanecer editáveis após uma viagem de ida e volta de PPTX, use ImageTransformOperationCollection.add_luminance_effect e verifique o resultado após reabrir o arquivo. A seção de limitações de formato explica essa distinção com mais detalhes.

Aplicar Transformações de Cor

Efeitos de cor podem ser aplicados independentemente a diferentes quadros de picture que reutilizam um recurso de imagem. O exemplo a seguir cria cinco quadros e aplica escala de cinza, duotone, tonalidade, ajuste HSL e substituição de cor.

Duotone contém dois parâmetros de cor editáveis independentemente: color1 mapeia pixels escuros, enquanto color2 mapeia pixels claros. Isso o torna um exemplo útil de um efeito cujas configurações são mais complexas que um único valor escalar.

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

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

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

    gray_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 20, 20, 180, 120, image)
    gray_frame.picture_format.picture.image_transform.add_gray_scale_effect()

    duotone_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 220, 20, 180, 120, image)
    duotone = duotone_frame.picture_format.picture.image_transform.add_duotone_effect()
    duotone.color1.color = draw.Color.navy
    duotone.color2.color = draw.Color.gold

    tint_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 420, 20, 180, 120, image)
    tint_frame.picture_format.picture.image_transform.add_tint_effect(210, 35)

    hsl_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 120, 170, 180, 120, image)
    hsl_frame.picture_format.picture.image_transform.add_hsl_effect(30, 20, -10)

    replacement_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 320, 170, 180, 120, image)
    color_replacement = replacement_frame.picture_format.picture.image_transform.add_color_replace_effect()
    color_replacement.color.color = draw.Color.cornflower_blue

    presentation.save("color-transformations.pptx", slides.export.SaveFormat.PPTX)

add_color_replace_effect substitui a cor de cada pixel por uma cor fixa preservando o alfa. É diferente de add_color_change_effect, que mapeia uma cor fonte para outra e expõe ambos os formatos de cor fonte e destino.

Adicionar Desfoque, Transparência e Efeitos Alfa

add_blur_effect afeta todos os canais de cor, incluindo alfa. Defina grow como True quando a borda desfocada puder se estender além dos limites originais da picture.

Para transparência uniforme, use add_alpha_modulate_fixed_effect. Ele multiplica cada valor alfa existente, de modo que pixels parcialmente transparentes permanecem proporcionalmente diferentes. add_alpha_replace_effect em vez disso atribui um único valor alfa a todos os pixels. add_alpha_bi_level_effect converte alfa em dois níveis com base em um limiar.

import aspose.slides as slides

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

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

    blurred_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 20, 20, 200, 140, image)
    blur = blurred_frame.picture_format.picture.image_transform.add_blur_effect(4.5, True)
    blur.radius = 5

    transparent_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 240, 20, 200, 140, image)
    alpha_modulate = transparent_frame.picture_format.picture.image_transform.add_alpha_modulate_fixed_effect(65)
    alpha_modulate.amount = 60

    uniform_alpha_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 20, 180, 200, 140, image)
    uniform_alpha_frame.picture_format.picture.image_transform.add_alpha_replace_effect(55)

    binary_alpha_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 240, 180, 200, 140, image)
    alpha_bi_level = binary_alpha_frame.picture_format.picture.image_transform.add_alpha_bi_level_effect(50)
    alpha_bi_level.threshold = 45
    binary_alpha_frame.picture_format.picture.image_transform.add_alpha_inverse_effect()

    presentation.save("blur-and-alpha-effects.pptx", slides.export.SaveFormat.PPTX)

Outras operações de alfa sem parâmetros incluem add_alpha_ceiling_effect, que torna todo alfa não zero totalmente opaco; add_alpha_floor_effect, que torna todo alfa abaixo de 100% totalmente transparente; e add_alpha_inverse_effect, que muda alfa para 100% - alfa.

Construir uma Cadeia de Efeitos Ordenada

Cada método add_..._effect anexa uma nova operação ao final da coleção. O renderizador usa a coleção como um pipeline ordenado: a saída da operação 0 torna‑se a entrada da operação 1, e assim sucessivamente. Consequentemente, as mesmas operações em ordem diferente podem produzir imagens diferentes.

Por exemplo, escala de cinza seguida de tonalidade primeiro remove informações cromáticas e então recolore o resultado de luminância. Tonalidade seguida de escala de cinza remove a tonalidade novamente. Da mesma forma, substituição de alfa pode sobrescrever valores de alfa calculados por operações anteriores, enquanto modulação de alfa preserva suas diferenças relativas.

O exemplo a seguir constrói uma cadeia de quatro operações, salva como PPTX, reabre a apresentação, verifica tanto os tipos das operações quanto sua ordem e renderiza o resultado reaberto:

import aspose.slides as slides

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

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

    picture_frame = slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, 50, 50, 400, 260, image)
    image_transform = picture_frame.picture_format.picture.image_transform
    image_transform.add_gray_scale_effect()
    image_transform.add_tint_effect(220, 25)
    image_transform.add_blur_effect(2.5, False)
    image_transform.add_alpha_modulate_fixed_effect(80)

    presentation.save("image-transform-chain.pptx", slides.export.SaveFormat.PPTX)

with slides.Presentation("image-transform-chain.pptx") as reopened_presentation:
    reopened_shape = reopened_presentation.slides[0].shapes[0]

    if isinstance(reopened_shape, slides.PictureFrame):
        reopened_transform = reopened_shape.picture_format.picture.image_transform
        order_is_preserved = (
            len(reopened_transform) == 4 and
            isinstance(reopened_transform[0], slides.effects.GrayScale) and
            isinstance(reopened_transform[1], slides.effects.Tint) and
            isinstance(reopened_transform[2], slides.effects.Blur) and
            isinstance(reopened_transform[3], slides.effects.AlphaModulateFixed)
        )
        print("The effect chain was preserved." if order_is_preserved else "The effect chain changed during the round trip.")

        with reopened_presentation.slides[0].get_image() as rendered_slide:
            rendered_slide.save("reopened-effect-chain.png")
    else:
        print("The reopened shape is not a picture frame.")

A coleção não impõe uma matriz de compatibilidade que restrinja operações de cor, alfa e desfoque a cadeias separadas. Elas podem ser combinadas, mas combinações nem sempre são úteis. Uma substituição de cor fixa remove variações RGB produzidas por efeitos de cor anteriores; escala de cinza após duotone remove as duas cores selecionadas; e operações de teto, piso, substituição ou bi‑nível de alfa podem descartar detalhes de alfa criados anteriormente. Construa a cadeia de acordo com a sequência desejada de processamento de pixels em vez de tratar seus itens como flags de formatação não ordenados.

Inspecionar Valores Editáveis e Efetivos

Uma operação editável é o objeto armazenado em Picture.image_transform. Dependendo do efeito, pode expor membros graváveis diretamente. Por exemplo, Blur expõe propriedades graváveis radius e grow, AlphaModulateFixed expõe uma propriedade gravável amount, e AlphaBiLevel expõe uma propriedade gravável threshold. Efeitos de cor como Duotone expõem objetos mutáveis ColorFormat.

Algumas operações, incluindo BrightnessContrast, HSL, Tint, e AlphaReplace, não expõem seus escalares de criação como propriedades graváveis. Para mudar essas configurações, remova a operação e adicione uma substituição na posição desejada.

Dados efetivos retornados por get_effective() são calculados e somente leitura. São úteis para resolver cores dependentes de tema e ler os valores normalizados que o renderizador usa, mas não constituem outra superfície de edição. O exemplo a seguir enumera a cadeia e inspeciona valores efetivos onde a API correspondente os fornece:

import aspose.slides as slides

with slides.Presentation("image-transform-chain.pptx") as presentation:
    picture_frame = None

    for shape in presentation.slides[0].shapes:
        if isinstance(shape, slides.PictureFrame):
            picture_frame = shape
            break

    if picture_frame is not None:
        image_transform = picture_frame.picture_format.picture.image_transform

        for index, operation in enumerate(image_transform):
            print(str(index) + ": " + type(operation).__name__)

            if isinstance(operation, slides.effects.BrightnessContrast):
                effect_data = operation.get_effective()
                print("  Brightness: " + str(effect_data.brightness))
                print("  Contrast: " + str(effect_data.contrast))
            elif isinstance(operation, slides.effects.Luminance):
                effect_data = operation.get_effective()
                print("  Brightness: " + str(effect_data.brightness))
                print("  Contrast: " + str(effect_data.contrast))
            elif isinstance(operation, slides.effects.Duotone):
                effect_data = operation.get_effective()
                print("  Dark color: " + str(effect_data.color1))
                print("  Light color: " + str(effect_data.color2))
            elif isinstance(operation, slides.effects.ColorReplace):
                effect_data = operation.get_effective()
                print("  Replacement color: " + str(effect_data.color))
            elif isinstance(operation, slides.effects.HSL):
                effect_data = operation.get_effective()
                print("  HSL: " + str(effect_data.hue) + ", " + str(effect_data.saturation) + ", " + str(effect_data.luminance))
            elif isinstance(operation, slides.effects.Tint):
                effect_data = operation.get_effective()
                print("  Tint: " + str(effect_data.hue) + ", " + str(effect_data.amount))
            elif isinstance(operation, slides.effects.Blur):
                effect_data = operation.get_effective()
                print("  Blur radius: " + str(effect_data.radius) + " pt")
            elif isinstance(operation, slides.effects.AlphaModulateFixed):
                effect_data = operation.get_effective()
                print("  Alpha amount: " + str(effect_data.amount) + "%")
            elif isinstance(operation, slides.effects.AlphaReplace):
                effect_data = operation.get_effective()
                print("  Replacement alpha: " + str(effect_data.alpha) + "%")
            elif isinstance(operation, slides.effects.AlphaBiLevel):
                effect_data = operation.get_effective()
                print("  Alpha threshold: " + str(effect_data.threshold) + "%")

Efeitos sem parâmetros como escala de cinza, teto de alfa e inverso de alfa ainda têm um objeto de dados efetivos, mas não há configurações escalares para imprimir. Sua presença e posição na coleção são as informações importantes.

Remover ou Limpar Transformações de Imagem

Use ImageTransformOperationCollection.remove_at para remover uma operação por índice. Como os índices mudam após a remoção, procure o alvo primeiro e remova‑o depois da enumeração. Use clear() para remover a cadeia inteira.

import aspose.slides as slides

with slides.Presentation("image-transform-chain.pptx") as presentation:
    picture_frame = None

    for shape in presentation.slides[0].shapes:
        if isinstance(shape, slides.PictureFrame):
            picture_frame = shape
            break

    if picture_frame is not None:
        image_transform = picture_frame.picture_format.picture.image_transform
        blur_index = None

        for index, operation in enumerate(image_transform):
            if isinstance(operation, slides.effects.Blur):
                blur_index = index
                break

        if blur_index is not None:
            image_transform.remove_at(blur_index)
            print("The blur operation was removed.")

        image_transform.clear()
        print("Remaining operations: " + str(len(image_transform)))
        presentation.save("image-transforms-cleared.pptx", slides.export.SaveFormat.PPTX)

Remover ou limpar transformações altera apenas a formatação da picture. Não exclui, recomprime ou altera de outra forma o recurso PPImage reutilizado.

Considerar Formatos de Apresentação e Destinos de Exportação

Transformações de imagem originam‑se no DrawingML, portanto PPTX é o formato editável preferido para cadeias de efeito. Mesmo com PPTX, nem toda operação tem portabilidade idêntica:

Operações padrão do DrawingML como luminância, escala de cinza, duotone, tonalidade, HSL, desfoque e operações alfa comuns têm a maior chance de sobreviver a uma viagem de ida e volta de PPTX. Sempre reabra o arquivo gerado e inspecione a coleção quando a preservação for necessária.
BrightnessContrast é uma extensão do Office 2010 em vez da operação padrão de luminância do DrawingML. Pode ser usado para renderização em memória, mas não há garantia de que permaneça como uma operação editável BrightnessContrast após salvar e reabrir o PPTX. Prefira add_luminance_effect para ajustes persistentes de brilho e contraste.
O formato binário PPT antecede o modelo completo de efeitos DrawingML. Salvar como PPT pode omitir operações não suportadas, reduzir a cadeia a um subconjunto suportado ou aproximar a aparência. Não use PPT como formato de verificação para uma cadeia editável complexa.
Renderizar para PNG, JPEG, TIFF, PDF, SVG, HTML ou outra saída visual aplica a cadeia suportada à aparência renderizada. Essas saídas não contêm uma ImageTransformOperationCollection editável; formatos raster flatten o resultado em pixels, e exportações de documento ou vetor armazenam sua própria representação de renderização.
Efeitos não tornam uma imagem vinculada autônoma. Renderizar uma picture vinculada ainda depende que o recurso vinculado esteja disponível quando a apresentação for carregada.

Consumidores diferentes de apresentações podem renderizar casos limites de forma diversa, especialmente quando várias operações alfa ou de quantização de cor são combinadas. Para saída crítica, teste tanto a viagem de ida e volta editável quanto o formato de exportação final com a mesma versão do Aspose.Slides usada em produção.

Perguntas Frequentes

Os efeitos de transformação de imagem modificam os dados da imagem incorporada?

Não. As operações pertencem ao Picture usado pelo preenchimento da picture. Os bytes subjacentes do PPImage permanecem inalterados.

Dois quadros de picture que reutilizam a mesma imagem compartilharão seus efeitos?

Não. Reutilizar um PPImage evita dados de imagem duplicados, mas cada quadro de picture normalmente tem um Picture separado e uma coleção de transformações de imagem.

É possível combinar efeitos de cor, desfoque e alfa?

Sim. A coleção aceita-os em uma única cadeia ordenada. Considere o que cada operação faz à saída da anterior, pois operações de substituição e limiar podem descartar detalhes de cor ou alfa anteriores.

Por que os valores efetivos são somente leitura?

Dados efetivos representam valores calculados usados para renderização, incluindo cores resolvidas. Edite a operação armazenada na coleção de transformações onde existam membros graváveis; caso contrário, remova‑a e adicione uma substituição com novos parâmetros de criação.

Qual formato devo usar para preservar uma cadeia de transformações?

Use PPTX e verifique o arquivo reaberto. O legado PPT não pode representar o modelo completo de efeitos DrawingML, e formatos de exportação renderizados preservam apenas a aparência, não as operações de transformação editáveis.

Gerenciar áudio em apresentações usando Python