Rendering di forme separatamente da un documento

Durante l’elaborazione dei documenti, un’attività comune consiste nell’estrarre tutte le immagini presenti nel documento ed esportarle in una posizione esterna. Questa attività diventa semplice con l’API Aspose.Words, che fornisce già la funzionalità per l’estrazione e il salvataggio dei dati dell’immagine. Tuttavia, a volte è possibile estrarre in modo simile altri tipi di contenuto grafico rappresentati da un diverso tipo di oggetto di disegno, ad esempio una casella di testo contenente paragrafi, forme di freccia e una piccola immagine. Non esiste un modo semplice per rendere questo oggetto poiché è una combinazione di singoli elementi di contenuto. È anche possibile che si verifichi un caso in cui i contenuti sono stati raggruppati nell’oggetto che assomiglia a una singola immagine.

Aspose.Words fornisce funzionalità per estrarre questo tipo di contenuto nello stesso modo in cui è possibile estrarre un’immagine semplice dalla forma come contenuto renderizzato. In questo articolo viene descritto come utilizzare questa funzionalità per eseguire il rendering delle forme indipendentemente dal documento.

Tipi di forma in Aspose.Words

Tutto il contenuto di un livello di disegno documento è rappresentato dal nodo Shape o GroupShape nel modulo oggetto documento (DOM) Aspose.Words. Tali contenuti possono essere caselle di testo, immagini, AutoShapes, oggetti OLE, ecc. Alcuni campi vengono importati anche come forme, ad esempio il campo INCLUDEPICTURE.

Un’immagine semplice è rappresentata da un nodo Shape di ShapeType.Image. Questo nodo forma non ha nodi figlio, ma i dati immagine contenuti all’interno di questo nodo forma sono accessibili dalla proprietà Shape.ImageData. D’altra parte, una forma può anche essere composta da molti nodi figli. Ad esempio, una forma di casella di testo, rappresentata dalla proprietà ShapeType.TextBox, può essere composta da molti nodi, ad esempio Paragraph e Table. La maggior parte delle forme può includere i nodi a livello di blocco Paragraph e Table. Questi sono gli stessi nodi di quelli che appaiono nel corpo principale. Le forme sono sempre parti di un paragrafo, incluse direttamente in linea o ancorate a Paragraph, ma" fluttuanti " in qualsiasi punto della pagina del documento.

Un documento può anche contenere forme raggruppate insieme. Il raggruppamento può essere abilitato in Microsoft Word selezionando più oggetti e facendo clic su “Gruppo” nel menu di scelta rapida.

In Aspose.Words, questi gruppi di forme sono rappresentati dal nodo GroupShape. Questi possono anche essere richiamati allo stesso modo per rendere l’intero gruppo all’immagine.

Il formato DOCX può contenere tipi speciali di immagini, come diagrammi o grafici. Queste forme sono rappresentate anche attraverso il nodo Shape in Aspose.Words, che fornisce anche un metodo simile per renderle come immagini. In base alla progettazione, una forma non può contenere un’altra forma come figlio, a meno che quella forma non sia un’immagine (ShapeType.Image). Ad esempio, Microsoft Word non consente di inserire una casella di testo all’interno di un’altra casella di testo.

I tipi di forma descritti sopra forniscono un metodo speciale per il rendering delle forme attraverso la classe ShapeRenderer. Un’istanza della classe ShapeRenderer viene recuperata per un Shape o GroupShape tramite il metodo GetShapeRenderer o passando il Shape al costruttore della classe ShapeRenderer. Questa classe fornisce l’accesso ai membri, che consentono il rendering di una forma al seguente:

• File sul disco utilizzando il metodo Save overload
• Stream utilizzando il metodo Save overload
• L’oggetto Graphics utilizzando i metodi RenderToSize e RenderToScale

Quando si esegue il rendering di un Shape, deve far parte della gerarchia del documento. Se Shape non fa parte dell’albero del documento, l’output renderizzato sarà vuoto dopo aver richiamato i metodi ShapeRenderer.

Rendering su file o stream

Il metodo Save fornisce sovraccarichi che rendono una forma direttamente in un file o flusso. Entrambi gli overload accettano un’istanza della classe ImageSaveOptions, che consente di definire le opzioni per il rendering della forma. Funziona allo stesso modo del metodo Document.Save. Anche se questo parametro è richiesto, è possibile passare un valore null, specificando che non ci sono opzioni personalizzate.

