用于计算机视觉任务的Marigold管道
Marigold是在将基于扩散的图像生成器重新用于单目深度估计中提出的，该论文是CVPR 2024年的一篇口头报告，作者是Bingxin Ke、Anton Obukhov、Shengyu Huang、Nando Metzger、Rodrigo Caye Daudt和Konrad Schindler。该想法是将文本到图像潜在扩散模型（LDM）丰富的生成先验重新用于传统的计算机视觉任务。最初，这个想法被探索用于微调Stable Diffusion以进行单目深度估计，如上面的预告片所示。后来，
- Tianfu Wang训练了第一个Marigold的潜在一致性模型（LCM），它解锁了快速单步推理；
- Kevin Qu将这种方法扩展到表面法线估计；
- Anton Obukhov将管道和文档贡献到diffusers（由YiYi Xu和Sayak Paul支持和启用）。
论文中的摘要是
单目深度估计是计算机视觉中一项基本任务。从单个图像中恢复3D深度在几何上是不适定的，需要场景理解，因此，深度学习的兴起带来了突破并不令人意外。单目深度估计器的显著进步反映了模型容量的增长，从相对简单的CNN到大型Transformer架构。尽管如此，单目深度估计器在遇到图像内容和布局不熟悉的情况下往往会挣扎，因为它们对视觉世界的知识受到训练期间所见数据的限制，并受到对新域的零样本泛化的挑战。这促使我们探索最近的生成扩散模型中捕获的广泛先验是否能够实现更好、更具泛化性的深度估计。我们介绍了Marigold，一种从Stable Diffusion衍生而来且保留其丰富先验知识的仿射不变单目深度估计方法。该估计器可以使用仅有的合成训练数据在几天内在一个GPU上进行微调。它在各种数据集上实现了最先进的性能，包括在某些情况下超过20%的性能提升。项目页面：https://marigoldmonodepth.github.io.
可用管道
每个管道支持一项计算机视觉任务，该任务以输入的RGB图像作为输入，并生成对感兴趣模态的预测，例如输入图像的深度图。目前，已实现以下任务
| 管道 | 预测的模态 | 演示 |
|---|---|---|
| MarigoldDepthPipeline | 深度、视差 | 快速演示（LCM）、慢速原始演示（DDIM） |
| MarigoldNormalsPipeline | 表面法线 | 快速演示（LCM） |
可用检查点
原始检查点可以在PRS-ETH Hugging Face组织中找到。
请务必查看计划程序指南，了解如何探索计划程序速度和质量之间的权衡，并查看跨管道重用组件部分，了解如何将相同的组件有效地加载到多个管道中。此外，要详细了解如何减少此管道的内存使用，请参考[“减少内存使用”]部分这里。
Marigold管道仅使用DDIMScheduler和LCMScheduler进行了设计和测试。根据计划程序的不同，获得可靠预测所需的推理步骤数量会有所不同，并且没有一个普遍适用的最佳值。因此，管道__call__方法中num_inference_steps的默认值设置为None（请参阅API参考）。除非显式设置，否则其值将取自检查点配置model_index.json。这样做是为了确保在仅使用image参数调用管道时获得高质量的预测。
另请参阅Marigold使用示例。
MarigoldDepthPipeline
class diffusers.MarigoldDepthPipeline
< 源代码 >( unet: UNet2DConditionModel vae: AutoencoderKL scheduler: Union text_encoder: CLIPTextModel tokenizer: CLIPTokenizer prediction_type: Optional = None scale_invariant: Optional = True shift_invariant: Optional = True default_denoising_steps: Optional = None default_processing_resolution: Optional = None )
参数
- unet (
UNet2DConditionModel) — 以图像潜在为条件，对深度潜在进行降噪的条件U-Net。 - vae (
AutoencoderKL) — 变分自编码器 (VAE) 模型，用于将图像和预测编码和解码到潜在表示中。 - scheduler (
DDIMScheduler或LCMScheduler) — 用于与unet结合以对编码的图像潜在特征进行降噪的调度器。 - text_encoder (
CLIPTextModel) — 用于空文本嵌入的文本编码器。 - tokenizer (
CLIPTokenizer) — CLIP 标记器。 - prediction_type (
str, 可选) — 模型做出的预测类型。 - scale_invariant (
bool, 可选) — 模型属性，指定预测的深度图是否尺度不变。此值必须在模型配置中设置。当与shift_invariant=True标志一起使用时，该模型也被称为“仿射不变”。注意：不支持覆盖此值。 - shift_invariant (
bool, 可选) — 模型属性，指定预测的深度图是否平移不变。此值必须在模型配置中设置。当与scale_invariant=True标志一起使用时，该模型也被称为“仿射不变”。注意：不支持覆盖此值。 - default_denoising_steps (
int, 可选) — 使用给定模型生成合理质量预测所需的最小降噪扩散步骤数。此值必须在模型配置中设置。当在没有显式设置num_inference_steps的情况下调用管道时，将使用默认值。这要求确保使用与管道兼容的各种模型风格获得合理的结果，例如那些依赖于非常短的降噪调度（LCMScheduler）的模型和那些具有完整扩散调度的模型（DDIMScheduler）。 - default_processing_resolution (
int, 可选) — 管道processing_resolution参数的推荐值。此值必须在模型配置中设置。当在没有显式设置processing_resolution的情况下调用管道时，将使用默认值。这要求确保使用以不同最佳处理分辨率值训练的各种模型风格获得合理的结果。
使用 Marigold 方法进行单目深度估计的管道： https://marigoldmonodepth.github.io.
此模型继承自 DiffusionPipeline。查看超类文档以了解库为所有管道实现的通用方法（例如下载或保存、在特定设备上运行等）。
__call__
< source >( image: Union num_inference_steps: Optional = None ensemble_size: int = 1 processing_resolution: Optional = None match_input_resolution: bool = True resample_method_input: str = 'bilinear' resample_method_output: str = 'bilinear' batch_size: int = 1 ensembling_kwargs: Optional = None latents: Union = None generator: Union = None output_type: str = 'np' output_uncertainty: bool = False output_latent: bool = False return_dict: bool = True ) → MarigoldDepthOutput 或 tuple
参数
- image (
PIL.Image.Image,np.ndarray,torch.Tensor,List[PIL.Image.Image],List[np.ndarray]), —List[torch.Tensor]: 用于深度估计任务的输入图像或图像列表。 对于数组和张量，预期值范围在[0, 1]之间。 通过提供四维数组或张量可以传递图像批次。 此外，还可以传递二维或三维数组或张量的图像列表。 在后一种情况下，所有列表元素必须具有相同的宽度和高度。 - num_inference_steps (
int, 可选, 默认值为None) — 推理过程中去噪扩散步骤的数量。 默认值None将导致自动选择。 对于完整的 Marigold 模型，步骤数应至少为 10，对于 Marigold-LCM 模型，步骤数应在 1 到 4 之间。 - ensemble_size (
int, 默认值为1) — 集成预测的数量。 建议值为 5 及以上以获得更高的精度，或 1 以获得更快的推断。 - processing_resolution (
int, 可选, 默认值为None) — 有效处理分辨率。 当设置为0时，与较大的输入图像尺寸匹配。 这将产生更清晰的预测，但也可能导致整体全局上下文丢失。 默认值None将解析为模型配置中的最佳值。 - match_input_resolution (
bool, 可选, 默认值为True) — 启用后，输出预测将调整大小以匹配输入尺寸。 禁用后，输出的较长边将等于processing_resolution。 - resample_method_input (
str, 可选, 默认值为"bilinear") — 用于将输入图像调整大小到processing_resolution的重采样方法。 接受的值为："nearest","nearest-exact","bilinear","bicubic"或"area"。 - resample_method_output (
str, 可选, 默认值为"bilinear") — 用于将输出预测调整大小以匹配输入分辨率的重采样方法。 接受的值为"nearest","nearest-exact","bilinear","bicubic"或"area"。 - batch_size (
int, 可选, 默认值为1) — 批次大小；仅在设置ensemble_size或传递图像张量时才重要。 - ensembling_kwargs (
dict, 可选, 默认为None) — 用于精确集成控制的额外字典参数。以下选项可用：- reduction (
str, 可选, 默认为"median"): 定义在每个像素位置应用的集成函数，可以是"median"或"mean"。 - regularizer_strength (
float, 可选, 默认为0.02): 将对齐的预测拉到 0 到 1 之间的单位范围的正则化器的强度。 - max_iter (
int, 可选, 默认为2): 对齐求解器步骤的最大次数。参考scipy.optimize.minimize函数的options参数。 - tol (
float, 可选, 默认为1e-3): 对齐求解器的容差。当达到容差时，求解器停止。 - max_res (
int, 可选, 默认为None): 执行对齐的分辨率；None匹配processing_resolution。
- reduction (
- latents (
torch.Tensor, 或List[torch.Tensor], 可选, 默认为None) — 要替换随机初始化的潜在噪声张量。这些可以从先前函数调用的输出中获取。 - generator (
torch.Generator, 或List[torch.Generator], 可选, 默认为None) — 用于确保可重复性的随机数生成器对象。 - output_type (
str, 可选, 默认为"np") — 输出的prediction和可选的uncertainty字段的首选格式。可接受的值为："np"(numpy 数组) 或"pt"(torch 张量)。 - output_uncertainty (
bool, 可选, 默认为False) — 当启用时，输出的uncertainty字段包含预测不确定性图，前提是ensemble_size参数设置为大于 2 的值。 - output_latent (
bool, 可选, 默认为False) — 当启用时，输出的latent字段包含对应于集成中预测的潜在代码。这些代码可以保存、修改，并用于后续的latents参数调用。 - return_dict (
bool, 可选, 默认为True) — 是否返回 MarigoldDepthOutput 而不是普通元组。
返回值
MarigoldDepthOutput 或 tuple
如果 return_dict 为 True，则返回 MarigoldDepthOutput，否则返回一个 tuple，其中第一个元素是预测，第二个元素是不确定性 (或 None)，第三个元素是潜在代码 (或 None)。
调用管道时调用的函数。
示例
>>> import diffusers
>>> import torch
>>> pipe = diffusers.MarigoldDepthPipeline.from_pretrained(
... "prs-eth/marigold-depth-lcm-v1-0", 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")ensemble_depth
< 源代码 >( depth: Tensor scale_invariant: bool = True shift_invariant: bool = True output_uncertainty: bool = False reduction: str = 'median' regularizer_strength: float = 0.02 max_iter: int = 2 tol: float = 0.001 max_res: int = 1024 ) → 对齐和集成的深度图张量，以及可选的相同形状的不确定性张量
参数
- depth (
torch.Tensor) — 输入的深度图集合。 - scale_invariant (
bool, 可选, 默认值为True) — 是否将预测视为尺度不变。 - shift_invariant (
bool, 可选, 默认值为True) — 是否将预测视为平移不变。 - output_uncertainty (
bool, 可选, 默认值为False) — 是否输出不确定性图。 - reduction (
str, 可选, 默认值为"median") — 用于对齐预测的集合方法。 接受的值为："mean"和"median"。 - regularizer_strength (
float, 可选, 默认值为0.02) — 将对齐预测拉到 0 到 1 之间单位范围的正则化强度。 - max_iter (
int, 可选, 默认值为2) — 对齐求解器步骤的最大数量。 参考scipy.optimize.minimize函数的options参数。 - tol (
float, 可选, 默认值为1e-3) — 对齐求解器的容差。 当达到容差时，求解器停止。 - max_res (
int, 可选, 默认值为1024) — 执行对齐的分辨率；None匹配processing_resolution。
返回值
对齐和集合后的深度图张量，以及可选的相同形状的不确定性张量
(1, 1, H, W).
对 depth 张量表示的深度图进行集合，预期形状为 (B, 1, H, W)，其中 B 是给定大小为 (H x W) 的预测的集合成员数量。 即使该函数是为深度图设计的，只要输入张量值非负，它也可以用于视差图。 当预测具有一或多个自由度时，即当它们是仿射不变（scale_invariant=True 和 shift_invariant=True）时，或只是尺度不变（仅 scale_invariant=True）时，对齐就会发生。 对于绝对预测（scale_invariant=False 和 shift_invariant=False），对齐将被跳过，只执行集合。
MarigoldNormalsPipeline
使用 Marigold 方法进行单目法线估计的管道：https://marigoldmonodepth.github.io。
此模型继承自 DiffusionPipeline。查看超类文档以了解库为所有管道实现的通用方法（例如下载或保存、在特定设备上运行等）。
__call__
< 源代码 >( image: Union num_inference_steps: Optional = None ensemble_size: int = 1 processing_resolution: Optional = None match_input_resolution: bool = True resample_method_input: str = 'bilinear' resample_method_output: str = 'bilinear' batch_size: int = 1 ensembling_kwargs: Optional = None latents: Union = None generator: Union = None output_type: str = 'np' output_uncertainty: bool = False output_latent: bool = False return_dict: bool = True ) → MarigoldNormalsOutput 或者 tuple
参数
- image (
PIL.Image.Image,np.ndarray,torch.Tensor,List[PIL.Image.Image],List[np.ndarray]), —List[torch.Tensor]: 用于法线估计任务的输入图像或图像列表。对于数组和张量，预期值范围在[0, 1]之间。通过提供四维数组或张量，可以传入图像批次。此外，还可以传入二维或三维数组或张量的图像列表。在后一种情况下，所有列表元素必须具有相同的宽度和高度。 - num_inference_steps (
int, 可选, 默认值为None) — 推理过程中的去噪扩散步骤数量。默认值None会导致自动选择。对于完整的 Marigold 模型，步骤数量至少应为 10，而对于 Marigold-LCM 模型，步骤数量应在 1 到 4 之间。 - ensemble_size (
int, 默认值为1) — 集成预测的数量。建议值为 5 及以上，以获得更高的精度，或 1，以获得更快的推理速度。 - processing_resolution (
int, 可选, 默认值为None) — 有效处理分辨率。当设置为0时，与较大的输入图像尺寸匹配。这会产生更清晰的预测，但也可能导致全局上下文整体丢失。默认值None将解析为模型配置中的最佳值。 - match_input_resolution (
bool, 可选, 默认值为True) — 启用时，输出预测将调整大小以匹配输入尺寸。禁用时，输出的长边将等于processing_resolution。 - resample_method_input (
str, 可选, 默认值为"bilinear") — 用于将输入图像调整大小到processing_resolution的重采样方法。可接受的值为："nearest","nearest-exact","bilinear","bicubic", 或"area"。 - resample_method_output (
str, 可选, 默认值为"bilinear") — 用于将输出预测调整大小以匹配输入分辨率的重采样方法。可接受的值为"nearest","nearest-exact","bilinear","bicubic", 或"area"。 - batch_size (
int, 可选, 默认值:1) — 批量大小；仅在设置ensemble_size或传递图像张量时才重要。 - ensembling_kwargs (
dict, 可选, 默认值:None) — 用于精确集成控制的额外字典参数。 可用以下选项：- reduction (
str, 可选, 默认值:"closest"): 定义在每个像素位置应用的集成函数，可以是"closest"或"mean"。
- reduction (
- latents (
torch.Tensor, 可选, 默认值:None) — 用于替换随机初始化的潜在噪声张量。 这些可以从先前函数调用的输出中获取。 - generator (
torch.Generator, orList[torch.Generator], 可选, 默认值:None) — 用于确保可重复性的随机数生成器对象。 - output_type (
str, 可选, 默认值:"np") — 输出的prediction和可选的uncertainty字段的首选格式。 可接受的值为："np"(NumPy 数组) 或"pt"(PyTorch 张量)。 - output_uncertainty (
bool, 可选, 默认值:False) — 启用后，输出的uncertainty字段包含预测不确定性图，前提是ensemble_size参数设置为大于 2 的值。 - output_latent (
bool, 可选, 默认值:False) — 启用后，输出的latent字段包含与集成内的预测相对应的潜在代码。 这些代码可以保存、修改并用于后续调用，使用latents参数。 - return_dict (
bool, 可选, 默认值:True) — 是否返回 MarigoldDepthOutput 而不是普通元组。
返回值
MarigoldNormalsOutput 或 tuple
如果 return_dict 为 True，则返回 MarigoldNormalsOutput，否则返回一个 tuple，其中第一个元素是预测，第二个元素是不确定性（或 None），第三个是潜在的（或 None）。
调用管道时调用的函数。
示例
>>> import diffusers
>>> import torch
>>> pipe = diffusers.MarigoldNormalsPipeline.from_pretrained(
... "prs-eth/marigold-normals-lcm-v0-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")ensemble_normals
< source >( normals: Tensor output_uncertainty: bool reduction: str = 'closest' )
对由 normals 张量表示的法线图进行集合，预期形状为 (B, 3, H, W)，其中 B 是给定大小为 (H x W) 的预测的集合成员数量。
MarigoldDepthOutput
class diffusers.pipelines.marigold.MarigoldDepthOutput
< 源代码 >( prediction: Union uncertainty: Union latent: Optional )
参数
- prediction (
np.ndarray,torch.Tensor) — 预测的深度图，值范围为 [0, 1]。 形状始终为 $numimages imes 1 imes height imes width$，无论图像是否以 4D 数组或列表形式传递。 - uncertainty (
None,np.ndarray,torch.Tensor) — 从集合中计算出的不确定性图，值范围为 [0, 1]。 形状为 $numimages imes 1 imes height imes width$。 - latent (
None,torch.Tensor) — 与预测相对应的潜在特征，与管道中的latents参数兼容。 形状为 $numimages * numensemble imes 4 imes latentheight imes latentwidth$。
Marigold 单目深度预测管道的输出类。
MarigoldNormalsOutput
class diffusers.pipelines.marigold.MarigoldNormalsOutput
< 源代码 >( prediction: Union uncertainty: Union latent: Optional )
参数
- prediction (
np.ndarray,torch.Tensor) — 预测的法线，值范围为 [-1, 1]。 形状始终为 $numimages imes 3 imes height imes width$，无论图像是否以 4D 数组或列表形式传递。 - uncertainty (
None,np.ndarray,torch.Tensor) — 从集成中计算出的不确定性图，值范围在 [0, 1] 之间。形状为 $numimages imes 1 imes height imes width$。 - latent (
None,torch.Tensor) — 与管道latents参数兼容的，对应于预测的潜在特征。形状为 $numimages * numensemble imes 4 imes latentheight imes latentwidth$。
Marigold 单目法线预测管道输出类。