# Shap-E

Model Shap-E diusulkan dalam [Shap-E: Generating Conditional 3D Implicit Functions](https://huggingface.co/papers/2305.02463) oleh Alex Nichol dan Heewoo Jun dari [OpenAI](https://github.com/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](https://github.com/openai/shap-e).

> [!TIP]
> Lihat bagian [memanfaatkan ulang komponen di antara pipeline](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) untuk mempelajari cara memuat komponen yang sama ke beberapa pipeline secara efisien.

Pastikan Anda telah menginstal pustaka berikut.

```py
# 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](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.ShapEPipeline). Pipeline ini menghasilkan daftar bingkai gambar yang digunakan untuk membuat objek 3D.

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

Sekarang gunakan fungsi [export_to_gif()](/docs/diffusers/v0.43.0/id/api/utilities#diffusers.utils.export_to_gif) untuk mengonversi daftar bingkai gambar menjadi gif dari objek 3D.

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

## Gambar-ke-3D

Untuk menghasilkan objek 3D dari gambar lain, gunakan [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline). Anda dapat menggunakan gambar yang sudah ada atau menghasilkan gambar yang sepenuhnya baru. Mari kita gunakan model [Kandinsky 2.1](./kandinsky) untuk menghasilkan gambar baru.

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

Lewatkan cheeseburger ke [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) untuk menghasilkan representasi 3D-nya.

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

  
    
    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](https://huggingface.co/docs/hub/datasets-viewer#dataset-preview).

Anda dapat menghasilkan output mesh untuk [ShapEPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.ShapEPipeline) dan [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) dengan menentukan parameter `output_type` sebagai `"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
```

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

> [!TIP]
> 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!

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

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

```py
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:

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

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

    

## ShapEPipeline[[diffusers.ShapEPipeline]]

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

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

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e.py#L87)

**Parameter:**

prior ([PriorTransformer](/docs/diffusers/v0.43.0/id/api/models/prior_transformer#diffusers.PriorTransformer)) : Prior unCLIP kanonik untuk mengaproksimasi embedding gambar dari embedding teks.

text_encoder ([CLIPTextModelWithProjection](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModelWithProjection)) : Text-encoder yang dibekukan.

tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)) : Sebuah `CLIPTokenizer` untuk melakukan tokenisasi teks.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/v0.43.0/id/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : Penjadwal yang digunakan bersama model `prior` untuk menghasilkan embedding gambar.

shap_e_renderer (`ShapERenderer`) : Shap-E renderer 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](/docs/diffusers/v0.43.0/id/api/pipelines/overview#diffusers.DiffusionPipeline). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline (mengunduh, menyimpan, menjalankan pada perangkat tertentu, dll.).

#### __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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e.py#L190)

**Parameter:**

prompt (`str` atau `list[str]`) : Prompt atau prompt-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*, defaultnya 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*) : Sebuah [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) untuk membuat proses generasi menjadi deterministik.

latents (`torch.Tensor`, *opsional*) : Laten berisik yang telah dibuat sebelumnya, 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 laten 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 dari setiap bingkai gambar dari output 3D yang dihasilkan.

output_type (`str`, *opsional*, defaultnya `"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](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) alih-alih tuple biasa.

**Mengembalikan:** [ShapEPipelineOutput](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) atau `tuple`

Jika `return_dict` adalah `True`, [ShapEPipelineOutput](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) dikembalikan, selain itu sebuah `tuple` dikembalikan di mana elemen pertama adalah daftar dengan gambar yang dihasilkan.

Fungsi panggilan untuk pipeline pada generasi.

Contoh:
```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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e_img2img.py#L88)

**Parameter:**

prior ([PriorTransformer](/docs/diffusers/v0.43.0/id/api/models/prior_transformer#diffusers.PriorTransformer)) : Prior unCLIP kanonik untuk mengaproksimasi embedding gambar dari embedding teks.

image_encoder ([CLIPVisionModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPVisionModel)) : Pengkode gambar beku.

image_processor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor)) : Sebuah `CLIPImageProcessor` untuk memproses gambar.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/v0.43.0/id/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : Penjadwal yang digunakan bersama model `prior` untuk menghasilkan embedding gambar.

shap_e_renderer (`ShapERenderer`) : Shap-E renderer 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](/docs/diffusers/v0.43.0/id/api/pipelines/overview#diffusers.DiffusionPipeline). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline (mengunduh, menyimpan, menjalankan pada perangkat tertentu, dll.).

#### __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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e_img2img.py#L172)

**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 gambar, 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*, defaultnya 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*) : Sebuah [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) untuk membuat proses generasi menjadi deterministik.

latents (`torch.Tensor`, *opsional*) : Laten berisik yang telah dibuat sebelumnya, 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 laten 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 dari setiap bingkai gambar dari output 3D yang dihasilkan.

output_type (`str`, *opsional*, defaultnya `"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](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) alih-alih tuple biasa.

**Mengembalikan:** [ShapEPipelineOutput](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) atau `tuple`

Jika `return_dict` adalah `True`, [ShapEPipelineOutput](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) dikembalikan, selain itu sebuah `tuple` dikembalikan di mana elemen pertama adalah daftar dengan gambar yang dihasilkan.

Fungsi panggilan untuk pipeline pada generasi.

Contoh:
```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]])
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e.py#L75)

**Parameter:**

images (`torch.Tensor`) : Daftar gambar untuk rendering 3D.

Kelas output untuk [ShapEPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.ShapEPipeline) dan [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline).