# Marigold Visão Computacional

![marigold](https://marigoldmonodepth.github.io/images/teaser_collage_compressed.jpg)

Marigold foi proposto em [Repurposing Diffusion-Based Image Generators for Monocular Depth Estimation](https://huggingface.co/papers/2312.02145), um paper Oral do CVPR 2024 de [Bingxin Ke](http://www.kebingxin.com/), [Anton Obukhov](https://www.obukhov.ai/), [Shengyu Huang](https://shengyuh.github.io/), [Nando Metzger](https://nandometzger.github.io/), [Rodrigo Caye Daudt](https://rcdaudt.github.io/) e [Konrad Schindler](https://scholar.google.com/citations?user=FZuNgqIAAAAJ&hl=en). A ideia central é **reaproveitar o prior generativo dos Text-to-Image Latent Diffusion Models (LDMs) para tarefas tradicionais de visão computacional**. Essa abordagem foi explorada por meio do fine-tuning do Stable Diffusion para **Monocular Depth Estimation**, conforme demonstrado no teaser acima.

Marigold foi posteriormente estendido no artigo de acompanhamento, [Marigold: Affordable Adaptation of Diffusion-Based Image Generators for Image Analysis](https://huggingface.co/papers/2312.02145), escrito por [Bingxin Ke](http://www.kebingxin.com/), [Kevin Qu](https://www.linkedin.com/in/kevin-qu-b3417621b/?locale=en_US), [Tianfu Wang](https://tianfwang.github.io/), [Nando Metzger](https://nandometzger.github.io/), [Shengyu Huang](https://shengyuh.github.io/), [Bo Li](https://www.linkedin.com/in/bobboli0202/), [Anton Obukhov](https://www.obukhov.ai/) e [Konrad Schindler](https://scholar.google.com/citations?user=FZuNgqIAAAAJ&hl=en). Este trabalho expandiu o Marigold para suportar novas modalidades, como **Surface Normals** e **Intrinsic Image Decomposition** (IID), introduziu um protocolo de treinamento para **Latent Consistency Models** (LCM) e demonstrou a capacidade de processamento em **High-Resolution** (HR).

> [!TIP]
> Os modelos iniciais do Marigold (`v1-0` e anteriores) foram otimizados para obter os melhores resultados com pelo menos 10 etapas de inferência. Os modelos LCM foram desenvolvidos posteriormente para permitir inferência de alta qualidade em apenas 1 a 4 etapas. Os modelos Marigold `v1-1` e posteriores usam o agendador DDIM para alcançar resultados ótimos em tão poucas quanto 1 a 4 etapas.

## Pipelines Disponíveis

Cada pipeline é adaptado para uma tarefa específica de visão computacional, processando uma imagem RGB de entrada e gerando uma previsão correspondente. Atualmente, as seguintes tarefas de visão computacional estão implementadas:

| Pipeline                                                                                                                                          | Pontos de verificação de modelos recomendados                                                                                                                                                                           |                              Spaces (Aplicativos Interativos)                               | Modalidades previstas                                                                                                                                                               |
|---------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [MarigoldDepthPipeline](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/marigold/pipeline_marigold_depth.py)           | [prs-eth/marigold-depth-v1-1](https://huggingface.co/prs-eth/marigold-depth-v1-1)                                                                                                                       |          [Estimativa de Profundidade](https://huggingface.co/spaces/prs-eth/marigold)          | [Profundidade](https://en.wikipedia.org/wiki/Depth_map), [Disparidade](https://en.wikipedia.org/wiki/Binocular_disparity)                                                                   |
| [MarigoldNormalsPipeline](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/marigold/pipeline_marigold_normals.py)       | [prs-eth/marigold-normals-v1-1](https://huggingface.co/prs-eth/marigold-normals-v1-1)                                                                                                                   | [Estimação de Normais de Superfície](https://huggingface.co/spaces/prs-eth/marigold-normals) | [Normais de superfície](https://en.wikipedia.org/wiki/Normal_mapping)                                                                                                                    |
| [MarigoldIntrinsicsPipeline](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/marigold/pipeline_marigold_intrinsics.py) | [prs-eth/marigold-iid-appearance-v1-1](https://huggingface.co/prs-eth/marigold-iid-appearance-v1-1),[prs-eth/marigold-iid-lighting-v1-1](https://huggingface.co/prs-eth/marigold-iid-lighting-v1-1) | [Decomposição de Imagem Intrínseca](https://huggingface.co/spaces/prs-eth/marigold-iid)  | [Albedo](https://en.wikipedia.org/wiki/Albedo), [Materiais](https://www.n.aiq3d.com/wiki/roughnessmetalnessao-map), [Iluminação](https://en.wikipedia.org/wiki/Diffuse_reflection)   |

## Checkpoints Disponíveis

Todos os checkpoints originais estão disponíveis sob a organização [PRS-ETH](https://huggingface.co/prs-eth/) no Hugging Face. Eles foram projetados para uso com pipelines de diffusers e o [original codebase](https://github.com/prs-eth/marigold), que também pode ser usado para treinar novos checkpoints de modelos. A seguir, há um resumo dos checkpoints recomendados, todos os quais produzem resultados confiáveis com 1 a 4 etapas.

| Checkpoint                                                                                          | Modalidade     | Comentário                                                                                                                                                                              |
|-----------------------------------------------------------------------------------------------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [prs-eth/marigold-depth-v1-1](https://huggingface.co/prs-eth/marigold-depth-v1-1)                   | Profundidade        | A predição de profundidade invariante por afinidade atribui a cada pixel um valor entre 0 (plano próximo) e 1 (plano distante), sendo ambos os planos determinados pelo modelo durante a inferência.                    |
| [prs-eth/marigold-normals-v0-1](https://huggingface.co/prs-eth/marigold-normals-v0-1)               | Normais      | As previsões de normais de superfície são vetores 3D de comprimento unitário no espaço de tela da câmera, com valores no intervalo de -1 a 1.                                                        |
| [prs-eth/marigold-iid-appearance-v1-1](https://huggingface.co/prs-eth/marigold-iid-appearance-v1-1) | Intrínsecos   | A decomposição do InteriorVerse é composta por Albedo e duas propriedades de material BRDF: Roughness e Metallicity.                                                                      |
| [prs-eth/marigold-iid-lighting-v1-1](https://huggingface.co/prs-eth/marigold-iid-lighting-v1-1)     | Intrínsecos   | A decomposição do HyperSim de uma imagem $I$ é composta por Albedo $A$, Sombreamento difuso $S$ e Resíduo não-difuso $R$: $I = A*S+R$. |

> [!TIP]
> Certifique-se de consultar o [guia](../../using-diffusers/schedulers) de Schedulers para aprender a explorar o compromisso entre a velocidade e a qualidade do scheduler, e veja a seção [reutilização de componentes entre pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) para aprender a carregar eficientemente os mesmos componentes em vários pipelines. Além disso, para saber mais sobre a redução do uso de memória deste pipeline, consulte a seção ["Reduce memory usage"] [aqui](./stable_diffusion/svd#reduce-memory-usage).

> [!WARNING]
> Os pipelines do Marigold foram projetados e testados com o scheduler embutido no checkpoint do modelo. O número ideal de etapas de inferência varia conforme o scheduler, não havendo um valor universal que funcione melhor em todos os casos. Para acomodar isso, o parâmetro `num_inference_steps` no método `__call__` do pipeline tem como padrão `None` (consulte a referência da API). A menos que seja definido explicitamente, ele herda o valor do campo `default_denoising_steps` no arquivo de configuração do checkpoint (`model_index.json`). Isso garante previsões de alta qualidade ao invocar o pipeline apenas com o argumento `image`.

Os exemplos abaixo são fornecidos principalmente para predição de profundidade, mas podem ser aplicados universalmente a outras modalidades suportadas. Apresentamos as predições usando a mesma imagem de entrada de Albert Einstein gerada pelo Midjourney. Isso facilita a comparação das visualizações das predições entre as diversas modalidades e checkpoints.

  
    
    
      Imagem de exemplo de entrada para todos os pipelines do Marigold
    
  

## Previsão de Profundidade

Para obter uma previsão de profundidade, carregue o checkpoint `prs-eth/marigold-depth-v1-1` no [MarigoldDepthPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.MarigoldDepthPipeline), processe a imagem pelo pipeline e salve as previsões:

```python
import diffusers
import torch

pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
    "prs-eth/marigold-depth-v1-1", variant="fp16", dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"

image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

depth = pipe(image)

vis = pipe.image_processor.visualize_depth(depth.prediction)
vis[0].save("einstein_depth.png")

depth_16bit = pipe.image_processor.export_depth_to_16bit_png(depth.prediction)
depth_16bit[0].save("einstein_depth_16bit.png")
```

A função [visualize_depth()](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_depth) aplica um dos [colormaps do matplotlib](https://matplotlib.org/stable/users/explain/colors/colormaps.html) (`Spectral` por padrão) para mapear os valores de pixels previstos de uma faixa de profundidade de canal único `[0, 1]` para uma imagem RGB. Com o colormap `Spectral`, pixels com profundidade próxima são pintados de vermelho e pixels distantes são azuis. O arquivo PNG de 16 bits armazena os valores de canal único mapeados linearmente da faixa `[0, 1]` para `[0, 65535]`. Abaixo estão as previsões brutas e as visualizadas. As áreas mais escuras e próximas (bigode) são mais fáceis de distinguir na visualização.

  
    
    
      Profundidade prevista (PNG de 16 bits)
    
  
  
    
    
      Visualização da profundidade prevista (Espectral)
    
  

## Estimação de Normais de Superfície

Carregue o checkpoint `prs-eth/marigold-normals-v1-1` no [MarigoldNormalsPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.MarigoldNormalsPipeline), processe a imagem pelo pipeline e salve as previsões:

```python
import diffusers
import torch

pipe = diffusers.MarigoldNormalsPipeline.from_pretrained(
    "prs-eth/marigold-normals-v1-1", variant="fp16", dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"

image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

normals = pipe(image)

vis = pipe.image_processor.visualize_normals(normals.prediction)
vis[0].save("einstein_normals.png")
```

A função [visualize_normals()](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_normals) mapeia a predição tridimensional com valores de pixel no intervalo `[-1, 1]` para uma imagem RGB. A função de visualização suporta a inversão dos eixos dos vetores normais da superfície para tornar a visualização compatível com outras escolhas do sistema de referência. Conceitualmente, cada pixel é pintado de acordo com o vetor normal da superfície no sistema de referência, em que o eixo `X` aponta para a direita, o eixo `Y` aponta para cima e o eixo `Z` aponta para o observador. Abaixo está a predição visualizada:

  
    
    
      Visualização dos normais de superfície previstos
    
  

Neste exemplo, a ponta do nariz quase certamente tem um ponto na superfície, no qual o vetor normal da superfície aponta diretamente para o observador, o que significa que suas coordenadas são `[0, 0, 1]`. Esse vetor é mapeado para o RGB `[128, 128, 255]`, que corresponde à cor violeta-azulada. Da mesma forma, uma normal de superfície na bochecha, na parte direita da imagem, tem uma grande componente `X`, o que aumenta a tonalidade vermelha. Pontos nos ombros apontando para cima com uma grande `Y` promovem a cor verde.

## Decomposição de Imagem Intrínseca

Marigold fornece dois modelos para Decomposição de Imagem Intrínseca (IID): "Appearance" e "Lighting". Cada modelo produz mapas de Albedo, derivados das anotações de InteriorVerse e Hypersim, respectivamente.

- O modelo "Appearance" também estima as propriedades de Material: Roughness e Metallicity.
- O modelo "Lighting" gera o Sombreamento Difuso e o Resíduo Não-difuso.

Aqui está o código de exemplo que salva as previsões feitas pelo modelo "Appearance":

```python
import diffusers
import torch

pipe = diffusers.MarigoldIntrinsicsPipeline.from_pretrained(
    "prs-eth/marigold-iid-appearance-v1-1", variant="fp16", dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"

image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

intrinsics = pipe(image)

vis = pipe.image_processor.visualize_intrinsics(intrinsics.prediction, pipe.target_properties)
vis[0]["albedo"].save("einstein_albedo.png")
vis[0]["roughness"].save("einstein_roughness.png")
vis[0]["metallicity"].save("einstein_metallicity.png")
```

Outro exemplo demonstrando as previsões feitas pelo modelo "Lighting":

```python
import diffusers
import torch

pipe = diffusers.MarigoldIntrinsicsPipeline.from_pretrained(
    "prs-eth/marigold-iid-lighting-v1-1", variant="fp16", dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"

image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

intrinsics = pipe(image)

vis = pipe.image_processor.visualize_intrinsics(intrinsics.prediction, pipe.target_properties)
vis[0]["albedo"].save("einstein_albedo.png")
vis[0]["shading"].save("einstein_shading.png")
vis[0]["residual"].save("einstein_residual.png")
```

Ambos os modelos compartilham o mesmo pipeline, mas suportam diferentes tipos de decomposição. A parametrização exata da decomposição (por exemplo, espaço sRGB vs. espaço linear) é armazenada no dicionário `pipe.target_properties`, que é passado para a função [visualize_intrinsics()](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_intrinsics).

Abaixo estão alguns exemplos que mostram as saídas de decomposição previstas. Todas as modalidades podem ser inspecionadas no Space [Intrinsic Image Decomposition](https://huggingface.co/spaces/prs-eth/marigold-iid).

  
    
    
      Albedo previsto (modelo "Aparência")
    
  
  
    
    
      Sombreamento difuso previsto (modelo "Lighting")
    
  

## Acelerando a inferência

Os trechos de início rápido acima já estão otimizados para qualidade e velocidade, carregando o checkpoint, utilizando a variante `fp16` dos pesos e da computação, e executando o número padrão (4) de etapas de difusão de desruido. O primeiro passo para acelerar a inferência, às custas da qualidade da previsão, é reduzir as etapas de difusão de desruido ao mínimo:

```diff
  import diffusers
  import torch

  pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
      "prs-eth/marigold-depth-v1-1", variant="fp16", dtype=torch.float16
  ).to("cuda")  # or "mps", "xpu", "cpu"

  image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")
  
- depth = pipe(image)
+ depth = pipe(image, num_inference_steps=1)
```

Com essa alteração, a chamada `pipe` é concluída em 280ms em uma GPU RTX 3090. Internamente, a imagem de entrada é primeiro codificada usando o codificador VAE do Stable Diffusion, seguida por uma única etapa de desruidamento executada pelo U-Net. Por fim, o latente da previsão é decodificado com o decodificador VAE para o espaço de pixels. Nesse setup, duas das três chamadas de módulos são dedicadas à conversão entre os espaços de pixels e latentes do LDM. Como o espaço latente do Marigold é compatível com o Stable Diffusion 2.0, a inferência pode ser acelerada em mais de 3x, reduzindo o tempo de chamada para 85ms em uma RTX 3090, ao usar um [substituto leve do VAE do SD](../models/autoencoder_tiny). Observe que o uso de um VAE leve pode reduzir ligeiramente a qualidade visual das previsões.

```diff
  import diffusers
  import torch

  pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
      "prs-eth/marigold-depth-v1-1", variant="fp16", dtype=torch.float16
  ).to("cuda")  # or "mps", "xpu", "cpu"

+ pipe.vae = diffusers.AutoencoderTiny.from_pretrained(
+     "madebyollin/taesd", dtype=torch.float16
+ ).cuda()

  image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

  depth = pipe(image, num_inference_steps=1)
```

Até agora, otimizamos o número de passos de difusão e os componentes do modelo. As operações de autoatenção representam uma parte significativa dos cálculos. Acelerar essas operações pode ser feito usando um processador de atenção mais eficiente:

```diff
  import diffusers
  import torch
+ from diffusers.models.attention_processor import AttnProcessor2_0

  pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
      "prs-eth/marigold-depth-v1-1", variant="fp16", dtype=torch.float16
  ).to("cuda")  # or "mps", "xpu", "cpu"

+ pipe.vae.set_attn_processor(AttnProcessor2_0()) 
+ pipe.unet.set_attn_processor(AttnProcessor2_0())

  image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

  depth = pipe(image, num_inference_steps=1)
```

Por fim, conforme sugerido em [Otimizações](../../optimization/fp16#torchcompile), habilitar `torch.compile` pode aprimorar ainda mais o desempenho, dependendo do hardware de destino. No entanto, a compilação gera um sobrecusto significativo durante a primeira invocação do pipeline, tornando-a vantajosa apenas quando a mesma instância do pipeline é chamada repetidamente, como dentro de um loop.

```diff
  import diffusers
  import torch
  from diffusers.models.attention_processor import AttnProcessor2_0

  pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
      "prs-eth/marigold-depth-v1-1", variant="fp16", dtype=torch.float16
  ).to("cuda")  # or "mps", "xpu", "cpu"

  pipe.vae.set_attn_processor(AttnProcessor2_0()) 
  pipe.unet.set_attn_processor(AttnProcessor2_0())

+ pipe.vae = torch.compile(pipe.vae, mode="reduce-overhead", fullgraph=True)
+ pipe.unet = torch.compile(pipe.unet, mode="reduce-overhead", fullgraph=True)

  image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

  depth = pipe(image, num_inference_steps=1)
```

## Maximizando a Precisão e Ensembling

Os pipelines do Marigold possuem um mecanismo de ensembling embutido que combina múltiplas previsões de diferentes latentes aleatórios. Essa é uma abordagem de força bruta para melhorar a precisão das previsões, aproveitando a natureza generativa da difusão. O caminho de ensembling é ativado automaticamente quando o argumento `ensemble_size` é definido com um valor maior ou igual a `3`. Ao buscar a máxima precisão, faz sentido ajustar `num_inference_steps` simultaneamente com `ensemble_size`. Os valores recomendados variam entre checkpoints, mas dependem principalmente do tipo de scheduler. O efeito do ensembling é particularmente bem observado com normais de superfície:

```diff
  import diffusers

  pipe = diffusers.MarigoldNormalsPipeline.from_pretrained("prs-eth/marigold-normals-v1-1").to("cuda")  # or "mps", "xpu", "cpu"

  image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

- depth = pipe(image)
+ depth = pipe(image, num_inference_steps=10, ensemble_size=5)

  vis = pipe.image_processor.visualize_normals(depth.prediction)
  vis[0].save("einstein_normals.png")
```

  
    
    
      Normais de superfície, sem ensembling
    
  
  
    
    
      Normais de superfície, com ensembling
    
  

Como pode ser observado, todas as áreas com estruturas de granulação fina, como o cabelo, obtiveram previsões mais conservadoras e, em média, mais corretas. Tal resultado é mais adequado para tarefas de nível inferior sensíveis à precisão, como a reconstrução 3D.

## Processamento de Vídeo Quadro a Quadro com Consistência Temporal

Devido à natureza generativa do Marigold, cada previsão é única e definida pelo ruído aleatório amostrado para a inicialização latente. Isso se torna uma desvantagem óbvia em comparação com as redes de regressão densa de ponta a ponta tradicionais, conforme exemplificado nos vídeos a seguir:

  
    
    Vídeo de entrada
  
  
    
    Marigold Depth aplicado independentemente aos quadros de vídeo de entrada
  

Para resolver esse problema, é possível passar o argumento `latents` para os pipelines, que define o ponto de partida da difusão. Empiricamente, descobrimos que uma combinação convexa do mesmo ruído latente de ponto de partida e do latente correspondente à previsão do quadro anterior produz resultados suficientemente suaves, conforme implementado no trecho abaixo:

```python
import imageio
import diffusers
import torch
from diffusers.models.attention_processor import AttnProcessor2_0
from PIL import Image
from tqdm import tqdm

device = "cuda"  # or "mps", "xpu", "cpu"
path_in = "https://huggingface.co/spaces/prs-eth/marigold-lcm/resolve/c7adb5427947d2680944f898cd91d386bf0d4924/files/video/obama.mp4"
path_out = "obama_depth.gif"

pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
    "prs-eth/marigold-depth-v1-1", variant="fp16", dtype=torch.float16
).to(device)
pipe.vae = diffusers.AutoencoderTiny.from_pretrained(
    "madebyollin/taesd", dtype=torch.float16
).to(device)
pipe.unet.set_attn_processor(AttnProcessor2_0())
pipe.vae = torch.compile(pipe.vae, mode="reduce-overhead", fullgraph=True)
pipe.unet = torch.compile(pipe.unet, mode="reduce-overhead", fullgraph=True)
pipe.set_progress_bar_config(disable=True)

with imageio.get_reader(path_in) as reader:
    size = reader.get_meta_data()['size']
    last_frame_latent = None
    latent_common = torch.randn(
        (1, 4, 768 * size[1] // (8 * max(size)), 768 * size[0] // (8 * max(size)))
    ).to(device=device, dtype=torch.float16)

    out = []
    for frame_id, frame in tqdm(enumerate(reader), desc="Processing Video"):
        frame = Image.fromarray(frame)
        latents = latent_common
        if last_frame_latent is not None:
            latents = 0.9 * latents + 0.1 * last_frame_latent

        depth = pipe(
            frame,
            num_inference_steps=1,
            match_input_resolution=False, 
            latents=latents, 
            output_latent=True,
        )
        last_frame_latent = depth.latent
        out.append(pipe.image_processor.visualize_depth(depth.prediction)[0])

    diffusers.utils.export_to_gif(out, path_out, fps=reader.get_meta_data()['fps'])
```

Aqui, o processo de difusão começa a partir do latente computado fornecido. O pipeline define `output_latent=True` para acessar `out.latent` e computa sua contribuição para a inicialização do latente do próximo quadro. O resultado agora é muito mais estável:

  
    
    Marigold Depth aplicado independentemente aos quadros de vídeo de entrada
  
  
    
    Marigold Depth com inicialização forçada de latentes
  

## Marigold para ControlNet

Um aplicativo muito comum para a predição de profundidade com modelos de difusão é o uso em conjunto com o ControlNet. A nitidez da profundidade desempenha um papel crucial na obtenção de resultados de alta qualidade do ControlNet. Como visto nas comparações com outros métodos acima, o Marigold se destaca nessa tarefa. O trecho abaixo demonstra como carregar uma imagem, calcular a profundidade e passá-la para o ControlNet em um formato compatível:

```python
import torch
import diffusers

device = "cuda"  # or "mps", "xpu", "cpu"
generator = torch.Generator(device=device).manual_seed(2024)
image = diffusers.utils.load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/controlnet_depth_source.png"
)

pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
    "prs-eth/marigold-depth-v1-1", dtype=torch.float16, variant="fp16"
).to(device)

depth_image = pipe(image, generator=generator).prediction
depth_image = pipe.image_processor.visualize_depth(depth_image, color_map="binary")
depth_image[0].save("motorcycle_controlnet_depth.png")

controlnet = diffusers.ControlNetModel.from_pretrained(
    "diffusers/controlnet-depth-sdxl-1.0", dtype=torch.float16, variant="fp16"
).to(device)
pipe = diffusers.StableDiffusionXLControlNetPipeline.from_pretrained(
    "SG161222/RealVisXL_V4.0", dtype=torch.float16, variant="fp16", controlnet=controlnet
).to(device)
pipe.scheduler = diffusers.DPMSolverMultistepScheduler.from_config(pipe.scheduler.config, use_karras_sigmas=True)

controlnet_out = pipe(
    prompt="high quality photo of a sports bike, city",
    negative_prompt="",
    guidance_scale=6.5,
    num_inference_steps=25,
    image=depth_image,
    controlnet_conditioning_scale=0.7,
    control_guidance_end=0.7,
    generator=generator,
).images
controlnet_out[0].save("motorcycle_controlnet_out.png")
```

  
    
    
      Imagem de entrada
    
  
  
    
    
      Profundidade no formato compatível com ControlNet
    
  
  
    
    
      Geração do ControlNet, condicionada em profundidade e prompt: "high quality photo of a sports bike, city"
    
  

## Avaliação Quantitativa

Para avaliar o Marigold quantitativamente em rankings e benchmarks padrão (como NYU, KITTI e outros conjuntos de dados), siga o protocolo de avaliação descrito no artigo: carregue o modelo de precisão completa fp32 e use valores apropriados para `num_inference_steps` e `ensemble_size`. Opcionalmente, defina a semente de aleatoriedade para garantir reprodutibilidade. Maximizar `batch_size` resultará no máximo uso do dispositivo.

```python
import diffusers
import torch

device = "cuda"  # or "mps", "xpu", "cpu"
seed = 2024

generator = torch.Generator(device=device).manual_seed(seed)
pipe = diffusers.MarigoldDepthPipeline.from_pretrained("prs-eth/marigold-depth-v1-1").to(device)

image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

depth = pipe(
    image, 
    num_inference_steps=4,  # set according to the evaluation protocol from the paper
    ensemble_size=10,       # set according to the evaluation protocol from the paper
    generator=generator,
)

# evaluate metrics
```

## Usando Incerteza Preditiva

O mecanismo de ensembling incorporado aos pipelines do Marigold combina múltiplas previsões obtidas a partir de diferentes latentes aleatórios. Como efeito colateral, ele pode ser usado para quantificar a incerteza epistêmica (do modelo); basta especificar `ensemble_size` maior ou igual a 3 e definir `output_uncertainty=True`. A incerteza resultante estará disponível no campo `uncertainty` da saída. Ela pode ser visualizada da seguinte forma:

```python
import diffusers
import torch

pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
    "prs-eth/marigold-depth-v1-1", variant="fp16", dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"

image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")

depth = pipe(
	image,
	ensemble_size=10,  # any number >= 3
	output_uncertainty=True,
)

uncertainty = pipe.image_processor.visualize_uncertainty(depth.uncertainty)
uncertainty[0].save("einstein_depth_uncertainty.png")
```

  
    
    
      Incerteza de profundidade
    
  
  
    
    
      Incerteza dos vetores normais
    
  
  
    
    
      Incerteza do albedo
    
  

A interpretação da incerteza é simples: valores mais altos (branco) correspondem a pixels em que o modelo tem dificuldade em fazer previsões consistentes.
- O modelo de profundidade apresenta a maior incerteza em torno de descontinuidades, onde a profundidade do objeto muda abruptamente.
- O modelo de normais de superfície tem a menor confiança em estruturas de grão fino, como cabelo, e em regiões escuras, como
área do colarinho.
- A incerteza do albedo é representada como uma imagem RGB, pois captura a incerteza de forma independente para cada canal de cor,
diferente da profundidade e das normais de superfície. Ele também é maior em regiões sombreadas e em descontinuidades.

## API de Predição de Profundidade Marigold[[diffusers.MarigoldDepthPipeline]]

#### diffusers.MarigoldDepthPipeline[[diffusers.MarigoldDepthPipeline]]

```python
diffusers.MarigoldDepthPipeline(unet: UNet2DConditionModel, vae: AutoencoderKL, scheduler: diffusers.schedulers.scheduling_ddim.DDIMScheduler | diffusers.schedulers.scheduling_lcm.LCMScheduler, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, prediction_type: str | None = None, scale_invariant: bool | None = True, shift_invariant: bool | None = True, default_denoising_steps: int | None = None, default_processing_resolution: int | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/pipeline_marigold_depth.py#L104)

**Parâmetros:**

unet (`UNet2DConditionModel`) : U-Net condicional para desruidar o latente de profundidade, condicionado ao latente de imagem.

vae (`AutoencoderKL`) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens e previsões para e a partir de representações latentes.

scheduler (`DDIMScheduler` ou `LCMScheduler`) : Um scheduler a ser usado em combinação com `unet` para desruidar os latentes da imagem codificada.

text_encoder (`CLIPTextModel`) : Codificador de texto, para incorporação de texto vazio.

tokenizer (`CLIPTokenizer`) : Tokenizador do CLIP.

prediction_type (`str`, *opcional*) : Tipo de previsões feitas pelo modelo.

scale_invariant (`bool`, *opcional*) : Uma propriedade do modelo que especifica se os mapas de profundidade previstos são invariantes em relação à escala. Este valor deve ser definido na configuração do modelo. Quando usado em conjunto com a flag `shift_invariant=True`, o modelo também é chamado de "invariante afim". Obs.: a substituição deste valor não é suportada.

shift_invariant (`bool`, *opcional*) : Uma propriedade do modelo que especifica se os mapas de profundidade previstos são invariantes a deslocamento. Este valor deve ser definido na configuração do modelo. Quando usado em conjunto com a flag `scale_invariant=True`, o modelo também é chamado de "invariante a afinidade". Obs.: a substituição deste valor não é suportada.

default_denoising_steps (`int`, *opcional*) : O número mínimo de etapas de difusão de desruido necessárias para produzir uma previsão de qualidade razoável com o modelo dado. Esse valor deve ser definido na configuração do modelo. Quando o pipeline é chamado sem definir explicitamente `num_inference_steps`, o valor padrão é utilizado. Isso é necessário para garantir resultados razoáveis com as diversas variações de modelos compatíveis com o pipeline, como aquelas que dependem de agendamentos de desruido muito curtos (`LCMScheduler`) e aquelas com agendamentos de difusão completos (`DDIMScheduler`).

default_processing_resolution (`int`, *opcional*) : O valor recomendado do parâmetro `processing_resolution` do pipeline. Esse valor deve ser definido na configuração do modelo. Quando o pipeline é chamado sem definir explicitamente `processing_resolution`, o valor padrão é utilizado. Isso é necessário para garantir resultados razoáveis com as diversas variações de modelos treinadas com valores de resolução de processamento ótimos variados.

Pipeline para estimativa de profundidade monocular usando o método Marigold: https://marigoldmonodepth.github.io.

Este modelo herda de [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos que a biblioteca implementa para todos os pipelines (como download ou salvamento, execução em um dispositivo específico, etc.)

#### __call__[[diffusers.MarigoldDepthPipeline.__call__]]

```python
__call__(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], num_inference_steps: int | None = None, ensemble_size: int = 1, processing_resolution: int | None = None, match_input_resolution: bool = True, resample_method_input: str = 'bilinear', resample_method_output: str = 'bilinear', batch_size: int = 1, ensembling_kwargs: dict[str, typing.Any] | None = None, latents: typing.Union[torch.Tensor, list[torch.Tensor], NoneType] = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'np', output_uncertainty: bool = False, output_latent: bool = False, return_dict: bool = True)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/pipeline_marigold_depth.py#L347)

**Parâmetros:**

image (`PIL.Image.Image`, `np.ndarray`, `torch.Tensor`, `list[PIL.Image.Image]`, `list[np.ndarray]`), : `list[torch.Tensor]`: Uma imagem de entrada ou imagens usadas como entrada para a tarefa de estimativa de profundidade. Para arrays e tensors, o intervalo de valores esperado é entre `[0, 1]`. É possível passar um lote de imagens fornecendo um array ou tensor de quatro dimensões. Além disso, é possível passar uma lista de imagens de arrays ou tensors de duas ou três dimensões. Nesse último caso, todos os elementos da lista devem ter a mesma largura e altura.

num_inference_steps (`int`, *opcional*, padrão `None`) : Número de etapas de difusão de desruido durante a inferência. O valor padrão `None` resulta em seleção automática.

ensemble_size (`int`, padrão `1`) : Número de previsões de ensemble. Valores mais altos resultam em melhorias mensuráveis e degradação visual.

processing_resolution (`int`, *opcional*, padrão `None`) : Resolução de processamento efetiva. Quando definido como `0`, corresponde à dimensão maior da imagem de entrada. Isso gera previsões mais nítidas, mas também pode levar à perda do contexto global. O valor padrão `None` é resolvido para o valor ótimo da configuração do modelo.

match_input_resolution (`bool`, *opcional*, padrão `True`) : Quando habilitado, a previsão de saída é redimensionada para corresponder às dimensões de entrada. Quando desabilitado, o lado mais longo da saída será igual a `processing_resolution`.

resample_method_input (`str`, *opcional*, padrão `"bilinear"`) : Método de reamostragem usado para redimensionar as imagens de entrada para `processing_resolution`. Os valores aceitos são: `"nearest"`, `"nearest-exact"`, `"bilinear"`, `"bicubic"` ou `"area"`.

resample_method_output (`str`, *opcional*, padrão `"bilinear"`) : Método de reamostragem usado para redimensionar as previsões de saída para corresponder à resolução de entrada. Os valores aceitos são `"nearest"`, `"nearest-exact"`, `"bilinear"`, `"bicubic"` ou `"area"`.

batch_size (`int`, *opcional*, padrão `1`) : Tamanho do lote; relevante apenas ao definir `ensemble_size` ou ao passar um tensor de imagens.

ensembling_kwargs (`dict`, *opcional*, padrão `None`) : Dicionário extra com argumentos para controle preciso do ensembling. As seguintes opções estão disponíveis: - reduction (`str`, *opcional*, padrão `"median"`): Define a função de ensembling aplicada em cada localização de pixel, podendo ser `"median"` ou `"mean"`. - regularizer_strength (`float`, *opcional*, padrão `0.02`): Força do regularizador que puxa as previsões alinhadas para o intervalo unitário de 0 a 1. - max_iter (`int`, *opcional*, padrão `2`): Número máximo de etapas do solucionador de alinhamento. Consulte a função `scipy.optimize.minimize`, argumento `options`. - tol (`float`, *opcional*, padrão `1e-3`): Tolerância do solucionador de alinhamento. O solucionador para quando a tolerância é atingida. - max_res (`int`, *opcional*, padrão `None`): Resolução na qual o alinhamento é realizado; `None` corresponde à `processing_resolution`.

latents (`torch.Tensor`, ou `list[torch.Tensor]`, *opcional*, padrão `None`) : Tensores de ruído latente para substituir a inicialização aleatória. Eles podem ser obtidos a partir da saída da chamada de função anterior.

generator (`torch.Generator`, ou `list[torch.Generator]`, *opcional*, padrão `None`) : Objeto gerador de números aleatórios para garantir reprodutibilidade.

output_type (`str`, *opcional*, padrão `"np"`) : Formato preferido dos campos `prediction` e `uncertainty` opcionais da saída. Os valores aceitos são: `"np"` (array numpy) ou `"pt"` (tensor torch).

output_uncertainty (`bool`, *opcional*, padrão `False`) : Quando habilitado, o campo `uncertainty` da saída contém o mapa de incerteza preditiva, desde que o argumento `ensemble_size` seja definido com um valor acima de 2.

output_latent (`bool`, *opcional*, padrão `False`) : Quando habilitado, o campo `latent` da saída contém os códigos latentes correspondentes às previsões dentro do ensemble. Esses códigos podem ser salvos, modificados e usados em chamadas subsequentes com o argumento `latents`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um [MarigoldDepthOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldDepthOutput) em vez de uma tupla simples.

**Retorna:** [MarigoldDepthOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldDepthOutput) ou `tuple`

Se `return_dict` for `True`, [MarigoldDepthOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldDepthOutput) é retornado; caso contrário, uma `tuple` é retornada, em que o primeiro elemento é a previsão, o segundo é a incerteza (ou `None`) e o terceiro é o latente (ou `None`).

Função invocada ao chamar o pipeline.

Exemplos:
```py
>>> import diffusers
>>> import torch

>>> pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
...     "prs-eth/marigold-depth-v1-1", variant="fp16", torch_dtype=torch.float16
... ).to("cuda")

>>> image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")
>>> depth = pipe(image)

>>> vis = pipe.image_processor.visualize_depth(depth.prediction)
>>> vis[0].save("einstein_depth.png")

>>> depth_16bit = pipe.image_processor.export_depth_to_16bit_png(depth.prediction)
>>> depth_16bit[0].save("einstein_depth_16bit.png")
```

#### diffusers.pipelines.marigold.MarigoldDepthOutput[[diffusers.pipelines.marigold.MarigoldDepthOutput]]

```python
diffusers.pipelines.marigold.MarigoldDepthOutput(prediction: typing.Union[numpy.ndarray, torch.Tensor], uncertainty: typing.Union[NoneType, numpy.ndarray, torch.Tensor], latent: typing.Optional[torch.Tensor])
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/pipeline_marigold_depth.py#L83)

**Parâmetros:**

prediction (`np.ndarray`, `torch.Tensor`) : Mapas de profundidade previstos com valores no intervalo [0, 1]. A forma é `numimages × 1 × height × width` para `torch.Tensor` ou `numimages × height × width × 1` para `np.ndarray`.

uncertainty (`None`, `np.ndarray`, `torch.Tensor`) : Mapas de incerteza calculados a partir do ensemble, com valores no intervalo [0, 1]. A forma é `numimages × 1 × height × width` para `torch.Tensor` ou `numimages × height × width × 1` para `np.ndarray`.

latent (`None`, `torch.Tensor`) : Recursos latentes correspondentes às previsões, compatíveis com o argumento `latents` do pipeline. A forma é `numimages * numensemble × 4 × latentheight × latentwidth`.

Classe de saída para o pipeline de predição de profundidade monocular do Marigold.

#### diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_depth[[diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_depth]]

```python
diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_depth(depth: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], val_min: float = 0.0, val_max: float = 1.0, color_map: str = 'Spectral')
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/marigold_image_processing.py#L387)

**Parâmetros:**

depth (`PIL.Image.Image | np.ndarray | torch.Tensor | list[PIL.Image.Image, list[np.ndarray], : list[torch.Tensor]]`): Mapas de profundidade.

val_min (`float`, *opcional*, padrão `0.0`) : Valor mínimo da faixa de profundura visualizada.

val_max (`float`, *opcional*, padrão `1.0`) : Valor máximo da faixa de profundura visualizada.

color_map (`str`, *opcional*, padrão `"Spectral"`) : Mapa de cores usado para converter uma previsão de profundidade de canal único em uma representação colorida.

Visualiza mapas de profundidade, como as previsões do `MarigoldDepthPipeline`.

Retorna: `list[PIL.Image.Image]` com a visualização dos mapas de profundidade.

## API de Estimação de Normais do Marigold[[diffusers.MarigoldNormalsPipeline]]

#### diffusers.MarigoldNormalsPipeline[[diffusers.MarigoldNormalsPipeline]]

```python
diffusers.MarigoldNormalsPipeline(unet: UNet2DConditionModel, vae: AutoencoderKL, scheduler: diffusers.schedulers.scheduling_ddim.DDIMScheduler | diffusers.schedulers.scheduling_lcm.LCMScheduler, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, prediction_type: str | None = None, use_full_z_range: bool | None = True, default_denoising_steps: int | None = None, default_processing_resolution: int | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/pipeline_marigold_normals.py#L99)

**Parâmetros:**

unet (`UNet2DConditionModel`) : U-Net condicional para desruidar o latente de normais, condicionado ao latente de imagem.

vae (`AutoencoderKL`) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens e previsões para e a partir de representações latentes.

scheduler (`DDIMScheduler` ou `LCMScheduler`) : Um scheduler a ser usado em combinação com `unet` para desruidar os latentes da imagem codificada.

text_encoder (`CLIPTextModel`) : Codificador de texto, para incorporação de texto vazio.

tokenizer (`CLIPTokenizer`) : Tokenizador do CLIP.

prediction_type (`str`, *opcional*) : Tipo de previsões feitas pelo modelo.

use_full_z_range (`bool`, *opcional*) : Se as normais previstas por este modelo utilizam a faixa completa da dimensão Z, ou apenas sua metade positiva.

default_denoising_steps (`int`, *opcional*) : O número mínimo de etapas de difusão de desruido necessárias para produzir uma previsão de qualidade razoável com o modelo dado. Esse valor deve ser definido na configuração do modelo. Quando o pipeline é chamado sem definir explicitamente `num_inference_steps`, o valor padrão é utilizado. Isso é necessário para garantir resultados razoáveis com as diversas variações de modelos compatíveis com o pipeline, como aquelas que dependem de agendamentos de desruido muito curtos (`LCMScheduler`) e aquelas com agendamentos de difusão completos (`DDIMScheduler`).

default_processing_resolution (`int`, *opcional*) : O valor recomendado do parâmetro `processing_resolution` do pipeline. Esse valor deve ser definido na configuração do modelo. Quando o pipeline é chamado sem definir explicitamente `processing_resolution`, o valor padrão é utilizado. Isso é necessário para garantir resultados razoáveis com as diversas variações de modelos treinadas com valores de resolução de processamento ótimos variados.

Pipeline para estimativa de normais monoculares usando o método Marigold: https://marigoldmonodepth.github.io.

Este modelo herda de [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos que a biblioteca implementa para todos os pipelines (como download ou salvamento, execução em um dispositivo específico, etc.)

#### __call__[[diffusers.MarigoldNormalsPipeline.__call__]]

```python
__call__(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], num_inference_steps: int | None = None, ensemble_size: int = 1, processing_resolution: int | None = None, match_input_resolution: bool = True, resample_method_input: str = 'bilinear', resample_method_output: str = 'bilinear', batch_size: int = 1, ensembling_kwargs: dict[str, typing.Any] | None = None, latents: typing.Union[torch.Tensor, list[torch.Tensor], NoneType] = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'np', output_uncertainty: bool = False, output_latent: bool = False, return_dict: bool = True)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/pipeline_marigold_normals.py#L332)

**Parâmetros:**

image (`PIL.Image.Image`, `np.ndarray`, `torch.Tensor`, `list[PIL.Image.Image]`, `list[np.ndarray]`), : `list[torch.Tensor]`: Uma imagem de entrada ou imagens usadas como entrada para a tarefa de estimativa de normais. Para arrays e tensors, o intervalo de valores esperado é entre `[0, 1]`. É possível passar um lote de imagens fornecendo um array ou tensor de quatro dimensões. Além disso, é possível passar uma lista de imagens de arrays ou tensors de duas ou três dimensões. Nesse último caso, todos os elementos da lista devem ter a mesma largura e altura.

num_inference_steps (`int`, *opcional*, padrão `None`) : Número de etapas de difusão de desruido durante a inferência. O valor padrão `None` resulta em seleção automática.

ensemble_size (`int`, padrão `1`) : Número de previsões de ensemble. Valores mais altos resultam em melhorias mensuráveis e degradação visual.

processing_resolution (`int`, *opcional*, padrão `None`) : Resolução de processamento efetiva. Quando definido como `0`, corresponde à dimensão maior da imagem de entrada. Isso gera previsões mais nítidas, mas também pode levar à perda do contexto global. O valor padrão `None` é resolvido para o valor ótimo da configuração do modelo.

match_input_resolution (`bool`, *opcional*, padrão `True`) : Quando habilitado, a previsão de saída é redimensionada para corresponder às dimensões de entrada. Quando desabilitado, o lado mais longo da saída será igual a `processing_resolution`.

resample_method_input (`str`, *opcional*, padrão `"bilinear"`) : Método de reamostragem usado para redimensionar as imagens de entrada para `processing_resolution`. Os valores aceitos são: `"nearest"`, `"nearest-exact"`, `"bilinear"`, `"bicubic"` ou `"area"`.

resample_method_output (`str`, *opcional*, padrão `"bilinear"`) : Método de reamostragem usado para redimensionar as previsões de saída para corresponder à resolução de entrada. Os valores aceitos são `"nearest"`, `"nearest-exact"`, `"bilinear"`, `"bicubic"` ou `"area"`.

batch_size (`int`, *opcional*, padrão `1`) : Tamanho do lote; relevante apenas ao definir `ensemble_size` ou ao passar um tensor de imagens.

ensembling_kwargs (`dict`, *opcional*, padrão `None`) : Dicionário extra com argumentos para controle preciso do ensembling. As seguintes opções estão disponíveis: - reduction (`str`, *opcional*, padrão `"closest"`): Define a função de ensembling aplicada em cada localização de pixel, podendo ser `"closest"` ou `"mean"`.

latents (`torch.Tensor`, *opcional*, padrão `None`) : Tensores de ruído latente para substituir a inicialização aleatória. Eles podem ser obtidos a partir da saída da chamada de função anterior.

generator (`torch.Generator`, ou `list[torch.Generator]`, *opcional*, padrão `None`) : Objeto gerador de números aleatórios para garantir reprodutibilidade.

output_type (`str`, *opcional*, padrão `"np"`) : Formato preferido dos campos `prediction` e `uncertainty` opcionais da saída. Os valores aceitos são: `"np"` (array numpy) ou `"pt"` (tensor torch).

output_uncertainty (`bool`, *opcional*, padrão `False`) : Quando habilitado, o campo `uncertainty` da saída contém o mapa de incerteza preditiva, desde que o argumento `ensemble_size` seja definido com um valor acima de 2.

output_latent (`bool`, *opcional*, padrão `False`) : Quando habilitado, o campo `latent` da saída contém os códigos latentes correspondentes às previsões dentro do ensemble. Esses códigos podem ser salvos, modificados e usados em chamadas subsequentes com o argumento `latents`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um [MarigoldNormalsOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldNormalsOutput) em vez de uma tupla simples.

**Retorna:** [MarigoldNormalsOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldNormalsOutput) ou `tuple`

Se `return_dict` for `True`, [MarigoldNormalsOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldNormalsOutput) é retornado; caso contrário, uma `tuple` é retornada, em que o primeiro elemento é a previsão, o segundo é a incerteza (ou `None`) e o terceiro é o latente (ou `None`).

Função invocada ao chamar o pipeline.

Exemplos:
```py
>>> import diffusers
>>> import torch

>>> pipe = diffusers.MarigoldNormalsPipeline.from_pretrained(
...     "prs-eth/marigold-normals-v1-1", variant="fp16", torch_dtype=torch.float16
... ).to("cuda")

>>> image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")
>>> normals = pipe(image)

>>> vis = pipe.image_processor.visualize_normals(normals.prediction)
>>> vis[0].save("einstein_normals.png")
```

#### diffusers.pipelines.marigold.MarigoldNormalsOutput[[diffusers.pipelines.marigold.MarigoldNormalsOutput]]

```python
diffusers.pipelines.marigold.MarigoldNormalsOutput(prediction: typing.Union[numpy.ndarray, torch.Tensor], uncertainty: typing.Union[NoneType, numpy.ndarray, torch.Tensor], latent: typing.Optional[torch.Tensor])
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/pipeline_marigold_normals.py#L78)

**Parâmetros:**

prediction (`np.ndarray`, `torch.Tensor`) : Normais previstas com valores no intervalo [-1, 1]. A forma é `numimages × 3 × height × width` para `torch.Tensor` ou `numimages × height × width × 3` para `np.ndarray`.

uncertainty (`None`, `np.ndarray`, `torch.Tensor`) : Mapas de incerteza calculados a partir do ensemble, com valores no intervalo [0, 1]. A forma é `numimages × 1 × height × width` para `torch.Tensor` ou `numimages × height × width × 1` para `np.ndarray`.

latent (`None`, `torch.Tensor`) : Recursos latentes correspondentes às previsões, compatíveis com o argumento `latents` do pipeline. A forma é `numimages * numensemble × 4 × latentheight × latentwidth`.

Classe de saída para o pipeline de predição de normais monoculares do Marigold.

#### diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_normals[[diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_normals]]

```python
diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_normals(normals: typing.Union[numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor]], flip_x: bool = False, flip_y: bool = False, flip_z: bool = False)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/marigold_image_processing.py#L486)

**Parâmetros:**

normals (`np.ndarray | torch.Tensor | list[np.ndarray, list[torch.Tensor]]`) : Normais da superfície.

flip_x (`bool`, *opcional*, padrão `False`) : Inverte o eixo X do referencial dos normais. A direção padrão é para a direita.

flip_y (`bool`, *opcional*, padrão `False`) : Inverte o eixo Y do referencial dos normais. A direção padrão é para cima.

flip_z (`bool`, *opcional*, padrão `False`) : Inverte o eixo Z do referencial dos normais. A direção padrão é voltada para o observador.

Visualiza normais de superfície, como as previsões do `MarigoldNormalsPipeline`.

Retorna: `list[PIL.Image.Image]` com a visualização dos normais da superfície.

## API de Decomposição de Imagem Intrínseca do Marigold[[diffusers.MarigoldIntrinsicsPipeline]]

#### diffusers.MarigoldIntrinsicsPipeline[[diffusers.MarigoldIntrinsicsPipeline]]

```python
diffusers.MarigoldIntrinsicsPipeline(unet: UNet2DConditionModel, vae: AutoencoderKL, scheduler: diffusers.schedulers.scheduling_ddim.DDIMScheduler | diffusers.schedulers.scheduling_lcm.LCMScheduler, text_encoder: CLIPTextModel, tokenizer: CLIPTokenizer, prediction_type: str | None = None, target_properties: dict[str, typing.Any] | None = None, default_denoising_steps: int | None = None, default_processing_resolution: int | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/pipeline_marigold_intrinsics.py#L120)

**Parâmetros:**

unet (`UNet2DConditionModel`) : U-Net condicional para desruidar o latente dos alvos, condicionado ao latente da imagem.

vae (`AutoencoderKL`) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens e previsões para e a partir de representações latentes.

scheduler (`DDIMScheduler` ou `LCMScheduler`) : Um scheduler a ser usado em combinação com `unet` para desruidar os latentes da imagem codificada.

text_encoder (`CLIPTextModel`) : Codificador de texto, para incorporação de texto vazio.

tokenizer (`CLIPTokenizer`) : Tokenizador do CLIP.

prediction_type (`str`, *opcional*) : Tipo de previsões feitas pelo modelo.

target_properties (`dict[str, Any]`, *opcional*) : Propriedades das modalidades previstas, como `target_names`, uma `list[str]` usada para definir o número, a ordem e os nomes das modalidades previstas, e quaisquer outros metadados que possam ser necessários para interpretar as previsões.

default_denoising_steps (`int`, *opcional*) : O número mínimo de etapas de difusão de desruido necessárias para produzir uma previsão de qualidade razoável com o modelo dado. Esse valor deve ser definido na configuração do modelo. Quando o pipeline é chamado sem definir explicitamente `num_inference_steps`, o valor padrão é utilizado. Isso é necessário para garantir resultados razoáveis com as diversas variações de modelos compatíveis com o pipeline, como aquelas que dependem de agendamentos de desruido muito curtos (`LCMScheduler`) e aquelas com agendamentos de difusão completos (`DDIMScheduler`).

default_processing_resolution (`int`, *opcional*) : O valor recomendado do parâmetro `processing_resolution` do pipeline. Esse valor deve ser definido na configuração do modelo. Quando o pipeline é chamado sem definir explicitamente `processing_resolution`, o valor padrão é utilizado. Isso é necessário para garantir resultados razoáveis com as diversas variações de modelos treinadas com valores de resolução de processamento ótimos variados.

Pipeline para Decomposição de Imagem Intrínseca (IID) usando o método Marigold: https://marigoldcomputervision.github.io.

Este modelo herda de [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos que a biblioteca implementa para todos os pipelines (como download ou salvamento, execução em um dispositivo específico, etc.)

#### __call__[[diffusers.MarigoldIntrinsicsPipeline.__call__]]

```python
__call__(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], num_inference_steps: int | None = None, ensemble_size: int = 1, processing_resolution: int | None = None, match_input_resolution: bool = True, resample_method_input: str = 'bilinear', resample_method_output: str = 'bilinear', batch_size: int = 1, ensembling_kwargs: dict[str, typing.Any] | None = None, latents: typing.Union[torch.Tensor, list[torch.Tensor], NoneType] = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'np', output_uncertainty: bool = False, output_latent: bool = False, return_dict: bool = True)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/pipeline_marigold_intrinsics.py#L359)

**Parâmetros:**

image (`PIL.Image.Image`, `np.ndarray`, `torch.Tensor`, `list[PIL.Image.Image]`, `list[np.ndarray]`), : `list[torch.Tensor]`: Uma imagem de entrada ou imagens usadas como entrada para a tarefa de decomposição intrínseca. Para arrays e tensors, o intervalo de valores esperado é entre `[0, 1]`. É possível passar um lote de imagens fornecendo um array ou tensor de quatro dimensões. Além disso, é possível passar uma lista de imagens de arrays ou tensors de duas ou três dimensões. Nesse último caso, todos os elementos da lista devem ter a mesma largura e altura.

num_inference_steps (`int`, *opcional*, padrão `None`) : Número de etapas de difusão de desruido durante a inferência. O valor padrão `None` resulta em seleção automática.

ensemble_size (`int`, padrão `1`) : Número de previsões de ensemble. Valores mais altos resultam em melhorias mensuráveis e degradação visual.

processing_resolution (`int`, *opcional*, padrão `None`) : Resolução de processamento efetiva. Quando definido como `0`, corresponde à dimensão maior da imagem de entrada. Isso gera previsões mais nítidas, mas também pode levar à perda do contexto global. O valor padrão `None` é resolvido para o valor ótimo da configuração do modelo.

match_input_resolution (`bool`, *opcional*, padrão `True`) : Quando habilitado, a previsão de saída é redimensionada para corresponder às dimensões de entrada. Quando desabilitado, o lado mais longo da saída será igual a `processing_resolution`.

resample_method_input (`str`, *opcional*, padrão `"bilinear"`) : Método de reamostragem usado para redimensionar as imagens de entrada para `processing_resolution`. Os valores aceitos são: `"nearest"`, `"nearest-exact"`, `"bilinear"`, `"bicubic"` ou `"area"`.

resample_method_output (`str`, *opcional*, padrão `"bilinear"`) : Método de reamostragem usado para redimensionar as previsões de saída para corresponder à resolução de entrada. Os valores aceitos são `"nearest"`, `"nearest-exact"`, `"bilinear"`, `"bicubic"` ou `"area"`.

batch_size (`int`, *opcional*, padrão `1`) : Tamanho do lote; relevante apenas ao definir `ensemble_size` ou ao passar um tensor de imagens.

ensembling_kwargs (`dict`, *opcional*, padrão `None`) : Dicionário extra com argumentos para controle preciso do ensembling. As seguintes opções estão disponíveis: - reduction (`str`, *opcional*, padrão `"median"`): Define a função de ensembling aplicada em cada localização de pixel, podendo ser `"median"` ou `"mean"`.

latents (`torch.Tensor`, *opcional*, padrão `None`) : Tensores de ruído latente para substituir a inicialização aleatória. Eles podem ser obtidos a partir da saída da chamada de função anterior.

generator (`torch.Generator`, ou `list[torch.Generator]`, *opcional*, padrão `None`) : Objeto gerador de números aleatórios para garantir reprodutibilidade.

output_type (`str`, *opcional*, padrão `"np"`) : Formato preferido dos campos `prediction` e `uncertainty` opcionais da saída. Os valores aceitos são: `"np"` (array numpy) ou `"pt"` (tensor torch).

output_uncertainty (`bool`, *opcional*, padrão `False`) : Quando habilitado, o campo `uncertainty` da saída contém o mapa de incerteza preditiva, desde que o argumento `ensemble_size` seja definido com um valor acima de 2.

output_latent (`bool`, *opcional*, padrão `False`) : Quando habilitado, o campo `latent` da saída contém os códigos latentes correspondentes às previsões dentro do ensemble. Esses códigos podem ser salvos, modificados e usados em chamadas subsequentes com o argumento `latents`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um [MarigoldIntrinsicsOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldIntrinsicsOutput) em vez de uma tupla simples.

**Retorna:** [MarigoldIntrinsicsOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldIntrinsicsOutput) ou `tuple`

Se `return_dict` for `True`, [MarigoldIntrinsicsOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/marigold#diffusers.pipelines.marigold.MarigoldIntrinsicsOutput) é retornado; caso contrário, uma `tuple` é retornada, em que o primeiro elemento é a previsão, o segundo é a incerteza (ou `None`) e o terceiro é o latente (ou `None`).

Função invocada ao chamar o pipeline.

Exemplos:
```py
>>> import diffusers
>>> import torch

>>> pipe = diffusers.MarigoldIntrinsicsPipeline.from_pretrained(
...     "prs-eth/marigold-iid-appearance-v1-1", variant="fp16", torch_dtype=torch.float16
... ).to("cuda")

>>> image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")
>>> intrinsics = pipe(image)

>>> vis = pipe.image_processor.visualize_intrinsics(intrinsics.prediction, pipe.target_properties)
>>> vis[0]["albedo"].save("einstein_albedo.png")
>>> vis[0]["roughness"].save("einstein_roughness.png")
>>> vis[0]["metallicity"].save("einstein_metallicity.png")
```

```py
>>> import diffusers
>>> import torch

>>> pipe = diffusers.MarigoldIntrinsicsPipeline.from_pretrained(
...     "prs-eth/marigold-iid-lighting-v1-1", variant="fp16", torch_dtype=torch.float16
... ).to("cuda")

>>> image = diffusers.utils.load_image("https://marigoldmonodepth.github.io/images/einstein.jpg")
>>> intrinsics = pipe(image)

>>> vis = pipe.image_processor.visualize_intrinsics(intrinsics.prediction, pipe.target_properties)
>>> vis[0]["albedo"].save("einstein_albedo.png")
>>> vis[0]["shading"].save("einstein_shading.png")
>>> vis[0]["residual"].save("einstein_residual.png")
```

#### diffusers.pipelines.marigold.MarigoldIntrinsicsOutput[[diffusers.pipelines.marigold.MarigoldIntrinsicsOutput]]

```python
diffusers.pipelines.marigold.MarigoldIntrinsicsOutput(prediction: typing.Union[numpy.ndarray, torch.Tensor], uncertainty: typing.Union[NoneType, numpy.ndarray, torch.Tensor], latent: typing.Optional[torch.Tensor])
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/pipeline_marigold_intrinsics.py#L96)

**Parâmetros:**

prediction (`np.ndarray`, `torch.Tensor`) : Intrínsecos da imagem previstos com valores no intervalo [0, 1]. A forma é `(numimages * numtargets) × 3 × height × width` para `torch.Tensor` ou `(numimages * numtargets) × height × width × 3` para `np.ndarray`, onde `numtargets` corresponde ao número de modalidades de destino previstas da decomposição da imagem intrínseca.

uncertainty (`None`, `np.ndarray`, `torch.Tensor`) : Mapas de incerteza calculados a partir do ensemble, com valores no intervalo [0, 1]. A forma é `(numimages * numtargets) × 3 × height × width` para `torch.Tensor` ou `(numimages * numtargets) × height × width × 3` para `np.ndarray`.

latent (`None`, `torch.Tensor`) : Recursos latentes correspondentes às previsões, compatíveis com o argumento `latents` do pipeline. A forma é `(numimages * numensemble) × (numtargets * 4) × latentheight × latentwidth`.

Classe de saída para o pipeline de Decomposição de Imagem Intrínseca do Marigold.

#### diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_intrinsics[[diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_intrinsics]]

```python
diffusers.pipelines.marigold.MarigoldImageProcessor.visualize_intrinsics(prediction: typing.Union[numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor]], target_properties: dict[str, typing.Any], color_map: str | dict[str, str] = 'binary')
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/marigold/marigold_image_processing.py#L542)

**Parâmetros:**

prediction (`np.ndarray | torch.Tensor | list[np.ndarray, list[torch.Tensor]]`) : Decomposição de imagem intrínseca.

target_properties (`dict[str, Any]`) : Propriedades de decomposição. Entradas esperadas: `target_names: list[str]` e um dicionário com as chaves `prediction_space: str`, `sub_target_names: list[str | Null]` (deve ter 3 entradas, null para modalidades ausentes), `up_to_scale: bool`, uma para cada alvo e subalvo.

color_map (`str | dict[str, str]`, *opcional*, padrão `"Spectral"`) : Mapa de cores usado para converter previsões de um único canal em representações coloridas. Quando um dicionário é passado, cada modalidade pode ser colorida com seu próprio mapa de cores.

Visualiza a decomposição de imagem intrínseca, como as previsões do `MarigoldIntrinsicsPipeline`.

Retorna: `list[dict[str, PIL.Image.Image]]` com a visualização da decomposição de imagem intrínseca.