# SAM-HQ

## نظرة عامة

قُدِّم نموذج SAM-HQ (نموذج Segment Anything عالي الجودة) في [Segment Anything in High Quality](https://huggingface.co/papers/2306.01567) بواسطة Lei Ke وMingqiao Ye وMartin Danelljan وYifan Liu وYu-Wing Tai وChi-Keung Tang وFisher Yu.

يُعدّ النموذج تحسينًا للنموذج الأصلي SAM، إذ ينتج أقنعة تجزئة بجودة أعلى بكثير مع الحفاظ على التصميم الأصلي القابل للتوجيه في SAM، وكفاءته، وقدرته على التعميم دون تدريب مسبق.

![example image](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-output.png)

يُقدّم SAM-HQ عدة تحسينات رئيسية مقارنةً بنموذج SAM الأصلي:

1. رمز إخراج عالي الجودة: رمز قابل للتعلّم يُحقن في مُفكّك الأقنعة الخاص بـ SAM لتحسين جودة تنبؤ الأقنعة
2. دمج الميزات المحلية والعالمية: يجمع بين الميزات من مراحل مختلفة من النموذج لتحسين تفاصيل الأقنعة
3. بيانات التدريب: يستخدم مجموعة بيانات مُنتقاة بعناية تتكون من 44 ألف قناع عالي الجودة بدلاً من SA-1B
4. الكفاءة: يضيف 0.5% فقط من المعاملات الإضافية مع تحسين كبير لجودة الأقنعة
5. Zero-shot Capability: Maintains SAM's strong zero-shot performance while improving accuracy

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

*يمثل نموذج Segment Anything Model (SAM) الحديث قفزة كبيرة في توسيع نطاق نماذج التقطيع، مما يتيح قدرات قوية بدون تدريب مسبق (zero-shot) وتوجيهًا مرنًا. وعلى الرغم من تدريبه باستخدام 1.1 مليار قناع، فإن جودة تنبؤات الأقنعة في SAM لا تزال غير كافية في كثير من الحالات، لا سيما عند التعامل مع كائنات ذات هياكل معقدة. نقترح HQ-SAM، الذي يزوّد SAM بالقدرة على تقطيع أي كائن بدقة، مع الحفاظ على التصميم الأصلي القابل للتوجيه في SAM وكفاءته وقابليته للتعميم بدون تدريب مسبق. يعيد تصميمنا الدقيق استخدام أوزان النموذج المُدرَّب مسبقًا في SAM والحفاظ عليها، مع إدخال معاملات وحسابات إضافية ضئيلة فقط. صممنا رمزًا قابلًا للتعلم للمخرجات عالية الجودة (High-Quality Output Token)، يُحقن في مُفكّك الأقنعة (mask decoder) في SAM وهو المسؤول عن تنبؤ القناع عالي الجودة. وبدلًا من تطبيقه على ميزات مُفكّك الأقنعة فقط، ندمجها أولًا مع ميزات ViT المبكرة والنهائية لتحسين تفاصيل الأقنعة. ولتدريب المعاملات القابلة للتعلم التي قدمناها، قمنا بتكوين مجموعة بيانات تضم 44 ألف قناع دقيق من مصادر متعددة. يُدرَّب HQ-SAM فقط على مجموعة البيانات المقدمة المكونة من 44 ألف قناع، ويستغرق ذلك 4 ساعات فقط على 8 وحدات معالجة رسومية (GPUs).*

نصائح:

- ينتج SAM-HQ أقنعة بجودة أعلى من نموذج SAM الأصلي، لا سيما في حالة الكائنات ذات الهياكل المعقدة والتفاصيل الدقيقة
- يتنبأ النموذج بأقنعة ثنائية ذات حدود أكثر دقة ومعالجة أفضل للبنى الدقيقة
- كما هو الحال مع SAM، يؤدي النموذج أداءً أفضل عند استخدام نقاط ثنائية الأبعاد كمدخلات و/أو صناديق تحديد كمدخلات
- يمكنك إدخال عدة نقاط لنفس الصورة والتنبؤ بقناع واحد عالي الجودة
- يحافظ النموذج على قدرات SAM في التعميم بدون تدريب مسبق
- يضيف SAM-HQ حوالي 0.5% من المعاملات الإضافية مقارنةً بـ SAM
- لا يُدعَم ضبط النموذج الدقيق بعد

تمت مساهمة هذا النموذج من قِبل [sushmanth](https://huggingface.co/sushmanth). يمكن العثور على الكود الأصلي [هنا](https://github.com/SysCV/SAM-HQ).

فيما يلي مثال على كيفية تشغيل توليد الأقنعة بناءً على صورة ونقطة ثنائية الأبعاد:

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

from transformers import SamHQModel, SamHQProcessor

model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores
```

يمكنك أيضًا معالجة أقنعتك الخاصة جنبًا إلى جنب مع الصور المدخلة في المعالج لتُمرَّر إلى النموذج:

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

from transformers import SamHQModel, SamHQProcessor

model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
mask_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
segmentation_map = Image.open(requests.get(mask_url, stream=True).raw).convert("1")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, segmentation_maps=segmentation_map, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores
```

## الموارد

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

- دفتر ملاحظات تجريبي لاستخدام النموذج (قريباً)
- تنفيذ الورقة والكود: [مستودع SAM-HQ على GitHub](https://github.com/SysCV/SAM-HQ)

## SamHQConfig[[transformers.SamHQConfig]]

#### transformers.SamHQConfig[[transformers.SamHQConfig]]

```python
transformers.SamHQConfig(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, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, prompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, mask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02, tie_word_embeddings: bool = True)
```

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

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

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`، *اختياري*) : كائن الإعداد أو قاموس العمود الفقري البصري.

prompt_encoder_config (Union[`dict`, `SamHQPromptEncoderConfig`], *اختياري*) : قاموس لخيارات التهيئة المستخدمة لتبني [SamHQPromptEncoderConfig](/docs/transformers/main/ar/model_doc/sam_hq#transformers.SamHQPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `SamHQMaskDecoderConfig`], *اختياري*) : قاموس لخيارات التهيئة المستخدمة لتبني [SamHQMaskDecoderConfig](/docs/transformers/main/ar/model_doc/sam_hq#transformers.SamHQMaskDecoderConfig).

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

tie_word_embeddings (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب ربط ترميزات الأوزان وفقاً لخريطة `tied_weights_keys` الخاصة بالنموذج.

هذه فئة الإعدادات المخزنة لإعدادات نموذج SamHQModel. تُستخدم لاستحداث نموذج Sam Hq وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

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

## SamHQVisionConfig[[transformers.SamHQVisionConfig]]

#### transformers.SamHQVisionConfig[[transformers.SamHQVisionConfig]]

```python
transformers.SamHQVisionConfig(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, hidden_size: int = 768, output_channels: int = 256, num_hidden_layers: int = 12, num_attention_heads: int = 12, num_channels: int = 3, image_size: int | list[int] | tuple[int, int] = 1024, patch_size: int | list[int] | tuple[int, int] = 16, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, attention_dropout: float | int = 0.0, initializer_range: float = 1e-10, qkv_bias: bool = True, mlp_ratio: float = 4.0, use_abs_pos: bool = True, use_rel_pos: bool = True, window_size: int = 14, global_attn_indexes: list[int] | tuple[int, ...] = (2, 5, 8, 11), num_pos_feats: int = 128, mlp_dim: int | None = None)
```

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

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

hidden_size (`int`، *اختياري*، القيمة الافتراضية `768`) : بُعد التمثيلات المخفية.

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

num_hidden_layers (`int`، *اختياري*، القيمة الافتراضية `12`) : عدد الطبقات المخفية في مُفكِّك Transformer.

num_attention_heads (`int`، *اختياري*، القيمة الافتراضية `12`) : عدد رؤوس الانتباه في كل طبقة انتباه داخل مُفكِّك Transformer.

num_channels (`int`، *اختياري*، القيمة الافتراضية `3`) : عدد قنوات الإدخال.

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

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

hidden_act (`str`، *اختياري*، القيمة الافتراضية `gelu`) : دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال، `"gelu"`، `"relu"`، `"silu"`، وما إلى ذلك.

layer_norm_eps (`float`, *اختياري*, الافتراضي هو `1e-06`) : قيمة إيبسلون المستخدمة في طبقات تطبيع الطبقة.

attention_dropout (`Union[float, int]`، *اختياري*، القيمة الافتراضية `0.0`) : نسبة الإسقاط (dropout) لاحتمالات الانتباه.

initializer_range (`float`, *اختياري*, القيمة الافتراضية `1e-10`) : انحراف المعيار لـ truncated_normal_initializer لتهيئة جميع مصفوفات الأوزان.

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

mlp_ratio (`float`، *اختياري*، القيمة الافتراضية `4.0`) : نسبة بُعد MLP المخفي إلى بُعد التضمين.

use_abs_pos (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم استخدام تضمينات الموضع المطلق.

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

window_size (`int`، *اختياري*، القيمة الافتراضية 14) : حجم النافذة للموضع النسبي.

global_attn_indexes (`list[int]`، *اختياري*، القيمة الافتراضية `[2, 5, 8, 11]`) : فهارس طبقات الانتباه الشامل.

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

mlp_dim (`int`, *اختياري*) : بُعد طبقة MLP في مُشفِّر Transformer. إذا كان `None`، فإن القيمة الافتراضية هي `mlp_ratio * hidden_size`.

هذه فئة الإعدادات المخزنة لإعدادات نموذج SamHQModel. تُستخدم لاستحداث نموذج Sam Hq وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

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

مثال:

```python
>>> from transformers import (
...     SamHQVisionConfig,
...     SamHQVisionModel,
... )

>>> # Initializing a SamHQVisionConfig with `"facebook/sam_hq-vit-huge"` style configuration
>>> configuration = SamHQVisionConfig()

>>> # Initializing a SamHQVisionModel (with random weights) from the `"facebook/sam_hq-vit-huge"` style configuration
>>> model = SamHQVisionModel(configuration)

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

## SamHQMaskDecoderConfig[[transformers.SamHQMaskDecoderConfig]]

#### transformers.SamHQMaskDecoderConfig[[transformers.SamHQMaskDecoderConfig]]

```python
transformers.SamHQMaskDecoderConfig(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, hidden_size: int = 256, hidden_act: str = 'relu', mlp_dim: int = 2048, num_hidden_layers: int = 2, num_attention_heads: int = 8, attention_downsample_rate: int = 2, num_multimask_outputs: int = 3, iou_head_depth: int = 3, iou_head_hidden_dim: int = 256, layer_norm_eps: float = 1e-06, vit_dim: int = 768)
```

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

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

hidden_size (`int`، *اختياري*، القيمة الافتراضية `256`) : بُعد التمثيلات المخفية.

hidden_act (`str`، *اختياري*، الافتراضي هو `relu`) : دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال، `"gelu"`، `"relu"`، `"silu"`، وغيرها.

mlp_dim (`int`، *اختياري*، القيمة الافتراضية 2048) : بُعد طبقة "الوسط" (أي طبقة التغذية الأمامية) في مُشفِّر Transformer.

num_hidden_layers (`int`، *اختياري*، الافتراضي `2`) : عدد الطبقات المخفية في مفكّك Transformer.

num_attention_heads (`int`، *اختياري*، القيمة الافتراضية `8`) : عدد رؤوس الانتباه في كل طبقة انتباه داخل مُفكِّك Transformer.

attention_downsample_rate (`int`، *اختياري*، القيمة الافتراضية 2) : معدل تقليل حجم طبقة الانتباه.

num_multimask_outputs (`int`، *اختياري*، القيمة الافتراضية 3) : عدد المخرجات من وحدة `SamMaskDecoder`. في ورقة Segment Anything، يتم ضبط هذا على 3.

iou_head_depth (`int`، *اختياري*، القيمة الافتراضية 3) : عدد الطبقات في وحدة رأس IoU.

iou_head_hidden_dim (`int`، *اختياري*، القيمة الافتراضية 256) : بُعد حالات الإخفاء في وحدة رأس IoU.

layer_norm_eps (`float`, *اختياري*, الافتراضي هو `1e-06`) : قيمة إيبسلون المستخدمة في طبقات تطبيع الطبقة.

vit_dim (`int`، *اختياري*، القيمة الافتراضية 768) : بُعد Vision Transformer (ViT) المستخدم في وحدة `SamHQMaskDecoder`.

هذه فئة الإعدادات المخزنة لإعدادات نموذج SamHQModel. تُستخدم لاستحداث نموذج Sam Hq وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

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

## SamHQPromptEncoderConfig[[transformers.SamHQPromptEncoderConfig]]

#### transformers.SamHQPromptEncoderConfig[[transformers.SamHQPromptEncoderConfig]]

```python
transformers.SamHQPromptEncoderConfig(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, hidden_size: int = 256, image_size: int | list[int] | tuple[int, int] = 1024, patch_size: int | list[int] | tuple[int, int] = 16, mask_input_channels: int = 16, num_point_embeddings: int = 4, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06)
```

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

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

hidden_size (`int`، *اختياري*، القيمة الافتراضية `256`) : بُعد التمثيلات المخفية.

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

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

mask_input_channels (`int`، *اختياري*، القيمة الافتراضية 16) : عدد القنوات التي تُمرَّر إلى وحدة `MaskDecoder`.

num_point_embeddings (`int`، *اختياري*، القيمة الافتراضية 4) : عدد تضمينات النقاط التي سيتم استخدامها.

hidden_act (`str`، *اختياري*، القيمة الافتراضية `gelu`) : دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال، `"gelu"`، `"relu"`، `"silu"`، وما إلى ذلك.

layer_norm_eps (`float`, *اختياري*, الافتراضي هو `1e-06`) : قيمة إيبسلون المستخدمة في طبقات تطبيع الطبقة.

هذه فئة الإعدادات المخزنة لإعدادات نموذج SamHQModel. تُستخدم لاستحداث نموذج Sam Hq وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

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

## SamHQProcessor[[transformers.SamHQProcessor]]

#### transformers.SamHQProcessor[[transformers.SamHQProcessor]]

```python
transformers.SamHQProcessor(image_processor)
```

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

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

image_processor (`SamImageProcessor`) : مُعالج الصور هو مدخل مطلوب.

ينشئ SamHQProcessor الذي يغلّف معالج الصور في معالج واحد.

يوفر [SamHQProcessor](/docs/transformers/main/ar/model_doc/sam_hq#transformers.SamHQProcessor) جميع وظائف [SamImageProcessor](/docs/transformers/main/ar/model_doc/sam#transformers.SamImageProcessor). راجع [~SamImageProcessor](/docs/transformers/main/ar/model_doc/sam#transformers.SamImageProcessor) لمزيد من المعلومات.

#### __call__[[transformers.SamHQProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, **kwargs: *<class 'transformers.models.sam_hq.processing_sam_hq.SamHQProcessorKwargs'>)
```

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

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

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`.

segmentation_maps (`ImageInput`، *kwargs*، *اختياري*) : خرائط التقسيم الصحيحة (Ground truth) التي تتم معالجتها بالتوازي مع الصور المدخلة. تُستخدم هذه الخرائط لأغراض التدريب أو التقييم، وتُعاد مقاساتها وتُطبع (normalized) لتتطابق مع أبعاد الصورة المعالجة.

input_points (`NestedList`، *kwargs*، *اختياري*) : نقاط الإدخال للتجزئة القائمة على الأوامر النصية. يجب أن تكون قائمة متداخلة بهيكل `[image_level, object_level, point_level, [x, y]]` حيث يُحدَّد كل نقطة بإحداثيات `[x, y]` في مساحة الصورة الأصلية. تُطبَّع النقاط إلى حجم الصورة المستهدفة قبل تمريرها إلى النموذج.

input_labels (`NestedList`، *kwargs*، *اختياري*) : تسميات لنقاط الإدخال، تُظهر ما إذا كانت كل نقطة من نقاط المقدمة (1) أو الخلفية (0). يجب أن تكون قائمة متداخلة بهيكل `[image_level, object_level, point_level]`. يجب أن يكون لها نفس هيكل `input_points` (باستبعاد بُعد الإحداثيات).

input_boxes (`NestedList`، *kwargs*، *اختياري*) : صناديق الحدود للتجزئة القائمة على الأوامر. يجب أن تكون قائمة متداخلة بهيكل `[image_level, box_level, [x1, y1, x2, y2]]` حيث يُحدد كل صندوق بإحداثيات `[x1, y1, x2, y2]` في مساحة الصورة الأصلية. يتم تطبيع الصناديق إلى حجم الصورة المستهدفة قبل تمريرها إلى النموذج.

point_pad_value (`int`, *kwargs*, *اختياري*، القيمة الافتراضية `None`) : القيمة المستخدمة لحشو نقاط الإدخال عند تجميع تسلسلات بطول مختلف. تُميّز هذه القيمة المواضع المحشوة وتُحافظ عليها أثناء تطبيع الإحداثيات للتمييز بين النقاط الحقيقية والحشو. إذا كانت `None`، تُستخدم قيمة الحشو الافتراضية من إعدادات المعالج.

mask_size (`dict[str, *kwargs*, int]`، *اختياري*) : قاموس يحدد حجم القناع المستهدف بمفاتيح `"height"` و`"width"`. يحدد هذا دقة أقنعة التقطيع الناتجة التي يولدها النموذج.

mask_pad_size (`dict[str, *kwargs*, int]`، *اختياري*) : قاموس يحدد حجم الحشو للقناع بمفاتيح `"height"` و`"width"`. يُستخدم هذا عند تجميع أقنعة بأحجام مختلفة لضمان أبعاد متسقة.

return_tensors (`str` أو [TensorType](/docs/transformers/main/ar/internal/file_utils#transformers.TensorType)، *اختياري*) : إذا تم تعيينه، فسيُرجع تينسورات من إطار عمل محدد. القيم المقبولة هي:  - `'pt'`: يُرجع كائنات `torch.Tensor` من PyTorch. - `'np'`: يُرجع كائنات `np.ndarray` من NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/ar/main_classes/processors#transformers.ProcessingKwargs)، *اختياري*) : خيارات معالجة إضافية لكل نمط (نص، صور، مقاطع فيديو، صوت). تُدرج المعلمات الخاصة بالنموذج أعلاه؛ راجع فئة TypedDict للحصول على القائمة الكاملة للحجج المدعومة.

**يعيد:** `~feature_extraction_utils.BatchFeature`

- **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`.

## SamHQVisionModel[[transformers.SamHQVisionModel]]

#### transformers.SamHQVisionModel[[transformers.SamHQVisionModel]]

```python
transformers.SamHQVisionModel(config: SamHQVisionConfig)
```

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

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

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

نموذج الرؤية من SamHQ دون أي رأس أو إسقاط في الأعلى.

يرث هذا النموذج من [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.SamHQVisionModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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

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

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

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

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

- **image_embeds** (`torch.Tensor` بأبعاد `(batch_size, output_dim)` *اختياري* يُعاد عند تهيئة النموذج مع `with_projection=True`) -- تضمينات الصور المُستخرجة بتطبيق طبقة الإسقاط على pooler_output.
- **last_hidden_state** (`torch.Tensor` بأبعاد `(batch_size, sequence_length, hidden_size)`، *اختياري*) -- تسلسل من الحالات المخفية عند مخرجات الطبقة الأخيرة من النموذج.
- **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 على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
- **intermediate_embeddings** (`list(torch.Tensor)`، *اختياري*) -- قائمة بتضمينات وسيطة تم جمعها من بعض الكتل داخل النموذج، وعادةً ما تكون تلك التي لا تستخدم الانتباه النافذي (windowed attention). كل عنصر في القائمة له الشكل `(batch_size, sequence_length, hidden_size)`. هذا الأمر خاص بـ SAM-HQ وغير موجود في SAM الأساسي.

## SamHQModel[[transformers.SamHQModel]]

#### transformers.SamHQModel[[transformers.SamHQModel]]

```python
transformers.SamHQModel(config: SamHQConfig)
```

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

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

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

نموذج Segment Anything Model HQ (SAM-HQ) لتوليد الأقنعة، بناءً على صورة مدخلة ومواقع ثنائية الأبعاد اختيارية ومربعات محيطة.

يرث هذا النموذج من [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.SamHQModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, input_points: typing.Optional[torch.Tensor] = None, input_labels: typing.Optional[torch.LongTensor] = None, input_boxes: typing.Optional[torch.Tensor] = None, input_masks: typing.Optional[torch.LongTensor] = None, image_embeddings: typing.Optional[torch.Tensor] = None, multimask_output: bool = True, hq_token_only: bool = False, attention_similarity: typing.Optional[torch.Tensor] = None, target_embedding: typing.Optional[torch.Tensor] = None, intermediate_embeddings: list[torch.Tensor] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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

input_points (`torch.Tensor` من الشكل `(batch_size, num_points, 2)`) : نقاط مكانية ثنائية الأبعاد مدخلة، تُستخدم بواسطة مُشفّر المُوجِّه (prompt encoder) لتشفير المُوجِّه. عادةً ما يؤدي ذلك إلى نتائج أفضل بكثير. يمكن الحصول على النقاط عن طريق تمرير قائمة من قوائم القوائم إلى المُعالِج (processor) الذي سيُنشئ `torch` tensors المقابلة من البُعد الرابع. البُعد الأول هو حجم دفعة الصور (image batch size)، والبُعد الثاني هو حجم دفعة النقاط (point batch size) (أي عدد أقنعة التقطيع (segmentation masks) التي نريد من النموذج أن يتنبأ بها لكل نقطة مدخلة)، والبُعد الثالث هو عدد النقاط لكل قناع تقطيع (من الممكن تمرير عدة نقاط لقناع واحد)، وآخر بُعد هو إحداثيات x (العمودية) و y (الأفقية) للنقطة. إذا تم تمرير عدد مختلف من النقاط إما لكل صورة، أو لكل قناع، فسيقوم المُعالِج بإنشاء نقاط "PAD" ستُطابق إحداثي (0, 0)، وسيتم تخطي حساب التضمين (embedding) لهذه النقاط باستخدام التسميات (labels).

input_labels (`torch.LongTensor` من الشكل `(batch_size, point_batch_size, num_points)`) : تسميات الإدخال للنقاط، تُستخدم هذه التسميات بواسطة مُشفِّر المُوجِّه (prompt encoder) لتشفير المُوجِّه. وفقًا للتنفيذ الرسمي، توجد 3 أنواع من التسميات - `1`: النقطة هي نقطة تحتوي على الكائن محل الاهتمام - `0`: النقطة هي نقطة لا تحتوي على الكائن محل الاهتمام - `-1`: النقطة تتوافق مع الخلفية  أضفنا التسمية: - `-10`: النقطة هي نقطة حشو (padding)، وبالتالي يجب أن يتجاهلها مُشفِّر المُوجِّه  يجب أن تتم تسميات الحشو تلقائيًا بواسطة المعالج (processor).

input_boxes (`torch.Tensor` من الشكل `(batch_size, num_boxes, 4)`) : صناديق الإدخال للنقاط، تُستخدم هذه الصناديق بواسطة مُشفِّر المُوجِّه (prompt encoder) لتشفير المُوجِّه. بشكل عام، يؤدي ذلك إلى أقنعة (masks) مولَّدة أفضل بكثير. يمكن الحصول على الصناديق عن طريق تمرير قائمة من قوائم القوائم إلى المُعالِج (processor)، والذي سيولّد مُتجه `torch`، حيث يتوافق كل بُعد على التوالي مع حجم دفعة الصور (image batch size)، وعدد الصناديق لكل صورة، وإحداثيات النقطة العلوية اليسرى والنقطة السفلية اليمنى للصندوق. بالترتيب (`x1`، `y1`، `x2`، `y2`): - `x1`: إحداثي x للنقطة العلوية اليسرى من صندوق الإدخال - `y1`: إحداثي y للنقطة العلوية اليسرى من صندوق الإدخال - `x2`: إحداثي x للنقطة السفلية اليمنى من صندوق الإدخال - `y2`: إحداثي y للنقطة السفلية اليمنى من صندوق الإدخال

input_masks (`torch.Tensor` من الشكل `(batch_size, image_size, image_size)`) : يقبل نموذج SAM_HQ أيضًا أقنعة التقسيم كمدخلات. سيتم تضمين القناع بواسطة مُشفِّر المُوجِّه لتوليد تضمين مطابق، سيُغذَّى لاحقًا إلى مُفكِّك الأقنعة. يجب على المستخدم تغذية هذه الأقنعة يدويًا، ويجب أن تكون من الشكل (`batch_size`، `image_size`، `image_size`).

image_embeddings (`torch.Tensor` من الشكل `(batch_size, output_channels, window_size, window_size)`) : تمثيلات الصور، تُستخدم من قِبَل مُفكّك الأقنعة لتوليد الأقنعة ودرجات iou. لحساب أكثر كفاءة في استخدام الذاكرة، يمكن للمستخدمين أولاً استرجاع تمثيلات الصور باستخدام طريقة `get_image_embeddings`، ثم تمريرها إلى طريقة `forward` بدلاً من تمرير `pixel_values`.

multimask_output (`bool`، *اختياري*) : في التنفيذ الأصلي والورقة البحثية، يُخرج النموذج دائمًا 3 أقنعة لكل صورة (أو لكل نقطة / لكل صندوق حدودي عند الاقتضاء). ومع ذلك، يمكن إخراج قناع واحد فقط، يتوافق مع "أفضل" قناع، عن طريق تحديد `multimask_output=False`.

hq_token_only (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب استخدام مسار رمز HQ فقط لتوليد الأقنعة. عند تعيينه إلى False، يتم دمج كلا المسارين القياسي وHQ. هذا الأمر خاص ببنية SAM-HQ.

attention_similarity (`torch.Tensor`، *اختياري*) : متجه تشابه الانتباه، يُقدَّم إلى مُفكّك الأقنعة (mask decoder) للانتباه الموجَّه بالهدف في حال استخدام النموذج للتخصيص كما طُرح في [PerSAM](https://huggingface.co/papers/2305.03048).

target_embedding (`torch.Tensor`، *اختياري*) : تمثيل (Embedding) للمفهوم المستهدف، يُقدَّم إلى فك الترميز (mask decoder) للتلميح الدلالي المستهدف في حال استخدام النموذج للتخصيص كما تم تقديمه في [PerSAM](https://huggingface.co/papers/2305.03048).

intermediate_embeddings (`List[torch.Tensor]`، *اختياري*) : تمثيلات وسيطة من الكتل غير النافذية لمشفّر الرؤية، تُستخدم في SAM-HQ لتحسين جودة الأقنعة. مطلوب عند تقديم image_embeddings محسوبة مسبقًا بدلاً من pixel_values.

**يعيد:**

`list[dict[str, torch.Tensor]]`

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

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

مثال:

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

>>> model = AutoModel.from_pretrained("sushmanth/sam_hq_vit_b")
>>> processor = AutoProcessor.from_pretrained("sushmanth/sam_hq_vit_b")

>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read())).convert("RGB")
>>> input_points = [[[400, 650]]]  # 2D location of a window on the car
>>> inputs = processor(images=image, input_points=input_points, return_tensors="pt")

>>> # Get high-quality segmentation mask
>>> outputs = model(**inputs)

>>> # For high-quality mask only
>>> outputs = model(**inputs, hq_token_only=True)

>>> # Postprocess masks
>>> masks = processor.post_process_masks(
...     outputs.pred_masks, inputs["original_sizes"], inputs["reshaped_input_sizes"]
... )
```