# Shap-E

Le modèle Shap-E a été proposé dans [Shap-E: Generating Conditional 3D Implicit Functions](https://huggingface.co/papers/2305.02463) par Alex Nichol et Heewoo Jun d'[OpenAI](https://github.com/openai).

L'abstract de l'article est :

*Nous présentons Shap-E, un modèle génératif conditionnel pour les actifs 3D. Contrairement aux travaux récents sur les modèles génératifs 3D qui produisent une seule représentation de sortie, Shap-E génère directement les paramètres de fonctions implicites qui peuvent être rendues sous forme de maillages texturés et de champs de radiance neuronaux. Nous entraînons Shap-E en deux étapes : d'abord, nous entraînons un encodeur qui mappe de manière déterministe les actifs 3D vers les paramètres d'une fonction implicite ; ensuite, nous entraînons un modèle de diffusion conditionnel sur les sorties de l'encodeur. Lorsqu'il est entraîné sur un grand jeu de données appariées 3D et texte, nos modèles résultants sont capables de générer des actifs 3D complexes et variés en quelques secondes. Comparé à Point-E, un modèle génératif explicite sur des nuages de points, Shap-E converge plus rapidement et atteint une qualité d'échantillonnage comparable ou supérieure, malgré un espace de sortie multi-représentations de dimension supérieure.*

Le code source original peut être trouvé sur [openai/shap-e](https://github.com/openai/shap-e).

> [!TIP]
> Consultez la section [réutilisation des composants entre les pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) pour apprendre à charger efficacement les mêmes composants dans plusieurs pipelines.

Assurez-vous d'avoir installé les bibliothèques suivantes.

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

## Texte vers 3D

Pour générer un gif d'un objet 3D, passez un prompt texte au [ShapEPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.ShapEPipeline). Le pipeline génère une liste d'images qui sont utilisées pour créer l'objet 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
```

Utilisez maintenant la fonction [export_to_gif()](/docs/diffusers/v0.43.0/fr/api/utilities#diffusers.utils.export_to_gif) pour convertir la liste d'images en un gif de l'objet 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"
  

## Image vers 3D

Pour générer un objet 3D à partir d'une autre image, utilisez le [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline). Vous pouvez utiliser une image existante ou en générer une entièrement nouvelle. Utilisons le modèle [Kandinsky 2.1](./kandinsky) pour générer une nouvelle image.

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

Transmettez le cheeseburger au [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) pour générer une représentation 3D.

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

## Générer un maillage

Shap-E est un modèle flexible qui peut également générer des maillages texturés à rendre pour des applications en aval. Dans cet exemple, vous convertissez la sortie en fichier `glb` car la bibliothèque 🤗 Datasets prend en charge la visualisation de maillages de fichiers `glb` qui peuvent être rendus par le [Dataset viewer](https://huggingface.co/docs/hub/datasets-viewer#dataset-preview).

Vous pouvez générer des sorties de maillage pour [ShapEPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.ShapEPipeline) et [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline) en spécifiant le paramètre `output_type` comme `"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
```

Utilisez la fonction `export_to_ply()` pour enregistrer la sortie du maillage sous forme de fichier `ply` :

> [!TIP]
> Vous pouvez éventuellement enregistrer la sortie du maillage sous forme de fichier `obj` à l'aide de la fonction `export_to_obj()`. La possibilité d'enregistrer la sortie du maillage dans divers formats le rend plus flexible pour les usages en aval !

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

Vous pouvez ensuite convertir le fichier `ply` en fichier `glb` à l'aide de la bibliothèque trimesh :

```py
import trimesh

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

Par défaut, la sortie du maillage est centrée sur la vue de bas en haut, mais vous pouvez modifier la vue par défaut en appliquant une transformation de rotation :

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

Téléchargez le fichier de maillage dans votre dépôt de jeu de données pour le visualiser avec le 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)
```

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

**Paramètres :**

prior ([PriorTransformer](/docs/diffusers/v0.43.0/fr/api/models/prior_transformer#diffusers.PriorTransformer)) : le prior unCLIP canonique pour approximer l’embedding d’image à partir de l’embedding de texte.

text_encoder ([CLIPTextModelWithProjection](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModelWithProjection)) : encodeur de texte figé.

tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)) : Un `CLIPTokenizer` pour tokeniser le texte.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/v0.43.0/fr/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : Un planificateur à utiliser en combinaison avec le modèle `prior` pour générer l'embedding d'image.

shap_e_renderer (`ShapERenderer`) : le renderer Shap-E projette les latents générés dans les paramètres d'un MLP pour créer des objets 3D à l'aide de la méthode de rendu NeRF.

Pipeline pour générer la représentation latente d'un actif 3D et le rendre avec la méthode NeRF.

Ce modèle hérite de [DiffusionPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/overview#diffusers.DiffusionPipeline). Consultez la documentation de la classe parente pour les méthodes génériques implémentées pour tous les pipelines (téléchargement, sauvegarde, exécution sur un appareil particulier, etc.).

#### __appel__[[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)
```

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

**Paramètres :**

prompt (`str` ou `list[str]`) : Le prompt ou les prompts pour guider la génération d'image.

num_images_per_prompt (`int`, *facultatif*, valeur par défaut 1) : Le nombre d'images à générer par invite.

num_inference_steps (`int`, *facultatif*, valeur par défaut 25) : Le nombre d'étapes de débruitage. Un plus grand nombre d'étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d'une inférence plus lente.

generator (`torch.Generator` ou `list[torch.Generator]`, *facultatif*) : Un [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) pour rendre la génération déterministe.

latents (`torch.Tensor`, *facultatif*) : Latents bruités pré-générés, échantillonnés à partir d'une distribution gaussienne, à utiliser comme entrées pour la génération d'images. Peut être utilisé pour ajuster la même génération avec des prompts différents. S'il n'est pas fourni, un tenseur de latents est généré par échantillonnage à l'aide du `generator` aléatoire fourni.

guidance_scale (`float`, *facultatif*, valeur par défaut 4.0) : Une valeur d'échelle de guidage plus élevée encourage le modèle à générer des images étroitement liées au `prompt` texte, au détriment de la qualité de l'image. L'échelle de guidage est activée lorsque `guidance_scale > 1`.

frame_size (`int`, *facultatif*, par défaut 64) : La largeur et la hauteur de chaque image de la sortie 3D générée.

output_type (`str`, *facultatif*, par défaut `"pil"`) : Le format de sortie de l'image générée. Choisissez entre `"pil"` (`PIL.Image.Image`), `"np"` (`np.array`), `"latent"` (`torch.Tensor`) ou mesh (`MeshDecoderOutput`).

return_dict (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut retourner un [ShapEPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) plutôt qu'un simple tuple.

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

Si `return_dict` est `True`, [ShapEPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) est retourné, sinon un `tuple` est retourné dont le premier élément est une liste contenant les images générées.

La fonction d'appel du pipeline pour la génération.

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

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

**Paramètres :**

prior ([PriorTransformer](/docs/diffusers/v0.43.0/fr/api/models/prior_transformer#diffusers.PriorTransformer)) : le prior unCLIP canonique pour approximer l’embedding d’image à partir de l’embedding de texte.

image_encoder ([CLIPVisionModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPVisionModel)) : encodeur d'images figé.

image_processor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor)) : Un `CLIPImageProcessor` pour traiter les images.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/v0.43.0/fr/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : Un planificateur à utiliser en combinaison avec le modèle `prior` pour générer l'embedding d'image.

shap_e_renderer (`ShapERenderer`) : le renderer Shap-E projette les latents générés dans les paramètres d'un MLP pour créer des objets 3D à l'aide de la méthode de rendu NeRF.

Pipeline pour générer la représentation latente d'un actif 3D et le rendre à partir d'une image avec la méthode NeRF.

Ce modèle hérite de [DiffusionPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/overview#diffusers.DiffusionPipeline). Consultez la documentation de la classe parente pour les méthodes génériques implémentées pour tous les pipelines (téléchargement, sauvegarde, exécution sur un appareil particulier, etc.).

#### __appel__[[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)
```

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

**Paramètres :**

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]` ou `list[np.ndarray]`) : `Image` ou tenseur représentant un lot d'images à utiliser comme point de départ. Peut également accepter des latents d'image en tant qu'image, mais si des latents sont transmis directement, ils ne sont pas réencodés.

num_images_per_prompt (`int`, *facultatif*, valeur par défaut 1) : Le nombre d'images à générer par invite.

num_inference_steps (`int`, *facultatif*, valeur par défaut 25) : Le nombre d'étapes de débruitage. Un plus grand nombre d'étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d'une inférence plus lente.

generator (`torch.Generator` ou `list[torch.Generator]`, *facultatif*) : Un [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) pour rendre la génération déterministe.

latents (`torch.Tensor`, *facultatif*) : Latents bruités pré-générés, échantillonnés à partir d'une distribution gaussienne, à utiliser comme entrées pour la génération d'images. Peut être utilisé pour ajuster la même génération avec des prompts différents. S'il n'est pas fourni, un tenseur de latents est généré par échantillonnage à l'aide du `generator` aléatoire fourni.

guidance_scale (`float`, *facultatif*, valeur par défaut 4.0) : Une valeur d'échelle de guidage plus élevée encourage le modèle à générer des images étroitement liées au `prompt` texte, au détriment de la qualité de l'image. L'échelle de guidage est activée lorsque `guidance_scale > 1`.

frame_size (`int`, *facultatif*, par défaut 64) : La largeur et la hauteur de chaque image de la sortie 3D générée.

output_type (`str`, *facultatif*, par défaut `"pil"`) : Le format de sortie de l'image générée. Choisissez entre `"pil"` (`PIL.Image.Image`), `"np"` (`np.array`), `"latent"` (`torch.Tensor`) ou mesh (`MeshDecoderOutput`).

return_dict (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut retourner un [ShapEPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) plutôt qu'un simple tuple.

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

Si `return_dict` est `True`, [ShapEPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) est retourné, sinon un `tuple` est retourné dont le premier élément est une liste contenant les images générées.

La fonction d'appel du pipeline pour la génération.

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

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

**Paramètres :**

images (`torch.Tensor`) : Une liste d'images pour le rendu 3D.

Classe de sortie pour [ShapEPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.ShapEPipeline) et [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline).