#
# Licenciado sob a Apache License, Versão 2.0 (a "Licença");
# você não pode usar este arquivo, exceto em conformidade com a Licença.
# Você pode obter uma cópia da Licença em
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# A menos que exigido pela lei aplicável ou acordado por escrito, o software
# distribuído sob a Licença é distribuído em uma base "COMO ESTÁ",
# SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas.
# Consulte a Licença para o idioma específico que rege as permissões e
# limitações sob a Licença.
-->

# VisualCloze

[VisualCloze: A Universal Image Generation Framework via Visual In-Context Learning](https://huggingface.co/papers/2504.07960) é um framework inovador de geração universal de imagens baseado em aprendizado in-context que oferece as seguintes capacidades principais:
1. Suporte a diversas tarefas em domínio
2. Generalização para tarefas não vistas por meio de aprendizado no contexto
3. Unifique várias tarefas em uma única etapa e gere tanto a imagem de destino quanto os resultados intermediários
4. Suporte a condições de engenharia reversa a partir de imagens de destino

## Visão geral

O resumo do artigo é:

*Os avanços recentes em modelos de difusão impulsionam significativamente diversas tarefas de geração de imagens. No entanto, a abordagem predominante atual continua focada na construção de modelos específicos para cada tarefa, que apresentam eficiência limitada ao atender a uma ampla variedade de necessidades diferentes. Embora modelos universais tentem abordar essa limitação, eles enfrentam desafios críticos, incluindo instruções de tarefa generalizáveis, distribuições de tarefas adequadas e design arquitetural unificado. Para enfrentar esses desafios, propomos o VisualCloze, um framework universal de geração de imagens, que suporta uma ampla gama de tarefas dentro do domínio, generalização para tarefas não vistas, unificação de múltiplas tarefas não vistas e geração reversa. Diferente de métodos existentes que dependem de instruções de tarefa baseadas em linguagem, o que leva a ambiguidade de tarefa e generalização fraca, integramos aprendizado visual in-context, permitindo que os modelos identifiquem tarefas a partir de demonstrações visuais. Ao mesmo tempo, a esparsidade inerente das distribuições de tarefas visuais prejudica o aprendizado de conhecimento transferível entre tarefas. Para isso, introduzimos o Graph200K, um conjunto de dados estruturado em grafo que estabelece diversas tarefas inter-relacionadas, aumentando a densidade de tarefas e o conhecimento transferível. Além disso, descobrimos que nossa formulação unificada de geração de imagens compartilha um objetivo consistente com o preenchimento de imagens (image infilling), permitindo-nos aproveitar os fortes priors generativos de modelos de infilling pré-treinados sem modificar as arquiteturas. Os códigos, o conjunto de dados e os modelos estão disponíveis em https://visualcloze.github.io.*

## Inferência

### Carregamento de modelos

VisualCloze é um pipeline em cascata de duas etapas, contendo `VisualClozeGenerationPipeline` e `VisualClozeUpsamplingPipeline`.
- Em `VisualClozeGenerationPipeline`, cada imagem é reduzida antes de concatenar as imagens em um layout de grade, evitando resoluções excessivamente altas. O VisualCloze disponibiliza dois modelos adequados para diffusers, ou seja, [VisualClozePipeline-384](https://huggingface.co/VisualCloze/VisualClozePipeline-384) e [VisualClozePipeline-512](https://huggingface.co/VisualCloze/VisualClozePipeline-384), que reduzem as imagens para resoluções de 384 e 512, respectivamente.
- `VisualClozeUpsamplingPipeline` usa [SDEdit](https://huggingface.co/papers/2108.01073) para permitir a síntese de imagens em alta resolução.

O `VisualClozePipeline` integra ambos os estágios para suportar amostragem conveniente de ponta a ponta, ao mesmo tempo em que permite que os usuários utilizem cada pipeline de forma independente, conforme necessário.

### Especificações de Entrada

#### Prompts de Tarefa e Conteúdo
- Prompt da tarefa: Obrigatório descrever a intenção da tarefa de geração
- Prompt de conteúdo: Descrição ou legenda opcional da imagem de destino
- Quando o prompt de conteúdo não é necessário, passe `None`
- Para inferência em lote, passe `List[str|None]`

#### Formato de Entrada de Imagem
- Formato: `List[List[Image|None]]`
- Estrutura:
  - Todas as linhas, exceto a última, representam exemplos no contexto
  - A última linha representa a consulta atual (conjunto de imagens de destino definido como `None`)
- Para inferência em lote, passe `List[List[List[Image|None]]]`

#### Controle de Resolução
- Comportamento padrão:
  - Geração inicial na primeira etapa: área de ${pipe.resolution}^2$
  - Upsampling na segunda etapa: fator 3x
- Resolução personalizada: ajuste usando os parâmetros `upsampling_height` e `upsampling_width`

### Exemplos

Para exemplos abrangentes que cobrem uma ampla variedade de tarefas, consulte a [Online Demo](https://huggingface.co/spaces/VisualCloze/VisualCloze) e o [GitHub Repository](https://github.com/lzyhha/VisualCloze). Abaixo estão exemplos simples para três casos: conversão de máscara para imagem, detecção de bordas e geração dirigida por sujeito.

#### Exemplo para mask2image

```python
import torch
from diffusers import VisualClozePipeline
from diffusers.utils import load_image

pipe = VisualClozePipeline.from_pretrained("VisualCloze/VisualClozePipeline-384", resolution=384, dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

# Load in-context images (make sure the paths are correct and accessible)
image_paths = [
    # in-context examples
    [
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_incontext-example-1_mask.jpg'),
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_incontext-example-1_image.jpg'),
    ],
    # query with the target image
    [
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_query_mask.jpg'),
        None, # No image needed for the target image
    ],
]

# Task and content prompt
task_prompt = "In each row, a logical task is demonstrated to achieve [IMAGE2] an aesthetically pleasing photograph based on [IMAGE1] sam 2-generated masks with rich color coding."
content_prompt = """Majestic photo of a golden eagle perched on a rocky outcrop in a mountainous landscape. 
The eagle is positioned in the right foreground, facing left, with its sharp beak and keen eyes prominently visible. 
Its plumage is a mix of dark brown and golden hues, with intricate feather details. 
The background features a soft-focus view of snow-capped mountains under a cloudy sky, creating a serene and grandiose atmosphere. 
The foreground includes rugged rocks and patches of green moss. Photorealistic, medium depth of field, 
soft natural lighting, cool color palette, high contrast, sharp focus on the eagle, blurred background, 
tranquil, majestic, wildlife photography."""

# Run the pipeline
image_result = pipe(
    task_prompt=task_prompt,
    content_prompt=content_prompt,
    image=image_paths,
    upsampling_width=1344,
    upsampling_height=768,
    upsampling_strength=0.4,
    guidance_scale=30,
    num_inference_steps=30,
    max_sequence_length=512,
    generator=torch.Generator("cpu").manual_seed(0)
).images[0][0]

# Save the resulting image
image_result.save("visualcloze.png")
```

#### Exemplo para detecção de bordas

```python
import torch
from diffusers import VisualClozePipeline
from diffusers.utils import load_image

pipe = VisualClozePipeline.from_pretrained("VisualCloze/VisualClozePipeline-384", resolution=384, dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

# Load in-context images (make sure the paths are correct and accessible)
image_paths = [
    # in-context examples
    [
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_edgedetection_incontext-example-1_image.jpg'),
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_edgedetection_incontext-example-1_edge.jpg'),
    ],
    [
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_edgedetection_incontext-example-2_image.jpg'),
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_edgedetection_incontext-example-2_edge.jpg'),
    ],
    # query with the target image
    [
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_edgedetection_query_image.jpg'),
        None, # No image needed for the target image
    ],
]

# Task and content prompt
task_prompt = "Each row illustrates a pathway from [IMAGE1] a sharp and beautifully composed photograph to [IMAGE2] edge map with natural well-connected outlines using a clear logical task."
content_prompt = ""

# Run the pipeline
image_result = pipe(
    task_prompt=task_prompt,
    content_prompt=content_prompt,
    image=image_paths,
    upsampling_width=864,
    upsampling_height=1152,
    upsampling_strength=0.4,
    guidance_scale=30,
    num_inference_steps=30,
    max_sequence_length=512,
    generator=torch.Generator("cpu").manual_seed(0)
).images[0][0]

# Save the resulting image
image_result.save("visualcloze.png")
```

#### Exemplo para geração orientada por assunto

```python
import torch
from diffusers import VisualClozePipeline
from diffusers.utils import load_image

pipe = VisualClozePipeline.from_pretrained("VisualCloze/VisualClozePipeline-384", resolution=384, dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

# Load in-context images (make sure the paths are correct and accessible)
image_paths = [
    # in-context examples
    [
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_subjectdriven_incontext-example-1_reference.jpg'),
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_subjectdriven_incontext-example-1_depth.jpg'),
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_subjectdriven_incontext-example-1_image.jpg'),
    ],
    [
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_subjectdriven_incontext-example-2_reference.jpg'),
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_subjectdriven_incontext-example-2_depth.jpg'),
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_subjectdriven_incontext-example-2_image.jpg'),
    ],
    # query with the target image
    [
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_subjectdriven_query_reference.jpg'),
        load_image('https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_subjectdriven_query_depth.jpg'),
        None, # No image needed for the target image
    ],
]

# Task and content prompt
task_prompt = """Each row describes a process that begins with [IMAGE1] an image containing the key object, 
[IMAGE2] depth map revealing gray-toned spatial layers and results in 
[IMAGE3] an image with artistic qualitya high-quality image with exceptional detail."""
content_prompt = """A vintage porcelain collector's item. Beneath a blossoming cherry tree in early spring, 
this treasure is photographed up close, with soft pink petals drifting through the air and vibrant blossoms framing the scene."""

# Run the pipeline
image_result = pipe(
    task_prompt=task_prompt,
    content_prompt=content_prompt,
    image=image_paths,
    upsampling_width=1024,
    upsampling_height=1024,
    upsampling_strength=0.2,
    guidance_scale=30,
    num_inference_steps=30,
    max_sequence_length=512,
    generator=torch.Generator("cpu").manual_seed(0)
).images[0][0]

# Save the resulting image
image_result.save("visualcloze.png")
```

#### Utilize cada pipeline de forma independente 

```python
import torch
from diffusers import VisualClozeGenerationPipeline, FluxFillPipeline as VisualClozeUpsamplingPipeline
from diffusers.utils import load_image
from PIL import Image

pipe = VisualClozeGenerationPipeline.from_pretrained(
    "VisualCloze/VisualClozePipeline-384", resolution=384, dtype=torch.bfloat16
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

image_paths = [
    # in-context examples
    [
        load_image(
            "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_incontext-example-1_mask.jpg"
        ),
        load_image(
            "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_incontext-example-1_image.jpg"
        ),
    ],
    # query with the target image
    [
        load_image(
            "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_query_mask.jpg"
        ),
        None,  # No image needed for the target image
    ],
]
task_prompt = "In each row, a logical task is demonstrated to achieve [IMAGE2] an aesthetically pleasing photograph based on [IMAGE1] sam 2-generated masks with rich color coding."
content_prompt = "Majestic photo of a golden eagle perched on a rocky outcrop in a mountainous landscape. The eagle is positioned in the right foreground, facing left, with its sharp beak and keen eyes prominently visible. Its plumage is a mix of dark brown and golden hues, with intricate feather details. The background features a soft-focus view of snow-capped mountains under a cloudy sky, creating a serene and grandiose atmosphere. The foreground includes rugged rocks and patches of green moss. Photorealistic, medium depth of field, soft natural lighting, cool color palette, high contrast, sharp focus on the eagle, blurred background, tranquil, majestic, wildlife photography."

# Stage 1: Generate initial image
image = pipe(
    task_prompt=task_prompt,
    content_prompt=content_prompt,
    image=image_paths,
    guidance_scale=30,
    num_inference_steps=30,
    max_sequence_length=512,
    generator=torch.Generator("cpu").manual_seed(0),
).images[0][0]

# Stage 2 (optional): Upsample the generated image
pipe_upsample = VisualClozeUpsamplingPipeline.from_pipe(pipe)
pipe_upsample.to("cuda")

mask_image = Image.new("RGB", image.size, (255, 255, 255))

image = pipe_upsample(
    image=image,
    mask_image=mask_image,
    prompt=content_prompt,
    width=1344,
    height=768,
    strength=0.4,
    guidance_scale=30,
    num_inference_steps=30,
    max_sequence_length=512,
    generator=torch.Generator("cpu").manual_seed(0),
).images[0]

image.save("visualcloze.png")
```

## VisualClozePipeline[[diffusers.VisualClozePipeline]]

#### diffusers.VisualClozePipeline[[diffusers.VisualClozePipeline]]

```python
diffusers.VisualClozePipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, text_encoder_2: T5EncoderModel, tokenizer_2: T5Tokenizer, transformer: FluxTransformer2DModel, resolution: int = 384)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/visualcloze/pipeline_visualcloze_combined.py#L89)

**Parâmetros:**

transformer ([FluxTransformer2DModel](/docs/diffusers/main/pt/api/models/flux_transformer#diffusers.FluxTransformer2DModel)) : Arquitetura de Transformer condicional (MMDiT) para desruidar os latentes da imagem codificada.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Um scheduler a ser usado em combinação com `transformer` para desruidar os latentes da imagem codificada.

vae ([AutoencoderKL](/docs/diffusers/main/pt/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.

text_encoder (`CLIPTextModel`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel), especificamente a variante [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14).

text_encoder_2 (`T5EncoderModel`) : [T5](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5EncoderModel), especificamente a variante [google/t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl).

tokenizer (`CLIPTokenizer`) : Tokenizer da classe [CLIPTokenizer](https://huggingface.co/docs/transformers/en/model_doc/clip#transformers.CLIPTokenizer).

tokenizer_2 (`T5TokenizerFast`) : Segundo Tokenizer da classe [T5TokenizerFast](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5TokenizerFast).

resolution (`int`, *opcional*, padrão 384) : A resolução de cada imagem ao concatenar imagens da consulta e dos exemplos no contexto.

O pipeline VisualCloze para geração de imagens com contexto visual. Referência: https://github.com/lzyhha/VisualCloze/tree/main. Este pipeline foi projetado para gerar imagens com base em exemplos visuais em contexto.

#### __call__[[diffusers.VisualClozePipeline.__call__]]

```python
__call__(task_prompt: str | list[str] = None, content_prompt: str | list[str] = None, image: typing.Optional[torch.FloatTensor] = None, upsampling_height: int | None = None, upsampling_width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 30.0, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 512, upsampling_strength: float = 1.0)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/visualcloze/pipeline_visualcloze_combined.py#L252)

**Parâmetros:**

task_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para definir a intenção da tarefa.

content_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para definir o conteúdo ou a legenda da imagem de destino a ser gerada.

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]` ou `list[np.ndarray]`) : `Image`, array numpy ou tensor representando um lote de imagens a ser usado como ponto de partida. Para arrays numpy e tensors pytorch, o intervalo de valores esperado é entre `[0, 1]` Se for um tensor ou uma lista de tensors, a forma esperada deve ser `(B, C, H, W)` ou `(C, H, W)`. Se for um array numpy ou uma lista de arrays, a forma esperada deve ser `(B, H, W, C)` ou `(H, W, C)`.

upsampling_height (`int`, *opcional*, padrão é self.unet.config.sample_size * self.vae_scale_factor) : A altura em pixels da imagem gerada (ou seja, a imagem de saída) após o upsampling via SDEdit. Por padrão, a imagem é ampliada por um fator de três, e a resolução base é determinada pelo parâmetro de resolução do pipeline. Quando apenas um de `upsampling_height` ou `upsampling_width` é especificado, o outro será definido automaticamente com base na proporção de aspecto.

upsampling_width (`int`, *opcional*, padrão é self.unet.config.sample_size * self.vae_scale_factor) : A largura em pixels da imagem gerada (ou seja, a imagem de saída) após o upsampling via SDEdit. Por padrão, a imagem é ampliada por um fator de três, e a resolução base é determinada pelo parâmetro de resolução do pipeline. Quando apenas um de `upsampling_height` ou `upsampling_width` é especificado, o outro será definido automaticamente com base na proporção de aspecto.

num_inference_steps (`int`, *opcional*, padrão 50) : O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, em detrimento de uma inferência mais lenta.

sigmas (`list[float]`, *opcional*) : Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento `sigmas` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado.

guidance_scale (`float`, *opcional*, padrão 30.0) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://huggingface.co/papers/2205.11487). A escala de orientação é ativada ao definir `guidance_scale > 1`. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas ao `prompt` de texto, geralmente em detrimento de uma menor qualidade de imagem.

num_images_per_prompt (`int`, *opcional*, padrão 1) : O número de imagens a serem geradas por prompt.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um ou uma lista de [geradores do torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística.

latents (`torch.FloatTensor`, *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 será gerado por amostragem usando o `generator` aleatório fornecido.

prompt_embeds (`torch.FloatTensor`, *opcional*) : Emojis de texto pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os emojis de texto serão gerados a partir do argumento de entrada `prompt`.

pooled_prompt_embeds (`torch.FloatTensor`, *opcional*) : Embeddings de texto agrupados pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os embeddings de texto agrupados serão gerados a partir do argumento de entrada `prompt`.

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída da imagem gerada. Escolha entre [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` ou `np.array`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um `~pipelines.flux.FluxPipelineOutput` em vez de uma tupla simples.

joint_attention_kwargs (`dict`, *opcional*) : Um dicionário de kwargs que, se especificado, é passado para o `AttentionProcessor` conforme definido em `self.processor` em [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

callback_on_step_end (`Callable`, *opcional*) : Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` incluirá uma lista de todos os tensores, conforme especificado por `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *opcional*) : A lista de entradas de tensor para a função `callback_on_step_end`. Os tensores especificados na lista serão passados como argumento `callback_kwargs`. Você só poderá incluir variáveis listadas no atributo `._callback_tensor_inputs` da sua classe de pipeline.

max_sequence_length (`int` padrão é 512) : Comprimento máximo da sequência a ser usado com o `prompt`.

upsampling_strength (`float`, *opcional*, padrão 1.0) : Indica o grau de transformação da `image` de referência ao fazer o upsampling dos resultados. Deve estar entre 0 e 1. A imagem gerada é usada como ponto de partida e mais ruído é adicionado quanto maior for o `upsampling_strength`. O número de etapas de desruído depende da quantidade de ruído inicialmente adicionada. Quando `upsampling_strength` é 1, o ruído adicionado é máximo e o processo de desruído executa pelo número total de iterações especificado em `num_inference_steps`. Um valor de 0 ignora a etapa de upsampling e exibe os resultados na resolução de `self.resolution`.

**Retorna:** `~pipelines.flux.FluxPipelineOutput` ou `tuple`

`~pipelines.flux.FluxPipelineOutput` se `return_dict` for True, caso contrário, uma `tuple`. Ao retornar uma tupla, o primeiro elemento é uma lista com as imagens geradas.

Função invocada ao chamar o pipeline VisualCloze para geração.

Exemplos:
```python
>>> import torch
>>> from diffusers import VisualClozePipeline
>>> from diffusers.utils import load_image

>>> image_paths = [
...     # in-context examples
...     [
...         load_image(
...             "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_incontext-example-1_mask.jpg"
...         ),
...         load_image(
...             "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_incontext-example-1_image.jpg"
...         ),
...     ],
...     # query with the target image
...     [
...         load_image(
...             "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_query_mask.jpg"
...         ),
...         None,  # No image needed for the target image
...     ],
... ]
>>> task_prompt = "In each row, a logical task is demonstrated to achieve [IMAGE2] an aesthetically pleasing photograph based on [IMAGE1] sam 2-generated masks with rich color coding."
>>> content_prompt = "Majestic photo of a golden eagle perched on a rocky outcrop in a mountainous landscape. The eagle is positioned in the right foreground, facing left, with its sharp beak and keen eyes prominently visible. Its plumage is a mix of dark brown and golden hues, with intricate feather details. The background features a soft-focus view of snow-capped mountains under a cloudy sky, creating a serene and grandiose atmosphere. The foreground includes rugged rocks and patches of green moss. Photorealistic, medium depth of field, soft natural lighting, cool color palette, high contrast, sharp focus on the eagle, blurred background, tranquil, majestic, wildlife photography."
>>> pipe = VisualClozePipeline.from_pretrained(
...     "VisualCloze/VisualClozePipeline-384", resolution=384, torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")

>>> image = pipe(
...     task_prompt=task_prompt,
...     content_prompt=content_prompt,
...     image=image_paths,
...     upsampling_width=1344,
...     upsampling_height=768,
...     upsampling_strength=0.4,
...     guidance_scale=30,
...     num_inference_steps=30,
...     max_sequence_length=512,
...     generator=torch.Generator("cpu").manual_seed(0),
... ).images[0][0]
>>> image.save("visualcloze.png")
```

## VisualClozeGenerationPipeline[[diffusers.VisualClozeGenerationPipeline]]

#### diffusers.VisualClozeGenerationPipeline[[diffusers.VisualClozeGenerationPipeline]]

```python
diffusers.VisualClozeGenerationPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, text_encoder_2: T5EncoderModel, tokenizer_2: T5Tokenizer, transformer: FluxTransformer2DModel, resolution: int = 384)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/visualcloze/pipeline_visualcloze_generation.py#L118)

**Parâmetros:**

transformer ([FluxTransformer2DModel](/docs/diffusers/main/pt/api/models/flux_transformer#diffusers.FluxTransformer2DModel)) : Arquitetura de Transformer condicional (MMDiT) para desruidar os latentes da imagem codificada.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Um scheduler a ser usado em combinação com `transformer` para desruidar os latentes da imagem codificada.

vae ([AutoencoderKL](/docs/diffusers/main/pt/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.

text_encoder (`CLIPTextModel`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel), especificamente a variante [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14).

text_encoder_2 (`T5EncoderModel`) : [T5](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5EncoderModel), especificamente a variante [google/t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl).

tokenizer (`CLIPTokenizer`) : Tokenizer da classe [CLIPTokenizer](https://huggingface.co/docs/transformers/en/model_doc/clip#transformers.CLIPTokenizer).

tokenizer_2 (`T5TokenizerFast`) : Segundo Tokenizer da classe [T5TokenizerFast](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5TokenizerFast).

resolution (`int`, *opcional*, padrão 384) : A resolução de cada imagem ao concatenar imagens da consulta e dos exemplos no contexto.

O pipeline VisualCloze para geração de imagens com contexto visual. Referência: https://github.com/lzyhha/VisualCloze/tree/main Este pipeline foi projetado para gerar imagens com base em exemplos visuais em contexto.

#### __call__[[diffusers.VisualClozeGenerationPipeline.__call__]]

```python
__call__(task_prompt: str | list[str] = None, content_prompt: str | list[str] = None, image: typing.Optional[torch.FloatTensor] = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 30.0, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 512)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/visualcloze/pipeline_visualcloze_generation.py#L659)

**Parâmetros:**

task_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para definir a intenção da tarefa.

content_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para definir o conteúdo ou a legenda da imagem de destino a ser gerada.

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]` ou `list[np.ndarray]`) : `Image`, array numpy ou tensor representando um lote de imagens a ser usado como ponto de partida. Para arrays numpy e tensors pytorch, o intervalo de valores esperado é entre `[0, 1]` Se for um tensor ou uma lista de tensors, a forma esperada deve ser `(B, C, H, W)` ou `(C, H, W)`. Se for um array numpy ou uma lista de arrays, a forma esperada deve ser `(B, H, W, C)` ou `(H, W, C)`.

num_inference_steps (`int`, *opcional*, padrão 50) : O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, em detrimento de uma inferência mais lenta.

sigmas (`list[float]`, *opcional*) : Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento `sigmas` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado.

guidance_scale (`float`, *opcional*, padrão 30.0) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://huggingface.co/papers/2205.11487). A escala de orientação é ativada ao definir `guidance_scale > 1`. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas ao `prompt` de texto, geralmente em detrimento de uma menor qualidade de imagem.

num_images_per_prompt (`int`, *opcional*, padrão 1) : O número de imagens a serem geradas por prompt.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um ou uma lista de [geradores do torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística.

latents (`torch.FloatTensor`, *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 será gerado por amostragem usando o `generator` aleatório fornecido.

prompt_embeds (`torch.FloatTensor`, *opcional*) : Emojis de texto pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os emojis de texto serão gerados a partir do argumento de entrada `prompt`.

pooled_prompt_embeds (`torch.FloatTensor`, *opcional*) : Embeddings de texto agrupados pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os embeddings de texto agrupados serão gerados a partir do argumento de entrada `prompt`.

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída da imagem gerada. Escolha entre `"pil"` ([PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image`), `"np"` (`np.array`) ou `"pt"` (`torch.Tensor`).

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um `~pipelines.flux.FluxPipelineOutput` em vez de uma tupla simples.

joint_attention_kwargs (`dict`, *opcional*) : Um dicionário de kwargs que, se especificado, é passado para o `AttentionProcessor` conforme definido em `self.processor` em [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

callback_on_step_end (`Callable`, *opcional*) : Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` incluirá uma lista de todos os tensores, conforme especificado por `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *opcional*) : A lista de entradas de tensor para a função `callback_on_step_end`. Os tensores especificados na lista serão passados como argumento `callback_kwargs`. Você só poderá incluir variáveis listadas no atributo `._callback_tensor_inputs` da sua classe de pipeline.

max_sequence_length (`int` padrão é 512) : Comprimento máximo da sequência a ser usado com o `prompt`.

**Retorna:** `~pipelines.flux.FluxPipelineOutput` ou `tuple`

`~pipelines.flux.FluxPipelineOutput` se `return_dict` for True, caso contrário, uma `tuple`. Ao retornar uma tupla, o primeiro elemento é uma lista com as imagens geradas.

Função invocada ao chamar o pipeline VisualCloze para geração.

Exemplos:
```python
>>> import torch
>>> from diffusers import VisualClozeGenerationPipeline, FluxFillPipeline as VisualClozeUpsamplingPipeline
>>> from diffusers.utils import load_image
>>> from PIL import Image

>>> image_paths = [
...     # in-context examples
...     [
...         load_image(
...             "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_incontext-example-1_mask.jpg"
...         ),
...         load_image(
...             "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_incontext-example-1_image.jpg"
...         ),
...     ],
...     # query with the target image
...     [
...         load_image(
...             "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/visualcloze/visualcloze_mask2image_query_mask.jpg"
...         ),
...         None,  # No image needed for the target image
...     ],
... ]
>>> task_prompt = "In each row, a logical task is demonstrated to achieve [IMAGE2] an aesthetically pleasing photograph based on [IMAGE1] sam 2-generated masks with rich color coding."
>>> content_prompt = "Majestic photo of a golden eagle perched on a rocky outcrop in a mountainous landscape. The eagle is positioned in the right foreground, facing left, with its sharp beak and keen eyes prominently visible. Its plumage is a mix of dark brown and golden hues, with intricate feather details. The background features a soft-focus view of snow-capped mountains under a cloudy sky, creating a serene and grandiose atmosphere. The foreground includes rugged rocks and patches of green moss. Photorealistic, medium depth of field, soft natural lighting, cool color palette, high contrast, sharp focus on the eagle, blurred background, tranquil, majestic, wildlife photography."
>>> pipe = VisualClozeGenerationPipeline.from_pretrained(
...     "VisualCloze/VisualClozePipeline-384", resolution=384, torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")

>>> image = pipe(
...     task_prompt=task_prompt,
...     content_prompt=content_prompt,
...     image=image_paths,
...     guidance_scale=30,
...     num_inference_steps=30,
...     max_sequence_length=512,
...     generator=torch.Generator("cpu").manual_seed(0),
... ).images[0][0]

>>> # optional, upsampling the generated image
>>> pipe_upsample = VisualClozeUpsamplingPipeline.from_pipe(pipe)
>>> pipe_upsample.to("cuda")

>>> mask_image = Image.new("RGB", image.size, (255, 255, 255))

>>> image = pipe_upsample(
...     image=image,
...     mask_image=mask_image,
...     prompt=content_prompt,
...     width=1344,
...     height=768,
...     strength=0.4,
...     guidance_scale=30,
...     num_inference_steps=30,
...     max_sequence_length=512,
...     generator=torch.Generator("cpu").manual_seed(0),
... ).images[0]

>>> image.save("visualcloze.png")
```

#### encode_prompt[[diffusers.VisualClozeGenerationPipeline.encode_prompt]]

```python
encode_prompt(layout_prompt: str | list[str], task_prompt: str | list[str], content_prompt: str | list[str], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.FloatTensor] = None, pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None, max_sequence_length: int = 512, lora_scale: float | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/visualcloze/pipeline_visualcloze_generation.py#L292)

**Parâmetros:**

layout_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para definir o número de exemplos em contexto e o número de imagens envolvidas na tarefa.

task_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para definir a intenção da tarefa.

content_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para definir o conteúdo ou a legenda da imagem de destino a ser gerada.

device : (`torch.device`): dispositivo torch

num_images_per_prompt (`int`) : número de imagens que devem ser geradas por prompt

prompt_embeds (`torch.FloatTensor`, *opcional*) : Emojis de texto pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os emojis de texto serão gerados a partir do argumento de entrada `prompt`.

pooled_prompt_embeds (`torch.FloatTensor`, *opcional*) : Embeddings de texto agrupados pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os embeddings de texto agrupados serão gerados a partir do argumento de entrada `prompt`.

lora_scale (`float`, *opcional*) : Uma escala lora que será aplicada a todas as camadas LoRA do text encoder, caso as camadas LoRA sejam carregadas.