# RePaintScheduler

`RePaintScheduler` 是一种基于 DDPM 的图像修复调度器，适用于极端掩码条件下的无监督图像修复。它专为配合 `RePaintPipeline` 使用而设计，其理论基础是 Andreas Lugmayr 等人发表的论文 [RePaint: Inpainting using Denoising Diffusion Probabilistic Models](https://huggingface.co/papers/2201.09865)。

该论文的摘要如下：

*自由形式图像修复（inpainting）是指在由任意二值掩码指定的区域中向图像添加新内容的任务。大多数现有方法针对特定的掩码分布进行训练，这限制了它们对未见过的掩码类型的泛化能力。此外，使用逐像素损失和感知损失进行训练往往导致向缺失区域进行简单的纹理扩展，而非语义上有意义的生成。在本工作中，我们提出了 RePaint：一种基于去噪扩散概率模型（DDPM）的图像修复方法，即使面对极端掩码也适用。我们采用预训练的非条件 DDPM 作为生成先验。为了对生成过程进行条件化，我们仅通过利用给定图像信息对未掩码区域进行采样来修改反向扩散迭代。由于该技术不修改或条件化原始 DDPM 网络本身，该模型能够为任何修复形式生成高质量且多样化的输出图像。我们使用标准掩码和极端掩码，针对人脸和通用图像修复验证了我们的方法。在至少六种掩码分布中的五种上，RePaint 的表现优于最先进的自回归（Autoregressive）和 GAN 方法。GitHub 仓库：[this http URL](http://git.io/RePaint)。*

原始实现可在 [andreas128/RePaint](https://github.com/andreas128/) 中找到。

## RePaintScheduler[[diffusers.RePaintScheduler]]

#### diffusers.RePaintScheduler[[diffusers.RePaintScheduler]]

```python
diffusers.RePaintScheduler(num_train_timesteps: int = 1000, beta_start: float = 0.0001, beta_end: float = 0.02, beta_schedule: str = 'linear', eta: float = 0.0, trained_betas: numpy.ndarray | None = None, clip_sample: bool = True)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_repaint.py#L99)

**参数：**

num_train_timesteps (`int`，默认为 `1000`)：用于训练模型的扩散步数。

beta_start (`float`，默认值为 `0.0001`)：推理的初始 `beta` 值。

beta_end (`float`，默认值为 `0.02`)：最终的 `beta` 值。

beta_schedule (`str`，默认为 `"linear"`)：beta 调度，即将 beta 范围映射为用于模型步进的一系列 beta 值。可选 `linear`、`scaled_linear`、`squaredcos_cap_v2` 或 `sigmoid`。

eta (`float`，默认值为 `0.0`)：扩散步骤中添加的噪声权重。`0.0` 对应 DDIM，`1.0` 对应 DDPM。

trained_betas (`np.ndarray`，*可选*)：将 beta 数组直接传递给构造函数，以绕过 `beta_start` 和 `beta_end`。

clip_sample (`bool`，默认为 `True`)：将预测样本裁剪到 -1 和 1 之间，以确保数值稳定性。

`RePaintScheduler` 是用于在给定掩码内进行 DDPM 图像修复的调度器。

该模型继承自 [SchedulerMixin](/docs/diffusers/v0.43.0/zh/api/schedulers/overview#diffusers.SchedulerMixin) 和 [ConfigMixin](/docs/diffusers/v0.43.0/zh/api/configuration#diffusers.ConfigMixin)。有关该库为所有调度器实现的通用方法（例如加载和保存），请参阅父类文档。

#### add_noise[[diffusers.RePaintScheduler.add_noise]]

```python
add_noise(original_samples: Tensor, noise: Tensor, timesteps: IntTensor)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_repaint.py#L395)

**参数：**

original_samples (`torch.Tensor`) : 原始样本，噪声将添加至这些样本。

noise (`torch.Tensor`) : 将添加到样本中的噪声。

timesteps (`torch.IntTensor`)：用于确定每个样本噪声水平的时间步。

**引发：** ``NotImplementedError``

- ``NotImplementedError`` -- RePaint 训练应使用 [DDPMScheduler.add_noise()](/docs/diffusers/v0.43.0/zh/api/schedulers/ddpm#diffusers.DDPMScheduler.add_noise)。

表示此调度器不支持在 RePaint 训练中添加噪声。

#### scale_model_input[[diffusers.RePaintScheduler.scale_model_input]]

```python
scale_model_input(sample: Tensor, timestep: int | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_repaint.py#L171)

**参数：**

sample (`torch.Tensor`)：输入样本。

timestep (`int`, *可选*) : 扩散链中的当前时间步。

**返回：** `torch.Tensor`

经过缩放的输入样本。

确保与那些需要根据当前时间步对去噪模型输入进行缩放的调度器保持可互换性。

#### set_timesteps[[diffusers.RePaintScheduler.set_timesteps]]

```python
set_timesteps(num_inference_steps: int, jump_length: int = 10, jump_n_sample: int = 10, device: typing.Union[str, torch.device, NoneType] = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_repaint.py#L188)

**参数：**

num_inference_steps (`int`) : 使用预训练模型生成样本时所用的扩散步数。

jump_length (`int`，默认为 `10`)：在单次跳跃（RePaint 论文中的“j”）中，向前推进的时间步数，之后才会向后回溯。请参阅论文中的图 9 和图 10。

jump_n_sample (`int`，默认为 `10`)：对于给定的选定时间样本，执行前向时间跳跃的次数。请参阅论文中的图 9 和图 10。

device (`str` 或 `torch.device`，*可选*)：时间步应移动到的设备。如果为 `None`，则不移动时间步。

设置扩散链所使用的离散时间步（需在推理之前运行）。

#### 步骤[[diffusers.RePaintScheduler.step]]

```python
step(model_output: Tensor, timestep: int, sample: Tensor, original_image: Tensor, mask: Tensor, generator: typing.Optional[torch.Generator] = None, return_dict: bool = True)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_repaint.py#L264)

**参数：**

model_output (`torch.Tensor`)：学习到的扩散模型的直接输出。

timestep (`int`)：扩散链中当前的离散时间步。

sample (`torch.Tensor`)：扩散过程生成的当前样本实例。

original_image (`torch.Tensor`) : 用于执行图像修复的原始图像。

mask (`torch.Tensor`) : 掩码，其中值为 0.0 的位置指示原始图像中需要修复的部分。

generator (`torch.Generator`, *可选*) : 随机数生成器。

return_dict (`bool`，默认为 `True`)：是否返回 [RePaintSchedulerOutput](/docs/diffusers/v0.43.0/zh/api/schedulers/repaint#diffusers.schedulers.scheduling_repaint.RePaintSchedulerOutput) 而不是元组。

**返回：** [RePaintSchedulerOutput](/docs/diffusers/v0.43.0/zh/api/schedulers/repaint#diffusers.schedulers.scheduling_repaint.RePaintSchedulerOutput) 或 `tuple[torch.Tensor, torch.Tensor]`

如果 return_dict 为 `True`，则返回 [RePaintSchedulerOutput](/docs/diffusers/v0.43.0/zh/api/schedulers/repaint#diffusers.schedulers.scheduling_repaint.RePaintSchedulerOutput)，否则返回一个元组，其中第一个元素是前一个样本，第二个元素是预测的原始样本。

通过逆向 SDE 预测上一时间步的样本。此函数将扩散过程从学习到的模型输出（通常是预测的噪声）进行传播。

#### undo_step[[diffusers.RePaintScheduler.undo_step]]

```python
undo_step(sample: Tensor, timestep: int, generator: typing.Optional[torch.Generator] = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_repaint.py#L358)

**参数：**

sample (`torch.Tensor`) : 添加噪声的样本。

timestep (`int`)：扩散链中当前的离散时间步。

generator (`torch.Generator`, *可选*) : 随机数生成器。

**返回：** `torch.Tensor`

扩散链中下一个时间步的样本。

向样本添加噪声，使其向前推进一个扩散步骤。

## RePaintSchedulerOutput[[diffusers.schedulers.scheduling_repaint.RePaintSchedulerOutput]]

#### diffusers.schedulers.scheduling_repaint.RePaintSchedulerOutput[[diffusers.schedulers.scheduling_repaint.RePaintSchedulerOutput]]

```python
diffusers.schedulers.scheduling_repaint.RePaintSchedulerOutput(prev_sample: Tensor, pred_original_sample: Tensor)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/schedulers/scheduling_repaint.py#L29)

**参数：**

prev_sample （对于图像，形状为 `(batch_size, num_channels, height, width)` 的 `torch.Tensor`）：前一时间步的已计算样本 (x_{t-1})。`prev_sample` 应作为去噪循环中下一个模型的输入。

pred_original_sample （对于图像，形状为 `(batch_size, num_channels, height, width)` 的 `torch.Tensor`）：基于当前时间步的模型输出预测的去噪样本 (x_{0})。`pred_original_sample` 可用于预览进度或进行引导。

调度器 step 函数输出的输出类。