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.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Shap-E

Shap-E modeli, OpenAI'den Alex Nichol ve Heewoo Jun tarafından Shap-E: Generating Conditional 3D Implicit Functions makalesinde önerilmiştir.

Makalenin özeti şudur:

Shap-E'yi sunuyoruz; bu, 3D varlıklar için koşullu bir üretken modeldir. 3D üretken modeller üzerine yapılan ve tek bir çıktı temsilini üreten son çalışmalardan farklı olarak Shap-E, hem dokulu ağlar (mesh) hem de sinirli radyans alanları (neural radiance fields) olarak render edilebilen örtük fonksiyonların (implicit functions) parametrelerini doğrudan üretir. Shap-E'yi iki aşamada eğitiriz: önce, 3D varlıkları örtük bir fonksiyonun parametrelerine deterministik olarak eşleyen bir kodlayıcı (encoder) eğitiriz; ikinci olarak, kodlayıcının çıktılarında koşullu bir difüzyon modeli eğitiriz. Eşleşen 3D ve metin verilerinden oluşan büyük bir veri setinde eğitildiğinde, elde ettiğimiz modeller, saniyeler içinde karmaşık ve çeşitli 3D varlıklar üretebilir. Nokta bulutları üzerinde açık bir üretken model olan Point-E ile karşılaştırıldığında, Shap-E daha hızlı yakınsar ve daha yüksek boyutlu, çoklu temsil çıktı uzayını modellemesine rağmen karşılaştırılabilir veya daha iyi örnek kalitesine ulaşır.

Orijinal kod tabanı openai/shap-e adresinde bulunabilir.

Aynı bileşenleri birden çok boru hattına verimli bir şekilde yüklemenin nasıl yapılacağını öğrenmek için boru hatları arasında bileşenleri yeniden kullanma bölümüne bakın.

Aşağıdaki kütüphanelerin yüklü olduğundan emin olun.

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

Metinden 3B'ye

3D bir nesnenin gif'ini oluşturmak için bir metin istemini ShapEPipeline'a iletin. Pipeline, 3D nesnenin oluşturulmasında kullanılan bir dizi görüntü karesi üretir.

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

Şimdi 3D nesnenin gif dosyasına dönüştürmek için görüntü karelerinin listesini export_to_gif() fonksiyonuyla dönüştürün.

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"

Görselden 3B

Başka bir görüntüden 3D bir nesne oluşturmak için ShapEImg2ImgPipeline kullanın. Mevcut bir görüntü kullanabilir veya tamamen yeni bir görüntü üretebilirsiniz. Yeni bir görüntü oluşturmak için Kandinsky 2.1 modelini kullanalım.

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

Cheeseburger'i ShapEImg2ImgPipeline'e iletin ve 3B temsilini oluşturun.

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

Mesh oluştur

Shap-E, aşağı akış uygulamaları için render edilebilecek dokulu mesh çıktıları üretebilen esnek bir modeldir. Bu örnekte, 🤗 Datasets kütüphanesi glb dosyalarının mesh görselleştirmesini desteklediği ve bu dosyaların Dataset viewer ile render edilebildiği için çıktıyı bir glb dosyasına dönüştürüyorsunuz.

output_type parametresini "mesh" olarak belirleyerek hem ShapEPipeline hem de ShapEImg2ImgPipeline için mesh çıktıları üretebilirsiniz:

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

Ağ çıktısını ply dosyası olarak kaydetmek için export_to_ply() fonksiyonunu kullanın:

İsteğe bağlı olarak, export_to_obj() işlevi ile mesh çıktısını bir obj dosyası olarak kaydedebilirsiniz. Mesh çıktısını çeşitli formatlarda kaydetme özelliği, sonraki aşamalarda kullanım için daha esnek hale getirir!

from diffusers.utils import export_to_ply

ply_path = export_to_ply(images[0], "3d_cake.ply")
print(f"Saved to folder: {ply_path}")

