استخراج تصاویر از اسناد PDF یک نیاز متداول هنگام ساخت خطوط پردازش سند است، به‌ویژه برای تولید تصویرهای کوچک یا استفاده مجدد از گرافیک‌ها در مکان‌های دیگر.
GroupDocs.Parser Cloud SDK for .NET یک API قدرتمند ارائه می‌دهد که این کار را در C# به‌صورت ساده انجام می‌دهد.

در این راهنما شما یاد خواهید گرفت که چگونه یک PDF را بارگذاری کنید، تمام تصاویر جاسازی‌شده را بازیابی کنید، آنها را به‌صورت محلی ذخیره کنید و به‌صورت اختیاری فایل راه‌دور را پاک کنید، همراه با کد کامل و مثال‌های REST.

مراحل استخراج تصاویر از اسناد PDF در C#

  1. بارگذاری PDF به GroupDocs Cloud storage: از StorageApi.UploadFile برای قرار دادن PDF منبع در ابر استفاده کنید.
var uploadRequest = new UploadFileRequest(remotePdfPath, File.ReadAllBytes(localPdfPath));
storageApi.UploadFile(uploadRequest);

این فراخوانی اطمینان می‌دهد که فایل برای تجزیه‌وتحلیل در دسترس است.

  1. درخواست تصاویر سند: فراخوانی ParserApi.GetDocumentImages با یک GetDocumentImagesRequest.
var imagesRequest = new GetDocumentImagesRequest(remotePdfPath);
ImagesResult imagesResult = parserApi.GetDocumentImages(imagesRequest);

پاسخ شامل مجموعه‌ای از اشیاء ImageInfo است که هر کدام داده‌های Base64 و متادیتا را نگه می‌دارند. برای جزئیات کامل به مرجع API مراجعه کنید.

  1. کدگشایی و ذخیره هر تصویر: از imagesResult.Images عبور کنید، رشته Base64 را به آرایه بایت تبدیل کنید و فایل را روی دیسک بنویسید.
foreach (ImageInfo imgInfo in imagesResult.Images)
{
    byte[] imageBytes = Convert.FromBase64String(imgInfo.Base64Data);
    string extension = imgInfo.FileExtension?.TrimStart('.').ToLower() ?? "bin";
    string fileName = $"extracted_page{imgInfo.PageNumber}_img{imgInfo.ImageIndex}_{imageCounter}.{extension}";
    File.WriteAllBytes(fileName, imageBytes);
}

کنسول نام فایل ذخیره‌شده، ابعاد و DPI را برای تأیید نمایش می‌دهد.

  1. (اختیاری) پاک‌سازی PDF راه دور: پس از استخراج می‌توانید فایل بارگذاری‌شده را حذف کنید تا فضای ذخیره‌سازی منظم بماند.
var deleteRequest = new DeleteFileRequest(remotePdfPath);
storageApi.DeleteFile(deleteRequest);

این گام در یک بلوک try‑catch بسته شده است تا خطاهای پاک‌سازی نادیده گرفته شوند.

  1. بازبینی خروجی: کنسول خلاصه‌ای مانند Total images extracted: 12 را نمایش می‌دهد که استخراج موفقیت‌آمیز را تأیید می‌کند.

مثال کامل کد: استخراج تصاویر از اسناد PDF با GroupDocs.Parser

مثال زیر جریان کاری کامل توصیف‌شده در بالا را نشان می‌دهد. این شامل پیکربندی، بارگذاری، استخراج تصویر، ذخیره‌سازی و پاک‌سازی اختیاری است.

using System;
using System.IO;
using System.Collections.Generic;
using GroupDocs.Parser.Cloud.Sdk.Api;
using GroupDocs.Parser.Cloud.Sdk.Client;
using GroupDocs.Parser.Cloud.Sdk.Model;
using GroupDocs.Parser.Cloud.Sdk.Model.Requests;

