Gestire le cornici immagine nelle presentazioni usando PHP

Panoramica

Un cornice immagine è una forma della diapositiva che visualizza un’immagine. In Aspose.Slides, la risorsa immagine e la forma che la visualizza sono oggetti separati: una Presentation possiede le risorse immagine incorporate tramite la sua ImageCollection, mentre una PictureFrame controlla la posizione, le dimensioni, la formattazione della linea, la rotazione, il ritaglio, gli effetti immagine e altre impostazioni a livello di cornice.

Questa separazione è utile quando la stessa immagine viene mostrata più di una volta. Aggiungi l’immagine alla presentazione una sola volta, conserva il PPImage restituito e utilizza quella risorsa immagine quando crei le cornici immagine.

Le cornici immagine possono contenere immagini raster come PNG o JPEG e immagini vettoriali SVG. Possono anche fare riferimento a immagini collegate invece di memorizzare i byte dell’immagine nella presentazione. La scelta influisce sulla portabilità, sulle dimensioni del file, sull’estrazione e sul comportamento di esportazione, quindi è utile decidere come l’immagine debba essere memorizzata prima di applicare formattazioni o ottimizzazioni.

Aggiungere e formattare un’immagine incorporata

Per un’immagine incorporata, aggiungi i dati dell’immagine alla presentazione e crea una cornice immagine con ShapeCollection::addPictureFrame. L’immagine diventa parte del pacchetto della presentazione, così la presentazione rimane autonoma quando viene spostata su un altro computer.

L’esempio seguente aggiunge un’immagine JPEG, crea una cornice con le dimensioni native dell’immagine e applica la formattazione della linea e la rotazione:

use aspose\slides\FillType;
use aspose\slides\Images;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;
use aspose\slides\ShapeType;

