# Shap-E

Модель Shap-E была предложена в работе [Shap-E: Generating Conditional 3D Implicit Functions](https://huggingface.co/papers/2305.02463) Алексом Ничолом и Хиу Джунем из [OpenAI](https://github.com/openai).

Аннотация из статьи:

*Мы представляем Shap-E — условную генеративную модель для 3D-ассетов. В отличие от недавних работ по 3D-генеративным моделям, которые формируют единственное выходное представление, Shap-E непосредственно генерирует параметры неявных функций, которые могут быть отрендерены как текстурированные меши, так и нейронные поля радиантности. Обучение Shap-E проходит в два этапа: сначала мы обучаем энкодер, который детерминированно отображает 3D-ассеты в параметры неявной функции; затем мы обучаем условную диффузионную модель на выходах энкодера. При обучении на большом наборе данных, содержащем пары 3D-ассетов и текстов, полученные модели способны генерировать сложные и разнообразные 3D-ассеты за считанные секунды. В сравнении с Point-E — явной генеративной моделью для облаков точек — Shap-E сходится быстрее и достигает сопоставимого или более высокого качества выборок, несмотря на то, что моделирует выходное пространство с более высокой размерностью и несколькими представлениями.*

Исходная кодовая база доступна по адресу [openai/shap-e](https://github.com/openai/shap-e).

> [!TIP]
> См. раздел [повторное использование компонентов в разных конвейерах](../../using-diffusers/loading#reusing-models-in-multiple-pipelines), чтобы узнать, как эффективно загружать одни и те же компоненты в несколько конвейеров.

Убедитесь, что у вас установлены следующие библиотеки.

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

## Текст в 3D

Чтобы создать gif-анимацию 3D-объекта, передайте текстовый промпт в [ShapEPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.ShapEPipeline). Пайплайн генерирует список кадров изображений, которые используются для создания 3D-объекта.

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

Теперь используйте функцию [export_to_gif()](/docs/diffusers/v0.43.0/ru/api/utilities#diffusers.utils.export_to_gif), чтобы преобразовать список кадров изображения в gif-файл 3D-объекта.

```py
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"
  

## Изображение в 3D

Чтобы создать 3D-объект по другому изображению, используйте [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline). Вы можете использовать существующее изображение или сгенерировать совершенно новое. Давайте сгенерируем новое изображение с помощью модели [Kandinsky 2.1](./kandinsky).

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

Передайте чизбургер в [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline), чтобы сгенерировать его 3D-представление.

```py
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-сырный бургер
  

## Создать сетку

Shap-E — это гибкая модель, которая также может генерировать текстурированные сетки для рендеринга в прикладных задачах. В этом примере выход конвертируется в файл `glb`, так как библиотека 🤗 Datasets поддерживает визуализацию сеток из файлов `glb`, которые могут быть отрендерены в [просмотрщике датасетов](https://huggingface.co/docs/hub/datasets-viewer#dataset-preview).

Вы можете генерировать выходные данные в формате сетки для [ShapEPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.ShapEPipeline) и [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline), указав параметр `output_type` со значением `"mesh"`:

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

Используйте функцию `export_to_ply()`, чтобы сохранить вывод сетки в файл `ply`:

> [!TIP]
> При необходимости можно сохранить вывод сетки в файл формата `obj` с помощью функции `export_to_obj()`. Возможность сохранять вывод сетки в различных форматах делает его более гибким для дальнейшего использования!

```py
from diffusers.utils import export_to_ply

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

Затем вы можете преобразовать файл `ply` в файл `glb` с помощью библиотеки trimesh:

```py
import trimesh

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

По умолчанию вывод сетки сфокусирован на нижнюю точку обзора, но вы можете изменить точку обзора по умолчанию, применив преобразование вращения:

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

Загрузите файл сетки в репозиторий датасета, чтобы визуализировать его с помощью Dataset viewer!

    

## ShapEPipeline[[diffusers.ShapEPipeline]]

#### diffusers.ShapEPipeline[[diffusers.ShapEPipeline]]

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e.py#L87)

**Параметры:**

prior ([PriorTransformer](/docs/diffusers/v0.43.0/ru/api/models/prior_transformer#diffusers.PriorTransformer)) : канонический prior unCLIP для приближения эмбеддинга изображения по эмбеддингу текста.

text_encoder ([CLIPTextModelWithProjection](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModelWithProjection)) : замороженный текстовый энкодер.

tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)) : `CLIPTokenizer` для токенизации текста.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : планировщик, используемый в сочетании с моделью `prior` для генерации эмбеддинга изображения.

shap_e_renderer (`ShapERenderer`) : рендерер Shap-E проецирует сгенерированные латенты в параметры MLP для создания 3D-объектов с использованием метода рендеринга NeRF.

Пайплайн для генерации латентного представления 3D-ассета и рендеринга с использованием метода NeRF.

Эта модель наследуется от [DiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/overview#diffusers.DiffusionPipeline). Общую документацию по методам, реализованным для всех пайплайнов (загрузка, сохранение, запуск на конкретном устройстве и т. д.), см. в документации родительского класса.

#### __call__[[diffusers.ShapEPipeline.__call__]]

```python
__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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e.py#L190)

**Параметры:**

prompt (`str` или `list[str]`) : Промпт или промпты для управления генерацией изображения.

num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.

num_inference_steps (`int`, *optional*, по умолчанию 25) : Количество шагов денойзинга. Как правило, большее количество шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.

generator (`torch.Generator` или `list[torch.Generator]`, *необязательно*) : [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности генерации.

latents (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные шумовые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Позволяет корректировать одну и ту же генерацию с помощью разных промптов. Если не задано, тензор латентов генерируется путём выборки с использованием переданного случайного `generator`.

guidance_scale (`float`, *optional*, по умолчанию 4.0) : Более высокое значение guidance scale побуждает модель генерировать изображения, тесно связанные с текстовым `prompt`, за счёт снижения качества изображения. Guidance scale активируется, когда `guidance_scale > 1`.

frame_size (`int`, *optional*, по умолчанию 64) : Ширина и высота каждого кадра изображения в генерируемом 3D-результате.

output_type (`str`, *необязательный*, по умолчанию `"pil"`) : Формат вывода сгенерированного изображения. Выберите один из вариантов: `"pil"` (`PIL.Image.Image`), `"np"` (`np.array`), `"latent"` (`torch.Tensor`) или mesh (`MeshDecoderOutput`).

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли [ShapEPipelineOutput](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) вместо обычного кортежа.

**Возвращает:** [ShapEPipelineOutput](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) или `tuple`

Если `return_dict` равно `True`, возвращается [ShapEPipelineOutput](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput), иначе возвращается `tuple`, где первый элемент — это список с сгенерированными изображениями.

Функция вызова конвейера для генерации.

Примеры:
```py
>>> 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]]

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e_img2img.py#L88)

**Параметры:**

prior ([PriorTransformer](/docs/diffusers/v0.43.0/ru/api/models/prior_transformer#diffusers.PriorTransformer)) : канонический prior unCLIP для приближения эмбеддинга изображения по эмбеддингу текста.

image_encoder ([CLIPVisionModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPVisionModel)) : замороженный энкодер изображений.

image_processor ([CLIPImageProcessor](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPImageProcessor)) : `CLIPImageProcessor` для обработки изображений.

scheduler ([HeunDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/heun#diffusers.HeunDiscreteScheduler)) : планировщик, используемый в сочетании с моделью `prior` для генерации эмбеддинга изображения.

shap_e_renderer (`ShapERenderer`) : рендерер Shap-E проецирует сгенерированные латенты в параметры MLP для создания 3D-объектов с использованием метода рендеринга NeRF.

Пайплайн для генерации латентного представления 3D-объекта и рендеринга методом NeRF по изображению.

Эта модель наследуется от [DiffusionPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/overview#diffusers.DiffusionPipeline). Общую документацию по методам, реализованным для всех пайплайнов (загрузка, сохранение, запуск на конкретном устройстве и т. д.), см. в документации родительского класса.

#### __call__[[diffusers.ShapEImg2ImgPipeline.__call__]]

```python
__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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e_img2img.py#L172)

**Параметры:**

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]` или `list[np.ndarray]`) : `Image` или тензор, представляющий пакет изображений, который будет использоваться в качестве начальной точки. Также можно передавать латенты изображений в качестве image, но при прямой передаче латентов они не кодируются повторно.

num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.

num_inference_steps (`int`, *optional*, по умолчанию 25) : Количество шагов денойзинга. Как правило, большее количество шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.

generator (`torch.Generator` или `list[torch.Generator]`, *необязательно*) : [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности генерации.

latents (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные шумовые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Позволяет корректировать одну и ту же генерацию с помощью разных промптов. Если не задано, тензор латентов генерируется путём выборки с использованием переданного случайного `generator`.

guidance_scale (`float`, *optional*, по умолчанию 4.0) : Более высокое значение guidance scale побуждает модель генерировать изображения, тесно связанные с текстовым `prompt`, за счёт снижения качества изображения. Guidance scale активируется, когда `guidance_scale > 1`.

frame_size (`int`, *optional*, по умолчанию 64) : Ширина и высота каждого кадра изображения в генерируемом 3D-результате.

output_type (`str`, *необязательный*, по умолчанию `"pil"`) : Формат вывода сгенерированного изображения. Выберите один из вариантов: `"pil"` (`PIL.Image.Image`), `"np"` (`np.array`), `"latent"` (`torch.Tensor`) или mesh (`MeshDecoderOutput`).

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли [ShapEPipelineOutput](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) вместо обычного кортежа.

**Возвращает:** [ShapEPipelineOutput](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput) или `tuple`

Если `return_dict` равно `True`, возвращается [ShapEPipelineOutput](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput), иначе возвращается `tuple`, где первый элемент — это список с сгенерированными изображениями.

Функция вызова конвейера для генерации.

Примеры:
```py
>>> 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]]

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/shap_e/pipeline_shap_e.py#L75)

**Параметры:**

images (`torch.Tensor`) : Список изображений для 3D-рендеринга.

Класс результата для [ShapEPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.ShapEPipeline) и [ShapEImg2ImgPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/shap_e#diffusers.ShapEImg2ImgPipeline).