Creare documenti immersivi che consentono agli utenti di ruotare, ingrandire e esplorare modelli tridimensionali direttamente all’interno di un PDF è un modo potente per migliorare cataloghi di prodotti, rapporti ingegneristici e manuali di formazione. Aspose.Words Cloud SDK for .NET offre una libreria basata sul cloud che facilita l’inserimento e la conservazione di contenuti 3D durante la conversione di file DOCX in PDF. In questa guida imparerai a generare PDF 3D interattivi in C#, vedrai un esempio di codice completo, esplorerai le chiamate REST cURL equivalenti e comprenderai le considerazioni di distribuzione per applicazioni reali.

Requisiti dello scenario di generazione PDF 3D

Gli sviluppatori che creano portali ingegneristici o brochure di prodotto interattive spesso hanno bisogno di fornire PDF che contengono modelli 3D incorporati. I requisiti tipici sono:

  • Il documento di origine deve essere un DOCX che includa già un modello 3D in formato U3D o PRC.
  • Il PDF risultante deve conservare i dati 3D in modo che visualizzatori come Adobe Acrobat possano renderizzarlo in modo interattivo.
  • Il processo di conversione dovrebbe essere automatizzato, eseguito su un server e funzionare con grandi lotti senza intervento manuale.

Gli strumenti desktop tradizionali non possono essere scriptati in modo affidabile in un ambiente cloud e spesso rimuovono i flussi 3D durante la conversione. Una soluzione programmatica che preserva il modello 3D offrendo al contempo la conformità PDF/A è quindi essenziale.

L’approccio: sfruttare Aspose.Words Cloud per PDF 3D

Aspose.Words Cloud SDK for .NET offre un insieme di operazioni basate su REST che vengono eseguite sui server sicuri di Aspose. Le principali funzionalità che affrontano lo scenario includono:

  • Caricamento diretto di file DOCX su Aspose Cloud storage.
  • PdfSaveOptionsData che ti consente di controllare la conformità PDF, gli aggiornamenti dei campi e, soprattutto, la conservazione del contenuto 3D incorporato.
  • Metodi di conversione asincroni che restituiscono uno stream, consentendoti di scrivere il file di output direttamente su disco.

Insieme, queste funzionalità consentono un flusso di lavoro pulito da 3D a PDF che può essere integrato in pipeline CI, servizi web o processi in background. Informazioni dettagliate sull’API sono disponibili nella documentazione ufficiale e nel riferimento API.

Genera PDF 3D Interattivo in C#: Implementazione

Di seguito è una panoramica passo‑passo dell’implementazione. Ogni passaggio include un breve estratto di codice preso direttamente dall’esempio completo.

Installa l’Aspose.Words Cloud SDK for .NET

Per prima cosa, aggiungi il pacchetto NuGet al tuo progetto.

dotnet add package Aspose.Words-Cloud

Puoi anche scaricare i binari dalla pagina di download.

Configura il client WordsApi

Crea un oggetto Configuration con le tue credenziali client e istanzia WordsApi.

var config = new Configuration
{
    ClientId = "YOUR_CLIENT_ID",
    ClientSecret = "YOUR_CLIENT_SECRET"
};
var wordsApi = new WordsApi(config);

La classe WordsApi è documentata nella documentazione API.

Carica un DOCX che contiene un modello 3D incorporato

Apri il file DOCX locale e caricalo su Aspose Cloud storage, sovrascrivendo eventuali file esistenti con lo stesso nome.

using (var fileStream = File.OpenRead(localDocxPath))
{
    var uploadRequest = new UploadFileRequest(fileStream, remoteFileName);
    await wordsApi.UploadFileAsync(uploadRequest);
}

Assicurati che il DOCX includa già un modello U3D o PRC; questo è il Formato modello 3D che l’SDK conserva.

Imposta le opzioni di salvataggio PDF per preservare il contenuto 3D

