# معالجات الصور

تحوّل معالجات الصور (Image processors) الصور إلى قيم بكسل، وهي تينسورات تمثل ألوان الصورة وأبعادها. وتُعدّ قيم البكسل مدخلات لنموذج الرؤية. ولضمان استلام النموذج المُدرَّب مسبقًا على المدخلات الصحيحة، يمكن لمعالج الصور تنفيذ العمليات التالية للتأكد من أن الصورة مطابقة تمامًا للصور التي تم تدريب النموذج عليها مسبقًا.

- قصّ من المنتصف أو تغيير حجم صورة
- تطبيع قيم البكسلات أو إعادة مقياسها

استخدم [from_pretrained()](/docs/transformers/main/ar/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained) لتحميل إعدادات معالج الصور (حجم الصورة، ما إذا كان سيتم تطبيع الصور وإعادة تحجيمها، إلخ) من نموذج رؤية على [Hub](https://hf.co) الخاص بـ Hugging Face أو من مجلد محلي. يتم حفظ إعدادات كل نموذج مُدرَّب مسبقًا في ملف [preprocessor_config.json](https://huggingface.co/google/vit-base-patch16-224/blob/main/preprocessor_config.json).

عندما يكون مُعالج الصور جزءًا من مُعالج متعدد الوسائط، فإن تكوينه يكون متداخلًا في `processor_config.json` بدلاً من ذلك. راجع [حفظ مُعالج وتحميله](./processors#save-and-load-a-processor) للحصول على التفاصيل.

```py
from transformers import AutoImageProcessor

image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")
```

مرّر صورة إلى معالج الصور لتحويلها إلى قيم بكسل، و اضبط `return_tensors="pt"` لإرجاع تينسورات PyTorch. يمكنك طباعة المدخلات لرؤية شكل الصورة كتينسور.

```py
from PIL import Image
import requests

url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/image_processor_example.png"
image = Image.open(requests.get(url, stream=True).raw).convert("RGB")
inputs = image_processor(image, return_tensors="pt")
```

يتناول هذا الدليل فئة معالج الصور وكيفية معالجة الصور مسبقًا لنماذج الرؤية.

## فئات معالج الصور

تستخدم معالجات الصور بنية معمارية مبنية على الخوادم الخلفية (backends) مع خادمين خلفيين:

- [TorchvisionBackend](/docs/transformers/main/ar/main_classes/image_processor#transformers.TorchvisionBackend) — التنفيذ الافتراضي المعتمد على [torchvision](https://pytorch.org/vision/stable/index.html). مُسرَّع بواسطة وحدة معالجة الرسوميات (GPU) وأسرع بمقدار يصل إلى 33 مرة مقارنةً بالخلفية (backend) الخاصة بـ PIL عند التعامل مع دفعات من مدخلات [torch.Tensor](https://pytorch.org/docs/stable/tensors.html). تدعم جميع النماذج هذه الخلفية؛ بينما تدعم النماذج الأحدث هذه الخلفية فقط.
- [PilBackend](/docs/transformers/main/ar/main_classes/image_processor#transformers.PilBackend) — بديل PIL/NumPy. قابل للنقل ويعمل على المعالج فقط. متوفر فقط للنماذج الأقدم، حيث يكون من المفيد إعادة إنتاج المخرجات العددية الدقيقة للتنفيذ الأصلي.

يمكن فحص الخلفية النشطة في المعالج المحمّل من خلال خاصية `backend` الخاصة به (على سبيل المثال، `processor.backend == "torchvision"`). كل معالج صور فرعي يرث من [ImageProcessingMixin](/docs/transformers/main/ar/internal/image_processing_utils#transformers.ImageProcessingMixin) الذي يوفر طريقتي [from_pretrained()](/docs/transformers/main/ar/internal/image_processing_utils#transformers.ImageProcessingMixin.from_pretrained) و [save_pretrained()](/docs/transformers/main/ar/internal/image_processing_utils#transformers.ImageProcessingMixin.save_pretrained).

هناك طريقتان لتحميل معالج الصور: إما باستخدام [AutoImageProcessor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoImageProcessor) أو مباشرةً من فئة محددة لنموذج معين.

توفر واجهة [AutoClass](./model_doc/auto) طريقة مريحة لتحميل معالج الصور دون الحاجة إلى تحديد النموذج المرتبط بمعالج الصور بشكل مباشر.

استخدم [from_pretrained()](/docs/transformers/main/ar/model_doc/auto#transformers.AutoImageProcessor.from_pretrained) مع الحجة `backend` لاختيار الخلفية. عند إغفال `backend` (الافتراضي)، يتم اختيار torchvision إذا كان مثبتًا، وإلا يُستخدم PIL. لاحظ أن `backend="pil"` مدعوم فقط للنماذج الأقدم؛ فالنماذج الأحدث تعرض فقط خلفية torchvision.

للحصول على أقرب تطابق مع معالجة ما قبل التدريب الخاصة بالنموذج، استخدم الواجهة الخلفية (backend) المحددة في وثائقه أو في كود التدريب. إذا كانت خط أنابيب التدريب يستخدم PIL ويدعم النموذج كلا الواجهتين الخلفيتين، فمرّر `backend="pil"`. يمكن أن يؤدي تبديل الواجهات الخلفية إلى تغيير قيم البكسل بعد إعادة التحجيم، كما يمكن أن تؤدي تحديثات Pillow أو torchvision إلى تغييرها أيضاً. لضمان قابلية إعادة إنتاج معالجة ما قبل التدريب، ثبّت إصدارات الواجهة الخلفية ومكتبة الصور.

> [!NOTE]
> تستخدم مجموعة صغيرة من النماذج الأقدم (Chameleon، Flava، Idefics3، SmolVLM) استيفاء Lanczos. يعتمد الخلفية الافتراضية الخاصة بها على إصدار torchvision لديك. مع torchvision > 0.27، يتم دعم Lanczos بشكل أصلي وتكون هذه النماذج افتراضياً على torchvision. أما إصدارات torchvision الأقدم فتعود إلى BICUBIC، لذا يكون الافتراضي هو PIL للحفاظ على المخرجات الأصلية. مرّر `backend="torchvision"` صراحةً لتجاوز الافتراضي.

```py
from transformers import AutoImageProcessor

# Default: picks torchvision if available, otherwise pil
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")

# Explicitly request the torchvision backend
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224", backend="torchvision")

# Explicitly request the PIL backend (only for models that support it)
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224", backend="pil")
```

يرتبط كل معالج صور بنموذج رؤية مُدرَّب مسبقًا محدد، وتحتوي إعداداته على حجم النموذج المتوقع ومعاملات التطبيع.

حمّل مُعالج الخلفية الخاص بـ torchvision مباشرةً من الفئة المحددة للنموذج.

```py
from transformers import ViTImageProcessor

image_processor = ViTImageProcessor.from_pretrained("google/vit-base-patch16-224")
```

بالنسبة للنماذج التي تدعم ذلك، يمكنك تحميل واجهة `Pil` الخلفية باستخدام الفئة التي تنتهي بلاحقة `Pil`. وهذا مفيد عندما تحتاج إلى تطابق عددي دقيق مع التنفيذ الأصلي.

```py
from transformers import ViTImageProcessorPil

image_processor = ViTImageProcessorPil.from_pretrained("google/vit-base-patch16-224")
```

## معالجات الخلفية الخاصة بـ Torchvision

[TorchvisionBackend](/docs/transformers/main/ar/main_classes/image_processor#transformers.TorchvisionBackend) هو الواجهة الخلفية **الافتراضية**. تأكد من تثبيت [torchvision](https://pytorch.org/get-started/locally/#mac-installation)، ثم حمّله باستخدام `backend="torchvision"` (أو ببساطة احذف `backend`، حيث يتم اختيار torchvision تلقائيًا عند توفره).

```py
from transformers import AutoImageProcessor

processor = AutoImageProcessor.from_pretrained("facebook/detr-resnet-50", backend="torchvision")
```

تحكّم في الجهاز الذي تُنفَّذ عليه المعالجة باستخدام الحجة `device`. تُنفَّذ المعالجة افتراضيًا على نفس الجهاز الذي توجد عليه المدخلات إذا كانت متجهات (tensors)، وإلا فإنها تعود إلى وحدة المعالجة المركزية (CPU). ينفّذ المثال أدناه المعالجة على مُسرِّع (accelerator).

```py
import torch
from torchvision.io import read_image
from transformers import DetrImageProcessor

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

images = read_image("image.jpg")
processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
images_processed = processor(images, return_tensors="pt", device=device)
```

المعايير

تم الحصول على نتائج الاختبارات المرجعية من وحدة [AWS EC2 g5.2xlarge](https://aws.amazon.com/ec2/instance-types/g5/) مزودة بمعالج رسومي NVIDIA A10G Tensor Core GPU.

  

  

  

  

## دقة ديناميكية

تعتمد معظم معالجات الصور على تغيير حجم كل صورة إلى دقة ثابتة واحدة. تتيح الدقة الديناميكية لبعض النماذج الحفاظ على نسبة الأبعاد الأصلية للسماح بزيادة كمية البيانات المُعالَجة مسبقًا مع حجم الصورة، بحيث تحصل الصورة عالية التفاصيل على عدد أكبر من البُقع (patches) مقارنةً بالأيقونة الصغيرة، مما يتيح للنموذج توجيه قدرته الحاسوبية إلى المناطق التي تحتوي على محتوى يستحق التحليل.

يعتمد تقسيم الصورة على النموذج. بعض النماذج تقصّ الصورة إلى عدد متغيّر من البقع ذات الحجم الثابت، محكومًا بمعاملات مثل `min_patches` و`max_patches`. أما نماذج أخرى فتعيد ضبط حجم الصورة إلى الدقة الأنسب لها، إما من خلال اختيارها من قائمة مسبقة التعريف لنسب الأبعاد، أو اشتقاقها من ميزانية بكسلات محددة.

راجع صفحة توثيق النموذج للاطلاع على معامِلاته وقيم افتراضية وأحجام المخرجات.

## المعالجة المسبقة

تتوقع نماذج الرؤية في Transformers الإدخال على شكل تينسورات PyTorch بقيم البكسل. يتولى معالج الصور تحويل الصور إلى قيم بكسل، والتي يتم تمثيلها بحجم الدفعة (batch size) وعدد القنوات والارتفاع والعرض. لتحقيق ذلك، يتم تغيير حجم الصورة (مع اقتطاع مركزي) وتطبيع قيم البكسل وإعادة تحجيمها إلى القيم المتوقعة من قبل النموذج.

لا تتطابق معالجة الصور المسبقة مع *تعزيز الصور*. يُجري تعزيز الصور تغييرات (مثل السطوع والألوان والدوران، إلخ) على الصورة بغرض إنشاء أمثلة تدريب جديدة أو منع الإفراط في التلاؤم. أما معالجة الصور المسبقة فتُجري تغييرات على الصورة بغرض مطابقة صيغة الإدخال المتوقعة لنموذج مُدرَّب مسبقًا.

عادةً، يتم تعزيز الصور (لزيادة الأداء) ثم معالجتها مسبقًا قبل تمريرها إلى نموذج. يمكنك استخدام أي مكتبة ([Albumentations](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification_albumentations.ipynb)، [Kornia](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification_kornia.ipynb)) لتعزيز الصور ومعالج صور للمعالجة المسبقة.

يستخدم هذا الدليل وحدة [transforms](https://pytorch.org/vision/stable/transforms.html) في torchvision للزيادة.

ابدأ بتحميل عينة صغيرة من مجموعة بيانات [food101](https://hf.co/datasets/food101).

```py
from datasets import load_dataset

dataset = load_dataset("ethz/food101", split="train[:100]")
```

من وحدة [transforms](https://pytorch.org/vision/stable/transforms.html)، استخدم واجهة [Compose](https://pytorch.org/vision/master/generated/torchvision.transforms.Compose.html) لربط [RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html) و [ColorJitter](https://pytorch.org/vision/main/generated/torchvision.transforms.ColorJitter.html) معًا. تقوم هذه التحويلات بقص الصورة وتغيير حجمها بشكل عشوائي، وتعديل ألوان الصورة بشكل عشوائي.

يمكن استرجاع حجم الصورة الذي سيتم اقتطاعها إليه عشوائيًا من معالج الصور. بالنسبة لبعض النماذج، يُتوقع تحديد ارتفاع وعرض دقيقين، بينما بالنسبة لغيرها، لا يُطلب سوى `shortest_edge`.

```py
from torchvision.transforms import RandomResizedCrop, ColorJitter, Compose

size = (
    image_processor.size["shortest_edge"]
    if "shortest_edge" in image_processor.size
    else (image_processor.size["height"], image_processor.size["width"])
)
_transforms = Compose([RandomResizedCrop(size), ColorJitter(brightness=0.5, hue=0.5)])
```

طبّق التحويلات على الصور وحولها إلى تنسيق RGB. ثم مرّر الصور المعززة إلى معالج الصور لإرجاع قيم البكسلات.

تم ضبط معامل `do_resize` على `False` لأن الصور تم تغيير حجمها بالفعل في خطوة المعالجة باستخدام [RandomResizedCrop](https://pytorch.org/vision/main/generated/torchvision.transforms.RandomResizedCrop.html). إذا لم تقم بمعالجة الصور، فإن معالج الصور يقوم تلقائيًا بتغيير حجم الصور وتطبيعها باستخدام قيم `image_mean` و`image_std`. يمكن العثور على هذه القيم في ملف إعدادات المعالج المسبق.

```py
def transforms(examples):
    images = [_transforms(img.convert("RGB")) for img in examples["image"]]
    examples["pixel_values"] = image_processor(images, do_resize=False, return_tensors="pt")["pixel_values"]
    return examples
```

طبّق دالة المعالجة المسبقة والتعزيز المدمجة على مجموعة البيانات بأكملها أثناء التشغيل باستخدام [set_transform](https://huggingface.co/docs/datasets/main/en/package_reference/main_classes#datasets.Dataset.set_transform).

```py
dataset.set_transform(transforms)
```

حوّل قيم البكسلات مرة أخرى إلى صورة لترى كيف تم توسيع الصورة ومعالجتها مسبقًا.

```py
import numpy as np
import matplotlib.pyplot as plt

img = dataset[0]["pixel_values"]
plt.imshow(img.permute(1, 2, 0))
```

  
    
    قبل
  
  
    
    بعد
  

بالنسبة لمهام الرؤية الأخرى مثل كشف الأشياء أو التقطيع، يتضمن معالج الصور طرقًا للمعالجة اللاحقة لتحويل المخرجات الخام للنموذج إلى تنبؤات ذات معنى مثل صناديق الحدود أو خرائط التقطيع.

### الحشو

تطبّق بعض النماذج، مثل [DETR](./model_doc/detr)، [scale augmentation](https://paperswithcode.com/method/image-scale-augmentation) أثناء التدريب، مما قد يؤدي إلى اختلاف أحجام الصور ضمن الدفعة الواحدة. ولا يمكن تجميع الصور ذات الأحجام المختلفة في دفعة واحدة.

لإصلاح ذلك، قم بتعبئة الصور باستخدام رمز التعبئة الخاص `0`. استخدم طريقة [pad](https://github.com/huggingface/transformers/blob/9578c2597e2d88b6f0b304b5a05864fd613ddcc1/src/transformers/models/detr/image_processing_detr.py#L1151) لتعبئة الصور، وحدد دالة collate مخصصة لتجميعها في دفعة واحدة.

```py
def collate_fn(batch):
    pixel_values = [item["pixel_values"] for item in batch]
    encoding = image_processor.pad(pixel_values, return_tensors="pt")
    labels = [item["labels"] for item in batch]
    batch = {}
    batch["pixel_values"] = encoding["pixel_values"]
    batch["pixel_mask"] = encoding["pixel_mask"]
    batch["labels"] = labels
    return batch
```