La forma può essere esportata in qualsiasi formato di immagine specificato nell’enumerazione SaveFormat. Ad esempio, l’immagine può essere renderizzata come immagine raster, ad esempio JPEG specificando l’enumerazione SaveFormat.Jpeg, o come immagine vettoriale, ad esempio EMF specificando il SaveFormat.Emf.

L’esempio di codice riportato di seguito illustra il rendering di una forma in un’immagine EMF separatamente dal documento e il salvataggio su disco:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
System::SharedPtr<ShapeRenderer> r = shape->GetShapeRenderer();

// Define custom options which control how the image is rendered. Render the shape to the JPEG raster format.
System::SharedPtr<ImageSaveOptions> imageOptions = System::MakeObject<ImageSaveOptions>(SaveFormat::Emf);
imageOptions->set_Scale(1.5f);

System::String outputPath = outputDataDir + u"RenderShape.RenderShapeToDisk.emf";
// Save the rendered image to disk.
r->Save(outputPath, imageOptions);

L’esempio di codice riportato di seguito illustra il rendering di una forma in un’immagine JPEG separatamente dal documento e il salvataggio in un flusso:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
System::SharedPtr<ShapeRenderer> r = System::MakeObject<ShapeRenderer>(shape);

// Define custom options which control how the image is rendered. Render the shape to the vector format EMF.
System::SharedPtr<ImageSaveOptions> imageOptions = System::MakeObject<ImageSaveOptions>(SaveFormat::Jpeg);
imageOptions->set_ImageColorMode(ImageColorMode::Grayscale);
imageOptions->set_ImageBrightness(0.45f);
System::String outputPath = outputDataDir + u"RenderShape.RenderShapeToStream.jpg";
System::SharedPtr<System::IO::FileStream> stream = System::MakeObject<System::IO::FileStream>(outputPath, System::IO::FileMode::Create);

// Save the rendered image to the stream using different options.
r->Save(stream, imageOptions);

La classe ImageSaveOptions consente di specificare una varietà di opzioni che controllano il rendering dell’immagine. La funzionalità sopra descritta può essere applicata allo stesso modo ai nodi GroupShape e Shape.

Rendering su un oggetto grafico .NET

Il rendering direttamente su un oggetto Graphics consente di definire le proprie impostazioni e lo stato per l’oggetto Graphics. Uno scenario comune prevede il rendering di una forma direttamente in un oggetto Graphics recuperato da un modulo Windows o da una Bitmap. Quando viene eseguito il rendering del nodo Shape, le impostazioni influenzeranno l’aspetto della forma. Ad esempio, è possibile ruotare o ridimensionare la forma utilizzando i metodi RotateTransform o ScaleTransform per l’oggetto Graphics.

L’esempio seguente mostra come eseguire il rendering di una forma su a .NET Graphics oggetto separatamente dal documento e applica la rotazione all’immagine renderizzata:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
System::SharedPtr<ShapeRenderer> r = shape->GetShapeRenderer();

// Find the size that the shape will be rendered to at the specified scale and resolution.
System::Drawing::Size shapeSizeInPixels = r->GetSizeInPixels(1.0f, 96.0f);

// Rotating the shape may result in clipping as the image canvas is too small. Find the longest side
// And make sure that the graphics canvas is large enough to compensate for this.
int32_t maxSide = System::Math::Max(shapeSizeInPixels.get_Width(), shapeSizeInPixels.get_Height());

{
    // Clearing resources under 'using' statement
    DisposableHolder<System::Drawing::Bitmap> imageHolder(System::MakeObject<System::Drawing::Bitmap>((int32_t)(maxSide * 1.25), (int32_t)(maxSide * 1.25)));

    {
        // Rendering to a graphics object means we can specify settings and transformations to be applied to 
        // The shape that is rendered. In our case we will rotate the rendered shape.
        // Clearing resources under 'using' statement
        DisposableHolder<System::Drawing::Graphics> grHolder(System::Drawing::Graphics::FromImage(imageHolder.GetObject()));

        // Clear the shape with the background color of the document.
        grHolder.GetObject()->Clear(shape->get_Document()->get_PageColor());
        // Center the rotation using translation method below
        grHolder.GetObject()->TranslateTransform((float)imageHolder.GetObject()->get_Width() / 8, (float)imageHolder.GetObject()->get_Height() / 2);
        // Rotate the image by 45 degrees.
        grHolder.GetObject()->RotateTransform(45.0f);
        // Undo the translation.
        grHolder.GetObject()->TranslateTransform(-(float)imageHolder.GetObject()->get_Width() / 8, -(float)imageHolder.GetObject()->get_Height() / 2);

        // Render the shape onto the graphics object.
        r->RenderToSize(grHolder.GetObject(), 0.0f, 0.0f, shapeSizeInPixels.get_Width(), shapeSizeInPixels.get_Height());
    }

    System::String outputPath = outputDataDir + u"RenderShape.RenderShapeToGraphics.png";
    imageHolder.GetObject()->Save(outputPath, System::Drawing::Imaging::ImageFormat::get_Png());
    std::cout << "Shape rendered to graphics successfully." << std::endl << "File saved at " << outputPath.ToUtf8String() << std::endl;
}

