Hugging Face's logo

Transformers documentation

معالج الصور

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

معالج الصور

يتولى مُعالج الصور مسؤولية تحميل الصور (اختياريًا)، وتجهيز ميزات الإدخال لنماذج الرؤية، ومعالجة مخرجاتها بعد التشغيل. وتشمل هذه العملية تحويلات مثل تغيير الحجم، والتطبيع، والتحويل إلى متجهات PyTorch وNumpy. وقد تشمل أيضًا معالجة لاحقة خاصة بالنموذج، مثل تحويل القيم الاحتمالية (logits) إلى أقنعة تجزئة.

تستخدم معالجات الصور بنية معمارية مبنية على الخلفية (backend). وهيكلية الفئات هي:

  • BaseImageProcessor — فئة أساسية مجردة (لأغراض التوافق مع الإصدارات السابقة فقط؛ لا تُنشأ مباشرةً)
    • TorchvisionBackend — الواجهة الخلفية الافتراضية المعتمدة على torchvision. تعمل بتسريع عبر وحدة معالجة الرسوميات (GPU) وهي أسرع بكثير من الواجهة الخلفية المعتمدة على PIL. جميع النماذج تعرض فئة <Model>ImageProcessor ترث منها.
    • PilBackend — بديل الخلفية المبنية على PIL/NumPy. محمولة، وتعتمد على المعالج المركزي فقط. متاحة فقط للنماذج الأقدم عبر فئة <Model>ImageProcessorPil؛ وهي مفيدة عند الحاجة إلى تطابق عددي دقيق مع التنفيذ الأصلي.

توفر كلا الواجهتين الخلفيتين نفس واجهة البرمجة. استخدم خاصية backend لفحص الواجهة الخلفية التي يستخدمها المعالج المحمّل (على سبيل المثال processor.backend == "torchvision").

مرّر backend إلى AutoImageProcessor.from_pretrained() لاختيار واجهة خلفية. عند إغفال backend (وهو الافتراضي)، يتم اختيار torchvision إذا كان مثبّتًا، وإلا يُستخدم PIL. بعض النماذج التي تستخدم استيفاء Lanczos (Chameleon، Flava، Idefics3، SmolVLM) هي استثناء، وتُستخدم PIL افتراضيًا عندما يكون torchvision < 0.27. فرض backend="torchvision" لهذه النماذج على torchvision < 0.27 يؤدي إلى الرجوع إلى استيفاء BICUBIC، لأن torchvision يدعم Lanczos للمصفوفات (tensors) فقط من الإصدار 0.27 فصاعدًا.

from transformers import AutoImageProcessor

# Default: picks torchvision if available, otherwise pil
processor = AutoImageProcessor.from_pretrained("facebook/detr-resnet-50")

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

# Explicitly request PIL
processor = AutoImageProcessor.from_pretrained("facebook/detr-resnet-50", backend="pil")

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

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)

فيما يلي بعض مقارنات السرعة بين واجهتي torchvision وPIL لنموذجي DETR وRT-DETR، وكيف تؤثران على زمن الاستدلال الكلي:

تم تشغيل هذه الاختبارات المرجعية على وحدة AWS EC2 g5.2xlarge، باستخدام معالج رسومي NVIDIA A10G Tensor Core.

ImageProcessingMixin

فئة transformers.ImageProcessingMixin

< >

( **kwargs )

هذا مزيج لمعالج الصور يُستخدم لتوفير وظائف الحفظ/التحميل لمستخرِقات الميزات التسلسلية والصور.

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLikecache_dir: str | os.PathLike | None = Noneforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'**kwargs )