$presentation = new Presentation();
try {
    $slide = $presentation->getSlides()->get_Item(0);

    $sourceImage = Images::fromFile("photo.jpg");
    try {
        $image = $presentation->getImages()->addImage($sourceImage);
    } finally {
        if (!java_is_null($sourceImage)) {
            $sourceImage->dispose();
        }
    }

    $pictureFrame = $slide->getShapes()->addPictureFrame(ShapeType::Rectangle, 50, 100, $image->getWidth(), $image->getHeight(), $image);
    $pictureFrame->getLineFormat()->getFillFormat()->setFillType(FillType::Solid);
    $pictureFrame->getLineFormat()->getFillFormat()->getSolidFillColor()->setColor(java("java.awt.Color")->BLUE);
    $pictureFrame->getLineFormat()->setWidth(3);
    $pictureFrame->setRotation(15);

    $presentation->save("picture-frame.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

La cornice immagine controlla la geometria visualizzata; modificare le dimensioni della cornice non cambia le dimensioni pixel originali memorizzate nella risorsa immagine incorporata. Questa distinzione diventa importante quando si ritaglia o si comprime un’immagine in seguito.

Utilizzare la scala relativa

PictureFrame espone la scalatura relativa di larghezza e altezza per la cornice tramite setRelativeScaleWidth e setRelativeScaleHeight. Un valore di 1.0 corrisponde al 100 % della dimensione originale dell’immagine. La scala relativa è utile quando un flusso di lavoro deve preservare una relazione con le dimensioni dell’immagine di origine invece di calcolare manualmente le dimensioni finali.

use aspose\slides\Images;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;
use aspose\slides\ShapeType;

$presentation = new Presentation();
try {
    $slide = $presentation->getSlides()->get_Item(0);

    $sourceImage = Images::fromFile("photo.jpg");
    try {
        $image = $presentation->getImages()->addImage($sourceImage);
    } finally {
        if (!java_is_null($sourceImage)) {
            $sourceImage->dispose();
        }
    }

    $pictureFrame = $slide->getShapes()->addPictureFrame(ShapeType::Rectangle, 50, 50, 100, 100, $image);
    $pictureFrame->setRelativeScaleWidth(1.35);
    $pictureFrame->setRelativeScaleHeight(0.8);

    $presentation->save("relative-scale.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

La scala relativa modifica le impostazioni di scala della cornice; non ricampiona né comprime l’immagine incorporata.

Immagini incorporate e collegate

Un’immagine incorporata memorizza i dati dell’immagine all’interno della presentazione ed è quindi la scelta più sicura per la portabilità e il rendering prevedibile. Un’immagine collegata memorizza un percorso esterno tramite il metodo Picture::setLinkPathLong invece di incorporare i dati dell’immagine nello stesso modo.

Le immagini collegate possono ridurre la quantità di dati immagine memorizzati nel PPTX, ma introducono una dipendenza esterna. Il file collegato deve rimanere accessibile all’applicazione che apre o rende la presentazione. Se il percorso cambia, il file è spostato o la risorsa non è disponibile, la foto collegata potrebbe non essere visualizzata come previsto. Per presentazioni che devono essere inviate via e‑mail, archiviate o renderizzate in ambienti isolati, le immagini incorporate sono generalmente più affidabili.

Aggiungere un’immagine collegata

L’esempio seguente crea una cornice immagine e la punta verso un file immagine locale. Gestisce solo il collegamento delle immagini; il collegamento dei video è un flusso di lavoro multimediale separato e non è mescolato in questo esempio.

use aspose\slides\Presentation;
use aspose\slides\SaveFormat;
use aspose\slides\ShapeType;

$presentation = new Presentation();
try {
    $slide = $presentation->getSlides()->get_Item(0);

    $pictureFrame = $slide->getShapes()->addPictureFrame(ShapeType::Rectangle, 50, 50, 320, 180, null);
    $linkedImageFile = new Java("java.io.File", "linked-image.jpg");
    $pictureFrame->getPictureFormat()->getPicture()->setLinkPathLong($linkedImageFile->getAbsolutePath());

    $presentation->save("linked-image.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

Usa i collegamenti quando la gestione di file esterni è intenzionale. Non usarli semplicemente come sostituto della compressione: un PPTX piccolo con dipendenze immagine interrotte è solitamente meno utile di una presentazione più grande e autonoma.

Estrarre immagini dalle cornici immagine

Prima di estrarre un’immagine da una presentazione esistente, verifica che una forma sia effettivamente una PictureFrame e che contenga un’immagine incorporata. Le cornici immagine collegate potrebbero non contenere byte immagine estraibili nello stesso modo.

Estrarre un’immagine raster

L’API immagine moderna utilizza direttamente IImage. L’esempio seguente trova la prima immagine raster incorporata su una diapositiva e la salva come PNG:

use aspose\slides\ImageFormat;
use aspose\slides\Presentation;

$presentation = new Presentation("sample.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shapeCount = java_values($slide->getShapes()->size());

    for ($index = 0; $index < $shapeCount; $index++) {
        $shape = $slide->getShapes()->get_Item($index);
        if (!java_instanceof($shape, new JavaClass("com.aspose.slides.PictureFrame"))) {
            continue;
        }

        $embeddedImage = $shape->getPictureFormat()->getPicture()->getImage();
        if (java_is_null($embeddedImage) || !java_is_null($embeddedImage->getSvgImage())) {
            continue;
        }

        $rasterImage = $embeddedImage->getImage();
        try {
            $rasterImage->save("extracted-image.png", ImageFormat::Png);
        } finally {
            if (!java_is_null($rasterImage)) {
                $rasterImage->dispose();
            }
        }
        break;
    }
} finally {
    $presentation->dispose();
}

Il salvataggio tramite IImage::save converte l’immagine estratta nel formato di output richiesto. Se ti servono i byte codificati memorizzati nella presentazione anziché un file raster convertito, usa i dati binari della risorsa immagine.

Estrarre un’immagine SVG

Per un’immagine SVG, il PPImage espone un oggetto SvgImage. Questo ti consente di recuperare direttamente i dati SVG invece di rasterizzare prima l’immagine.

use aspose\slides\Presentation;

$presentation = new Presentation("sample.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shapeCount = java_values($slide->getShapes()->size());

    for ($index = 0; $index < $shapeCount; $index++) {
        $shape = $slide->getShapes()->get_Item($index);
        if (!java_instanceof($shape, new JavaClass("com.aspose.slides.PictureFrame"))) {
            continue;
        }

        $embeddedImage = $shape->getPictureFormat()->getPicture()->getImage();
        $svgImage = java_is_null($embeddedImage) ? null : $embeddedImage->getSvgImage();
        if ($svgImage === null || java_is_null($svgImage)) {
            continue;
        }

        $outputStream = new Java("java.io.FileOutputStream", "extracted-image.svg");
        try {
            $outputStream->write($svgImage->getSvgData());
        } finally {
            $outputStream->close();
        }
        break;
    }
} finally {
    $presentation->dispose();
}

Mantenere il contenuto SVG come SVG preserva la sorgente vettoriale all’interno della presentazione. Le esportazioni raster come PNG o JPEG rendono necessariamente quel contenuto vettoriale in pixel. Anche l’esportazione di diapositive in PDF o SVG è un’operazione di rendering, quindi la grafica esportata non dovrebbe essere trattata come una copia byte‑per‑byte dell’originale SVG incorporato; usa i dati SvgImage::getSvgData incorporati quando è necessaria la risorsa vettoriale originale.

Ritagliare un’immagine

Il ritaglio modifica quale parte di un’immagine è visibile all’interno della cornice. I valori di ritaglio su PictureFillFormat sono percentuali delle dimensioni dell’immagine di origine. Il ritaglio non elimina inizialmente i pixel nascosti dall’immagine incorporata; cambia solo la regione visibile.

L’esempio seguente trova una cornice immagine in modo sicuro e applica i valori di ritaglio:

use aspose\slides\Presentation;
use aspose\slides\SaveFormat;

$presentation = new Presentation("sample.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $pictureFrame = null;
    $shapeCount = java_values($slide->getShapes()->size());

    for ($index = 0; $index < $shapeCount; $index++) {
        $shape = $slide->getShapes()->get_Item($index);
        if (java_instanceof($shape, new JavaClass("com.aspose.slides.PictureFrame"))) {
            $pictureFrame = $shape;
            break;
        }
    }

    if ($pictureFrame !== null) {
        $pictureFrame->getPictureFormat()->setCropLeft(23.6);
        $pictureFrame->getPictureFormat()->setCropRight(21.5);
        $pictureFrame->getPictureFormat()->setCropTop(3);
        $pictureFrame->getPictureFormat()->setCropBottom(31);
        $presentation->save("cropped-image.pptx", SaveFormat::Pptx);
    }
} finally {
    $presentation->dispose();
}

Poiché i dati dell’immagine nascosta sono ancora presenti, il ritaglio può essere modificato in seguito senza perdere i pixel originali. Se le dimensioni del file sono più importanti della reversibilità, le regioni ritagliate possono essere rimosse fisicamente come descritto nella sezione successiva.

Rimuovere i dati dell’immagine ritagliata

PictureFillFormat::deletePictureCroppedAreas rimuove i dati immagine al di fuori del rettangolo di ritaglio corrente e restituisce la risorsa immagine risultante. Questo può ridurre le dimensioni del file, ma è un’ottimizzazione distruttiva: dopo il salvataggio della presentazione, i pixel rimossi non sono più disponibili per un’operazione di “uncrop”.

use aspose\slides\Presentation;
use aspose\slides\SaveFormat;

$presentation = new Presentation("cropped-image.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $pictureFrame = null;
    $shapeCount = java_values($slide->getShapes()->size());

    for ($index = 0; $index < $shapeCount; $index++) {
        $shape = $slide->getShapes()->get_Item($index);
        if (java_instanceof($shape, new JavaClass("com.aspose.slides.PictureFrame"))) {
            $pictureFrame = $shape;
            break;
        }
    }

    if ($pictureFrame !== null) {
        $croppedImage = $pictureFrame->getPictureFormat()->deletePictureCroppedAreas();
        if (!java_is_null($croppedImage)) {
            $presentation->save("cropped-data-removed.pptx", SaveFormat::Pptx);
        }
    }
} finally {
    $presentation->dispose();
}

Il metodo può aggiungere una nuova risorsa immagine alla presentazione. Se l’immagine originale è utilizzata anche da altre cornici immagine, quelle cornici hanno comunque bisogno della risorsa esistente, quindi l’eliminazione delle aree ritagliate non riduce necessariamente il numero totale di immagini. Il ritaglio di contenuti WMF o EMF con questo metodo rasterizza il risultato ritagliato in PNG.

Comprimere immagini raster

PictureFillFormat::compressImage riduce la risoluzione dell’immagine raster rispetto alle dimensioni con cui l’immagine è visualizzata. Può anche rimuovere le regioni ritagliate nella stessa operazione. Il metodo restituisce true quando l’immagine è stata ridimensionata o ritagliata e false quando non è stato necessario alcun cambiamento.

Usa un valore predefinito di PicturesCompression quando è sufficiente una risoluzione target standard:

use aspose\slides\PicturesCompression;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;

$presentation = new Presentation("sample.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $pictureFrame = null;
    $shapeCount = java_values($slide->getShapes()->size());

    for ($index = 0; $index < $shapeCount; $index++) {
        $shape = $slide->getShapes()->get_Item($index);
        if (java_instanceof($shape, new JavaClass("com.aspose.slides.PictureFrame"))) {
            $pictureFrame = $shape;
            break;
        }
    }

    if ($pictureFrame !== null) {
        $compressed = $pictureFrame->getPictureFormat()->compressImage(true, PicturesCompression::Dpi150);
        echo $compressed ? "The image was compressed." : "No compression was necessary.";
        $presentation->save("compressed-image.pptx", SaveFormat::Pptx);
    }
} finally {
    $presentation->dispose();
}

È possibile passare un valore DPI positivo personalizzato al posto di un valore predefinito quando è richiesto un target specifico.

La compressione è destinata alle immagini raster. I contenuti SVG e metafile non vengono ridotti da questo flusso di lavoro di compressione raster. Ricorda anche che risoluzioni più basse e regioni ritagliate eliminate non possono essere recuperate dalla presentazione ottimizzata. Scegli una risoluzione target basata sulla dimensione massima alla quale l’immagine sarà realmente visualizzata o esportata, piuttosto che applicare il DPI più basso a livello globale.

Gestire gli effetti di trasformazione dell’immagine

Per un flusso di lavoro completo che copra luminosità, contrasto, trasformazioni colore, sfocatura, effetti alfa, catene ordinate, ispezione, rimozione e verifica round‑trip, vedi Image Transform Effects.

Bloccare la geometria della cornice immagine

Le impostazioni di PictureFrameLock controllano quali operazioni di modifica sono disabilitate per una cornice immagine. Per esempio, setAspectRatioLocked preserva le proporzioni della forma mentre viene ridimensionata.

use aspose\slides\Images;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;
use aspose\slides\ShapeType;

$presentation = new Presentation();
try {
    $slide = $presentation->getSlides()->get_Item(0);

    $sourceImage = Images::fromFile("photo.jpg");
    try {
        $image = $presentation->getImages()->addImage($sourceImage);
    } finally {
        if (!java_is_null($sourceImage)) {
            $sourceImage->dispose();
        }
    }

    $pictureFrame = $slide->getShapes()->addPictureFrame(ShapeType::Rectangle, 50, 100, $image->getWidth(), $image->getHeight(), $image);
    $pictureFrame->getPictureFrameLock()->setAspectRatioLocked(true);

    $presentation->save("locked-picture-frame.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

Il blocco si applica alla forma della cornice immagine. Non forza l’immagine sorgente a essere ricampionata o permanentemente modificata per avere lo stesso rapporto d’aspetto.

Regolare i valori StretchOffset

Quando la modalità di riempimento immagine è stretch, i valori stretch‑offset su PictureFillFormat definiscono il rettangolo di riempimento relativo al riquadro della cornice immagine. Percentuali positive creano un rientro da un bordo, mentre percentuali negative creano un’estensione.

Questo è diverso dal ritaglio. I valori di ritaglio selezionano quale parte dell’immagine di origine è visibile; gli offset di stretch modificano il rettangolo nel quale il riempimento immagine visibile è esteso.

use aspose\slides\Images;
use aspose\slides\PictureFillMode;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;
use aspose\slides\ShapeType;

$presentation = new Presentation();
try {
    $slide = $presentation->getSlides()->get_Item(0);

    $sourceImage = Images::fromFile("photo.png");
    try {
        $image = $presentation->getImages()->addImage($sourceImage);
    } finally {
        if (!java_is_null($sourceImage)) {
            $sourceImage->dispose();
        }
    }

    $pictureFrame = $slide->getShapes()->addPictureFrame(ShapeType::Rectangle, 10, 10, 400, 300, $image);
    $pictureFrame->getPictureFormat()->setPictureFillMode(PictureFillMode::Stretch);
    $pictureFrame->getPictureFormat()->setStretchOffsetLeft(12);
    $pictureFrame->getPictureFormat()->setStretchOffsetRight(12);
    $pictureFrame->getPictureFormat()->setStretchOffsetTop(8);
    $pictureFrame->getPictureFormat()->setStretchOffsetBottom(8);

    $presentation->save("stretch-offsets.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

Usa gli stretch‑offset per il posizionamento del riempimento. Usa le proprietà di ritaglio quando l’obiettivo è nascondere i bordi dell’immagine di origine.

Considerazioni su archiviazione, dimensione del file ed esportazione

I principali compromessi sono più facili da gestire quando l’archiviazione delle immagini e la formattazione della cornice immagine sono trattate separatamente:

  • Immagini incorporate rendono la presentazione autonoma e sono le più affidabili per la condivisione e il rendering lato server, ma le grandi immagini raster aumentano la dimensione del PPTX e l’uso di memoria.
  • Immagini collegate possono mantenere il pacchetto più piccolo, ma la presentazione dipende dal fatto che i file esterni rimangano disponibili nei percorsi o nelle posizioni memorizzate.
  • Ritaglio è inizialmente non distruttivo. I pixel nascosti rimangono incorporati finché le aree ritagliate non vengono eliminate esplicitamente o rimosse durante la compressione.
  • Compressione può ridurre in modo significativo le dimensioni del file per immagini raster sovradimensionate, ma sacrifica la risoluzione di origine. Deve essere applicata dopo aver conosciuto la dimensione effettiva sull‑slide.
  • Immagini SVG dovrebbero rimanere come SVG quando la preservazione vettoriale è importante. Estrai direttamente l’SVG incorporato quando hai bisogno della risorsa vettoriale stessa. Le esportazioni raster delle diapositive convertono sempre la diapositiva renderizzata in pixel.
  • Immagini ripetute dovrebbero riutilizzare una risorsa PPImage esistente quando possibile invece di caricare ripetutamente lo stesso file nel flusso di lavoro della presentazione.

Per presentazioni di grandi dimensioni, l’ottimizzazione delle immagini è di solito più efficace quando eseguita in modo selettivo: mantieni loghi e diagrammi come contenuto vettoriale, comprimi le fotografie in base alla loro reale dimensione di visualizzazione, rimuovi i pixel ritagliati solo quando non è più necessario modificare in seguito e evita i collegamenti esterni a meno che la gestione delle dipendenze non faccia parte del design di distribuzione.

FAQ

Qual è la differenza tra una cornice immagine e una risorsa immagine?

Un PPImage rappresenta una risorsa immagine associata alla presentazione. Un PictureFrame è una forma su una diapositiva che visualizza un’immagine e memorizza geometria e formattazione a livello di cornice come dimensioni, rotazione, valori di ritaglio, effetti e blocchi.

Devo incorporare o collegare le immagini?

Incorpora le immagini quando la presentazione deve essere portabile, archiviata o renderizzata senza accesso a risorse esterne. Collega le immagini solo quando tenere i file immagine fuori dal PPTX è intenzionale e le posizioni esterne possono essere mantenute in modo affidabile.

Il ritaglio riduce le dimensioni del file PPTX?

Non di per sé. Le impostazioni di ritaglio normale nascondono parti dell’immagine di origine ma conservano i pixel sottostanti. Usa PictureFillFormat::deletePictureCroppedAreas o la compressione dell’immagine con rimozione delle aree ritagliate quando quei pixel possono essere scartati definitivamente.

Posso ripristinare la qualità dell’immagine dopo la compressione?

No. La compressione può ridurre la risoluzione raster memorizzata e la rimozione delle regioni ritagliate elimina i dati immagine. Conserva l’immagine originale al di fuori della presentazione se in seguito potrebbe essere necessario un editing ad alta risoluzione.

Come devono essere gestite le immagini SVG?

Mantieni il contenuto SVG come SVG quando la fedeltà vettoriale è importante. L’SvgImage incorporato può essere estratto direttamente. Renderizzare una diapositiva in un formato raster come PNG o JPEG rasterizza l’SVG come parte dell’immagine della diapositiva.

Come posso evitare cast non sicuri durante la lettura di diapositive esistenti?

Verifica il tipo di forma prima di utilizzare i membri specifici della cornice immagine. Un controllo java_instanceof contro PictureFrame evita cast non validi e consente al codice di gestire le diapositive che non contengono cornici immagine.

Gestire gli effetti di trasformazione delle immagini nelle presentazioni con PHP