Hugging Face's logo

Diffusers documentation

Shap-E

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Shap-E

El modelo Shap-E fue propuesto en Shap-E: Generating Conditional 3D Implicit Functions por Alex Nichol y Heewoo Jun de 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.

Consulte la sección reutilizar componentes entre pipelines para aprender a cargar eficientemente los mismos componentes en varios pipelines.

Asegúrate de tener instaladas las siguientes bibliotecas.

# 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. El pipeline genera una lista de fotogramas de imagen que se utilizan para crear el objeto 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,
).images

Ahora usa la función export_to_gif() para convertir la lista de fotogramas de imagen en un gif del objeto 3D.

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. Puede usar una imagen existente o generar una completamente nueva. Vamos a usar el modelo Kandinsky 2.1 para generar una nueva imagen.

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 para generar una representación 3D de la misma.

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.

Puede generar salidas de malla tanto para ShapEPipeline como para ShapEImg2ImgPipeline especificando el parámetro output_type como "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").images

Use la función export_to_ply() para guardar la malla de salida como un archivo ply:

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.

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:

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:

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

clase diffusers.ShapEPipeline

< >

( prior: PriorTransformertext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizerscheduler: HeunDiscreteSchedulershap_e_renderer: ShapERenderer )

Parámetros

  • prior (PriorTransformer) — El prior unCLIP canónico para aproximar el embedding de imagen a partir del embedding de texto.
  • text_encoder (CLIPTextModelWithProjection) — Codificador de texto congelado.
  • tokenizer (CLIPTokenizer) — Un CLIPTokenizer para tokenizar texto.
  • scheduler (HeunDiscreteScheduler) — Un scheduler para usar en combinación con el modelo prior para generar el embedding de la imagen.
  • shap_e_renderer (ShapERenderer) — El renderizador de Shap-E 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. 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__

< >

( 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

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 que se generarán 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 para hacer que la generación sea 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 de escala de guía más alto 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, valor predeterminado True) — Indica si se debe devolver un ShapEPipelineOutput en lugar de una tupla simple.

Devuelve

ShapEPipelineOutput o tuple

Si return_dict es True, se devuelve 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:

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

clase diffusers.ShapEImg2ImgPipeline

< >

( prior: PriorTransformerimage_encoder: CLIPVisionModelimage_processor: CLIPImageProcessorPilscheduler: HeunDiscreteSchedulershap_e_renderer: ShapERenderer )

Parámetros

  • prior (PriorTransformer) — El prior unCLIP canónico para aproximar el embedding de imagen a partir del embedding de texto.
  • image_encoder (CLIPVisionModel) — Codificador de imágenes congelado.
  • image_processor (CLIPImageProcessor) — Un CLIPImageProcessor para procesar imágenes.
  • scheduler (HeunDiscreteScheduler) — Un scheduler para usar en combinación con el modelo prior para generar el embedding de la imagen.
  • shap_e_renderer (ShapERenderer) — El renderizador de Shap-E 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. 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__

< >

( 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

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 image, 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 que se generarán 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 para hacer que la generación sea 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 de escala de guía más alto 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, valor predeterminado True) — Indica si se debe devolver un ShapEPipelineOutput en lugar de una tupla simple.

Devuelve

ShapEPipelineOutput o tuple

Si return_dict es True, se devuelve 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:

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

clase diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput

< >

( images: list[list[PIL.Image.Image]] | list[list[numpy.ndarray]] )

Parámetros

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

Clase de salida para ShapEPipeline y ShapEImg2ImgPipeline.

Update on GitHub

←SANA-WM Stable Cascade→