المعاملات

  • pretrained_model_name_or_path (str أو os.PathLike) — يمكن أن يكون هذا:
    • سلسلة نصية، وهي معرف النموذج لمعالج صور مُدرَّب مسبقًا مستضاف داخل مستودع نموذج على huggingface.co.
    • مسار إلى مجلد يحتوي على معالج صور محفوظ باستخدام طريقة save_pretrained()، على سبيل المثال ./my_model_directory/.
    • مسار إلى ملف JSON لمعالج صور محفوظ، على سبيل المثال ./my_model_directory/preprocessor_config.json.
  • cache_dir (str أو os.PathLike، اختياري) — المسار إلى مجلد يجب تخزين مُعالج الصور المُسبق التدريب في الموديل المُحمّل فيه إذا لم يُستخدم المجلد المؤقت القياسي.
  • force_download (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إجبار (إعادة) تنزيل ملفات معالج الصور وتجاوز الإصدارات المخزنة مؤقتًا إذا كانت موجودة.
  • proxies (dict[str, str], اختياري) — قاموس لخوادم الوكيل (proxy) للاستخدام حسب البروتوكول أو نقطة النهاية، على سبيل المثال {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. تُستخدم هذه الوكلاء في كل طلب.
  • token (str أو bool، اختياري) — الرمز الذي يُستخدم كتفويض حامل HTTP للملفات البعيدة. إذا كان True، أو لم يُحدد، فسيتم استخدام الرمز الذي تم إنشاؤه عند تشغيل hf auth login (المخزَّن في ~/.huggingface).
  • revision (str، اختياري، القيمة الافتراضية "main") — الإصدار المحدد من النموذج الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف commit، نظرًا لاستخدامنا نظامًا قائمًا على git لتخزين النماذج والمخرجات الأخرى على huggingface.co، لذا يمكن أن يكون revision أي معرّف يسمح به git.

أنشئ نوعًا من ImageProcessingMixin من معالج الصور.

أمثلة:

# We can't instantiate directly the base class *ImageProcessingMixin* so let's show the examples on a
# derived class: *CLIPImageProcessor*
image_processor = CLIPImageProcessor.from_pretrained(
    "openai/clip-vit-base-patch32"
)  # Download image_processing_config from huggingface.co and cache.
image_processor = CLIPImageProcessor.from_pretrained(
    "./test/saved_model/"
)  # E.g. image processor (or model) was saved using *save_pretrained('./test/saved_model/')*
image_processor = CLIPImageProcessor.from_pretrained("./test/saved_model/preprocessor_config.json")
image_processor = CLIPImageProcessor.from_pretrained(
    "openai/clip-vit-base-patch32", do_normalize=False, foo=False
)
assert image_processor.do_normalize is False
image_processor, unused_kwargs = CLIPImageProcessor.from_pretrained(
    "openai/clip-vit-base-patch32", do_normalize=False, foo=False, return_unused_kwargs=True
)
assert image_processor.do_normalize is False
assert unused_kwargs == {"foo": False}

save_pretrained

< >

( save_directory: str | os.PathLikepush_to_hub: bool = False**kwargs )

المعاملات

  • save_directory (str أو os.PathLike) — المجلد الذي سيتم حفظ ملف JSON لمعالج الصور فيه (سيتم إنشاؤه إذا لم يكن موجودًا).
  • push_to_hub (bool، اختياري، الافتراضي False) — ما إذا كان سيتم دفع نموذجك إلى مركز نماذج Hugging Face بعد حفظه. يمكنك تحديد المستودع الذي تريد الدفع إليه باستخدام repo_id (سيكون الافتراضي هو اسم save_directory في نطاقك).
  • kwargs (dict[str, Any]، اختياري) — حجج إضافية بأسماء تُمرَّر إلى طريقة push_to_hub().

احفظ كائن معالج الصور في المجلد save_directory حتى يمكن إعادة تحميله باستخدام طريقة الفئة from_pretrained().

BatchFeature

فئة transformers.BatchFeature

< >

( data: dict[str, typing.Any] | None = Nonetensor_type: None | str | transformers.utils.generic.TensorType = Noneskip_tensor_conversion: list[str] | set[str] | None = None )

المعاملات

  • data (dict, اختياري) — قاموس من القوائم/المصفوفات/الموترات التي تُعاد بواسطة طرائق call/pad (مثل ‘input_values’، ‘attention_mask’، وما إلى ذلك).
  • tensor_type (Union[None, str, TensorType]، اختياري) — يمكنك تحديد tensor_type هنا لتحويل قوائم الأعداد الصحيحة إلى تينسورات PyTorch/Numpy عند التهيئة.
  • skip_tensor_conversion (list[str] أو set[str]، اختياري) — قائمة أو مجموعة من المفاتيح التي يجب ألا تُحوَّل إلى متجهات، حتى لو تم تحديد tensor_type.

يحتوي على مخرجات طريقة pad() وطريقة __call__ الخاصة بمستخرج الميزات.

تُشتق هذه الفئة من قاموس بايثون ويمكن استخدامها كقاموس.

convert_to_tensors

< >

( tensor_type: str | transformers.utils.generic.TensorType | None = Noneskip_tensor_conversion: list[str] | set[str] | None = None )

المعاملات

  • tensor_type (str أو TensorType، اختياري) — نوع المصفوفات (tensors) المراد استخدامه. إذا كان str، فيجب أن يكون أحد قيم التعداد TensorType. إذا كان None، فلا يتم إجراء أي تعديل.
  • skip_tensor_conversion (list[str] أو set[str]، اختياري) — قائمة أو مجموعة من المفاتيح التي يجب ألا تُحوَّل إلى متجهات، حتى لو تم تحديد tensor_type.

قم بتحويل المحتوى الداخلي إلى متجهات.

ملاحظة: تُتجاهل تلقائيًا القيم التي لا تملك بنية تشبه المصفوفة (مثل السلاسل النصية، والقواميس، وقوائم السلاسل النصية) ولن يتم تحويلها إلى متجهات. أما المصفوفات غير المنتظمة (قوائم من المصفوفات بطول مختلف) فيُحاول تحويلها، لكنها قد تثير أخطاء أثناء عملية التحويل.

إلى

< >

( *args**kwargs ) → BatchFeature

المعاملات

  • args (Tuple) — سيتم تمريرها إلى دالة to(...) الخاصة بالمصفوفات.
  • kwargs (Dict, اختياري) — سيتم تمريرها إلى دالة to(...) الخاصة بالمصفوفات. لتفعيل نقل البيانات غير المتزامن، اضبط علم non_blocking داخل kwargs (الافتراضي هو False).

يعيد

BatchFeature

نفس الكائن بعد التعديل.

أرسل جميع القيم إلى الجهاز عن طريق استدعاء v.to(*args, **kwargs) (PyTorch فقط). يجب أن يدعم هذا التحويل إلى أنواع بيانات dtypes مختلفة وإرسال BatchFeature إلى جهاز device مختلف.

BaseImageProcessor

فئة transformers.BaseImageProcessor

< >

( **kwargs: *<class 'transformers.processing_utils.ImagesKwargs'> )

الفئة الأساسية لمعالجات الصور مع بنية خلفية مبنية على الوراثة.

تعريف هذا الصنف خط المعالجة المسبقة: التحقق من صحة معاملات kwargs، وتجهيز المدخلات، وتوجيه الطلبات إلى طريقة _preprocess الخاصة بالخلفية. ترث صنفات الخلفية الفرعية (TorchvisionBackend، PilBackend) من هذا الصنف وتنفذ عمليات الصور الفعلية (تحديد الحجم، القص، إعادة التحجيم، التطبيع، وما إلى ذلك). ثم ترث معالجات الصور الخاصة بالنموذج من صنف الخلفية المناسب.

نظرة عامة على البنية

هيكلية الفئات هي:

BaseImageProcessor (هذه الفئة) ├── TorchvisionBackend (مع تسريع GPU، torch.Tensor) │ └── ModelImageProcessor (مثل LlavaNextImageProcessor) └── PilBackend (CPU محمول، np.ndarray) └── ModelImageProcessorPil (مثل CLIPImageProcessorPil)

مسار المعالجة المسبقة هو:

call() → preprocess() → _preprocess_image_like_inputs() → _prepare_image_like_inputs() (يستدعي process_image لكل صورة) → _preprocess() (عمليات الدفعة: تغيير الحجم، القص، إلخ)

  • process_image: تنفّذها الخوادم الخلفية. تحوّل مدخلاً خاماً واحداً (PIL أو NumPy أو Tensor) إلى الصيغة التشغيلية للخادم الخلفي (torch.Tensor أو np.ndarray)، وتتعامل مع تحويل RGB وإعادة ترتيب القنوات.
  • _preprocess: تنفّذه الخوادم الخلفية. يقوم بمعالجة الدفعة الفعلية (تحديد الحجم، القص المركزي، إعادة التحجيم، التطبيع، الحشو) ويعيد BatchFeature.

التطبيق الأساسي

للمعالجات التي تحتاج فقط إلى عمليات قياسية (تغيير الحجم، القص من المنتصف، إعادة التحجيم، التطبيع)، ورّث من backend وحدد سمات الفئة:

from transformers.image_processing_backends import PilBackend

class MyImageProcessorPil(PilBackend): resample = PILImageResampling.BILINEAR image_mean = IMAGENET_DEFAULT_MEAN image_std = IMAGENET_DEFAULT_STD size = {“height”: 224, “width”: 224} do_resize = True do_rescale = True do_normalize = True

يتولى منهج _preprocess الخاص بالخلفية معالجة خط المعالجة القياسي تلقائيًا.

المعالجة المخصصة

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

class MyImageProcessor(TorchvisionBackend): def _preprocess(self, images, do_resize, size, do_normalize, image_mean, image_std, **kwargs):

تجميع الصور حسب الشكل لعمليات الدفع الفعّالة

grouped_images, grouped_images_index = group_images_by_shape(images) processed_groups = {} for shape, stacked_images in grouped_images.items(): if do_resize: stacked_images = self.resize(stacked_images, size=size) if do_normalize: stacked_images = self.normalize(stacked_images, mean=image_mean, std=image_std) processed_groups[shape] = stacked_images processed_images = reorder_images(processed_groups, grouped_images_index) return BatchFeature(data={“pixel_values”: processed_images})

للمعالجات التي تتعامل مع أنواع مدخلات متعددة (مثل الصور + خرائط التقسيم)، تجاوز _preprocess_image_like_inputs:

def _preprocess_image_like_inputs( self, images: ImageInput, segmentation_maps: ImageInput | None = None, kwargs, ) -> BatchFeature: images = self._prepare_image_like_inputs(images,kwargs) batch_feature = self._preprocess(images, **kwargs)

if segmentation_maps is not None: maps = self._prepare_image_like_inputs(segmentation_maps, kwargs) batch_feature[“labels”] = self._preprocess(maps,kwargs).pixel_values

return batch_feature

توسيع سلوك الخلفية

لتخصيص العمليات لواجهة خلفية محددة، قم بإنشاء فئة فرعية من الواجهة الخلفية وتجاوز دوالها:

from transformers.image_processing_backends import TorchvisionBackend, PilBackend

class MyTorchvisionProcessor(TorchvisionBackend): def resize(self, image, size, **kwargs):

منطق تحجيم مخصص لـ torchvision

return super().resize(image, size, **kwargs)

class MyPilProcessor(PilBackend): def resize(self, image, size, **kwargs):

منطق تحجيم مخصص لـ PIL

return super().resize(image, size, **kwargs)

معلمات مخصصة

لإضافة معاملات تتجاوز ImagesKwargs، أنشئ فئة kwargs مخصصة واضبطها كـvalid_kwargs:

class MyImageProcessorKwargs(ImagesKwargs): custom_param: int | None = None

class MyImageProcessor(TorchvisionBackend): valid_kwargs = MyImageProcessorKwargs custom_param = 10 # القيمة الافتراضية

ملاحظات رئيسية

  • يتم اختيار الخلفية على مستوى الفئة: ورث من TorchvisionBackend أو PilBackend
  • تستقبل الخلفيات الصور على شكل torch.Tensor (Torchvision) أو np.ndarray (PIL)، مع وضع القنوات أولاً دائماً
  • جميع الصور تحتوي على بُعد القناة أولاً أثناء المعالجة، بغض النظر عن الخلفية
  • تتخذ الحُجج التي لا يوفّرها المستخدمون قيمَ سمات الفئة افتراضيًا
  • تُغلّف فئات الخلفية (Backend) المنطق الخاص بالخلفية (مثل تغيير الحجم والتطبيع، إلخ) ويمكن تجاوزها

center_crop

< >

( image: ndarraysize: dictdata_format: str | transformers.image_utils.ChannelDimension | None = Noneinput_data_format: str | transformers.image_utils.ChannelDimension | None = None**kwargs )

المعاملات

  • image (np.ndarray) — الصورة التي سيتم قصّها من المنتصف.
  • size (dict[str, int]) — حجم الصورة الناتجة.
  • data_format (str أو ChannelDimension, اختياري) — تنسيق بُعد القناة للصورة الناتجة. إذا لم يُضبط، يُستخدم تنسيق بُعد القناة للصورة المدخلة. يمكن أن يكون أحد ما يلي:
    • "channels_first" أو ChannelDimension.FIRST: صورة بتنسيق (num_channels, height, width).
    • "channels_last" أو ChannelDimension.LAST: صورة بصيغة (الارتفاع، العرض، عدد القنوات).
  • input_data_format (ChannelDimension أو str, اختياري) — تنسيق بُعد القنوات للصورة المدخلة. إذا لم يُضبط، يُستنتج تنسيق بُعد القنوات من الصورة المدخلة. يمكن أن يكون أحد ما يلي:
    • "channels_first" أو ChannelDimension.FIRST: صورة بتنسيق (num_channels, height, width).
    • "channels_last" أو ChannelDimension.LAST: صورة بصيغة (الارتفاع، العرض، عدد القنوات).

يقوم بقصّ صورة من المنتصف إلى (size["height"], size["width"]). إذا كانت أبعاد المدخل أصغر من crop_size على أي حافة، يتم ملء الصورة بأصفار ثم قصّها من المنتصف.

normalize

< >

( image: ndarraymean: float | collections.abc.Iterable[float]std: float | collections.abc.Iterable[float]data_format: str | transformers.image_utils.ChannelDimension | None = Noneinput_data_format: str | transformers.image_utils.ChannelDimension | None = None**kwargs ) → np.ndarray

المعاملات

  • image (np.ndarray) — الصورة المراد تطبيعها.
  • mean (float أو Iterable[float]) — متوسط الصورة المستخدم للتطبيع.
  • std (float أو Iterable[float]) — انحراف المعيار للصورة المستخدم في عملية التطبيع.
  • data_format (str أو ChannelDimension, اختياري) — تنسيق بُعد القناة للصورة الناتجة. إذا لم يُضبط، يُستخدم تنسيق بُعد القناة للصورة المدخلة. يمكن أن يكون أحد ما يلي:
    • "channels_first" أو ChannelDimension.FIRST: صورة بتنسيق (num_channels, height, width).
    • "channels_last" أو ChannelDimension.LAST: صورة بصيغة (الارتفاع، العرض، عدد القنوات).
  • input_data_format (ChannelDimension أو str, اختياري) — تنسيق بُعد القنوات للصورة المدخلة. إذا لم يُضبط، يُستنتج تنسيق بُعد القنوات من الصورة المدخلة. يمكن أن يكون أحد ما يلي:
    • "channels_first" أو ChannelDimension.FIRST: صورة بتنسيق (num_channels, height, width).
    • "channels_last" أو ChannelDimension.LAST: صورة بصيغة (الارتفاع، العرض، عدد القنوات).

يعيد

np.ndarray

الصورة المُطبَّعة.

تطبيع صورة. image = (image - image_mean) / image_std.

preprocess

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]*argsimage_like_kwargs: dict[str, typing.Any] | None = None**kwargs: *<class 'transformers.processing_utils.ImagesKwargs'> ) → ~image_processing_base.BatchFeature

