사용자가 3‑차원 모델을 회전하고 확대·축소하며 직접 PDF 내부에서 탐색할 수 있는 몰입형 문서를 만드는 것은 제품 카탈로그, 엔지니어링 보고서 및 교육 매뉴얼을 향상시키는 강력한 방법입니다. Aspose.Words Cloud SDK for .NET은 클라우드 기반 라이브러리를 제공하여 DOCX 파일을 PDF로 변환할 때 3D 콘텐츠를 쉽게 삽입하고 보존할 수 있게 합니다. 이 가이드에서는 C#에서 인터랙티브 3D PDF를 생성하는 방법을 배우고, 전체 코드 샘플을 확인하며, 동등한 cURL REST 호출을 살펴보고, 실제 애플리케이션을 위한 배포 고려 사항을 이해하게 됩니다.

3D PDF 생성 시나리오 요구 사항

엔지니어링 포털이나 인터랙티브 제품 브로셔를 구축하는 개발자는 종종 임베드된 3D 모델을 포함한 PDF를 제공해야 합니다. 일반적인 요구 사항은 다음과 같습니다:

  • 원본 문서는 이미 U3D 또는 PRC 형식의 3D 모델을 포함하고 있는 DOCX여야 합니다.
  • 결과 PDF는 3D 데이터를 유지하여 Adobe Acrobat과 같은 뷰어에서 인터랙티브하게 렌더링될 수 있어야 합니다.
  • 변환 프로세스는 자동화되어 서버에서 실행되고, 수동 개입 없이 대량 배치를 처리할 수 있어야 합니다.

전통적인 데스크톱 도구는 클라우드 환경에서 신뢰성 있게 스크립팅할 수 없으며, 변환 중에 3D 스트림을 종종 제거합니다. 3D 모델을 보존하면서 PDF/A 준수를 제공하는 프로그래밍 솔루션이 따라서 필수적입니다.

접근 방식: Aspose.Words Cloud를 활용한 3D PDF

Aspose.Words Cloud SDK for .NET은 Aspose의 보안 서버에서 실행되는 REST 기반 작업 세트를 제공합니다. 시나리오를 해결하는 주요 기능은 다음과 같습니다:

  • DOCX 파일을 Aspose Cloud 스토리지에 직접 업로드합니다.
  • PdfSaveOptionsData는 PDF 규격 준수, 필드 업데이트 및 특히 포함된 3D 콘텐츠 보존을 제어할 수 있게 해줍니다.
  • 스트림을 반환하는 비동기 변환 메서드로, 출력 파일을 직접 디스크에 쓸 수 있습니다.

함께 이러한 기능들은 CI 파이프라인, 웹 서비스 또는 백그라운드 작업에 통합될 수 있는 깔끔한 3D에서 PDF로의 워크플로우를 가능하게 합니다. 자세한 API 정보는 공식 문서와 API 참조에서 확인할 수 있습니다.

C#에서 인터랙티브 3D PDF 생성: 구현

아래는 구현에 대한 단계별 walkthrough입니다. 각 단계에는 전체 예제에서 직접 가져온 짧은 코드 발췌가 포함되어 있습니다.

Aspose.Words Cloud SDK for .NET 설치

먼저, 프로젝트에 NuGet 패키지를 추가합니다.

dotnet add package Aspose.Words-Cloud

바이너리를 다운로드 페이지에서 다운로드할 수도 있습니다.

WordsApi 클라이언트 구성

클라이언트 자격 증명을 사용하여 Configuration 객체를 생성하고 WordsApi를 인스턴스화합니다.

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

WordsApi 클래스는 API 참조에 문서화되어 있습니다.

임베디드 3D 모델이 포함된 DOCX 업로드

로컬 DOCX 파일을 열고 Aspose Cloud 스토리지에 업로드하여 동일한 이름의 기존 파일을 덮어씁니다.

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

DOCX에 이미 U3D 또는 PRC 모델이 포함되어 있는지 확인하십시오; 이것은 SDK가 보존하는 3D Model Format입니다.

3D 콘텐츠 보존을 위한 PDF 저장 옵션 설정

PDF/A‑1b 규격을 사용하고 3D 스트림을 유지하도록 PdfSaveOptionsData를 구성합니다.

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

이 옵션들은 인터랙티브 모델을 온전하게 유지하는 3D to PDF Workflow의 일부입니다.

대화형 3D PDF 변환 및 다운로드