namespace ExtractImagesFromPdf
{
    class Program
    {
        static void Main(string[] args)
        {
            // Configuration – replace with your actual credentials
            var config = new Configuration
            {
                ClientId = "YOUR_CLIENT_ID",
                ClientSecret = "YOUR_CLIENT_SECRET"
            };

// APIs
            var storageApi = new StorageApi(config);
            var parserApi = new ParserApi(config);

// Input PDF path (local) and remote name in storage
            const string localPdfPath = "input.pdf";
            const string remotePdfPath = "input.pdf";

try
            {
                // -------------------------------------------------
                // 1. Upload PDF to GroupDocs Cloud storage (if not already there)
                // -------------------------------------------------
                if (!File.Exists(localPdfPath))
                    throw new FileNotFoundException($"Local file not found: {localPdfPath}");

var uploadRequest = new UploadFileRequest(remotePdfPath, File.ReadAllBytes(localPdfPath));
                storageApi.UploadFile(uploadRequest);

// -------------------------------------------------
                // 2. Retrieve document images (all pages)
                // -------------------------------------------------
                var imagesRequest = new GetDocumentImagesRequest(remotePdfPath);
                ImagesResult imagesResult = parserApi.GetDocumentImages(imagesRequest);

// -------------------------------------------------
                // 3. Save each extracted image to disk
                // -------------------------------------------------
                int imageCounter = 0;
                foreach (ImageInfo imgInfo in imagesResult.Images)
                {
                    // Image data is returned as Base64 string
                    byte[] imageBytes = Convert.FromBase64String(imgInfo.Base64Data);

// Build a descriptive file name
                    string extension = imgInfo.FileExtension?.TrimStart('.').ToLower() ?? "bin";
                    string fileName = $"extracted_page{imgInfo.PageNumber}_img{imgInfo.ImageIndex}_{imageCounter}.{extension}";
                    File.WriteAllBytes(fileName, imageBytes);

Console.WriteLine($"Saved: {fileName} ({imgInfo.Width}x{imgInfo.Height} px, {imgInfo.Resolution} DPI)");
                    imageCounter++;
                }

Console.WriteLine($"Total images extracted: {imageCounter}");
            }
            catch (ApiException apiEx)
            {
                Console.Error.WriteLine($"GroupDocs API error: {apiEx.ErrorCode} - {apiEx.Message}");
            }
            catch (Exception ex)
            {
                Console.Error.WriteLine($"Unexpected error: {ex.Message}");
            }
            finally
            {
                // -------------------------------------------------
                // 4. Optional cleanup – delete the uploaded PDF from storage
                // -------------------------------------------------
                try
                {
                    var deleteRequest = new DeleteFileRequest(remotePdfPath);
                    storageApi.DeleteFile(deleteRequest);
                }
                catch
                {
                    // Ignored – cleanup is optional
                }
            }
        }
    }
}

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه خود، اطمینان حاصل کنید که مسیرهای فایل و مقادیر پیکربندی را به‌گونه‌ای به‌روزرسانی کنید که با محیط واقعی شما مطابقت داشته باشد، بررسی کنید که تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند، و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک با تیم پشتیبانی تماس بگیرید.

استخراج تصاویر از طریق REST API با استفاده از cURL

همین عملیات را می‌توان با تماس‌های مستقیم REST انجام داد. در زیر یک جریان کاری حداقل cURL آورده شده است.

  1. دریافت توکن دسترسی (OAuth 2.0 client credentials grant).
curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

پاسخ شامل access_token است.

  1. آپلود PDF به فضای ذخیره‌سازی ابری.
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/pdf" \
     --data-binary "@input.pdf"
  1. درخواست تصاویر برای سند بارگذاری شده.
curl -X GET "https://api.groupdocs.cloud/v2.0/parser/input.pdf/images" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

پاسخ JSON شامل یک آرایه از تصاویر با base64Data، fileExtension، pageNumber و غیره است.

  1. هر تصویر را ذخیره کنید به‌صورت محلی (مثال با استفاده از jq و base64).
curl -X GET "https://api.groupdocs.cloud/v2.0/parser/input.pdf/images" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" | \
     jq -r '.images[] | "\(.pageNumber)_\(.imageIndex).\(.fileExtension) \(.base64Data)"' | \
     while read filename b64; do
         echo "$b64" | base64 -d > "$filename"
     done

برای جزئیات بیشتر در مورد نقاط انتهایی و پارامترها، به مستندات رسمی API مراجعه کنید.

آماده‌سازی محیط

  1. کتابخانهٔ مشتری .NET را از طریق NuGet نصب کنید:
dotnet add package GroupDocs.Parser-Cloud

پکیج از صفحهٔ دانلود رسمی در دسترس است.

  1. اطمینان حاصل کنید که .NET 6.0 یا نسخه بالاتر نصب شده است و یک حساب کاربری معتبر GroupDocs Cloud با اعتبارهای مشتری دارید.

  2. (اختیاری) مخزن نمونه را برای مرجع کلون کنید:

git clone https://github.com/groupdocs-parser-cloud/groupdocs-parser-cloud-dotnet.git

چه عواملی GroupDocs.Parser را برای استخراج تصویر مناسب می‌کند

  • Direct image retrieval: فراخوانی GetDocumentImages تصاویر را در قالب اصلی خود بدون مراحل تبدیل اضافی برمی‌گرداند.
  • Base64 delivery: تصاویر به‌صورت رشته‌های Base64 ارائه می‌شوند، که باعث می‌شود در هر زبانی به‌راحتی رمزگشایی شوند.
  • Page‑level metadata: هر ImageInfo شامل شماره صفحه، ابعاد، وضوح و شاخص است که به سازماندهی دارایی‌های استخراج‌شده کمک می‌کند.
  • Support for all common raster formats: PNG، JPEG، BMP، GIF، TIFF و موارد دیگر دقیقاً همان‌گونه که در PDF ذخیره شده‌اند حفظ می‌شوند.
  • Scalable cloud processing: PDFهای بزرگ بر روی سرورهای GroupDocs پردازش می‌شوند و فشار حافظه بر روی برنامه شما را کاهش می‌دهند.

پیکربندی گزینه‌های استخراج تصویر

در حالی که مثال پایه به‌صورت پیش‌فرض کار می‌کند، می‌توانید درخواست را به‌دقت تنظیم کنید:

  • مشخص کردن محدوده صفحه: مقدار pages = "1-5" را به GetDocumentImagesRequest اضافه کنید تا استخراج محدود شود.
  • تنظیم کیفیت تصویر: از پارامتر imageQuality (0‑100) استفاده کنید اگر به خروجی فشرده نیاز دارید.
  • فیلتر بر اساس فرمت: مقدار fileExtensions = ["png","jpeg"] را ارائه دهید تا فقط فرمت‌های انتخاب‌شده دریافت شوند.

این گزینه‌ها در مرجع API مستند شده‌اند.

نتیجه‌گیری

استخراج تصاویر از اسناد PDF در C# زمانی که از GroupDocs.Parser Cloud SDK for .NET استفاده می‌کنید، به فرآیندی ساده و قابل اعتماد تبدیل می‌شود. این SDK بارگذاری، تجزیه و تبدیل Base64 را مدیریت می‌کند و به شما امکان می‌دهد بر ذخیره‌سازی فایل‌ها و یکپارچه‌سازی آن‌ها در جریان کار خود تمرکز کنید. به‌خاطر داشته باشید که اعتبارنامه‌های مشتری خود را ایمن کنید، به شرایط مجوز احترام بگذارید و برای ارزیابی یک مجوز موقت را در صفحه مجوز موقت در نظر بگیرید. با کدها و مثال‌های REST ارائه‌شده، آماده‌اید تا استخراج تصویر PDF قدرتمندی را به هر برنامه .NET اضافه کنید.

سوالات متداول

چگونه می‌توانم تصاویر را از اسناد PDF با استفاده از C# استخراج کنم؟
از متد GetDocumentImages API تجزیه‌کننده پس از بارگذاری PDF با StorageApi.UploadFile استفاده کنید. رشته‌های Base64 بازگردانده‌شده را رمزگشایی کنید و همان‌طور که در مثال کد نشان داده شده است، آن‌ها را روی دیسک بنویسید.

اگر PDF با رمز عبور محافظت شده باشد چه می‌شود؟
رمز عبور را در مدل درخواست گنجانده کنید. SDK قبل از استخراج تصاویر، فایل را رمزگشایی می‌کند. برای نام دقیق ویژگی، به مستندات مراجعه کنید.

آیا می‌توانم استخراج را به صفحات خاص محدود کنم؟
بله، ویژگی pages را در GetDocumentImagesRequest به یک لیست یا بازهٔ جداشده با کاما تنظیم کنید (مثلاً "1-3,5"). API فقط تصاویر را از آن صفحات برمی‌گرداند.

آیا برای تصاویر استخراج‌شده محدودیت اندازه‌ای وجود دارد؟
SDK داده‌های تصویر اصلی را بدون تغییر اندازه برمی‌گرداند. اگر به فایل‌های کوچکتر نیاز دارید، می‌توانید تصاویر ذخیره‌شده را با استفاده از هر کتابخانه پردازش تصویر پس‌پردازش کنید.

بیشتر بخوانید