المعاملات

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — الصورة التي سيتم معالجتها مسبقاً. يتوقع صورة واحدة أو دفعة من الصور بقيم بكسل تتراوح بين 0 و255. إذا كنت تمرر صوراً بقيم بكسل بين 0 و1، فاضبط do_rescale=False.
  • image_like_kwargs (dict[str, Any], اختياري) — علامة مخصّصة للمطوّرين لإدخال مدخلات إضافية مشابهة للصور ستخضع أيضاً للمعالجة المسبقة. استخدم هذا الخيار فقط إذا لم يعمل تمرير المدخلات كحجج اسمية (kwargs). على سبيل المثال، preprocess(images, masks=masks) هو الخيار المفضّل، لكنه قد يسبّب مشاكل في أولوية الحُجج لبعض النماذج. في تلك الحالات يمكن استخدام preprocess(images, image_like_inputs={"masks": masks}) بدلاً منه.
  • do_convert_rgb (bool، kwargs، اختياري) — ما إذا كان يجب تحويل الصورة إلى RGB.
  • do_resize (bool، kwargs، اختياري) — ما إذا كان يجب تغيير حجم الصورة.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — يصف الأبعاد القصوى للمدخلات إلى النموذج.
  • default_to_square (bool، kwargs، اختياري) — ما إذا كان يجب افتراض صورة مربعة عند تغيير الحجم، إذا كانت القيمة عددًا صحيحًا.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — حجم الصورة الناتجة بعد تطبيق center_crop.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — مرشّح إعادة العينة (Resampling filter) المستخدم عند تغيير حجم الصورة. يمكن أن يكون أحد قيم التعداد PILImageResampling. لا يكون له أي تأثير إلا إذا تم تعيين do_resize إلى True.
  • do_rescale (bool، kwargs، اختياري) — ما إذا كان يجب إعادة تحجيم الصورة.
  • rescale_factor (float، kwargs، اختياري) — معامل إعادة التحجيم لإعادة تحجيم الصورة إذا كان do_rescale مضبوطاً على True.
  • do_normalize (bool، kwargs، اختياري) — ما إذا كان سيتم تطبيع الصورة.
  • image_mean (Union[float, list[float], tuple[float, ...]]، kwargs، اختياري) — متوسط الصورة المستخدم للتطبيع. لا يكون له أي تأثير إلا إذا تم تعيين do_normalize إلى True.
  • image_std (Union[float, list[float], tuple[float, ...]]، kwargs، اختياري) — انحراف المعيار للصورة المستخدم للتطبيع. لا يكون له أي تأثير إلا إذا تم تعيين do_normalize إلى True.
  • do_pad (bool، kwargs، اختياري) — ما إذا كان سيتم توسيط الصورة. يتم التوسيط إما إلى أكبر حجم في الدفعة أو إلى حجم مربع ثابت لكل صورة. تعتمد استراتيجية التوسيط الدقيقة على النموذج.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — الحجم على شكل {"height": int, "width" int} الذي يجب توسيد الصور إليه. يجب أن يكون أكبر من أي حجم صورة مُقدَّم للمعالجة المسبقة. إذا لم يُقدَّم pad_size، فسيتم توسيد الصور إلى أكبر ارتفاع وعرض في الدفعة. يُطبَّق فقط عندما يكون do_pad=True.
  • do_center_crop (bool، kwargs، اختياري) — ما إذا كان يجب قص الصورة من المنتصف.
  • data_format (Union[str, ~image_utils.ChannelDimension]، kwargs، اختياري) — يُؤمَّن دعم ChannelDimension.FIRST فقط. أُضيف من أجل التوافق مع المعالجات البطيئة.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, اختياري) — تنسيق بُعد القناة للصورة المدخلة. إذا لم يُضبط، يُستنتج تنسيق بُعد القناة من الصورة المدخلة. يمكن أن يكون أحد ما يلي:
    • "channels_first" أو ChannelDimension.FIRST: صورة بتنسيق (num_channels, height, width).
    • "channels_last" أو ChannelDimension.LAST: صورة بصيغة (الارتفاع، العرض، عدد القنوات).
    • "none" أو ChannelDimension.NONE: صورة بصيغة (الارتفاع، العرض).
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — الجهاز الذي تتم عليه معالجة مقاطع الفيديو. إذا لم يتم تعيينه، يُستنتج الجهاز من مقاطع الفيديو المدخلة.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — تُرجع تينسورات مكدّسة إذا تم ضبطها على 'pt'، وإلا تُرجع قائمة من التينسورات.
  • disable_grouping (bool، kwargs، اختياري) — ما إذا كان سيتم تعطيل تجميع الصور حسب الحجم لمعالجتها بشكل فردي بدلاً من دفعات. إذا كانت القيمة None، فسيتم تعيينها إلى True إذا كانت الصور على وحدة المعالجة المركزية (CPU)، وإلا فستكون False. تستند هذه الخيارات إلى ملاحظات تجريبية، كما هو موضح هنا: https://github.com/huggingface/transformers/pull/38157
  • image_seq_length (int، kwargs، اختياري) — عدد رموز الصورة التي سيتم استخدامها لكل صورة في المدخلات. تمت إضافته من أجل التوافق مع الإصدارات السابقة، لكن ينبغي ضبطه كخاصية للمعالج في النماذج المستقبلية.

