استخراج الصور من مستندات PDF هو طلب شائع عند بناء خطوط معالجة المستندات، خاصةً لتوليد الصور المصغرة أو إعادة استخدام الرسومات في أماكن أخرى. يوفر GroupDocs.Parser Cloud SDK for .NET واجهة برمجة تطبيقات قوية تجعل هذه المهمة سهلة في 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 باستخدام 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 مناسبًا لاستخراج الصور

  • استرجاع الصور مباشرة: استدعاء GetDocumentImages يُعيد الصور بصيغتها الأصلية دون خطوات تحويل إضافية.
  • تسليم Base64: تُقدم الصور كسلاسل Base64، مما يجعل من السهل فك تشفيرها بأي لغة.
  • البيانات الوصفية على مستوى الصفحة: كل ImageInfo يتضمن رقم الصفحة، الأبعاد، الدقة والفهرس، مما يساعد على تنظيم الأصول المستخرجة.
  • دعم جميع صيغ الصور النقطية الشائعة: PNG, JPEG, BMP, GIF, TIFF وغيرها تُحفظ تمامًا كما هي مخزنة في PDF.
  • معالجة سحابية قابلة للتوسع: يتم معالجة ملفات 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 في واجهة برمجة تطبيقات Parser بعد رفع ملف PDF باستخدام StorageApi.UploadFile. فكّ الترميز Base64 للنتائج واكتبها إلى القرص، كما هو موضح في مثال الشيفرة.

ماذا لو كان ملف PDF محميًا بكلمة مرور؟
قم بتضمين كلمة المرور في نموذج الطلب. سيقوم SDK بفك تشفير الملف قبل استخراج الصور. راجع التوثيق للحصول على اسم الخاصية الدقيق.

هل يمكنني تحديد استخراج الصفحات المحددة؟
نعم، قم بتعيين خاصية pages في GetDocumentImagesRequest إلى قائمة مفصولة بفواصل أو نطاق (مثال: "1-3,5"). سيعيد الـ API الصور فقط من تلك الصفحات.

هل هناك أي حدود لحجم الصور المستخرجة؟
يعيد SDK بيانات الصورة الأصلية دون تعديل الحجم. إذا كنت بحاجة إلى ملفات أصغر، قم بمعالجة الصور المحفوظة لاحقًا باستخدام أي مكتبة معالجة صور.

Read More