# Shap-E

El modelo Shap-E fue propuesto en [Shap-E: Generating Conditional 3D Implicit Functions](https://huggingface.co/papers/2305.02463) por Alex Nichol y Heewoo Jun de [OpenAI](https://github.com/openai).

El resumen del artículo es:

*Presentamos Shap-E, un modelo generativo condicional para activos 3D. A diferencia del trabajo reciente en modelos generativos 3D, que produce una única representación de salida, Shap-E genera directamente los parámetros de funciones implícitas que pueden renderizarse tanto como mallas texturizadas como campos de radiancia neuronal. Entrenamos Shap-E en dos etapas: primero, entrenamos un codificador que mapea de forma determinista los activos 3D a los parámetros de una función implícita; segundo, entrenamos un modelo de difusión condicional sobre las salidas del codificador. Cuando se entrena en un gran conjunto de datos de pares de datos 3D y texto, nuestros modelos resultantes son capaces de generar activos 3D complejos y diversos en cuestión de segundos. En comparación con Point-E, un modelo generativo explícito sobre nubes de puntos, Shap-E converge más rápido y alcanza una calidad de muestra comparable o superior, a pesar de modelar un espacio de salida de mayor dimensión y con múltiples representaciones.*

El código original se puede encontrar en [openai/shap-e](https://github.com/openai/shap-e).

> [!TIP]
> Consulte la sección [reutilizar componentes entre pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) para aprender a cargar eficientemente los mismos componentes en varios pipelines.

Asegúrate de tener instaladas las siguientes bibliotecas.

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

## Texto a 3D

Para generar un gif de un objeto 3D, pase un prompt de texto al [ShapEPipeline](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.ShapEPipeline). El pipeline genera una lista de fotogramas de imagen que se utilizan para crear el 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
```

Ahora usa la función [export_to_gif()](/docs/diffusers/main/es/api/utilities#diffusers.utils.export_to_gif) para convertir la lista de fotogramas de imagen en un gif del 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 = "Un petardo"
  
  
    
    prompt = "A birthday cupcake"
  

## Imagen a 3D

Para generar un objeto 3D a partir de otra imagen, use [ShapEImg2ImgPipeline](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline). Puede usar una imagen existente o generar una completamente nueva. Usaremos el modelo [Kandinsky 2.1](./kandinsky) para generar una nueva imagen.

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

Pasa la hamburguesa al [ShapEImg2ImgPipeline](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) para generar una representación 3D de la misma.

```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
  
  
    
    Hamburguesa de queso 3D
  

## Generar malla

Shap-E es un modelo flexible que también puede generar mallas con texturas para ser renderizadas en aplicaciones posteriores. En este ejemplo, se convierte la salida en un archivo `glb` porque la biblioteca 🤗 Datasets admite la visualización de mallas de archivos `glb`, que pueden ser renderizados por el [visor de Dataset](https://huggingface.co/docs/hub/datasets-viewer#dataset-preview).

Puede generar salidas de malla tanto para [ShapEPipeline](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.ShapEPipeline) como para [ShapEImg2ImgPipeline](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) especificando el 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 la función `export_to_ply()` para guardar la malla de salida como un archivo `ply`:

> [!TIP]
> Puedes guardar opcionalmente la salida de la malla como un archivo `obj` con la función `export_to_obj()`. La posibilidad de guardar la salida de la malla en una variedad de formatos la hace más flexible para su 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}")
```

Luego, puedes convertir el archivo `ply` en un archivo `glb` con la biblioteca trimesh:

```py
import trimesh

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

Por defecto, la salida de la malla se enfoca desde el punto de vista inferior, pero puedes cambiar el punto de vista predeterminado aplicando una transformación de rotación:

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

Sube el archivo de malla a tu repositorio de datos para visualizarlo con el visor de datos (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)
```

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

**Parámetros:**

prior ([PriorTransformer](/docs/diffusers/main/es/api/models/prior_transformer#diffusers.PriorTransformer)) : El prior de unCLIP canónico para aproximar el embedding de imagen a partir del embedding de texto.

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

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

scheduler ([HeunDiscreteScheduler](/docs/diffusers/main/es/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : Un programador para usar en combinación con el modelo `prior` para generar la incrustación de imagen.

shap_e_renderer (`ShapERenderer`) : Shap-E renderer proyecta los latentes generados en los parámetros de un MLP para crear objetos 3D con el método de renderizado NeRF.

Pipeline para generar la representación latente de un activo 3D y renderizarlo con el método NeRF.

Este modelo hereda de [DiffusionPipeline](/docs/diffusers/main/es/api/pipelines/overview#diffusers.DiffusionPipeline). Consulta la documentación de la clase superior para los métodos genéricos implementados en todas las tuberías (descarga, guardado, ejecución en un 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)
```

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

**Parámetros:**

prompt (`str` o `list[str]`) : El prompt o los prompts para guiar la generación de la imagen.

num_images_per_prompt (`int`, *opcional*, valor predeterminado 1) : El número de imágenes a generar por indicación.

num_inference_steps (`int`, *opcional*, valor predeterminado 25) : El número de pasos de desruido. Más pasos de desruido suelen conducir a una imagen de mayor calidad a costa de una inferencia más lenta.

generator (`torch.Generator` o `list[torch.Generator]`, *opcional*) : Un [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) para hacer la generación determinista.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pregenerados muestreados de una distribución gaussiana, que se utilizarán como entradas para la generación de imágenes. Se pueden usar para ajustar la misma generación con diferentes prompts. Si no se proporciona, se genera un tensor de latentes mediante muestreo usando el `generator` aleatorio suministrado.

guidance_scale (`float`, *opcional*, valor predeterminado 4.0) : Un valor más alto de la escala de guía anima al modelo a generar imágenes estrechamente vinculadas al `prompt` de texto a costa de una menor calidad de imagen. La escala de guía se habilita cuando `guidance_scale > 1`.

frame_size (`int`, *opcional*, valor predeterminado 64) : El ancho y la altura de cada cuadro de imagen de la salida 3D generada.

output_type (`str`, *opcional*, valor predeterminado `"pil"`) : El formato de salida de la imagen generada. Elija entre `"pil"` (`PIL.Image.Image`), `"np"` (`np.array`), `"latent"` (`torch.Tensor`) o malla (`MeshDecoderOutput`).

return_dict (`bool`, *opcional*, por defecto `True`) : Si se devuelve un [ShapEPipelineOutput](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) en lugar de una tupla simple.

**Devuelve:** [ShapEPipelineOutput](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) o `tuple`

Si `return_dict` es `True`, se devuelve [ShapEPipelineOutput](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput); en caso contrario, se devuelve una `tuple` cuyo primer elemento es una lista con las imágenes generadas.

La función de llamada para el pipeline de generación.

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

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

**Parámetros:**

prior ([PriorTransformer](/docs/diffusers/main/es/api/models/prior_transformer#diffusers.PriorTransformer)) : El prior de unCLIP canónico para aproximar el embedding de imagen a partir del embedding de texto.

image_encoder ([CLIPVisionModel](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPVisionModel)) : Codificador de imágenes congelado.

image_processor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/main/en/model_doc/clip#transformers.CLIPImageProcessor)) : Un `CLIPImageProcessor` para procesar imágenes.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/main/es/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : Un programador para usar en combinación con el modelo `prior` para generar la incrustación de imagen.

shap_e_renderer (`ShapERenderer`) : Shap-E renderer proyecta los latentes generados en los parámetros de un MLP para crear objetos 3D con el método de renderizado NeRF.

Pipeline para generar la representación latente de un activo 3D y renderizarlo con el método NeRF a partir de una imagen.

Este modelo hereda de [DiffusionPipeline](/docs/diffusers/main/es/api/pipelines/overview#diffusers.DiffusionPipeline). Consulta la documentación de la clase superior para los métodos genéricos implementados en todas las tuberías (descarga, guardado, ejecución en un 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)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/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]` o `list[np.ndarray]`) : `Image` o tensor que representa un lote de imágenes para usarse como punto de partida. También puede aceptar latentes de imagen como imagen, pero si se pasan latentes directamente, no se vuelven a codificar.

num_images_per_prompt (`int`, *opcional*, valor predeterminado 1) : El número de imágenes a generar por indicación.

num_inference_steps (`int`, *opcional*, valor predeterminado 25) : El número de pasos de desruido. Más pasos de desruido suelen conducir a una imagen de mayor calidad a costa de una inferencia más lenta.

generator (`torch.Generator` o `list[torch.Generator]`, *opcional*) : Un [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) para hacer la generación determinista.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pregenerados muestreados de una distribución gaussiana, que se utilizarán como entradas para la generación de imágenes. Se pueden usar para ajustar la misma generación con diferentes prompts. Si no se proporciona, se genera un tensor de latentes mediante muestreo usando el `generator` aleatorio suministrado.

guidance_scale (`float`, *opcional*, valor predeterminado 4.0) : Un valor más alto de la escala de guía anima al modelo a generar imágenes estrechamente vinculadas al `prompt` de texto a costa de una menor calidad de imagen. La escala de guía se habilita cuando `guidance_scale > 1`.

frame_size (`int`, *opcional*, valor predeterminado 64) : El ancho y la altura de cada cuadro de imagen de la salida 3D generada.

output_type (`str`, *opcional*, valor predeterminado `"pil"`) : El formato de salida de la imagen generada. Elija entre `"pil"` (`PIL.Image.Image`), `"np"` (`np.array`), `"latent"` (`torch.Tensor`) o malla (`MeshDecoderOutput`).

return_dict (`bool`, *opcional*, por defecto `True`) : Si se devuelve un [ShapEPipelineOutput](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) en lugar de una tupla simple.

**Devuelve:** [ShapEPipelineOutput](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) o `tuple`

Si `return_dict` es `True`, se devuelve [ShapEPipelineOutput](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput); en caso contrario, se devuelve una `tuple` cuyo primer elemento es una lista con las imágenes generadas.

La función de llamada para el pipeline de generación.

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

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

**Parámetros:**

images (`torch.Tensor`) : Una lista de imágenes para renderizado 3D.

Clase de salida para [ShapEPipeline](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.ShapEPipeline) y [ShapEImg2ImgPipeline](/docs/diffusers/main/es/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline).