diffusers/v0.43.0/zh/api/image_processor.md

VAE 图像处理器

VaeImageProcessor 为 StableDiffusionPipeline 提供了统一的 API，用于在 VAE 编码前准备图像输入，以及在解码后对输出进行后处理。这包括调整大小、归一化，以及在 PIL Image、PyTorch 和 NumPy 数组之间进行转换等操作。

所有使用 VaeImageProcessor 的 pipeline 均接受 PIL Image、PyTorch tensor 或 NumPy 数组作为图像输入，并根据用户提供的 output_type 参数返回相应的输出。您可以直接将编码后的图像 latents 传入 pipeline，并通过 output_type 参数（例如 output_type="latent"）将 latents 作为特定输出从 pipeline 返回。这使得您可以将一个 pipeline 生成的 latents 直接作为输入传递给另一个 pipeline，而无需离开 latent 空间。此外，通过在不同 pipeline 之间直接传递 PyTorch tensor，使用多个 pipeline 协同工作也变得更加简单。

VaeImageProcessor[[diffusers.VaeImageProcessor]]

diffusers.VaeImageProcessor[[diffusers.VaeImageProcessor]]

diffusers.VaeImageProcessor(do_resize: bool = True, vae_scale_factor: int = 8, vae_latent_channels: int = 4, resample: str = 'lanczos', reducing_gap: int | None = None, do_normalize: bool = True, do_binarize: bool = False, do_convert_rgb: bool = False, do_convert_grayscale: bool = False)

源代码

参数：

do_resize (bool，可选，默认为 True)：是否将图像的（高度，宽度）维度缩小为 vae_scale_factor 的倍数。可以接受来自 image_processor.VaeImageProcessor.preprocess() 方法的 height 和 width 参数。

vae_scale_factor (int，可选，默认为 8)：VAE 缩放因子。如果 do_resize 为 True，图像将自动调整为该因子的整数倍。

resample (str，可选，默认为 lanczos)：调整图像大小时使用的重采样滤波器。

do_normalize (bool，可选，默认为 True)：是否将图像归一化到 [-1,1]。

do_binarize (bool，可选，默认为 False)：是否将图像二值化为 0/1。

do_convert_rgb (bool，可选，默认为 False)：是否将图像转换为 RGB 格式。

do_convert_grayscale (bool，可选，默认为 False)：是否将图像转换为灰度格式。

VAE 的图像处理器。

apply_overlay[[diffusers.VaeImageProcessor.apply_overlay]]

apply_overlay(mask: Image, init_image: Image, image: Image, crop_coords: tuple[int, int, int, int] | None = None)

源代码

参数：

mask (PIL.Image.Image)：用于突出显示需要叠加区域的遮罩图像。

init_image (PIL.Image.Image)：应用叠加层的原始图像。

image (PIL.Image.Image)：要叠加到原始图像上的图像。

crop_coords (tuple[int, int, int, int]，可选)：用于裁剪图像的坐标。如果提供，图像将按此进行裁剪。

返回： PIL.Image.Image

应用叠加层后的最终图像。

在原始图像上叠加显示掩码和修复后的图像。

binarize[[diffusers.VaeImageProcessor.binarize]]

binarize(image: Image)

源代码

参数：

image (PIL.Image.Image)：图像输入，应为 PIL 图像。

返回： PIL.Image.Image

二值化图像。小于 0.5 的值被设置为 0，大于 0.5 的值被设置为 1。

创建一个掩码。

模糊[[diffusers.VaeImageProcessor.blur]]

blur(image: Image, blur_factor: int = 4)

源代码

参数：

image (PIL.Image.Image)：要转换为灰度图的 PIL 图像。

返回： PIL.Image.Image

经过灰度转换的 PIL 图像。

对图像应用高斯模糊。

convert_to_grayscale[[diffusers.VaeImageProcessor.convert_to_grayscale]]

convert_to_grayscale(image: Image)

源代码

参数：

image (PIL.Image.Image)：要转换的输入图像。

返回： PIL.Image.Image

转换为灰度图像后的图像。

将给定的 PIL 图像转换为灰度图像。

convert_to_rgb[[diffusers.VaeImageProcessor.convert_to_rgb]]

convert_to_rgb(image: Image)

源代码

