# Shap-E

O modelo Shap-E foi proposto em [Shap-E: Generating Conditional 3D Implicit Functions](https://huggingface.co/papers/2305.02463) por Alex Nichol e Heewoo Jun, da [OpenAI](https://github.com/openai).

O resumo do artigo é:

*Apresentamos o Shap-E, um modelo generativo condicional para ativos 3D. Diferentemente de trabalhos recentes sobre modelos generativos 3D que produzem uma única representação de saída, o Shap-E gera diretamente os parâmetros de funções implícitas que podem ser renderizadas tanto como malhas texturizadas quanto como campos de radiação neural. Treinamos o Shap-E em duas etapas: primeiro, treinamos um codificador que mapeia deterministicamente ativos 3D para os parâmetros de uma função implícita; em seguida, treinamos um modelo de difusão condicional nas saídas do codificador. Quando treinado em um grande conjunto de dados de pares de dados 3D e texto, nossos modelos resultantes são capazes de gerar ativos 3D complexos e diversos em questão de segundos. Quando comparado ao Point-E, um modelo generativo explícito sobre nuvens de pontos, o Shap-E converge mais rápido e atinge qualidade de amostras comparável ou superior, apesar de modelar um espaço de saída de múltiplas representações e de dimensão mais alta.*

O código original pode ser encontrado em [openai/shap-e](https://github.com/openai/shap-e).

> [!TIP]
> Veja a seção [reutilizar componentes entre pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

Certifique-se de que as seguintes bibliotecas estão instaladas.

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

## Texto para 3D

Para gerar um gif de um objeto 3D, passe um prompt de texto para o [ShapEPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.ShapEPipeline). O pipeline gera uma lista de quadros de imagem que são usados para criar o objeto 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
```

Agora use a função [export_to_gif()](/docs/diffusers/v0.43.0/pt/api/utilities#diffusers.utils.export_to_gif) para converter a lista de quadros de imagem em um gif do objeto 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"
  

## Imagem para 3D

Para gerar um objeto 3D a partir de outra imagem, use o [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline). Você pode usar uma imagem existente ou gerar uma totalmente nova. Vamos usar o modelo [Kandinsky 2.1](./kandinsky) para gerar uma nova imagem.

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

Passe o cheeseburger para o [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) para gerar uma representação 3D dele.

```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
  
  
    
    Hambúrguer de queijo 3D
  

## Gerar malha

Shap-E é um modelo flexível que também pode gerar malhas texturizadas para serem renderizadas em aplicações subsequentes. Neste exemplo, você converterá a saída em um arquivo `glb`, pois a biblioteca 🤗 Datasets suporta a visualização de malhas de arquivos `glb`, que podem ser renderizados pelo [visualizador de Dataset](https://huggingface.co/docs/hub/datasets-viewer#dataset-preview).

Você pode gerar saídas em malha tanto para o [ShapEPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.ShapEPipeline) quanto para o [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) especificando o parâmetro `output_type` como `"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
```

Use a função `export_to_ply()` para salvar a saída da malha como um arquivo `ply`:

> [!TIP]
> Você pode salvar opcionalmente a saída da malha como um arquivo `obj` com a função `export_to_obj()`. A capacidade de salvar a saída da malha em uma variedade de formatos a torna mais flexível para uso posterior!

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

Em seguida, você pode converter o arquivo `ply` para um arquivo `glb` com a biblioteca trimesh:

```py
import trimesh

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

Por padrão, a saída da malha é focada a partir da perspectiva inferior, mas você pode alterar a perspectiva padrão aplicando uma transformação de rotação:

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

Envie o arquivo de malha para o repositório do seu conjunto de dados para visualizá-lo com o 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)
```

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

**Parâmetros:**

prior ([PriorTransformer](/docs/diffusers/v0.43.0/pt/api/models/prior_transformer#diffusers.PriorTransformer)) : O prior unCLIP canônico para aproximar o embedding da imagem a partir do embedding do texto.

text_encoder ([CLIPTextModelWithProjection](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModelWithProjection)) : Codificador de texto congelado.

tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)) : Um `CLIPTokenizer` para tokenizar texto.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : Um agendador a ser usado em combinação com o modelo `prior` para gerar incorporação de imagem.

shap_e_renderer (`ShapERenderer`) : O renderer do Shap-E projeta os latentes gerados para os parâmetros de um MLP para criar objetos 3D com o método de renderização NeRF.

Pipeline para gerar a representação latente de um ativo 3D e renderizá-lo com o método NeRF.

Este modelo herda de [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos implementados para todos os pipelines (download, salvamento, execução em um dispositivo específico, etc.).

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

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

**Parâmetros:**

prompt (`str` ou `list[str]`) : O prompt ou os prompts para orientar a geração da imagem.

num_images_per_prompt (`int`, *opcional*, padrão 1) : O número de imagens a serem geradas por prompt.

num_inference_steps (`int`, *opcional*, padrão 25) : O número de etapas de remoção de ruído. Mais etapas de remoção de ruído geralmente resultam em uma imagem de maior qualidade, às custas de uma inferência mais lenta.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes é gerado por amostragem usando o `generator` aleatório fornecido.

guidance_scale (`float`, *opcional*, padrão 4.0) : Um valor mais alto de guidance scale incentiva o modelo a gerar imagens fortemente ligadas ao `prompt` de texto, em detrimento de uma menor qualidade de imagem. O guidance scale é ativado quando `guidance_scale > 1`.

frame_size (`int`, *opcional*, padrão 64) : A largura e a altura de cada quadro de imagem da saída 3D gerada.

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída da imagem gerada. Escolha entre `"pil"` (`PIL.Image.Image`), `"np"` (`np.array`), `"latent"` (`torch.Tensor`) ou malha (`MeshDecoderOutput`).

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um [ShapEPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) em vez de uma tupla simples.

**Retorna:** [ShapEPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) ou `tuple`

Se `return_dict` for `True`, [ShapEPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) é retornado; caso contrário, uma `tuple` é retornada, em que o primeiro elemento é uma lista com as imagens geradas.

A função de chamada do pipeline para geração.

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

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

**Parâmetros:**

prior ([PriorTransformer](/docs/diffusers/v0.43.0/pt/api/models/prior_transformer#diffusers.PriorTransformer)) : O prior unCLIP canônico para aproximar o embedding da imagem a partir do embedding do texto.

image_encoder ([CLIPVisionModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPVisionModel)) : Codificador de imagem congelado.

image_processor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor)) : Um `CLIPImageProcessor` para processar imagens.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : Um agendador a ser usado em combinação com o modelo `prior` para gerar incorporação de imagem.

shap_e_renderer (`ShapERenderer`) : O renderer do Shap-E projeta os latentes gerados para os parâmetros de um MLP para criar objetos 3D com o método de renderização NeRF.

Pipeline para gerar a representação latente de um ativo 3D e renderizá-lo com o método NeRF a partir de uma imagem.

Este modelo herda de [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos implementados para todos os pipelines (download, salvamento, execução em um dispositivo específico, etc.).

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

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

**Parâmetros:**

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]` ou `list[np.ndarray]`) : `Image` ou tensor representando um lote de imagens a ser usado como ponto de partida. Também pode aceitar latentes de imagem como imagem, mas, se latentes forem passados diretamente, eles não são codificados novamente.

num_images_per_prompt (`int`, *opcional*, padrão 1) : O número de imagens a serem geradas por prompt.

num_inference_steps (`int`, *opcional*, padrão 25) : O número de etapas de remoção de ruído. Mais etapas de remoção de ruído geralmente resultam em uma imagem de maior qualidade, às custas de uma inferência mais lenta.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes é gerado por amostragem usando o `generator` aleatório fornecido.

guidance_scale (`float`, *opcional*, padrão 4.0) : Um valor mais alto de guidance scale incentiva o modelo a gerar imagens fortemente ligadas ao `prompt` de texto, em detrimento de uma menor qualidade de imagem. O guidance scale é ativado quando `guidance_scale > 1`.

frame_size (`int`, *opcional*, padrão 64) : A largura e a altura de cada quadro de imagem da saída 3D gerada.

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída da imagem gerada. Escolha entre `"pil"` (`PIL.Image.Image`), `"np"` (`np.array`), `"latent"` (`torch.Tensor`) ou malha (`MeshDecoderOutput`).

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um [ShapEPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) em vez de uma tupla simples.

**Retorna:** [ShapEPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) ou `tuple`

Se `return_dict` for `True`, [ShapEPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) é retornado; caso contrário, uma `tuple` é retornada, em que o primeiro elemento é uma lista com as imagens geradas.

A função de chamada do pipeline para geração.

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

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

**Parâmetros:**

images (`torch.Tensor`) : Uma lista de imagens para renderização 3D.

Classe de saída para [ShapEPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.ShapEPipeline) e [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline).