# Shap-E

قُدِّم نموذج Shap-E في [Shap-E: Generating Conditional 3D Implicit Functions](https://huggingface.co/papers/2305.02463) بواسطة Alex Nichol وHeewoo Jun من [OpenAI](https://github.com/openai).

ملخص الورقة البحثية هو:

*نقدّم Shap-E، وهو نموذج توليدي مشروط للأصول ثلاثية الأبعاد. على عكس الأعمال الحديثة في نماذج التوليد ثلاثي الأبعاد التي تنتج تمثيلاً واحداً للمخرجات، يولّد Shap-E بشكل مباشر معاملات الدوال الضمنية التي يمكن عرضها كلوحات شبكية مُنمّطة ومجالات إشعاعية عصبية. ندرّب Shap-E في مرحلتين: أولاً، ندرّب مُشفِّراً يُحوّل الأصول ثلاثية الأبعاد بشكل حتمي إلى معاملات دالة ضمنية؛ ثانياً، ندرّب نموذج انتشار مشروط على مخرجات المُشفِّر. عند التدريب على مجموعة بيانات كبيرة من البيانات النصية والأصول ثلاثية الأبعاد المقترنة، تكون النماذج الناتجة قادرة على توليد أصول ثلاثية الأبعاد معقدة ومتنوعة في غضون ثوانٍ. عند المقارنة مع Point-E، وهو نموذج توليدي صريح فوق سحاب النقاط، يتقارب Shap-E بشكل أسرع ويصل إلى جودة عينات مماثلة أو أفضل على الرغم من نمذجة فضاء مخرجات أعلى الأبعاد ومتعدد التمثيلات.*

يمكن العثور على قاعدة الكود الأصلية في [openai/shap-e](https://github.com/openai/shap-e).

> [!TIP]
> راجع قسم [إعادة استخدام المكونات عبر خطوط الأنابيب](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.

تأكد من تثبيت المكتبات التالية.

```py
# uncomment to install the necessary libraries in Colab
#!pip install -q diffusers transformers accelerate trimesh
```

## النص إلى ثلاثي الأبعاد

لتوليد ملف gif لجسم ثلاثي الأبعاد، مرّر موجهًا نصيًا إلى [ShapEPipeline](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.ShapEPipeline). يقوم خط الأنابيب بتوليد قائمة من إطارات الصور التي تُستخدم لإنشاء الجسم ثلاثي الأبعاد.

```py
import torch
from diffusers import ShapEPipeline

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

pipe = ShapEPipeline.from_pretrained("openai/shap-e", dtype=torch.float16, variant="fp16")
pipe = pipe.to(device)

guidance_scale = 15.0
prompt = ["A firecracker", "A birthday cupcake"]

images = pipe(
    prompt,
    guidance_scale=guidance_scale,
    num_inference_steps=64,
    frame_size=256,
).images
```

الآن استخدم دالة [export_to_gif()](/docs/diffusers/main/ar/api/utilities#diffusers.utils.export_to_gif) لتحويل قائمة إطارات الصور إلى ملف gif للكائن ثلاثي الأبعاد.

```py
from diffusers.utils import export_to_gif

export_to_gif(images[0], "firecracker_3d.gif")
export_to_gif(images[1], "cake_3d.gif")
```

  
    
    prompt = "A firecracker"
  
  
    
    prompt = "A birthday cupcake"
  

## من الصورة إلى ثلاثية الأبعاد

لإنشاء كائن ثلاثي الأبعاد من صورة أخرى، استخدم [ShapEImg2ImgPipeline](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline). يمكنك استخدام صورة موجودة أو توليد صورة جديدة بالكامل. دعنا نستخدم نموذج [Kandinsky 2.1](./kandinsky) لتوليد صورة جديدة.

```py
from diffusers import DiffusionPipeline
import torch

prior_pipeline = DiffusionPipeline.from_pretrained("kandinsky-community/kandinsky-2-1-prior", dtype=torch.float16, use_safetensors=True).to("cuda")  # or "mps", "xpu", "cpu"
pipeline = DiffusionPipeline.from_pretrained("kandinsky-community/kandinsky-2-1", dtype=torch.float16, use_safetensors=True).to("cuda")

prompt = "A cheeseburger, white background"

image_embeds, negative_image_embeds = prior_pipeline(prompt, guidance_scale=1.0).to_tuple()
image = pipeline(
    prompt,
    image_embeds=image_embeds,
    negative_image_embeds=negative_image_embeds,
).images[0]

image.save("burger.png")
```

مرّر شيشبرغر إلى [ShapEImg2ImgPipeline](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) لتوليد تمثيل ثلاثي الأبعاد له.

```py
from PIL import Image
from diffusers import ShapEImg2ImgPipeline
from diffusers.utils import export_to_gif

pipe = ShapEImg2ImgPipeline.from_pretrained("openai/shap-e-img2img", dtype=torch.float16, variant="fp16").to("cuda")  # or "mps", "xpu", "cpu"

guidance_scale = 3.0
image = Image.open("burger.png").resize((256, 256))

images = pipe(
    image,
    guidance_scale=guidance_scale,
    num_inference_steps=64,
    frame_size=256,
).images

gif_path = export_to_gif(images[0], "burger_3d.gif")
```

  
    
    برغر الجبن
  
  
    
    برغر جبن ثلاثي الأبعاد
  

## توليد شبكة

Shap-E هو نموذج مرن يمكنه أيضًا توليد مخرجات شبكية ذات نسيج لعرضها في التطبيقات اللاحقة. في هذا المثال، ستقوم بتحويل المخرجات إلى ملف `glb` لأن مكتبة 🤗 Datasets تدعم عرض الشبكات ثلاثية الأبعاد لملفات `glb` التي يمكن عرضها بواسطة [Dataset viewer](https://huggingface.co/docs/hub/datasets-viewer#dataset-preview).

يمكنك توليد مخرجات شبكية (mesh) لكل من [ShapEPipeline](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.ShapEPipeline) و [ShapEImg2ImgPipeline](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) عن طريق تحديد معامل `output_type` بقيمة `"mesh"`:

```py
import torch
from diffusers import ShapEPipeline

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

pipe = ShapEPipeline.from_pretrained("openai/shap-e", dtype=torch.float16, variant="fp16")
pipe = pipe.to(device)

guidance_scale = 15.0
prompt = "A birthday cupcake"

images = pipe(prompt, guidance_scale=guidance_scale, num_inference_steps=64, frame_size=256, output_type="mesh").images
```

استخدم دالة `export_to_ply()` لحفظ مخرجات الشبكة كملف `ply`:

> [!TIP]
> يمكنك اختيارياً حفظ مخرجات الشبكة (mesh) كملف `obj` باستخدام الدالة `export_to_obj()`. تتيح لك القدرة على حفظ مخرجات الشبكة بتنسيقات متنوعة مرونة أكبر في الاستخدام اللاحق!

```py
from diffusers.utils import export_to_ply

ply_path = export_to_ply(images[0], "3d_cake.ply")
print(f"Saved to folder: {ply_path}")
```

ثم يمكنك تحويل ملف `ply` إلى ملف `glb` باستخدام مكتبة trimesh:

```py
import trimesh

mesh = trimesh.load("3d_cake.ply")
mesh_export = mesh.export("3d_cake.glb", file_type="glb")
```

بشكل افتراضي، يكون مخرج الشبكة مركّزًا من منظور سفلي، لكن يمكنك تغيير المنظور الافتراضي من خلال تطبيق تحويل دوران:

```py
import trimesh
import numpy as np

mesh = trimesh.load("3d_cake.ply")
rot = trimesh.transformations.rotation_matrix(-np.pi / 2, [1, 0, 0])
mesh = mesh.apply_transform(rot)
mesh_export = mesh.export("3d_cake.glb", file_type="glb")
```

ارفع ملف الشبكة إلى مستودع مجموعة البيانات الخاصة بك لعرضه باستخدام عارض مجموعات البيانات!

    

## ShapEPipeline[[diffusers.ShapEPipeline]]

#### diffusers.ShapEPipeline[[diffusers.ShapEPipeline]]

```python
diffusers.ShapEPipeline(prior: PriorTransformer, text_encoder: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, scheduler: HeunDiscreteScheduler, shap_e_renderer: ShapERenderer)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/shap_e/pipeline_shap_e.py#L87)

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

prior ([PriorTransformer](/docs/diffusers/main/ar/api/models/prior_transformer#diffusers.PriorTransformer)) : النموذج المسبق القياسي لـ unCLIP لتقريب تضمين الصورة من تضمين النص.

text_encoder ([CLIPTextModelWithProjection](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPTextModelWithProjection)) : مُشفِّر نص ثابت.

tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPTokenizer)) : `CLIPTokenizer` لتجزئة النص.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/main/ar/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : مُجدول يُستخدم بالاقتران مع نموذج `prior` لتوليد تضمين الصورة.

shap_e_renderer (`ShapERenderer`) : يقوم مُصيِّر Shap-E بإسقاط الكمونيات المولَّدة إلى معاملات شبكة عصبية متعددة الطبقات (MLP) لإنشاء كائنات ثلاثية الأبعاد باستخدام طريقة التصيير NeRF.

خط أنابيب لتوليد تمثيل كامن لأصل ثلاثي الأبعاد وعرضه باستخدام طريقة NeRF.

يرث هذا النموذج من [DiffusionPipeline](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المُنفَّذة لجميع خطوط الأنابيب (التنزيل، الحفظ، التشغيل على جهاز معين، إلخ).

#### __call__[[diffusers.ShapEPipeline.__call__]]

```python
__call__(prompt: str, num_images_per_prompt: int = 1, num_inference_steps: int = 25, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, guidance_scale: float = 4.0, frame_size: int = 64, output_type: str | None = 'pil', return_dict: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/shap_e/pipeline_shap_e.py#L190)

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

prompt (`str` أو `list[str]`) : الأمر أو الأوامر التي تُوجّه توليد الصورة.

num_images_per_prompt (`int`، *اختياري*، القيمة الافتراضية 1) : عدد الصور التي سيتم توليدها لكل موجه.

num_inference_steps (`int`، *اختياري*، القيمة الافتراضية 25) : عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال.

generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا.

latents (`torch.Tensor`، *اختياري*) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، يتم توليد كامنات من خلال الاستخراج باستخدام `generator` العشوائي المُقدَّم.

guidance_scale (`float`، *اختياري*، القيمة الافتراضية 4.0) : كلما زادت قيمة مقياس التوجيه، شجّع النموذج على توليد صور مرتبطة ارتباطًا وثيقًا بنص `prompt` على حساب انخفاض جودة الصورة. يتم تفعيل مقياس التوجيه عندما يكون `guidance_scale > 1`.

frame_size (`int`، *اختياري*، الافتراضي 64) : عرض وارتفاع كل إطار صورة من المخرجات ثلاثية الأبعاد المولّدة.

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة المولّدة. اختر بين `"pil"` (`PIL.Image.Image`)، `"np"` (`np.array`)، `"latent"` (`torch.Tensor`)، أو mesh (`MeshDecoderOutput`).

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [ShapEPipelineOutput](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) بدلاً من tuple عادي.

**يعيد:** [ShapEPipelineOutput](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) أو `tuple`

إذا كان `return_dict` هو `True`، يُعاد [ShapEPipelineOutput](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput)، وإلا يُعاد `tuple` يكون عنصره الأول قائمة بالصور المولّدة.

دالة الاستدعاء call لخط الأنابيب pipeline الخاص بالتوليد.

أمثلة:
```py
>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from diffusers.utils import export_to_gif

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

>>> repo = "openai/shap-e"
>>> pipe = DiffusionPipeline.from_pretrained(repo, torch_dtype=torch.float16)
>>> pipe = pipe.to(device)

>>> guidance_scale = 15.0
>>> prompt = "a shark"

>>> images = pipe(
...     prompt,
...     guidance_scale=guidance_scale,
...     num_inference_steps=64,
...     frame_size=256,
... ).images

>>> gif_path = export_to_gif(images[0], "shark_3d.gif")
```

## ShapEImg2ImgPipeline[[diffusers.ShapEImg2ImgPipeline]]

#### diffusers.ShapEImg2ImgPipeline[[diffusers.ShapEImg2ImgPipeline]]

```python
diffusers.ShapEImg2ImgPipeline(prior: PriorTransformer, image_encoder: CLIPVisionModel, image_processor: CLIPImageProcessorPil, scheduler: HeunDiscreteScheduler, shap_e_renderer: ShapERenderer)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/shap_e/pipeline_shap_e_img2img.py#L88)

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

prior ([PriorTransformer](/docs/diffusers/main/ar/api/models/prior_transformer#diffusers.PriorTransformer)) : النموذج المسبق القياسي لـ unCLIP لتقريب تضمين الصورة من تضمين النص.

image_encoder ([CLIPVisionModel](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPVisionModel)) : مُشفِّر صور مجمّد.

image_processor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPImageProcessor)) : `CLIPImageProcessor` لمعالجة الصور.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/main/ar/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : مُجدول يُستخدم بالاقتران مع نموذج `prior` لتوليد تضمين الصورة.

shap_e_renderer (`ShapERenderer`) : يقوم مُصيِّر Shap-E بإسقاط الكمونيات المولَّدة إلى معاملات شبكة عصبية متعددة الطبقات (MLP) لإنشاء كائنات ثلاثية الأبعاد باستخدام طريقة التصيير NeRF.

خط أنابيب لتوليد تمثيل كامن لأصل ثلاثي الأبعاد وعرضه باستخدام طريقة NeRF من صورة.

يرث هذا النموذج من [DiffusionPipeline](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المُنفَّذة لجميع خطوط الأنابيب (التنزيل، الحفظ، التشغيل على جهاز معين، إلخ).

#### __call__[[diffusers.ShapEImg2ImgPipeline.__call__]]

```python
__call__(image: PIL.Image.Image | list[PIL.Image.Image], num_images_per_prompt: int = 1, num_inference_steps: int = 25, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, guidance_scale: float = 4.0, frame_size: int = 64, output_type: str | None = 'pil', return_dict: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/shap_e/pipeline_shap_e_img2img.py#L172)

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

image (`torch.Tensor`، `PIL.Image.Image`، `np.ndarray`، `list[torch.Tensor]`، `list[PIL.Image.Image]`، أو `list[np.ndarray]`) : `Image` أو tensor يمثل دفعة من الصور (image batch) ليُستخدم كنقطة انطلاق. يمكن أيضًا قبول كامنات الصور (image latents) كصورة، ولكن إذا تم تمرير الكامنات مباشرةً فلن يتم ترميزها مرة أخرى.

num_images_per_prompt (`int`، *اختياري*، القيمة الافتراضية 1) : عدد الصور التي سيتم توليدها لكل موجه.

num_inference_steps (`int`، *اختياري*، القيمة الافتراضية 25) : عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال.

generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا.

latents (`torch.Tensor`، *اختياري*) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، يتم توليد كامنات من خلال الاستخراج باستخدام `generator` العشوائي المُقدَّم.

guidance_scale (`float`، *اختياري*، القيمة الافتراضية 4.0) : كلما زادت قيمة مقياس التوجيه، شجّع النموذج على توليد صور مرتبطة ارتباطًا وثيقًا بنص `prompt` على حساب انخفاض جودة الصورة. يتم تفعيل مقياس التوجيه عندما يكون `guidance_scale > 1`.

frame_size (`int`، *اختياري*، الافتراضي 64) : عرض وارتفاع كل إطار صورة من المخرجات ثلاثية الأبعاد المولّدة.

output_type (`str`، *اختياري*، القيمة الافتراضية `"pil"`) : صيغة الصورة المولّدة. اختر بين `"pil"` (`PIL.Image.Image`)، `"np"` (`np.array`)، `"latent"` (`torch.Tensor`)، أو mesh (`MeshDecoderOutput`).

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [ShapEPipelineOutput](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) بدلاً من tuple عادي.

**يعيد:** [ShapEPipelineOutput](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) أو `tuple`

إذا كان `return_dict` هو `True`، يُعاد [ShapEPipelineOutput](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput)، وإلا يُعاد `tuple` يكون عنصره الأول قائمة بالصور المولّدة.

دالة الاستدعاء call لخط الأنابيب pipeline الخاص بالتوليد.

أمثلة:
```py
>>> from PIL import Image
>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from diffusers.utils import export_to_gif, load_image

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

>>> repo = "openai/shap-e-img2img"
>>> pipe = DiffusionPipeline.from_pretrained(repo, torch_dtype=torch.float16)
>>> pipe = pipe.to(device)

>>> guidance_scale = 3.0
>>> image_url = "https://hf.co/datasets/diffusers/docs-images/resolve/main/shap-e/corgi.png"
>>> image = load_image(image_url).convert("RGB")

>>> images = pipe(
...     image,
...     guidance_scale=guidance_scale,
...     num_inference_steps=64,
...     frame_size=256,
... ).images

>>> gif_path = export_to_gif(images[0], "corgi_3d.gif")
```

## ShapEPipelineOutput[[diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput]]

#### diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput[[diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput]]

```python
diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput(images: list[list[PIL.Image.Image]] | list[list[numpy.ndarray]])
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/shap_e/pipeline_shap_e.py#L75)

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

images (`torch.Tensor`) : قائمة من الصور لعرض ثلاثي الأبعاد.

فئة الإخراج الخاصة بـ [ShapEPipeline](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.ShapEPipeline) و [ShapEImg2ImgPipeline](/docs/diffusers/main/ar/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline).