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

O modelo Shap-E foi proposto em Shap-E: Generating Conditional 3D Implicit Functions por Alex Nichol e Heewoo Jun, da 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.

Veja a seção reutilizar componentes entre pipelines para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

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

# 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. O pipeline gera uma lista de quadros de imagem que são usados para criar o 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

Agora use a função export_to_gif() para converter a lista de quadros de imagem em um gif do 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 = "A firecracker"
prompt = "A birthday cupcake"

Imagem para 3D

Para gerar um objeto 3D a partir de outra imagem, use o ShapEImg2ImgPipeline. Você pode usar uma imagem existente ou gerar uma totalmente nova. Vamos usar o modelo Kandinsky 2.1 para gerar uma nova imagem.

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 para gerar uma representação 3D dele.

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.

Você pode gerar saídas em malha tanto para o ShapEPipeline quanto para o ShapEImg2ImgPipeline especificando o 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 a função export_to_ply() para salvar a saída da malha como um arquivo ply:

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!

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:

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:

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

classe diffusers.ShapEPipeline

< >

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

Parâmetros

  • prior (PriorTransformer) — O prior unCLIP canônico para aproximar o embedding da imagem a partir do embedding do texto.
  • text_encoder (CLIPTextModelWithProjection) — Codificador de texto congelado.
  • tokenizer (CLIPTokenizer) — Um CLIPTokenizer para tokenizar texto.
  • scheduler (HeunDiscreteScheduler) — Um scheduler a ser usado em combinação com o modelo prior para gerar o embedding da imagem.
  • shap_e_renderer (ShapERenderer) — O renderizador do Shap-E projeta os latentes gerados em 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. 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__

< >

( 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 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 desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, à custa de uma inferência mais lenta.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Um torch.Generator 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 da qualidade da 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 mesh (MeshDecoderOutput).
  • return_dict (bool, opcional, padrão True) — Se deve ou não retornar um ShapEPipelineOutput em vez de uma tupla simples.

Retorna

ShapEPipelineOutput ou tuple

Se return_dict for True, ShapEPipelineOutput é retornado, caso contrário, uma tuple é retornada, onde o primeiro elemento é uma lista com as imagens geradas.

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

Exemplos:

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

< >

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

Parâmetros

  • prior (PriorTransformer) — O prior unCLIP canônico para aproximar o embedding da imagem a partir do embedding do texto.
  • image_encoder (CLIPVisionModel) — Codificador de imagem congelado.
  • image_processor (CLIPImageProcessor) — Um CLIPImageProcessor para processar imagens.
  • scheduler (HeunDiscreteScheduler) — Um scheduler a ser usado em combinação com o modelo prior para gerar o embedding da imagem.
  • shap_e_renderer (ShapERenderer) — O renderizador do Shap-E projeta os latentes gerados em 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. 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__

< >

( 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] 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 image, 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 desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, à custa de uma inferência mais lenta.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Um torch.Generator 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 da qualidade da 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 mesh (MeshDecoderOutput).
  • return_dict (bool, opcional, padrão True) — Se deve ou não retornar um ShapEPipelineOutput em vez de uma tupla simples.

Retorna

ShapEPipelineOutput ou tuple

Se return_dict for True, ShapEPipelineOutput é retornado, caso contrário, uma tuple é retornada, onde o primeiro elemento é uma lista com as imagens geradas.

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

Exemplos:

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

< >

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

Parâmetros

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

Classe de saída para ShapEPipeline e ShapEImg2ImgPipeline.

Update on GitHub

←SANA-WM Stable Cascade→