يعيد

~image_processing_base.BatchFeature

  • data (dict) — قاموس من القوائم/المصفوفات/الموترات التي يعيدها أسلوب call (مثل ‘pixel_values’).
  • tensor_type (Union[None, str, TensorType]، اختياري) — يمكنك تحديد tensor_type هنا لتحويل قوائم الأعداد الصحيحة إلى تينسورات PyTorch/Numpy عند التهيئة.

معالجة صورة أو دفعة من الصور مسبقًا.

process_image

< >

( *args**kwargs )

معالجة صورة خام واحدة إلى الصيغة التشغيلية للجهة الخلفية.

يُنفَّذ بواسطة فئات فرعية تابعة للواجهة الخلفية (TorchvisionBackend، PilBackend). يحوّل مدخلاً خاماً (صورة PIL، مصفوفة NumPy، أو متجه torch) إلى الصيغة الداخلية للواجهة الخلفية (torch.Tensor في حالة Torchvision، وnp.ndarray في حالة PIL)، ويتعامل مع التحويل إلى RGB ويضمن ترتيب القنوات أولاً.

rescale

< >

( image: ndarrayscale: floatdata_format: str | transformers.image_utils.ChannelDimension | None = Noneinput_data_format: str | transformers.image_utils.ChannelDimension | None = None**kwargs ) → np.ndarray