参数：

image (PIL.Image.Image)：要转换为 RGB 的 PIL 图像。

返回： PIL.Image.Image

经过 RGB 转换的 PIL 图像。

将 PIL 图像转换为 RGB 格式。

反规范化[[diffusers.VaeImageProcessor.denormalize]]

denormalize(images: typing.Union[numpy.ndarray, torch.Tensor])

源代码

参数：

images (np.ndarray 或 torch.Tensor)：要反归一化的图像数组。

返回： np.ndarray 或 torch.Tensor

反归一化的图像数组。

将图像数组反归一化到 [0,1] 范围。

get_crop_region[[diffusers.VaeImageProcessor.get_crop_region]]

get_crop_region(mask_image: Image, width: int, height: int, pad = 0)

源代码

参数：

mask_image (PIL.Image.Image) : 掩码图像。

width (int)：要处理的图像的宽度。

height (int)：要处理的图像的高度。

pad (int, 可选) : 要添加到裁剪区域的填充。默认值为 0。

返回： tuple

(x1, y1, x2, y2) 表示一个矩形区域，该区域包含图像中所有被掩码的区域，并且与原始宽高比相匹配。

查找包含图像中所有掩码区域的矩形区域，并将该区域扩展以匹配原始图像的宽高比；例如，如果用户在 128x32 的区域中绘制了掩码，而处理尺寸为 512x512，则该区域将被扩展为 128x128。

get_default_height_width[[diffusers.VaeImageProcessor.get_default_height_width]]

get_default_height_width(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor], height: int | None = None, width: int | None = None)

源代码

参数：

image (PIL.Image.Image | np.ndarray | torch.Tensor)：图像输入，可以是 PIL 图像、NumPy 数组或 PyTorch 张量。如果是 NumPy 数组，其形状应为 [batch, height, width] 或 [batch, height, width, channels]。如果是 PyTorch 张量，其形状应为 [batch, channels, height, width]。

height (int | None，可选，默认为 None)：预处理图像的高度。如果为 None，则使用 image 输入的高度。

width (int | None，可选，默认为 None)：预处理图像的宽度。如果为 None，则使用 image 输入的宽度。

返回： tuple[int, int]

一个元组，包含高度和宽度，两者均调整为 vae_scale_factor 的最近整数倍。

返回图像的高度和宽度，向下取整为 vae_scale_factor 的下一个整数倍。

normalize[[diffusers.VaeImageProcessor.normalize]]

normalize(images: typing.Union[numpy.ndarray, torch.Tensor])

源代码

参数：

images (np.ndarray 或 torch.Tensor)：要归一化的图像数组。

返回： np.ndarray 或 torch.Tensor

归一化后的图像数组。

将图像数组归一化到 [-1,1]。

numpy_to_pil[[diffusers.VaeImageProcessor.numpy_to_pil]]

numpy_to_pil(images: ndarray)

源代码

参数：

images (np.ndarray) : 要转换为 PIL 格式的图像数组。

返回： list[PIL.Image.Image]

PIL 图像列表。

将 numpy 图像或一批图像转换为 PIL 图像。

numpy_to_pt[[diffusers.VaeImageProcessor.numpy_to_pt]]

numpy_to_pt(images: ndarray)

源代码

参数：

images (np.ndarray) : 要转换为 PyTorch 格式的 NumPy 图像数组。

返回： torch.Tensor

图像的 PyTorch 张量表示。

将 NumPy 图像转换为 PyTorch 张量。

pil_to_numpy[[diffusers.VaeImageProcessor.pil_to_numpy]]

pil_to_numpy(images: list[PIL.Image.Image] | PIL.Image.Image)

源代码

参数：

images (PIL.Image.Image 或 list[PIL.Image.Image])：要转换为 NumPy 格式的 PIL 图像或图像列表。

返回： np.ndarray

图像的 NumPy 数组表示。

将 PIL 图像或 PIL 图像列表转换为 NumPy 数组。

postprocess[[diffusers.VaeImageProcessor.postprocess]]

postprocess(image: Tensor, output_type: str = 'pil', do_denormalize: list[bool] | None = None)

源代码

参数：

image (torch.Tensor) : 图像输入，应为形状为 B x C x H x W 的 PyTorch 张量。

