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

Model Shap-E diusulkan dalam Shap-E: Generating Conditional 3D Implicit Functions oleh Alex Nichol dan Heewoo Jun dari OpenAI.

Abstrak dari makalah tersebut adalah:

Kami memperkenalkan Shap-E, sebuah model generatif bersyarat untuk aset 3D. Berbeda dengan karya terbaru tentang model generatif 3D yang menghasilkan satu representasi output, Shap-E secara langsung menghasilkan parameter dari fungsi implisit yang dapat dirender sebagai mesh bertekstur maupun medan radiasi neural. Kami melatih Shap-E dalam dua tahap: pertama, kami melatih encoder yang memetakan aset 3D ke parameter fungsi implisit secara deterministik; kedua, kami melatih model difusi bersyarat pada output dari encoder. Ketika dilatih pada dataset besar data 3D dan teks yang berpasangan, model yang dihasilkan mampu menghasilkan aset 3D yang kompleks dan beragam dalam hitungan detik. Ketika dibandingkan dengan Point-E, sebuah model generatif eksplisit di atas awan titik, Shap-E konvergen lebih cepat dan mencapai kualitas sampel yang setara atau lebih baik meskipun memodelkan ruang output multi-representasi dengan dimensi yang lebih tinggi.

Kodebase asli dapat ditemukan di openai/shap-e.

Lihat bagian memanfaatkan ulang komponen di antara pipeline untuk mempelajari cara memuat komponen yang sama ke beberapa pipeline secara efisien.

Pastikan Anda telah menginstal pustaka berikut.

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

Teks-ke-3D

Untuk menghasilkan gif dari objek 3D, berikan prompt teks ke ShapEPipeline. Pipeline ini menghasilkan daftar bingkai gambar yang digunakan untuk membuat objek 3D.

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

Sekarang gunakan fungsi export_to_gif() untuk mengonversi daftar bingkai gambar menjadi gif dari objek 3D.

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"

Gambar-ke-3D

Untuk menghasilkan objek 3D dari gambar lain, gunakan ShapEImg2ImgPipeline. Anda dapat menggunakan gambar yang sudah ada atau menghasilkan gambar yang sepenuhnya baru. Mari kita gunakan model Kandinsky 2.1 untuk menghasilkan gambar baru.

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

Lewatkan cheeseburger ke ShapEImg2ImgPipeline untuk menghasilkan representasi 3D-nya.

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")
cheeseburger
3D cheeseburger

Generate mesh

Shap-E adalah model fleksibel yang juga dapat menghasilkan output mesh bertekstur untuk dirender pada aplikasi hilir. Pada contoh ini, Anda akan mengonversi output menjadi file glb karena pustaka 🤗 Datasets mendukung visualisasi mesh untuk file glb yang dapat dirender oleh Dataset viewer.

Anda dapat menghasilkan output mesh untuk ShapEPipeline dan ShapEImg2ImgPipeline dengan menentukan parameter output_type sebagai "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

Gunakan fungsi export_to_ply() untuk menyimpan output mesh sebagai file ply:

Anda dapat secara opsional menyimpan output mesh sebagai file obj dengan fungsi export_to_obj(). Kemampuan untuk menyimpan output mesh dalam berbagai format membuatnya lebih fleksibel untuk penggunaan di tahap berikutnya!

from diffusers.utils import export_to_ply

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

Lalu Anda dapat mengonversi file ply menjadi file glb dengan pustaka trimesh:

import trimesh

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

Secara default, output mesh difokuskan dari sudut pandang bawah, tetapi Anda dapat mengubah sudut pandang default dengan menerapkan transformasi rotasi:

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

Unggah file mesh ke repositori dataset Anda untuk memvisualisasikannya dengan Dataset viewer!

ShapEPipeline

kelas diffusers.ShapEPipeline

< >

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

Parameter

  • prior (PriorTransformer) — prior unCLIP kanonik untuk mengaproksimasi embedding gambar dari embedding teks.
  • text_encoder (CLIPTextModelWithProjection) — Text-encoder yang dibekukan.
  • tokenizer (CLIPTokenizer) — CLIPTokenizer untuk melakukan tokenisasi teks.
  • scheduler (HeunDiscreteScheduler) — Scheduler yang digunakan bersama model prior untuk menghasilkan embedding gambar.
  • shap_e_renderer (ShapERenderer) — Renderer Shap-E memproyeksikan latents yang dihasilkan ke dalam parameter MLP untuk membuat objek 3D dengan metode rendering NeRF.

Pipeline untuk menghasilkan representasi laten dari aset 3D dan merender dengan metode NeRF.