Configura PdfSaveOptionsData per mantenere i flussi 3D e utilizzare la conformità PDF/A‑1b.

var pdfOptions = new PdfSaveOptionsData
{
    UpdateFields = false,
    Compliance = PdfCompliance.PdfA1b,
    SaveFormat = "pdf"
};

Queste opzioni fanno parte del 3D to PDF Workflow che garantisce che il modello interattivo rimanga intatto.

Converti e scarica il PDF 3D interattivo

Invoca la richiesta di conversione e scrivi lo stream risultante in un file PDF locale.

var convertRequest = new ConvertDocumentRequest(
    remoteFileName,
    format: "pdf",
    saveOptions: pdfOptions
);

using (var pdfStream = await wordsApi.ConvertDocumentAsync(convertRequest))
using (var fileWriter = File.Create(outputPdfPath))
{
    await pdfStream.CopyToAsync(fileWriter);
}

Dopo la conversione, è possibile eliminare facoltativamente il file temporaneo dall’archiviazione cloud.

Esempio di Codice Completo: Generazione Interattiva di PDF 3D in C#

Il codice seguente dimostra l’intero processo dall’inizio alla fine.

using System;
using System.IO;
using System.Threading.Tasks;
using Aspose.Words.Cloud.Sdk;
using Aspose.Words.Cloud.Sdk.Model;
using Aspose.Words.Cloud.Sdk.Model.Requests;

namespace Generate3DPdfExample
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // -----------------------------------------------------------------
            // 1. Configure Aspose.Words Cloud client (replace with your credentials)
            // -----------------------------------------------------------------
            var config = new Configuration
            {
                ClientId = "YOUR_CLIENT_ID",
                ClientSecret = "YOUR_CLIENT_SECRET"
            };
            var wordsApi = new WordsApi(config);

// -----------------------------------------------------------------
            // 2. Define file names and paths (generic placeholders)
            // -----------------------------------------------------------------
            const string localDocxPath = "input.docx";   // DOCX that already contains an embedded 3D model (U3D/PRC)
            const string remoteFileName = "input.docx"; // Name used in Aspose Cloud storage
            const string outputPdfPath = "output.pdf";

// -----------------------------------------------------------------
            // 3. Upload the DOCX to Aspose Cloud storage (overwrites if exists)
            // -----------------------------------------------------------------
            using (var fileStream = File.OpenRead(localDocxPath))
            {
                var uploadRequest = new UploadFileRequest(fileStream, remoteFileName);
                await wordsApi.UploadFileAsync(uploadRequest);
            }

// -----------------------------------------------------------------
            // 4. Prepare PDF save options – enable 3D content preservation
            // -----------------------------------------------------------------
            var pdfOptions = new PdfSaveOptionsData
            {
                // Preserve the embedded 3D model; the option name may vary depending on API version.
                // Setting 'UpdateFields' to false speeds up conversion when fields are not required.
                UpdateFields = false,
                // Use PDF/A-1b compliance to keep the document portable while still supporting 3D.
                Compliance = PdfCompliance.PdfA1b,
                // Ensure the output is a single PDF file.
                SaveFormat = "pdf"
            };

// -----------------------------------------------------------------
            // 5. Convert the uploaded DOCX to PDF with the defined options
            // -----------------------------------------------------------------
            var convertRequest = new ConvertDocumentRequest(
                remoteFileName,
                format: "pdf",
                saveOptions: pdfOptions
            );

using (var pdfStream = await wordsApi.ConvertDocumentAsync(convertRequest))
            using (var fileWriter = File.Create(outputPdfPath))
            {
                await pdfStream.CopyToAsync(fileWriter);
            }

// -----------------------------------------------------------------
            // 6. Clean up remote file (optional)
            // -----------------------------------------------------------------
            var deleteRequest = new DeleteFileRequest(remoteFileName);
            await wordsApi.DeleteFileAsync(deleteRequest);

Console.WriteLine($"3D PDF generated successfully at '{Path.GetFullPath(outputPdfPath)}'.");
        }
    }
}