المعاملات

  • image (np.ndarray) — الصورة التي سيتم إعادة تحجيمها.
  • scale (float) — عامل التوسيع الذي يُستخدم لإعادة توسيع قيم البكسل.
  • data_format (str أو ChannelDimension, اختياري) — تنسيق بُعد القناة للصورة الناتجة. إذا لم يُضبط، يُستخدم تنسيق بُعد القناة للصورة المدخلة. يمكن أن يكون أحد ما يلي:
    • "channels_first" أو ChannelDimension.FIRST: صورة بتنسيق (num_channels, height, width).
    • "channels_last" أو ChannelDimension.LAST: صورة بصيغة (الارتفاع، العرض، عدد القنوات).
  • input_data_format (ChannelDimension أو str, اختياري) — تنسيق بُعد القنوات للصورة المدخلة. إذا لم يُضبط، يُستنتج تنسيق بُعد القنوات من الصورة المدخلة. يمكن أن يكون أحد ما يلي:
    • "channels_first" أو ChannelDimension.FIRST: صورة بتنسيق (num_channels, height, width).
    • "channels_last" أو ChannelDimension.LAST: صورة بصيغة (الارتفاع، العرض، عدد القنوات).

يعيد

np.ndarray

الصورة المُعاد تحجيمها.

إعادة تحجيم صورة بمعامل تحجيم. image = image * scale.

