Hugging Face's logo

Diffusers documentation

Shap-E

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
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 Sprint Stable Cascade→