변환 요청을 호출하고 결과 스트림을 로컬 PDF 파일에 씁니다.

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);
}

변환 후에 클라우드 스토리지에 있는 임시 파일을 선택적으로 삭제할 수 있습니다.

전체 코드 예제: C#에서 인터랙티브 3D PDF 생성

다음 코드는 시작부터 끝까지 전체 프로세스를 보여줍니다.

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)}'.");
        }
    }
}

Note: 이 코드 예제는 핵심 기능을 보여줍니다. 프로젝트에 사용하기 전에 파일 경로(input.docx, output.pdf 등)를 실제 파일 위치에 맞게 업데이트하고, 모든 필수 종속성이 올바르게 설치되었는지 확인한 뒤 개발 환경에서 충분히 테스트하십시오. 문제가 발생하면 공식 문서를 참고하거나 지원 팀에게 문의하십시오.

cURL 및 REST API를 사용한 3D PDF 변환 수행

동일한 작업은 Aspose.Words Cloud REST 엔드포인트에 대한 cURL 호출을 통해 실행할 수 있습니다.

  1. 액세스 토큰 얻기 (자리 표시자를 자격 증명으로 교체하십시오.)
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. DOCX 업로드를 통해 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. 3D 보존을 포함한 PDF 변환 요청.
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. 결과 PDF 다운로드 (이전 명령이 이미 로컬에 저장했지만, 직접 가져올 수도 있습니다.)

요청 본문 및 추가 매개변수에 대한 자세한 내용은 공식 API 문서를 참조하십시오.

3D PDF 생성에 대한 배포 고려 사항

이 솔루션을 프로덕션 환경에 통합할 때는 다음 사항을 염두에 두세요:

  • 서버 위치 - 변환은 Aspose의 클라우드 서버에서 실행되므로 네트워크가 api.aspose.cloud에 대한 외부 HTTPS 트래픽을 허용하는지 확인하십시오.
  • 라이선스 - 프로덕션 사용을 위해서는 상업용 라이선스가 필요합니다. 임시 라이선스 페이지에서 임시 라이선스로 시작할 수 있습니다.
  • 확장성 - API가 무상태이므로 여러 워커 인스턴스에 걸쳐 업로드 및 변환을 병렬화하여 대량 배치를 처리할 수 있으며, 전체 3D to PDF Automation을 지원합니다.

결론

C#에서 대화형 3D PDF 생성이 Aspose.Words Cloud SDK for .NET를 사용하면 간단해집니다. 위 단계들을 따라하면 U3D 또는 PRC 모델을 삽입하고, PDF 변환 중에 이를 보존하며, .NET 라이브러리 또는 직접 REST 호출을 통해 워크플로를 자동화할 수 있습니다. 프로덕션용 적절한 라이선스를 확보하고, Adobe Acrobat과 같이 3D를 지원하는 뷰어에서 생성된 PDF를 테스트하는 것을 기억하세요. 이 기능을 통해 엔지니어링, 마케팅 및 교육 시나리오에 더 풍부하고 매력적인 문서를 제공할 수 있습니다.

FAQs

C#와 Aspose.Words Cloud를 사용하여 인터랙티브 3D PDF를 생성하려면 어떻게 해야 하나요?
SDK를 사용하여 이미 U3D 또는 PRC 모델이 포함된 DOCX를 업로드하고, PdfSaveOptionsData를 구성하여 3D 스트림을 유지한 뒤 ConvertDocumentAsync를 호출합니다. 이 문서의 전체 코드 예제는 정확한 순서를 보여줍니다.

PDF 변환을 위해 삽입할 수 있는 3D 모델 형식은 무엇인가요?
Aspose.Words Cloud는 U3D 및 PRC 형식을 지원하며, 이는 PDF에서 인터랙티브 3D 콘텐츠를 위한 표준 형식입니다.

C# 코드를 작성하지 않고 변환을 실행할 수 있나요?
예, 동일한 프로세스를 cURL 명령을 사용하여 Aspose.Words Cloud REST API에 대해 수행할 수 있으며, 이는 cURL 섹션에示된 바와 같습니다.

가격 및 라이선스 정보는 어디서 찾을 수 있나요?
상업용 라이선스 세부 정보는 제품 페이지에서 확인할 수 있으며, 평가용 임시 라이선스는 임시 라이선스 페이지에서 얻을 수 있습니다.

더 읽기