TorchvisionBackend

فئة transformers.TorchvisionBackend

< >

( **kwargs: *<class 'transformers.processing_utils.ImagesKwargs'> )

واجهة Torchvision الخلفية لمعالجة الصور الدفعية مع تسريع GPU.

center_crop

< >

( image: torch.Tensorsize: SizeDict**kwargs )

قصّ صورة في المنتصف باستخدام Torchvision.

convert_to_rgb

< >

( image: torch.Tensorinput_data_format: str | transformers.image_utils.ChannelDimension | None = None )

تحويل صورة إلى تنسيق RGB.

fetch_images

< >

( image_url_or_urls: str | list[str] | list[list[str]] )

تحويل عنوان URL واحد أو قائمة من عناوين URL / المسارات إلى كائنات torch.Tensor.

تُمرَّر كائنات الصور الصالحة مسبقًا (المصفوفات المتوترة، مصفوفات numpy، صور PIL) دون أي تغيير، بحيث لا يتأثر المستدعون الذين يقومون بتحميل الصور مسبقًا.

normalize

< >

( image: torch.Tensormean: float | collections.abc.Iterable[float]std: float | collections.abc.Iterable[float]inplace: bool = False**kwargs )

تطبيع صورة باستخدام Torchvision.

pad

< >

( images: listpad_size: SizeDict = Nonefill_value: int | None = 0padding_mode: str | None = 'constant'return_mask: bool = Falsedisable_grouping: bool | None = Falseis_nested: bool | None = False**kwargs )

