Hugging Face's logo

Diffusers documentation

Shap-E

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

and get access to the augmented documentation experience

to get started

Shap-E

قُدِّم نموذج Shap-E في Shap-E: Generating Conditional 3D Implicit Functions بواسطة Alex Nichol وHeewoo Jun من OpenAI.

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

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

يمكن العثور على قاعدة الكود الأصلية في openai/shap-e.

راجع قسم إعادة استخدام المكونات عبر خطوط الأنابيب لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.

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

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

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

لتوليد ملف gif لجسم ثلاثي الأبعاد، مرّر موجهًا نصيًا إلى ShapEPipeline. يقوم خط الأنابيب بتوليد قائمة من إطارات الصور التي تُستخدم لإنشاء الجسم ثلاثي الأبعاد.

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() لتحويل قائمة إطارات الصور إلى ملف gif للكائن ثلاثي الأبعاد.

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. يمكنك استخدام صورة موجودة أو توليد صورة جديدة بالكامل. دعنا نستخدم نموذج Kandinsky 2.1 لتوليد صورة جديدة.

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 لتوليد تمثيل ثلاثي الأبعاد له.

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.

يمكنك توليد مخرجات شبكية (mesh) لكل من ShapEPipeline و ShapEImg2ImgPipeline عن طريق تحديد معامل output_type بقيمة "mesh":

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:

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

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:

import trimesh

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

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

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

< >

( prior: PriorTransformertext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizerscheduler: HeunDiscreteSchedulershap_e_renderer: ShapERenderer )

المعاملات

  • prior (PriorTransformer) — النموذج السابق القياسي في unCLIP لتقريب تضمين الصورة من تضمين النص.
  • text_encoder (CLIPTextModelWithProjection) — مُشفِّر نص ثابت.
  • tokenizer (CLIPTokenizer) — CLIPTokenizer لتجزئة النص.
  • scheduler (HeunDiscreteScheduler) — جدولة تُستخدم بالاقتران مع نموذج prior لتوليد تضمين الصورة.
  • shap_e_renderer (ShapERenderer) — يعمل مُصيِّر Shap-E على إسقاط الكمونيات المولَّدة إلى معاملات شبكة عصبية متعددة الطبقات (MLP) لإنشاء كائنات ثلاثية الأبعاد باستخدام طريقة التصيير NeRF.

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

يرث هذا النموذج من DiffusionPipeline. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المُنفَّذة لجميع خطوط الأنابيب (التنزيل، الحفظ، التشغيل على جهاز معين، إلخ).

__call__

< >

( prompt: strnum_images_per_prompt: int = 1num_inference_steps: int = 25generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneguidance_scale: float = 4.0frame_size: int = 64output_type: str | None = 'pil'return_dict: bool = True ) → ShapEPipelineOutput or tuple

المعاملات

  • prompt (str أو list[str]) — الموجّه أو الموجّهات التي تُوجّه توليد الصورة.
  • num_images_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد الصور التي سيتم توليدها لكل موجه.
  • num_inference_steps (int، اختياري، القيمة الافتراضية 25) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة بجودة أعلى على حساب بطء الاستدلال.
  • generator (torch.Generator أو list[torch.Generator]، اختياري) — torch.Generator لجعل التوليد حتميًا.
  • latents (torch.Tensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، يتم توليد كائن latents عن طريق الاستخراج باستخدام 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 بدلاً من tuple عادي.

يعيد

ShapEPipelineOutput أو tuple

إذا كان return_dict هو True، يُعاد ShapEPipelineOutput، وإلا يُعاد tuple يكون عنصره الأول قائمة بالصور المولّدة.

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

أمثلة:

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

< >

( prior: PriorTransformerimage_encoder: CLIPVisionModelimage_processor: CLIPImageProcessorPilscheduler: HeunDiscreteSchedulershap_e_renderer: ShapERenderer )

المعاملات

  • prior (PriorTransformer) — النموذج السابق القياسي في unCLIP لتقريب تضمين الصورة من تضمين النص.
  • image_encoder (CLIPVisionModel) — مُشفِّر صور مجمّد.
  • image_processor (CLIPImageProcessor) — معالج CLIPImageProcessor لمعالجة الصور.
  • scheduler (HeunDiscreteScheduler) — جدولة تُستخدم بالاقتران مع نموذج prior لتوليد تضمين الصورة.
  • shap_e_renderer (ShapERenderer) — يعمل مُصيِّر Shap-E على إسقاط الكمونيات المولَّدة إلى معاملات شبكة عصبية متعددة الطبقات (MLP) لإنشاء كائنات ثلاثية الأبعاد باستخدام طريقة التصيير NeRF.

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

يرث هذا النموذج من DiffusionPipeline. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المُنفَّذة لجميع خطوط الأنابيب (التنزيل، الحفظ، التشغيل على جهاز معين، إلخ).

__call__

< >

( image: PIL.Image.Image | list[PIL.Image.Image]num_images_per_prompt: int = 1num_inference_steps: int = 25generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneguidance_scale: float = 4.0frame_size: int = 64output_type: str | None = 'pil'return_dict: bool = True ) → ShapEPipelineOutput or tuple

المعاملات

  • image (torch.Tensor، PIL.Image.Image، np.ndarray، list[torch.Tensor]، list[PIL.Image.Image]، أو list[np.ndarray]) — Image أو tensor يمثل دفعة من الصور لاستخدامها كنقطة انطلاق. يمكن أيضًا قبول كامنات الصور (image latents) كصورة، ولكن إذا تم تمرير الكامنات مباشرةً فلن يتم ترميزها مرة أخرى.
  • num_images_per_prompt (int، اختياري، القيمة الافتراضية 1) — عدد الصور التي سيتم توليدها لكل موجه.
  • num_inference_steps (int، اختياري، القيمة الافتراضية 25) — عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة بجودة أعلى على حساب بطء الاستدلال.
  • generator (torch.Generator أو list[torch.Generator]، اختياري) — torch.Generator لجعل التوليد حتميًا.
  • latents (torch.Tensor، اختياري) — كائنات latents ضجيجية مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، يتم توليد كائن latents عن طريق الاستخراج باستخدام 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 بدلاً من tuple عادي.

يعيد

ShapEPipelineOutput أو tuple

إذا كان return_dict هو True، يُعاد ShapEPipelineOutput، وإلا يُعاد tuple يكون عنصره الأول قائمة بالصور المولّدة.

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

أمثلة:

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

< >

( images: list[list[PIL.Image.Image]] | list[list[numpy.ndarray]] )

المعاملات

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

فئة الإخراج الخاصة بـ ShapEPipeline و ShapEImg2ImgPipeline.

Update on GitHub

←SANA-WM Stable Cascade→