diffusers/main/tr/api/pipelines/shap_e.md

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 Dataset viewer tarafından 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[[diffusers.ShapEPipeline]]

diffusers.ShapEPipeline[[diffusers.ShapEPipeline]]

diffusers.ShapEPipeline(prior: PriorTransformer, text_encoder: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, scheduler: HeunDiscreteScheduler, shap_e_renderer: ShapERenderer)

Kaynak

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 belirteçleştirmek için bir CLIPTokenizer.

scheduler (HeunDiscreteScheduler) : prior modeliyle birlikte kullanılarak gömme (embedding) üretmek için kullanılacak bir zamanlayıcı (scheduler).

shap_e_renderer (ShapERenderer) : Shap-E renderer, oluşturulan latentleri MLP parametrelerine yansıtarak NeRF renderlama 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ınmıştı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[[diffusers.ShapEPipeline.call]]

__call__(prompt: str, num_images_per_prompt: int = 1, num_inference_steps: int = 25, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, guidance_scale: float = 4.0, frame_size: int = 64, output_type: str | None = 'pil', return_dict: bool = True)

Kaynak

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 üretilecek 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 bir torch.Generator.

latents (torch.Tensor, isteğe bağlı) : Görsel üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenen önceden oluşturulmuş gürültülü latensler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklem yoluyla bir latens tensörü oluşturulur.

guidance_scale (float, opsiyonel, varsayılan 4.0) : Daha yüksek bir guidance scale değeri, modelin metin prompt'u ile yakından ilişkili görseller üretmesini teşvik eder; bunun bedeli ise daha düşük görsel kalitedir. Guidance scale, guidance_scale > 1 olduğunda etkinleşir.

frame_size (int, isteğe bağlı, varsayılan 64) : Üretilen 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") : Üretilen görüntünün çıktı biçimi. "pil" (PIL.Image.Image), "np" (np.array), "latent" (torch.Tensor) veya mesh (MeshDecoderOutput) seçeneklerinden birini seçin.

return_dict (bool, isteğe bağlı, varsayılan True) : Düz bir tuple yerine ShapEPipelineOutput döndürülecek mi?

Dönüş: 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[[diffusers.ShapEImg2ImgPipeline]]

diffusers.ShapEImg2ImgPipeline[[diffusers.ShapEImg2ImgPipeline]]

diffusers.ShapEImg2ImgPipeline(prior: PriorTransformer, image_encoder: CLIPVisionModel, image_processor: CLIPImageProcessorPil, scheduler: HeunDiscreteScheduler, shap_e_renderer: ShapERenderer)

Kaynak

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) : prior modeliyle birlikte kullanılarak gömme (embedding) üretmek için kullanılacak bir zamanlayıcı (scheduler).

shap_e_renderer (ShapERenderer) : Shap-E renderer, oluşturulan latentleri MLP parametrelerine yansıtarak NeRF renderlama 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ınmıştı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[[diffusers.ShapEImg2ImgPipeline.call]]

__call__(image: PIL.Image.Image | list[PIL.Image.Image], num_images_per_prompt: int = 1, num_inference_steps: int = 25, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, guidance_scale: float = 4.0, frame_size: int = 64, output_type: str | None = 'pil', return_dict: bool = True)

Kaynak

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ü partisyonunu temsil eden Image veya tensör. Görüntü olarak görüntü latentlerini de 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 üretilecek 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 bir torch.Generator.

latents (torch.Tensor, isteğe bağlı) : Görsel üretimi için girdi olarak kullanılacak, Gauss dağılımından örneklenen önceden oluşturulmuş gürültülü latensler. Farklı istemlerle aynı üretimi ayarlamak için kullanılabilir. Sağlanmazsa, sağlanan rastgele generator kullanılarak örneklem yoluyla bir latens tensörü oluşturulur.

guidance_scale (float, opsiyonel, varsayılan 4.0) : Daha yüksek bir guidance scale değeri, modelin metin prompt'u ile yakından ilişkili görseller üretmesini teşvik eder; bunun bedeli ise daha düşük görsel kalitedir. Guidance scale, guidance_scale > 1 olduğunda etkinleşir.

frame_size (int, isteğe bağlı, varsayılan 64) : Üretilen 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") : Üretilen görüntünün çıktı biçimi. "pil" (PIL.Image.Image), "np" (np.array), "latent" (torch.Tensor) veya mesh (MeshDecoderOutput) seçeneklerinden birini seçin.

return_dict (bool, isteğe bağlı, varsayılan True) : Düz bir tuple yerine ShapEPipelineOutput döndürülecek mi?

Dönüş: 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[[diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput]]

diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput[[diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput]]

diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput(images: list[list[PIL.Image.Image]] | list[list[numpy.ndarray]])

Kaynak

Parametreler:

images (torch.Tensor) : 3D render için görüntülerin listesi.

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