Diffusers documentation
Shap-E
Shap-E
Le modèle Shap-E a été proposé dans Shap-E: Generating Conditional 3D Implicit Functions par Alex Nichol et Heewoo Jun d'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.
Consultez la section réutilisation des composants entre les pipelines pour apprendre à charger efficacement les mêmes composants dans plusieurs pipelines.
Assurez-vous d'avoir installé les bibliothèques suivantes.
# uncomment to install the necessary libraries in Colab
#!pip install -q diffusers transformers accelerate trimeshTexte vers 3D
Pour générer un gif d'un objet 3D, passez un prompt texte au ShapEPipeline. Le pipeline génère une liste d'images qui sont utilisées pour créer l'objet 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,
).imagesUtilisez maintenant la fonction export_to_gif() pour convertir la liste d'images en un gif de l'objet 3D.
from diffusers.utils import export_to_gif
export_to_gif(images[0], "firecracker_3d.gif")
export_to_gif(images[1], "cake_3d.gif")
Image vers 3D
Pour générer un objet 3D à partir d'une autre image, utilisez le ShapEImg2ImgPipeline. Vous pouvez utiliser une image existante ou en générer une entièrement nouvelle. Utilisons le modèle Kandinsky 2.1 pour générer une nouvelle image.
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 pour générer une représentation 3D.
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")
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.
Vous pouvez générer des sorties de maillage pour ShapEPipeline et ShapEImg2ImgPipeline en spécifiant le paramètre output_type comme "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").imagesUtilisez la fonction export_to_ply() pour enregistrer la sortie du maillage sous forme de fichier ply :
Vous pouvez éventuellement enregistrer la sortie du maillage sous forme de fichier
objà l'aide de la fonctionexport_to_obj(). La possibilité d'enregistrer la sortie du maillage dans divers formats le rend plus flexible pour les usages en aval !
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 :
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 :
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
classe diffusers.ShapEPipeline
< source >( prior: PriorTransformertext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizerscheduler: HeunDiscreteSchedulershap_e_renderer: ShapERenderer )
Paramètres
- prior (PriorTransformer) — Le prior unCLIP canonique pour approximer l’embedding d’image à partir de l’embedding de texte.
- text_encoder (CLIPTextModelWithProjection) — Encodeur de texte figé.
- tokenizer (CLIPTokenizer) —
Un
CLIPTokenizerpour tokeniser le texte. - scheduler (HeunDiscreteScheduler) —
Un planificateur à utiliser en combinaison avec le modèle
priorpour 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. 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.).
__call__
< source >( 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
Paramètres
- prompt (
stroulist[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.Generatoroulist[torch.Generator], facultatif) — Untorch.Generatorpour 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 servir à 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 dugeneratoraléatoire fourni. - guidance_scale (
float, facultatif, valeur par défaut 4.0) — Une valeur de guidance scale plus élevée encourage le modèle à générer des images étroitement liées auprompttexte, au détriment de la qualité de l'image. Le guidance scale est activé lorsqueguidance_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éfautTrue) — Indique s'il faut retourner un ShapEPipelineOutput plutôt qu'un simple tuplet.
Retourne
ShapEPipelineOutput ou tuple
Si return_dict est True, 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 :
>>> 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
classe diffusers.ShapEImg2ImgPipeline
< source >( prior: PriorTransformerimage_encoder: CLIPVisionModelimage_processor: CLIPImageProcessorPilscheduler: HeunDiscreteSchedulershap_e_renderer: ShapERenderer )
Paramètres
- prior (PriorTransformer) — Le prior unCLIP canonique pour approximer l’embedding d’image à partir de l’embedding de texte.
- image_encoder (CLIPVisionModel) — Encodeur d’images figé.
- image_processor (CLIPImageProcessor) —
Un
CLIPImageProcessorpour traiter les images. - scheduler (HeunDiscreteScheduler) —
Un planificateur à utiliser en combinaison avec le modèle
priorpour 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. 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.).
__call__
< source >( 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
Paramètres
- image (
torch.Tensor,PIL.Image.Image,np.ndarray,list[torch.Tensor],list[PIL.Image.Image]oulist[np.ndarray]) —Imageou 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.Generatoroulist[torch.Generator], facultatif) — Untorch.Generatorpour 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 servir à 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 dugeneratoraléatoire fourni. - guidance_scale (
float, facultatif, valeur par défaut 4.0) — Une valeur de guidance scale plus élevée encourage le modèle à générer des images étroitement liées auprompttexte, au détriment de la qualité de l'image. Le guidance scale est activé lorsqueguidance_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éfautTrue) — Indique s'il faut retourner un ShapEPipelineOutput plutôt qu'un simple tuplet.
Retourne
ShapEPipelineOutput ou tuple
Si return_dict est True, 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 :
>>> 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
classe diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput
< source >( images: list[list[PIL.Image.Image]] | list[list[numpy.ndarray]] )
Classe de sortie pour ShapEPipeline et ShapEImg2ImgPipeline.