قم بتوسيط الصور باستخدام Torchvision مع عمليات الدُفعات.

process_image

< >

( image: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]do_convert_rgb: bool | None = Noneinput_data_format: str | transformers.image_utils.ChannelDimension | None = Nonedevice: typing.Optional[ForwardRef('torch.device')] = None**kwargs: *<class 'transformers.processing_utils.ImagesKwargs'> )

معالجة صورة واحدة لخلفية torchvision.

rescale

< >

( image: torch.Tensorscale: float**kwargs )

إعادة تحجيم صورة بمعامل تحجيم باستخدام Torchvision.

rescale_and_normalize

< >

( images: torch.Tensordo_rescale: boolrescale_factor: floatdo_normalize: boolimage_mean: float | list[float]image_std: float | list[float] )

إعادة تحجيم الصور وتطبيعها باستخدام Torchvision (مدمجة من أجل الكفاءة).

resize

< >

( image: torch.Tensorsize: SizeDictresample: PILImageResampling | tvF.InterpolationMode | int | None = Noneantialias: bool = True**kwargs )

تغيير حجم صورة باستخدام Torchvision.

PilBackend

فئة transformers.PilBackend

< >

( **kwargs: *<class 'transformers.processing_utils.ImagesKwargs'> )

واجهة خلفية PIL/NumPy لمعالجة الصور على المعالج فقط، مع قابلية نقل عالية.

center_crop

< >

( image: ndarraysize: SizeDict**kwargs )

قصّ صورة من المنتصف باستخدام NumPy.

convert_to_rgb

< >

( image: ndarrayinput_data_format: str | transformers.image_utils.ChannelDimension | None = None )

تحويل صورة إلى تنسيق RGB.

normalize

< >

( image: ndarraymean: float | collections.abc.Iterable[float]std: float | collections.abc.Iterable[float]**kwargs )

تطبيع صورة باستخدام NumPy.

pad

< >

( images: listpad_size: SizeDict = Nonefill_value: int | None = 0padding_mode: str | None = 'constant'return_mask: bool = False**kwargs )

حشو الصور إلى الحجم المحدد باستخدام NumPy.

process_image

< >

( image: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]do_convert_rgb: bool | None = Noneinput_data_format: str | transformers.image_utils.ChannelDimension | None = None**kwargs: *<class 'transformers.processing_utils.ImagesKwargs'> )

معالجة صورة واحدة لخلفية PIL.

rescale

< >

( image: ndarrayscale: float**kwargs )

إعادة تحجيم صورة بمعامل تحجيم باستخدام NumPy.

resize

< >

( image: ndarraysize: SizeDictresample: PILImageResampling | None = Nonereducing_gap: int | None = None**kwargs )

تغيير حجم صورة باستخدام PIL/NumPy.

Update on GitHub

←مستخرج الميزات معالج الفيديو→