output_type (str，可选，默认为 pil)：图像的pil、np、pt、latent输出类型之一。

do_denormalize (list[bool]，可选，默认为 None)：是否将图像反归一化到 [0,1]。如果为 None，将使用 VaeImageProcessor 配置中 do_normalize 的值。

返回： PIL.Image.Image、np.ndarray 或 torch.Tensor

后处理后的图像。

将图像输出从张量后处理为output_type。

preprocess[[diffusers.VaeImageProcessor.preprocess]]

preprocess(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], height: int | None = None, width: int | None = None, resize_mode: str = 'default', crops_coords: tuple[int, int, int, int] | None = None)

源代码

参数：

image (PipelineImageInput)：图像输入，支持的格式包括 PIL 图像、NumPy 数组、PyTorch 张量；也接受上述支持格式的列表。

height (int, 可选) : 预处理图像的高度。如果为 None，将使用 get_default_height_width() 获取默认高度。

width (int, 可选) : 预处理后的宽度。如果为 None，将使用 get_default_height_width()` 获取默认宽度。

resize_mode (str, 可选，默认为 default) : 调整大小模式，可以是 default 或 fill 之一。如果为 default，则将图像调整大小以适应指定的宽度和高度，且可能不保持原始宽高比。如果为 fill，则将图像调整大小以适应指定的宽度和高度，保持宽高比，然后将图像居中于该尺寸内，并用图像数据填充空白区域。如果为 crop，则将图像调整大小以适应指定的宽度和高度，保持宽高比，然后将图像居中于该尺寸内，并裁剪掉多余部分。请注意，resize_mode fill 和 crop 仅支持 PIL 图像输入。

crops_coords (list[tuple[int, int, int, int]]，可选，默认为 None)：批次中每张图片的裁剪坐标。如果为 None，则不对图片进行裁剪。

返回： torch.Tensor

预处理后的图像。

预处理图像输入。

pt_to_numpy[[diffusers.VaeImageProcessor.pt_to_numpy]]

pt_to_numpy(images: Tensor)

源代码

参数：

images (torch.Tensor) : 要转换为 NumPy 格式的 PyTorch 张量。

返回： np.ndarray

图像的 NumPy 数组表示。

将 PyTorch 张量转换为 NumPy 图像。

resize[[diffusers.VaeImageProcessor.resize]]

resize(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor], height: int, width: int, resize_mode: str = 'default')

源代码

参数：

image (PIL.Image.Image、np.ndarray 或 torch.Tensor)：图像输入，可以是 PIL 图像、numpy 数组或 pytorch 张量。

height (int) : 要调整到的高度。

width (int) : 调整后的宽度。

resize_mode (str，可选，默认为 default)：要使用的缩放模式，可以是 default 或 fill 之一。如果为 default，则将图像缩放以适应指定的宽度和高度，且可能不保持原始宽高比。如果为 fill，则将图像缩放以适应指定的宽度和高度，保持宽高比，然后将图像居中于该尺寸内，并用图像数据填充空白区域。如果为 crop，则将图像缩放以适应指定的宽度和高度，保持宽高比，然后将图像居中于该尺寸内，并裁剪掉多余部分。请注意，resize_mode fill 和 crop 仅支持 PIL 图像输入。

返回： PIL.Image.Image、np.ndarray 或 torch.Tensor

调整大小后的图像。

调整图像大小。

InpaintProcessor[[diffusers.InpaintProcessor]]

InpaintProcessor 接受 mask 和 image 输入并一起处理它们。可选地，它可以接受 padding_mask_crop 并应用 mask 叠加。

diffusers.InpaintProcessor[[diffusers.InpaintProcessor]]

diffusers.InpaintProcessor(do_resize: bool = True, vae_scale_factor: int = 8, vae_latent_channels: int = 4, resample: str = 'lanczos', reducing_gap: int | None = None, do_normalize: bool = True, do_binarize: bool = False, do_convert_grayscale: bool = False, mask_do_normalize: bool = False, mask_do_binarize: bool = True, mask_do_convert_grayscale: bool = True)

源代码

用于图像和掩码修复的图像处理器。

postprocess[[diffusers.InpaintProcessor.postprocess]]

postprocess(image: Tensor, output_type: str = 'pil', original_image: PIL.Image.Image | None = None, original_mask: PIL.Image.Image | None = None, crops_coords: tuple[int, int, int, int] | None = None)

源代码

对图像进行后处理，可选地应用遮罩叠加

preprocess[[diffusers.InpaintProcessor.preprocess]]

preprocess(image: Image, mask: PIL.Image.Image | None = None, height: int | None = None, width: int | None = None, padding_mask_crop: int | None = None)

源代码

预处理图像和掩码。

VaeImageProcessorLDM3D[[diffusers.VaeImageProcessorLDM3D]]

VaeImageProcessorLDM3D 接受 RGB 和深度输入，并返回 RGB 和深度输出。

diffusers.VaeImageProcessorLDM3D[[diffusers.VaeImageProcessorLDM3D]]

diffusers.VaeImageProcessorLDM3D(do_resize: bool = True, vae_scale_factor: int = 8, resample: str = 'lanczos', do_normalize: bool = True)

源代码

参数：

do_resize (bool，可选，默认为 True)：是否将图像的 (height, width) 维度缩小为 vae_scale_factor 的整数倍。

vae_scale_factor (int，可选，默认为 8)：VAE 缩放因子。如果 do_resize 为 True，图像将自动调整为该因子的整数倍。

resample (str，可选，默认为 lanczos)：调整图像大小时使用的重采样滤波器。

do_normalize (bool，可选，默认为 True)：是否将图像归一化到 [-1,1]。

VAE LDM3D 的图像处理器。

depth_pil_to_numpy[[diffusers.VaeImageProcessorLDM3D.depth_pil_to_numpy]]

depth_pil_to_numpy(images: list[PIL.Image.Image] | PIL.Image.Image)

源代码

参数：

images (list[PIL.Image.Image, PIL.Image.Image]) : 要转换的输入图像或图像列表。

返回： np.ndarray

转换后的图像组成的 NumPy 数组。

将 PIL 图像或 PIL 图像列表转换为 NumPy 数组。

numpy_to_depth[[diffusers.VaeImageProcessorLDM3D.numpy_to_depth]]

numpy_to_depth(images: ndarray)

源代码

参数：

images (np.ndarray)：输入的 NumPy 深度图像数组，可以是单张图像或一个批次。

返回： list[PIL.Image.Image]

从输入的 NumPy 深度图像转换而来的 PIL 图像列表。

将 NumPy 深度图像或一批图像转换为 PIL 图像列表。

numpy_to_pil[[diffusers.VaeImageProcessorLDM3D.numpy_to_pil]]

numpy_to_pil(images: ndarray)

源代码

参数：

images (np.ndarray) : 输入的 NumPy 图像数组，可以是单张图像或一个批次。

返回： list[PIL.Image.Image]

从输入 NumPy 数组转换而来的 PIL 图像列表。

将 NumPy 图像或一批图像转换为 PIL 图像列表。

preprocess[[diffusers.VaeImageProcessorLDM3D.preprocess]]

preprocess(rgb: typing.Union[torch.Tensor, PIL.Image.Image, numpy.ndarray], depth: typing.Union[torch.Tensor, PIL.Image.Image, numpy.ndarray], height: int | None = None, width: int | None = None, target_res: int | None = None)

源代码

参数：

rgb (torch.Tensor | PIL.Image.Image | np.ndarray) : RGB 输入图像，可以是单张图像或一个批次。

depth (torch.Tensor | PIL.Image.Image | np.ndarray)：深度输入图像，可以是单张图像或一个批次。

height (int | None，可选，默认为 None)：处理后图像的目标高度。如果为 None，则默认为输入图像的高度。

width (int | None，可选，默认为 None)：处理后图像的期望宽度。如果为 None，则默认为输入图像的宽度。

target_res (int | None，可选，默认为 None)：用于调整图像大小的目标分辨率。如果指定，将覆盖 height 和 width。

返回： tuple[torch.Tensor, torch.Tensor]

一个元组，包含处理后的 RGB 图像和深度图像，均为 PyTorch 张量。

预处理图像输入。接受的格式为 PIL 图像、NumPy 数组或 PyTorch 张量。

rgblike_to_depthmap[[diffusers.VaeImageProcessorLDM3D.rgblike_to_depthmap]]

rgblike_to_depthmap(image: typing.Union[numpy.ndarray, torch.Tensor])

源代码

将类似 RGB 的深度图像转换为深度图。

PixArtImageProcessor[[diffusers.PixArtImageProcessor]]

diffusers.PixArtImageProcessor[[diffusers.PixArtImageProcessor]]

diffusers.PixArtImageProcessor(do_resize: bool = True, vae_scale_factor: int = 8, resample: str = 'lanczos', do_normalize: bool = True, do_binarize: bool = False, do_convert_grayscale: bool = False)

源代码

参数：

do_resize (bool，可选，默认为 True)：是否将图像的（高度，宽度）维度缩小为 vae_scale_factor 的倍数。可以接受来自 image_processor.VaeImageProcessor.preprocess() 方法的 height 和 width 参数。

vae_scale_factor (int，可选，默认为 8)：VAE 缩放因子。如果 do_resize 为 True，图像将自动调整为该因子的整数倍。

resample (str，可选，默认为 lanczos)：调整图像大小时使用的重采样滤波器。

do_normalize (bool，可选，默认为 True)：是否将图像归一化到 [-1,1]。

do_binarize (bool，可选，默认为 False)：是否将图像二值化为 0/1。

do_convert_rgb (bool，可选，默认为 False)：是否将图像转换为 RGB 格式。

do_convert_grayscale (bool，可选，默认为 False)：是否将图像转换为灰度格式。

用于 PixArt 图像缩放和裁剪的图像处理器。

classify_height_width_bin[[diffusers.PixArtImageProcessor.classify_height_width_bin]]

classify_height_width_bin(height: int, width: int, ratios: dict)

源代码

参数：

height (int) : 图像的高度。

width (int) : 图像的宽度。

ratios (dict) : 一个字典，其中键为宽高比，值为 (height, width) 元组。

返回： tuple[int, int]

最接近的分箱高度和宽度。

根据宽高比返回分箱后的高度和宽度。

resize_and_crop_tensor[[diffusers.PixArtImageProcessor.resize_and_crop_tensor]]

resize_and_crop_tensor(samples: Tensor, new_width: int, new_height: int)

源代码

参数：

samples (torch.Tensor) : 形状为 (N, C, H, W) 的张量，其中 N 为批次大小，C 为通道数，H 为高度，W 为宽度。

new_width (int) : 期望的输出图像宽度。

new_height (int) : 期望的输出图像高度。

返回： torch.Tensor

包含调整大小并裁剪后的图像的张量。

将图像张量调整大小并裁剪到指定尺寸。

IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

diffusers.IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

diffusers.IPAdapterMaskProcessor(do_resize: bool = True, vae_scale_factor: int = 8, resample: str = 'lanczos', do_normalize: bool = False, do_binarize: bool = True, do_convert_grayscale: bool = True)

源代码

参数：

do_resize (bool，可选，默认为 True)：是否将图像的 (height, width) 维度缩小为 vae_scale_factor 的整数倍。

vae_scale_factor (int，可选，默认为 8)：VAE 缩放因子。如果 do_resize 为 True，图像将自动调整为该因子的整数倍。

resample (str，可选，默认为 lanczos)：调整图像大小时使用的重采样滤波器。

do_normalize (bool，可选，默认为 False)：是否将图像归一化到 [-1,1]。

do_binarize (bool，可选，默认为 True)：是否将图像二值化为 0/1。

do_convert_grayscale (bool，可选，默认为 True)：是否将图像转换为灰度格式。

用于 IP Adapter 图像蒙版的图像处理器。

下采样[[diffusers.IPAdapterMaskProcessor.downsample]]

downsample(mask: Tensor, batch_size: int, num_queries: int, value_embed_dim: int)

源代码

参数：

mask (torch.Tensor) : 使用 IPAdapterMaskProcessor.preprocess() 生成的输入掩码张量。

batch_size (int) : 批次大小。

num_queries (int) : 查询的数量。

value_embed_dim (int)：值嵌入的维度。

返回： torch.Tensor

下采样后的掩码张量。

将提供的掩码张量下采样，以匹配缩放点积注意力所需的预期维度。如果掩码的宽高比与输出图像的宽高比不匹配，则会发出警告。