Analogamente, al metodo RenderToSize, il metodo RenderToSize ereditato da NodeRendererBase è utile per creare miniature del contenuto del documento. La dimensione della forma viene specificata tramite il costruttore. Il metodo RenderToSize accetta l’oggetto Graphics, le coordinate X e Y della posizione dell’immagine e la dimensione dell’immagine (larghezza e altezza) che verrà disegnata sull’oggetto Graphics.

Il Shape può essere reso su una certa scala usando il metodo ShapeRenderer.RenderToScale ereditato dalla classe NodeRendererBase. Questo è simile al metodo Document.RenderToScale che accetta gli stessi parametri principali. La differenza tra questi due metodi è che con il metodo ShapeRenderer.RenderToScale, invece di una dimensione letterale, si sceglie un valore float che ridimensiona la forma durante il rendering. Se il valore float è uguale a 1.0, il rendering della forma100% della sua dimensione originale. Un valore float di 0.5 ridurrà la dimensione dell’immagine della metà.

Rendering di un’immagine di forma

La classe Shape rappresenta gli oggetti nel livello di disegno, ad esempio un AutoShape, una casella di testo, una forma libera, un oggetto OLE, un controllo ActiveX o un’immagine. Utilizzando la classe Shape, è possibile creare o modificare forme in un documento Microsoft Word. Una proprietà importante di una forma è il suo ShapeType. Forme di tipi diversi possono avere funzionalità diverse in un documento di Word. Ad esempio, solo le immagini e le forme OLE possono avere immagini al loro interno mentre la maggior parte delle forme può avere solo testo.

L’esempio seguente mostra come eseguire il rendering di un’immagine Forma in un’immagine JPEG separatamente dal documento e salvarla sul disco:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
System::String outputPath = outputDataDir + u"RenderShape.RenderShapeImage.jpg";
// Save the Shape image to disk in JPEG format and using default options.
shape->GetShapeRenderer()->Save(outputPath, nullptr);

Recupero di una dimensione forma

La classe ShapeRenderer fornisce anche funzionalità per recuperare la dimensione della forma in pixel tramite il metodo GetSizeInPixels. Questo metodo accetta due parametri di tipo float (singoli) - la scala e DPI, che vengono utilizzati nel calcolo della dimensione della forma quando la forma viene renderizzata. Il metodo restituisce l’oggetto Size, che contiene la larghezza e l’altezza della dimensione calcolata. Ciò è utile quando è necessario conoscere in anticipo la dimensione della forma renderizzata, ad esempio quando si crea una nuova bitmap dall’output renderizzato.

L’esempio seguente mostra come creare un nuovo oggetto Bitmap e Grafico con la larghezza e l’altezza della forma da renderizzare:

For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-C
System::Drawing::SizeF shapeSizeInDocument = shape->GetShapeRenderer()->get_SizeInPoints();
float width = shapeSizeInDocument.get_Width();
// The width of the shape.
float height = shapeSizeInDocument.get_Height();
// The height of the shape.

System::Drawing::Size shapeRenderedSize = shape->GetShapeRenderer()->GetSizeInPixels(1.0f, 96.0f);

{
    // Clearing resources under 'using' statement
    DisposableHolder<System::Drawing::Bitmap> imageHolder(System::MakeObject<System::Drawing::Bitmap>(shapeRenderedSize.get_Width(), shapeRenderedSize.get_Height()));
    {
        // Clearing resources under 'using' statement
        DisposableHolder<System::Drawing::Graphics> gHolder(System::Drawing::Graphics::FromImage(imageHolder.GetObject()));
        // Render shape onto the graphics object using the RenderToScale or RenderToSize methods of ShapeRenderer class.
    }
}

Quando si utilizzano i metodi RenderToSize o RenderToScale, la dimensione dell’immagine renderizzata viene restituita anche nell’oggetto SizeF. Questo può essere assegnato a una variabile e utilizzato se necessario.

La proprietà SizeInPoints restituisce la dimensione della Forma misurata in punti (vedere ShapeRenderer. Un risultato è un oggetto SizeF contenente la larghezza e l’altezza.