Ardından ply dosyasını trimesh kütüphanesiyle glb dosyasına dönüştürebilirsiniz:

import trimesh

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

Varsayılan olarak, mesh çıktısı alt bakış açısına odaklanır ancak bir dönüşüm dönüşümü uygulayarak varsayılan bakış açısını değiştirebilirsiniz:

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

Mesh dosyasını, Dataset viewer ile görselleştirmek için veri seti deposunuza yükleyin!

ShapEPipeline

sınıf diffusers.ShapEPipeline

< >

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

Parametreler

  • prior (PriorTransformer) — Metin gömümünden görüntü gömümünü yaklaşık olarak elde etmek için kullanılan standart unCLIP önceli.
  • text_encoder (CLIPTextModelWithProjection) — Donmuş metin kodlayıcı.
  • tokenizer (CLIPTokenizer) — Metni tokenleştirmek için bir CLIPTokenizer.
  • scheduler (HeunDiscreteScheduler) — Görsel gömme üretmek için prior modeliyle birlikte kullanılacak bir zamanlayıcı.
  • shap_e_renderer (ShapERenderer) — Shap-E rendereri, üretilen latentleri MLP parametrelerine yansıtarak NeRF renderleme yöntemiyle 3D nesneler oluşturur.

Bir 3D varlığın gizil (latent) temsili oluşturmak ve NeRF yöntemiyle renderlamak için kullanılan pipeline.

Bu model DiffusionPipeline sınıfından devralır. Tüm pipeline'lar için uygulanan genel yöntemlerin (indirme, kaydetme, belirli bir cihazda çalıştırma vb.) belgelerini üst sınıfın dokümantasyonunda bulabilirsiniz.

__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

Parametreler

  • prompt (str veya list[str]) — Görsel üretimi yönlendirmek için istem veya istemler.
  • num_images_per_prompt (int, isteğe bağlı, varsayılan 1) — Her istem için oluşturulacak görsel sayısı.
  • num_inference_steps (int, isteğe bağlı, varsayılan 25) — Gürültü azaltma adım sayısı. Daha fazla gürültü azaltma adımı genellikle daha yavaş çıkarım pahasına daha yüksek kaliteli bir görüntüye yol açar.
  • generator (torch.Generator veya list[torch.Generator], isteğe bağlı) — Üretimi deterministik hale getirmek için kullanılan bir torch.Generator.
  • latents (torch.Tensor, isteğe bağlı) — Gaussian dağılımdan örneklenen, gürültülü ve önceden oluşturulmuş latents; görüntü üretimi için girdi olarak kullanılabilir. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklemeye dayalı bir latents tensörü oluşturulur.
  • guidance_scale (float, isteğe bağlı, varsayılan 4.0) — Daha yüksek bir guidance scale değeri, modelin metinle prompt ile yakından ilişkili görseller üretmesini teşvik eder, ancak bu durum görsel kalitesinin düşmesine yol açar. Guidance scale, guidance_scale > 1 olduğunda etkinleştirilir.
  • frame_size (int, isteğe bağlı, varsayılan 64) — Oluşturulan 3D çıktının her görüntü karesinin genişliği ve yüksekliği.
  • output_type (str, isteğe bağlı, varsayılan "pil") — Oluşturulan görüntünün çıktı biçimi. "pil" (PIL.Image.Image), "np" (np.array), "latent" (torch.Tensor) veya mesh (MeshDecoderOutput) arasında seçim yapın.
  • return_dict (bool, isteğe bağlı, varsayılan True) — Düz bir tuple yerine ShapEPipelineOutput döndürülüp döndürülmemesi.

Dönüş değeri

ShapEPipelineOutput veya tuple

return_dict True ise ShapEPipelineOutput döndürülür, aksi halde ilk öğesi üretilen görsellerin listesini içeren bir tuple döndürülür.

Üretim için pipeline'ın çağrı fonksiyonu.

Örnekler:

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

sınıf diffusers.ShapEImg2ImgPipeline

< >

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

Parametreler

  • prior (PriorTransformer) — Metin gömümünden görüntü gömümünü yaklaşık olarak elde etmek için kullanılan standart unCLIP önceli.
  • image_encoder (CLIPVisionModel) — Donmuş görüntü kodlayıcı.
  • image_processor (CLIPImageProcessor) — Görselleri işlemek için bir CLIPImageProcessor.
  • scheduler (HeunDiscreteScheduler) — Görsel gömme üretmek için prior modeliyle birlikte kullanılacak bir zamanlayıcı.
  • shap_e_renderer (ShapERenderer) — Shap-E rendereri, üretilen latentleri MLP parametrelerine yansıtarak NeRF renderleme yöntemiyle 3D nesneler oluşturur.

Bir 3D varlığın gizil (latent) temsili oluşturmak ve bir görüntüden NeRF yöntemiyle render almak için kullanılan pipeline.

Bu model DiffusionPipeline sınıfından devralır. Tüm pipeline'lar için uygulanan genel yöntemlerin (indirme, kaydetme, belirli bir cihazda çalıştırma vb.) belgelerini üst sınıfın dokümantasyonunda bulabilirsiniz.

__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

Parametreler

  • image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image] veya list[np.ndarray]) — Başlangıç noktası olarak kullanılacak bir görüntü veya görüntü partisini temsil eden Image veya tensör. Ayrıca görüntü latentlerini de görüntü olarak kabul edebilir, ancak latentler doğrudan geçirilirse yeniden kodlanmaz.
  • num_images_per_prompt (int, isteğe bağlı, varsayılan 1) — Her istem için oluşturulacak görsel sayısı.
  • num_inference_steps (int, isteğe bağlı, varsayılan 25) — Gürültü azaltma adım sayısı. Daha fazla gürültü azaltma adımı genellikle daha yavaş çıkarım pahasına daha yüksek kaliteli bir görüntüye yol açar.
  • generator (torch.Generator veya list[torch.Generator], isteğe bağlı) — Üretimi deterministik hale getirmek için kullanılan bir torch.Generator.
  • latents (torch.Tensor, isteğe bağlı) — Gaussian dağılımdan örneklenen, gürültülü ve önceden oluşturulmuş latents; görüntü üretimi için girdi olarak kullanılabilir. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklemeye dayalı bir latents tensörü oluşturulur.
  • guidance_scale (float, isteğe bağlı, varsayılan 4.0) — Daha yüksek bir guidance scale değeri, modelin metinle prompt ile yakından ilişkili görseller üretmesini teşvik eder, ancak bu durum görsel kalitesinin düşmesine yol açar. Guidance scale, guidance_scale > 1 olduğunda etkinleştirilir.
  • frame_size (int, isteğe bağlı, varsayılan 64) — Oluşturulan 3D çıktının her görüntü karesinin genişliği ve yüksekliği.
  • output_type (str, isteğe bağlı, varsayılan "pil") — Oluşturulan görüntünün çıktı biçimi. "pil" (PIL.Image.Image), "np" (np.array), "latent" (torch.Tensor) veya mesh (MeshDecoderOutput) arasında seçim yapın.
  • return_dict (bool, isteğe bağlı, varsayılan True) — Düz bir tuple yerine ShapEPipelineOutput döndürülüp döndürülmemesi.

Dönüş değeri

ShapEPipelineOutput veya tuple

return_dict True ise ShapEPipelineOutput döndürülür, aksi halde ilk öğesi üretilen görsellerin listesini içeren bir tuple döndürülür.

Üretim için pipeline'ın çağrı fonksiyonu.

Örnekler:

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

sınıf diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput

< >

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

Parametreler

  • images (torch.Tensor) — 3D render için görüntüler listesi.

ShapEPipeline ve ShapEImg2ImgPipeline için çıktı sınıfı.

Update on GitHub

←SANA-WM Stable Cascade→