Nota: Questo esempio di codice dimostra la funzionalità principale. Prima di usarlo nel tuo progetto, assicurati di aggiornare i percorsi dei file (input.docx, output.pdf, ecc.) per corrispondere alle tue effettive posizioni dei file, verifica che tutte le dipendenze richieste siano installate correttamente e testa accuratamente nell’ambiente di sviluppo. Se riscontri problemi, consulta la documentazione ufficiale o contatta il team di supporto per assistenza.

Esegui la conversione PDF 3D con cURL e l’API REST

La stessa operazione può essere eseguita tramite chiamate cURL contro gli endpoint REST di Aspose.Words Cloud.

  1. Ottieni un token di accesso (sostituisci i segnaposto con le tue credenziali).
curl -X POST "https://api.aspose.cloud/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
  1. Carica il DOCX contenente il modello 3D.
curl -X PUT "https://api.aspose.cloud/v4.0/words/storage/file/input.docx" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @input.docx
  1. Richiedi la conversione PDF con conservazione 3D.
curl -X POST "https://api.aspose.cloud/v4.0/words/input.docx/saveAs/pdf" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "PdfSaveOptions": {
            "UpdateFields": false,
            "Compliance": "PdfA1b"
        }
      }' \
  -o output.pdf
  1. Scarica il PDF risultante (il comando precedente lo ha già salvato localmente, ma puoi anche scaricarlo direttamente).

Per ulteriori dettagli sui corpi della richiesta e sui parametri aggiuntivi, consultare la documentazione API ufficiale.

Considerazioni sulla distribuzione per la generazione di PDF 3D

Durante l’integrazione di questa soluzione in un ambiente di produzione, tenere presente i seguenti punti:

  • Posizione del server - La conversione viene eseguita sui server cloud di Aspose, quindi assicurati che la tua rete consenta il traffico HTTPS in uscita verso api.aspose.cloud.
  • Licenza - È necessaria una licenza commerciale per l’uso in produzione. Puoi iniziare con una licenza temporanea dalla pagina della licenza temporanea.
  • Scalabilità - Poiché l’API è senza stato, puoi parallelizzare i caricamenti e le conversioni su più istanze di worker per gestire batch ad alto volume, supportando l’Automazione 3D to PDF.

Conclusione

Generare PDF 3D interattivi in C# diventa semplice con il Aspose.Words Cloud SDK for .NET. Seguendo i passaggi sopra è possibile incorporare modelli U3D o PRC, conservarli durante la conversione in PDF e automatizzare il flusso di lavoro sia con la libreria .NET sia con chiamate REST dirette. Ricorda di ottenere una licenza adeguata per la produzione e di testare i PDF generati in un visualizzatore che supporti il 3D, come Adobe Acrobat. Con questa funzionalità puoi fornire documenti più ricchi e coinvolgenti per scenari di ingegneria, marketing e formazione.

FAQs

Come genero un PDF 3D interattivo in C# usando Aspose.Words Cloud?
Utilizza l’SDK per caricare un DOCX che contiene già un modello U3D o PRC, configura PdfSaveOptionsData per mantenere i flussi 3D e chiama ConvertDocumentAsync. L’esempio di codice completo in questo articolo mostra la sequenza esatta.

Quali formati di modello 3D posso incorporare per la conversione PDF?
Aspose.Words Cloud supporta i formati U3D e PRC, che sono i formati standard per contenuti 3D interattivi nei PDF.

È possibile eseguire la conversione senza scrivere alcun codice C#?
Sì, lo stesso processo può essere eseguito con comandi cURL contro l’Aspose.Words Cloud REST API, come dimostrato nella sezione cURL.

Dove posso trovare informazioni su prezzi e licenze?
I dettagli della licenza commerciale sono disponibili nella pagina del prodotto e puoi ottenere una licenza temporanea per la valutazione dalla pagina della licenza temporanea.

Leggi di più