Model ini mewarisi dari DiffusionPipeline. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline (mengunduh, menyimpan, menjalankan pada perangkat tertentu, dll.).

__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

Parameter

  • prompt (str atau list[str]) — Prompt atau kumpulan prompt untuk mengarahkan generasi gambar.
  • num_images_per_prompt (int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • num_inference_steps (int, opsional, default 25) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.
  • generator (torch.Generator atau list[torch.Generator], opsional) — torch.Generator untuk membuat generasi menjadi deterministik.
  • latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya dan diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.
  • guidance_scale (float, opsional, default 4.0) — Nilai guidance scale yang lebih tinggi mendorong model untuk menghasilkan gambar yang sangat terkait dengan prompt teks, dengan mengorbankan kualitas gambar yang lebih rendah. Guidance scale diaktifkan ketika guidance_scale > 1.
  • frame_size (int, opsional, default 64) — Lebar dan tinggi setiap bingkai gambar dari output 3D yang dihasilkan.
  • output_type (str, opsional, default "pil") — Format output dari gambar yang dihasilkan. Pilih antara "pil" (PIL.Image.Image), "np" (np.array), "latent" (torch.Tensor), atau mesh (MeshDecoderOutput).
  • return_dict (bool, opsional, defaultnya True) — Apakah akan mengembalikan ShapEPipelineOutput alih-alih tuple biasa.

Mengembalikan

ShapEPipelineOutput atau tuple

Jika return_dict adalah True, ShapEPipelineOutput dikembalikan, sebaliknya sebuah tuple dikembalikan di mana elemen pertama adalah daftar dengan gambar yang dihasilkan.

Fungsi panggilan untuk pipeline pada generasi.

Contoh:

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

kelas diffusers.ShapEImg2ImgPipeline

< >

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

Parameter

  • prior (PriorTransformer) — prior unCLIP kanonik untuk mengaproksimasi embedding gambar dari embedding teks.
  • image_encoder (CLIPVisionModel) — Image-encoder yang dibekukan.
  • image_processor (CLIPImageProcessor) — CLIPImageProcessor untuk memproses gambar.
  • scheduler (HeunDiscreteScheduler) — Scheduler yang digunakan bersama model prior untuk menghasilkan embedding gambar.
  • shap_e_renderer (ShapERenderer) — Renderer Shap-E memproyeksikan latents yang dihasilkan ke dalam parameter MLP untuk membuat objek 3D dengan metode rendering NeRF.

Pipeline untuk menghasilkan representasi laten dari aset 3D dan merender dengan metode NeRF dari sebuah gambar.

Model ini mewarisi dari DiffusionPipeline. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline (mengunduh, menyimpan, menjalankan pada perangkat tertentu, dll.).

__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

Parameter

  • image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image], atau list[np.ndarray]) — Image atau tensor yang mewakili batch gambar untuk digunakan sebagai titik awal. Dapat juga menerima latens gambar sebagai image, tetapi jika latens dilewatkan secara langsung, ia tidak akan di-encode ulang.
  • num_images_per_prompt (int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • num_inference_steps (int, opsional, default 25) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.
  • generator (torch.Generator atau list[torch.Generator], opsional) — torch.Generator untuk membuat generasi menjadi deterministik.
  • latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya dan diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor latents akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.
  • guidance_scale (float, opsional, default 4.0) — Nilai guidance scale yang lebih tinggi mendorong model untuk menghasilkan gambar yang sangat terkait dengan prompt teks, dengan mengorbankan kualitas gambar yang lebih rendah. Guidance scale diaktifkan ketika guidance_scale > 1.
  • frame_size (int, opsional, default 64) — Lebar dan tinggi setiap bingkai gambar dari output 3D yang dihasilkan.
  • output_type (str, opsional, default "pil") — Format output dari gambar yang dihasilkan. Pilih antara "pil" (PIL.Image.Image), "np" (np.array), "latent" (torch.Tensor), atau mesh (MeshDecoderOutput).
  • return_dict (bool, opsional, defaultnya True) — Apakah akan mengembalikan ShapEPipelineOutput alih-alih tuple biasa.

Mengembalikan

ShapEPipelineOutput atau tuple

Jika return_dict adalah True, ShapEPipelineOutput dikembalikan, sebaliknya sebuah tuple dikembalikan di mana elemen pertama adalah daftar dengan gambar yang dihasilkan.

Fungsi panggilan untuk pipeline pada generasi.

Contoh:

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

kelas diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput

< >

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

Parameter

  • images (torch.Tensor) — Daftar gambar untuk rendering 3D.

Kelas output untuk ShapEPipeline dan ShapEImg2ImgPipeline.

Update on GitHub

←SANA-WM Stable Cascade→