# DepthPro

## نظرة عامة

قُدِّم نموذج DepthPro في [Depth Pro: Sharp Monocular Metric Depth in Less Than a Second](https://huggingface.co/papers/2410.02073) بواسطة Aleksei Bochkovskii وAmaël Delaunoy وHugo Germain وMarcel Santos وYichao Zhou وStephan R. Richter وVladlen Koltun.

DepthPro هو نموذج أساسي لتقدير العمق أحادي العين بالمقياس في وضع الصفرية (zero-shot)، مصمَّم لتوليد خرائط عمق عالية الدقة مع حدة ملحوظة وتفاصيل دقيقة. يعتمد على بنية متعددة المقاييس مبنية على Vision Transformer (ViT)، حيث يتم تقليل حجم الصور، وقسمتها إلى رقعات (patches)، ومعالجتها باستخدام مُشفِّر Dinov2 مشترك. يتم دمج ميزات مستوى الرقعة المستخرجة، ثم رفع حجمها وتحسينها باستخدام مرحلة دمج تشبه DPT، مما يتيح تقديرًا دقيقًا للعمق.

المستخلص من الورقة البحثية هو كالتالي:

*نقدّم نموذجًا أساسيًا لتقدير العمق أحادي العين بالمقياس دون تدريب مسبق. يولّد نموذجنا، Depth Pro، خرائط عمق عالية الدقة مع حدة غير مسبوقة وتفاصيل عالية التردد. التنبؤات مقياسية، ذات مقياس مطلق، دون الاعتماد على توفر بيانات وصفية مثل معاملات الكاميرا الداخلية. كما أن النموذج سريع، إذ ينتج خريطة عمق بدقة 2.25 ميجابكسل في 0.3 ثانية على وحدة معالجة رسومية قياسية. تُمكّن هذه الخصائص من مجموعة من المساهمات التقنية، بما في ذلك محول رؤية متعدد المقاييس فعال للتنبؤ الكثيف، وبروتوكول تدريب يجمع بين مجموعات البيانات الحقيقية والاصطناعية لتحقيق دقة مقياسية عالية إلى جانب تتبع دقيق للحدود، ومؤشرات تقييم مخصصة لدقة الحدود في خرائط العمق المقدّرة، وتقدير طول البؤرة بأحدث التقنيات من صورة واحدة. تحلل التجارب الواسعة اختيارات التصميم المحددة وتُظهر أن Depth Pro يتفوق على الأعمال السابقة على عدة أبعاد.*

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/depth_pro_teaser.png"
alt="drawing" width="600"/>

 مخرجات DepthPro. مأخوذة من الكود الرسمي.

تمت مساهمة هذا النموذج من قِبل [geetu040](https://github.com/geetu040). يمكن العثور على الكود الأصلي [هنا](https://github.com/apple/ml-depth-pro).

## نصائح للاستخدام

يعالج نموذج DepthPro صورة الإدخال أولاً عن طريق تقليل حجمها على مستويات متعددة، ثم تقسيم كل نسخة مُصغّرة إلى رقعات. بعد ذلك، يتم ترميز هذه الرقعات باستخدام مُرمّز رقعات Dinov2 المشترك المبني على Vision Transformer (ViT)، بينما تُعالَج الصورة الكاملة بواسطة مُرمّز صور منفصل. تُدمَج ميزات الرقعات المستخرجة في خرائط الميزات، ثم تُوسَّع، وتُدمج باستخدام مُفكّك يشبه DPT لتوليد تقدير العمق النهائي. إذا تم تفعيله، يعالج مُرمّز مجال الرؤية (FOV) الإضافي الصورة لتقدير مجال رؤية الكاميرا، مما يساعد في دقة العمق.

```python
import requests
import torch
from PIL import Image

from transformers import DepthProForDepthEstimation, DepthProImageProcessor

url = 'http://images.cocodataset.org/val2017/000000039769.jpg'
image = Image.open(requests.get(url, stream=True).raw)

image_processor = DepthProImageProcessor.from_pretrained("apple/DepthPro-hf")
model = DepthProForDepthEstimation.from_pretrained("apple/DepthPro-hf", device_map="auto")

inputs = image_processor(images=image, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

post_processed_output = image_processor.post_process_depth_estimation(
    outputs, target_sizes=[(image.height, image.width)],
)

field_of_view = post_processed_output[0]["field_of_view"]
focal_length = post_processed_output[0]["focal_length"]
depth = post_processed_output[0]["predicted_depth"]
depth = (depth - depth.min()) / depth.max()
depth = depth * 255.
depth = depth.detach().cpu().numpy()
depth = Image.fromarray(depth.astype("uint8"))
```

### البنية والتكوين

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/depth_pro_architecture.png"
alt="drawing" width="600"/>

 بنية DepthPro. مأخوذة من الورقة الأصلية.

يستخدم نموذج `DepthProForDepthEstimation` مُشفِّر `DepthProEncoder` لتشفير الصورة المدخلة، ومرحلة `FeatureFusionStage` لدمج الميزات الناتجة عن المُشفِّر.

يستخدم `DepthProEncoder` بشكل إضافي مشفّرين اثنين:

- `patch_encoder`
  - يتم تحجيم الصورة المدخلة باستخدام عدة نسب، كما هو محدد في إعداد `scaled_images_ratios`.
  - يتم تقسيم كل صورة مُقيّمة إلى **بقع** أصغر بحجم `patch_size` مع تحديد مناطق التداخل بواسطة `scaled_images_overlap_ratios`.
  - تُعالَج هذه البُقع بواسطة **`patch_encoder`**
- `image_encoder`
  - يتم أيضًا إعادة تحجيم الصورة المدخلة إلى `patch_size` ومعالجتها بواسطة **`image_encoder`**

يمكن تكوين كلٍّ من هذين المشفّرين عبر `patch_model_config` و`image_model_config` على التوالي، وكلاهما يمثل `Dinov2Model` منفصلًا افتراضيًا.

تُدمج المخرجات من كلا المشفّرين (`last_hidden_state`) والحالات الوسيطة المحددة (`hidden_states`) من **`patch_encoder`** بواسطة `FeatureFusionStage` مبني على `DPT` لتقدير العمق.

### تنبؤ مجال الرؤية (FOV)

يُكمَّل الشبكة برأس لتقدير البعد البؤري. يستهلك رأس تجميعي صغير ميزات مجمّدة من شبكة تقدير العمق وميزات خاصة بالمهمة من مشفّر صور ViT منفصل، وذلك للتقدير على مجال الرؤية الزاوي الأفقي.

يتحكم معامل `use_fov_model` في `DepthProConfig` فيما إذا كان **تنبؤ FOV** مفعلاً أم لا. افتراضياً، يُضبط على `False` لتوفير الذاكرة والحوسبة. عند التفعيل، يتم إنشاء **مشفّر FOV** بناءً على معامل `fov_model_config`، والذي يكون افتراضياً `Dinov2Model`. كما يمكن تمرير معامل `use_fov_model` عند تهيئة نموذج `DepthProForDepthEstimation`.

يستخدم النموذج المُدرَّب مسبقًا عند نقطة التفتيش `apple/DepthPro-hf` مُشفِّر FOV. لاستخدام النموذج المُدرَّب مسبقًا دون مُشفِّر FOV، اضبط `use_fov_model=False` عند تحميل النموذج، مما يوفر في الحسابات.

```python
from transformers import DepthProForDepthEstimation

model = DepthProForDepthEstimation.from_pretrained("apple/DepthPro-hf", use_fov_model=False, device_map="auto")
```

لإنشاء نموذج جديد بمشفّر FOV، اضبط `use_fov_model=True` في الإعدادات.

```python
from transformers import DepthProConfig, DepthProForDepthEstimation

config = DepthProConfig(use_fov_model=True)
model = DepthProForDepthEstimation(config)
```

أو اضبط `use_fov_model=True` عند تهيئة النموذج، حيث يتجاوز هذا القيمة الموجودة في الإعدادات.

```python
from transformers import DepthProConfig, DepthProForDepthEstimation

config = DepthProConfig()
model = DepthProForDepthEstimation(config, use_fov_model=True)
```

### استخدام الانتباه القياسي بنقطة منتج

يتضمن PyTorch مُشغّلًا أصليًا للانتباه بنقطة جداء مُقيّمة (SDPA) كجزء من `torch.nn.functional`. تشمل هذه الدالة عدة تطبيقات يمكن تطبيقها اعتمادًا على المدخلات والعتاد المستخدم. راجع [التوثيق الرسمي](https://pytorch.org/docs/stable/generated/torch.nn.functional.scaled_dot_product_attention.html) أو صفحة [GPU Inference](https://huggingface.co/docs/transformers/main/en/perf_infer_gpu_one#pytorch-scaled-dot-product-attention) لمزيد من المعلومات.

يُستخدم SDPA افتراضيًا لـ `torch>=2.1.1` عندما تكون هناك نسخة تنفيذية متاحة، لكن يمكنك أيضًا تعيين `attn_implementation="sdpa"` في `from_pretrained()` لطلب استخدام SDPA بشكل صريح.

```python
from transformers import DepthProForDepthEstimation

model = DepthProForDepthEstimation.from_pretrained("apple/DepthPro-hf", attn_implementation="sdpa", device_map="auto")
```

للحصول على أفضل تسارعات، ننصح بتحميل النموذج بدقة نصفية (مثل `torch.float16` أو `torch.bfloat16`).

في معيار محلي (A100-40GB، PyTorch 2.3.0، نظام التشغيل Ubuntu 22.04) باستخدام `float32` ونموذج `google/vit-base-patch16-224`، لاحظنا التسارعات التالية أثناء الاستدلال.

|   حجم الدفعة |   متوسط زمن الاستدلال (مللي ثانية)، وضع العاجل |   متوسط زمن الاستدلال (مللي ثانية)، نموذج sdpa |   تسريع، Sdpa / Eager (x) |
|--------------|-------------------------------------------|-------------------------------------------|------------------------------|
|            1 |                                         7 |                                         6 |                      1.17 |
|            2 |                                         8 |                                         6 |                      1.33 |
|            4 |                                         8 |                                         6 |                      1.33 |
|            8 |                                         8 |                                         6 |                      1.33 |

## الموارد

قائمة بالموارد الرسمية من Hugging Face وموارد المجتمع (المشار إليها بـ 🌎) لمساعدتك على البدء مع DepthPro:

- ورقة البحث: [Depth Pro: Sharp Monocular Metric Depth in Less Than a Second](https://huggingface.co/papers/2410.02073)
- التنفيذ الرسمي: [apple/ml-depth-pro](https://github.com/apple/ml-depth-pro)
- دفتر ملاحظات استنتاج DepthPro: [استنتاج DepthPro](https://github.com/qubvel/transformers-notebooks/blob/main/notebooks/DepthPro_inference.ipynb)
- DepthPro لرفع الدقة وتجزئة الصور
  - اقرأ المدونة على Medium: [Depth Pro: Beyond Depth](https://medium.com/@raoarmaghanshakir040/depth-pro-beyond-depth-9d822fc557ba)
  - الكود على Github: [geetu040/depthpro-beyond-depth](https://github.com/geetu040/depthpro-beyond-depth)

إذا كنت مهتمًا بتقديم مورد ليُدرج هنا، فلا تتردد في فتح طلب سحب وسنقوم بمراجعته! يُفضَّل أن يُظهر المورد شيئًا جديدًا بدلاً من تكرار مورد موجود مسبقًا.

## DepthProConfig[[transformers.DepthProConfig]]

#### transformers.DepthProConfig[[transformers.DepthProConfig]]

```python
transformers.DepthProConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, fusion_hidden_size: int = 256, patch_size: int | list[int] | tuple[int, int] = 384, initializer_range: float = 0.02, intermediate_hook_ids: list[int] | tuple[int, ...] = (11, 5), intermediate_feature_dims: list[int] | tuple[int, ...] = (256, 256), scaled_images_ratios: list[int | float] | tuple[int | float, ...] = (0.25, 0.5, 1), scaled_images_overlap_ratios: list[float] | tuple[float, ...] = (0.0, 0.5, 0.25), scaled_images_feature_dims: list[int] | tuple[int, ...] = (1024, 1024, 512), merge_padding_value: int = 3, use_batch_norm_in_fusion_residual: bool = False, use_bias_in_fusion_residual: bool = True, use_fov_model: bool = False, num_fov_head_layers: int = 2, image_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, patch_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, fov_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/depth_pro/configuration_depth_pro.py#L28)

**المعاملات:**

fusion_hidden_size (`int`، *اختياري*، القيمة الافتراضية 256) : عدد القنوات قبل الدمج.

patch_size (`Union[int, list[int], tuple[int, int]]`، *اختياري*، القيمة الافتراضية `384`) : حجم (دقة) كل رقعة.

initializer_range (`float`، *اختياري*، القيمة الافتراضية `0.02`) : الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان.

intermediate_hook_ids (`list[int]`، *اختياري*، القيمة الافتراضية `[11, 5]`) : فهارس حالات الإخفاء الوسيطة من مُشفِّر الباتش (patch encoder) التي تُستخدم للدمج.

intermediate_feature_dims (`list[int]`، *اختياري*، القيمة الافتراضية `[256, 256]`) : أبعاد حالة الإخفاء أثناء إعادة العينات للأعلى لكل حالة إخفاء وسيطة في `intermediate_hook_ids`.

scaled_images_ratios (`list[float]`، *اختياري*، القيمة الافتراضية `[0.25, 0.5, 1]`) : النسب للصور المُقيَّسة التي سيستخدمها مُشفِّر البُقع.

scaled_images_overlap_ratios (`list[float]`، *اختياري*، القيمة الافتراضية `[0.0, 0.5, 0.25]`) : نسب التداخل بين البقع لكل صورة مُقيَّمة في `scaled_images_ratios`.

scaled_images_feature_dims (`list[int]`، *اختياري*، القيمة الافتراضية `[1024, 1024, 512]`) : أبعاد حالة المخفية أثناء إعادة التصغير (upsampling) لكل صورة مُصعَّدة في `scaled_images_ratios`.

merge_padding_value (`int`، *اختياري*، القيمة الافتراضية 3) : عند دمج البقع الأصغر مرة أخرى إلى حجم الصورة، تُزال الأجزاء المتداخلة بهذا الحجم.

use_batch_norm_in_fusion_residual (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان سيتم استخدام تطبيع الدفعة (batch normalization) في وحدات البقايا قبل التفعيل (pre-activate residual units) داخل كتل الدمج (fusion blocks).

use_bias_in_fusion_residual (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم استخدام الانحياز في وحدات البقايا قبل التفعيل في كتل الدمج.

use_fov_model (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان سيتم استخدام `DepthProFovModel` لتوليد مجال الرؤية.

num_fov_head_layers (`int`، *اختياري*، القيمة الافتراضية 2) : عدد طبقات الالتفاف في رأس `DepthProFovModel`.

image_model_config (`Union[dict[str, Any], PreTrainedConfig]`، *اختياري*) : إعدادات نموذج مُشفِّر الصور، الذي يتم تحميله باستخدام واجهة [AutoModel](/docs/transformers/main/ar/model_doc/auto#transformers.AutoModel). افتراضيًا، يُستخدم نموذج Dinov2 كهيكل أساسي.

patch_model_config (`Union[dict[str, Any], PreTrainedConfig]`، *اختياري*) : إعدادات نموذج مُشفِّر البقع (patch encoder)، الذي يتم تحميله باستخدام واجهة [AutoModel](/docs/transformers/main/ar/model_doc/auto#transformers.AutoModel). افتراضيًا، يُستخدم نموذج Dinov2 كهيكل أساسي (backbone).

fov_model_config (`Union[dict[str, Any], PreTrainedConfig]`، *اختياري*) : إعدادات نموذج مشفّر fov، الذي يتم تحميله باستخدام واجهة [AutoModel](/docs/transformers/main/ar/model_doc/auto#transformers.AutoModel). افتراضيًا، يُستخدم نموذج Dinov2 كهيكل أساسي.

هذه فئة الإعدادات المخزنة لإعدادات نموذج DepthProModel. تُستخدم لاستحداث نموذج Depth Pro وفقًا للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [apple/DepthPro](https://huggingface.co/apple/DepthPro)

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

مثال:

```python
>>> from transformers import DepthProConfig, DepthProModel

>>> # Initializing a DepthPro apple/DepthPro style configuration
>>> configuration = DepthProConfig()

>>> # Initializing a model (with random weights) from the apple/DepthPro style configuration
>>> model = DepthProModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## DepthProImageProcessor[[transformers.DepthProImageProcessor]]

#### transformers.DepthProImageProcessor[[transformers.DepthProImageProcessor]]

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

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/depth_pro/image_processing_depth_pro.py#L45)

**المعاملات:**

do_convert_rgb (`bool`، *kwargs*، *اختياري*) : ما إذا كان يجب تحويل الصورة إلى RGB.

do_resize (`bool`، *kwargs*، *اختياري*، الافتراضي هو `True`) : ما إذا كان سيتم تغيير حجم الصورة.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`، *kwargs*، القيمة الافتراضية `{'height' : 1536, 'width': 1536}`): يصف الأبعاد القصوى للإدخال إلى النموذج.

default_to_square (`bool`، *kwargs*، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب افتراض صورة مربعة عند تغيير الحجم، إذا كان الحجم من نوع عدد صحيح.

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`، *kwargs*) : حجم الصورة الناتجة بعد تطبيق `center_crop`.

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`، *kwargs*، القيمة الافتراضية `2`) : مرشح إعادة العينة المستخدم عند تغيير حجم الصورة. يمكن أن يكون أحد قيم التعداد `PILImageResampling`. لا يؤثر إلا إذا كانت قيمة `do_resize` هي `True`.

do_rescale (`bool`، *kwargs*، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إعادة تحجيم الصورة.

rescale_factor (`float`، *kwargs*، *اختياري*، القيمة الافتراضية هي `0.00392156862745098`) : عامل إعادة التحجيم لإعادة تحجيم الصورة إذا كان `do_rescale` مضبوطاً على `True`.

do_normalize (`bool`، *kwargs*، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم تطبيع الصورة.

image_mean (`Union[float, list[float], tuple[float, ...]]`، *kwargs*، *اختياري*، القيمة الافتراضية هي `[0.5, 0.5, 0.5]`) : متوسط الصورة المستخدم للتطبيع. لا يكون له تأثير إلا إذا تم تعيين `do_normalize` إلى `True`.

image_std (`Union[float, list[float], tuple[float, ...]]`، *kwargs*، *اختياري*، القيمة الافتراضية هي `[0.5, 0.5, 0.5]`) : الانحراف المعياري للصورة المستخدم للتطبيع. لا يكون له أي تأثير إلا إذا تم تعيين `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`: صورة بتنسيق (height, width, num_channels). - `"none"` أو `ChannelDimension.NONE`: صورة بتنسيق (height, width).

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*، *optional*) : عدد رموز الصور المستخدمة لكل صورة في المدخلات. أُضيف للتوافق الرجعي، لكن ينبغي ضبطه كخاصية للمعالج في النماذج المستقبلية. يعيد تينسورات مكدسة إذا ضُبط على `'pt'`، وإلا يعيد قائمة من التينسورات.

disable_grouping (`bool`، *kwargs*، *اختياري*) : ما إذا كان سيتم تعطيل تجميع الصور حسب الحجم لمعالجتها بشكل فردي بدلاً من دفعات. إذا كانت القيمة None، فسيتم تعيينها إلى True إذا كانت الصور على وحدة المعالجة المركزية (CPU)، وإلا فستكون False. تستند هذه الخيارات إلى ملاحظات تجريبية، كما هو موضح هنا: https://github.com/huggingface/transformers/pull/38157

image_seq_length (`int`، *kwargs*، *اختياري*) : عدد رموز الصور التي سيتم استخدامها لكل صورة في المدخلات. أُضيفت لضمان التوافق مع الإصدارات السابقة، لكن ينبغي ضبطها كخاصية للمعالج في النماذج المستقبلية.

يعيد تينسورات مكدسة إذا تم ضبطه على `'pt'`، وإلا يعيد قائمة من التينسورات. --

ينشئ معالج صور DepthPro.

disable_grouping (`bool`، *kwargs*، *اختياري*): هل يتم تعطيل تجميع الصور حسب الحجم لمعالجتها بشكل فردي وليس على شكل دفعات. إذا كانت القيمة None، فسيتم تعيينها إلى True إذا كانت الصور على CPU، وإلا فسيتم تعيينها إلى False. هذا الاختيار مبني على ملاحظات تجريبية، كما هو موضح هنا: https://github.com/huggingface/transformers/pull/38157 image_seq_length (`int`، *kwargs*، *اختياري*): عدد رموز الصور التي سيتم استخدامها لكل صورة في المدخلات. أُضيفت للتوافق مع الإصدارات السابقة، لكن يجب تعيينها كخاصية لـ processor في النماذج المستقبلية.

#### preprocess[[transformers.DepthProImageProcessor.preprocess]]

```python
preprocess(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']], *args, image_like_kwargs: dict[str, typing.Any] | None = None, **kwargs: *<class 'transformers.processing_utils.ImagesKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/image_processing_utils.py#L382)

**المعاملات:**

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]`، *اختياري*) : علم مخصص للمطورين لإدخال مدخلات إضافية تشبه الصور والتي سيتم معالجتها مسبقًا أيضًا. استخدم هذا الخيار فقط إذا لم يعمل تمرير المدخلات كحجة اسمية (kwarg). على سبيل المثال، يُعد `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*) : مرشح إعادة العينة المستخدم عند تغيير حجم الصورة. يمكن أن يكون أحد قيم enum `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`: صورة بتنسيق (height, width, num_channels). - `"none"` أو `ChannelDimension.NONE`: صورة بتنسيق (height, width).

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 عند التهيئة.

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

#### post_process_depth_estimation[[transformers.DepthProImageProcessor.post_process_depth_estimation]]

```python
post_process_depth_estimation(outputs: DepthProDepthEstimatorOutput, target_sizes: transformers.utils.generic.TensorType | list[tuple[int, int]] | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/depth_pro/image_processing_depth_pro.py#L84)

يعالج تنبؤات العمق الخام من النموذج بعد المعالجة.

## DepthProModel[[transformers.DepthProModel]]

#### transformers.DepthProModel[[transformers.DepthProModel]]

```python
transformers.DepthProModel(config: DepthProConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/depth_pro/modeling_depth_pro.py#L624)

**المعاملات:**

config ([DepthProConfig](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

نموذج Depth Pro الأساسي الذي يُخرج حالات مخفية خام دون أي رأس محدد في الأعلى.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.DepthProModel.forward]]

```python
forward(pixel_values: Tensor, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/depth_pro/modeling_depth_pro.py#L636)

**المعاملات:**

pixel_values (`torch.Tensor` من الشكل `(batch_size, num_channels, image_size, image_size)`) : المصفوفات المقابلة لصور الإدخال. يمكن الحصول على قيم البكسل باستخدام [DepthProImageProcessor](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProImageProcessor). راجع [DepthProImageProcessor.__call__()](/docs/transformers/main/ar/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) للتفاصيل (`processor_class` يستخدم [DepthProImageProcessor](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProImageProcessor) لمعالجة الصور).

output_attentions (`bool`، *اختياري*) : ما إذا كان سيتم إرجاع مصفوفات الانتباه لجميع طبقات الانتباه. راجع `attentions` ضمن المصفوفات المُرجعة لمزيد من التفاصيل.

output_hidden_states (`bool`, *اختياري*) : ما إذا كان سيتم إرجاع الحالات المخفية لجميع الطبقات. راجع `hidden_states` ضمن الموترات المُرجعة لمزيد من التفاصيل.

return_dict (`bool`، *اختياري*) : ما إذا كان سيتم إرجاع [ModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.utils.ModelOutput) بدلاً من tuple عادي.

**يعيد:** `DepthProOutput` أو `tuple(torch.Tensor)`

`DepthProOutput` أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([DepthProConfig](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProConfig)) والمدخلات.

تتجاوز طريقة [DepthProModel](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProModel) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

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

- **last_hidden_state** (`torch.Tensor` من الشكل `(batch_size, n_patches_per_batch, sequence_length, hidden_size)`) -- تسلسل من حالات الإخفاء عند مخرج الطبقة الأخيرة من النموذج.
- **الميزات** (`Union[torch.Tensor, List[torch.Tensor]]`، *اختياري*) -- ميزات من المُشفِّرات. يمكن أن تكون ميزة واحدة أو قائمة من الميزات.
- **hidden_states** (`tuple[torch.Tensor, ...]`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) من الشكل `(batch_size, sequence_length, hidden_size)`.

  حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.
- **attentions** (`tuple[torch.Tensor, ...]`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) من الشكل `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

أمثلة:

```python
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoProcessor, DepthProModel

>>> url = "https://www.ilankelman.org/stopsigns/australia.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> checkpoint = "apple/DepthPro-hf"
>>> processor = AutoProcessor.from_pretrained(checkpoint)
>>> model = DepthProModel.from_pretrained(checkpoint)

>>> # prepare image for the model
>>> inputs = processor(images=image, return_tensors="pt")

>>> with torch.no_grad():
...     output = model(**inputs)

>>> output.last_hidden_state.shape
torch.Size([1, 35, 577, 1024])
```

## DepthProForDepthEstimation[[transformers.DepthProForDepthEstimation]]

#### transformers.DepthProForDepthEstimation[[transformers.DepthProForDepthEstimation]]

```python
transformers.DepthProForDepthEstimation(config: DepthProConfig, use_fov_model = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/depth_pro/modeling_depth_pro.py#L995)

**المعاملات:**

config ([DepthProConfig](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

use_fov_model (`bool`، *اختياري*) : ما إذا كان سيتم استخدام نموذج مجال الرؤية.

نموذج DepthPro مع رأس لتقدير العمق في الأعلى (يتكون من 3 طبقات تلافيفية).

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.DepthProForDepthEstimation.forward]]

```python
forward(pixel_values: Tensor, labels: typing.Optional[torch.LongTensor] = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/depth_pro/modeling_depth_pro.py#L1020)

**المعاملات:**

pixel_values (`torch.Tensor` من الشكل `(batch_size, num_channels, image_size, image_size)`) : المصفوفات المقابلة لصور الإدخال. يمكن الحصول على قيم البكسل باستخدام [DepthProImageProcessor](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProImageProcessor). راجع [DepthProImageProcessor.__call__()](/docs/transformers/main/ar/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) للتفاصيل (`processor_class` يستخدم [DepthProImageProcessor](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProImageProcessor) لمعالجة الصور).

labels (`torch.LongTensor` من الشكل `(batch_size, height, width)`، *اختياري*) : خرائط تقدير العمق الصحيحة (Ground truth) لحساب الخسارة.

output_attentions (`bool`، *اختياري*) : ما إذا كان سيتم إرجاع مصفوفات الانتباه لجميع طبقات الانتباه. راجع `attentions` ضمن المصفوفات المُرجعة لمزيد من التفاصيل.

output_hidden_states (`bool`, *اختياري*) : ما إذا كان سيتم إرجاع الحالات المخفية لجميع الطبقات. راجع `hidden_states` ضمن الموترات المُرجعة لمزيد من التفاصيل.

return_dict (`bool`، *اختياري*) : ما إذا كان سيتم إرجاع [ModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.utils.ModelOutput) بدلاً من tuple عادي.

**يعيد:** `DepthProDepthEstimatorOutput` أو `tuple(torch.Tensor)`

`DepthProDepthEstimatorOutput` أو مجموعة (tuple) من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([DepthProConfig](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProConfig)) والمدخلات.

تتجاوز طريقة [DepthProForDepthEstimation](/docs/transformers/main/ar/model_doc/depth_pro#transformers.DepthProForDepthEstimation) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

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

- **loss** (`torch.Tensor` من الشكل `(1,)`, *اختياري*، يُعاد عند تقديم `labels`) -- خسارة التصنيف (أو الانحدار إذا كان config.num_labels==1).
- **predicted_depth** (`torch.Tensor` من الشكل `(batch_size, height, width)`، *اختياري*) -- العمق المتوقع لكل بكسل.
- **field_of_view** (`torch.Tensor` من الشكل `(batch_size,)`، *اختياري*، يُعاد عند تقديم `use_fov_model`) -- مُقيِّم مجال الرؤية.
- **hidden_states** (`tuple[torch.Tensor, ...]`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) من الشكل `(batch_size, sequence_length, hidden_size)`.

  حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.
- **attentions** (`tuple[torch.Tensor, ...]`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) من الشكل `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

أمثلة:

```python
>>> from transformers import AutoImageProcessor, DepthProForDepthEstimation
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> checkpoint = "apple/DepthPro-hf"
>>> processor = AutoImageProcessor.from_pretrained(checkpoint)
>>> model = DepthProForDepthEstimation.from_pretrained(checkpoint)

>>> device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
>>> model.to(device)

>>> # prepare image for the model
>>> inputs = processor(images=image, return_tensors="pt").to(device)

>>> with torch.no_grad():
...     outputs = model(**inputs)

>>> # interpolate to original size
>>> post_processed_output = processor.post_process_depth_estimation(
...     outputs, target_sizes=[(image.height, image.width)],
... )

>>> # get the field of view (fov) predictions
>>> field_of_view = post_processed_output[0]["field_of_view"]
>>> focal_length = post_processed_output[0]["focal_length"]

>>> # visualize the prediction
>>> predicted_depth = post_processed_output[0]["predicted_depth"]
>>> depth = predicted_depth * 255 / predicted_depth.max()
>>> depth = depth.detach().cpu().numpy()
>>> depth = Image.fromarray(depth.astype("uint8"))
```