Diffusers documentation

VAE 图像处理器

Diffusers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

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

( do_resize: bool = Truevae_scale_factor: int = 8vae_latent_channels: int = 4resample: str = 'lanczos'reducing_gap: int | None = Nonedo_normalize: bool = Truedo_binarize: bool = Falsedo_convert_rgb: bool = Falsedo_convert_grayscale: bool = False )

参数

do_resize (bool，可选，默认为 True) — 是否将图像的 (height, width) 维度缩小为 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 的图像处理器。

应用叠加层

( mask: Imageinit_image: Imageimage: Imagecrop_coords: tuple[int, int, int, int] | None = None ) → PIL.Image.Image

参数

mask (PIL.Image.Image) — 用于突出显示要叠加区域的遮罩图像。
init_image (PIL.Image.Image) — 应用叠加层的原始图像。
image (PIL.Image.Image) — 要叠加到原始图像上的图像。
crop_coords (tuple[int, int, int, int], 可选) — 用于裁剪图像的坐标。如果提供，图像将按此坐标进行裁剪。

返回值

PIL.Image.Image

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

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

binarize

( image: Image ) → PIL.Image.Image

参数

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

返回值

PIL.Image.Image

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

创建一个掩码。

模糊

( image: Imageblur_factor: int = 4 ) → PIL.Image.Image

参数

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

返回值

PIL.Image.Image

经过灰度转换的 PIL 图像。

对图像应用高斯模糊。

convert_to_grayscale

( image: Image ) → PIL.Image.Image

参数

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

返回值

PIL.Image.Image

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

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

convert_to_rgb

( image: Image ) → PIL.Image.Image

参数

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

返回值

PIL.Image.Image

经过 RGB 转换的 PIL 图像。

将 PIL 图像转换为 RGB 格式。

denormalize

( images: typing.Union[numpy.ndarray, torch.Tensor] ) → np.ndarray or torch.Tensor

参数

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

返回值

np.ndarray 或 torch.Tensor

反归一化的图像数组。

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

get_crop_region

( mask_image: Imagewidth: intheight: intpad = 0 ) → tuple

参数

mask_image (PIL.Image.Image) — 掩码图像。
width (int) — 要处理的图像的宽度。
height (int) — 要处理的图像的高度。
pad (int, 可选) — 添加到裁剪区域的填充。默认值为 0。

返回值

tuple

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

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

get_default_height_width

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

参数

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

( images: typing.Union[numpy.ndarray, torch.Tensor] ) → np.ndarray or torch.Tensor

参数

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

返回值

np.ndarray 或 torch.Tensor

归一化后的图像数组。

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

numpy_to_pil

( images: ndarray ) → list[PIL.Image.Image]

参数

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

返回值

list[PIL.Image.Image]

PIL 图像列表。

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

numpy_to_pt

( images: ndarray ) → torch.Tensor

参数

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

返回值

torch.Tensor

图像的 PyTorch 张量表示。

将 NumPy 图像转换为 PyTorch 张量。

pil_to_numpy

( images: list[PIL.Image.Image] | PIL.Image.Image ) → np.ndarray

参数

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

返回值

np.ndarray

图像的 NumPy 数组表示。

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

后处理

( image: Tensoroutput_type: str = 'pil'do_denormalize: list[bool] | None = None ) → PIL.Image.Image, np.ndarray or torch.Tensor

参数

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。

预处理

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

参数

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，则将图像缩放以适应指定的宽度和高度，保持宽高比，然后将图像居中于该尺寸内，并裁剪掉多余部分。请注意，fill 和 crop 这两种 resize_mode 仅支持 PIL 图像输入。
crops_coords (list[tuple[int, int, int, int]]，可选，默认为 None) — 批次中每张图片的裁剪坐标。如果为 None，则不对图片进行裁剪。

返回值

torch.Tensor

预处理后的图像。

预处理图像输入。

pt_to_numpy

( images: Tensor ) → np.ndarray

参数

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

返回值

np.ndarray

图像的 NumPy 数组表示。

将 PyTorch 张量转换为 NumPy 图像。

调整大小

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor]height: intwidth: intresize_mode: str = 'default' ) → PIL.Image.Image, np.ndarray or torch.Tensor

参数

image (PIL.Image.Image、np.ndarray 或 torch.Tensor) — 图像输入，可以是 PIL 图像、numpy 数组或 pytorch 张量。
height (int) — 要调整到的目标高度。
width (int) — 要调整到的宽度。
resize_mode (str, 可选, 默认为 default) — 要使用的缩放模式，可以是 default 或 fill 之一。如果为 default，则将图像缩放以适应指定的宽度和高度，且可能不保持原始宽高比。如果为 fill，则将图像缩放以适应指定的宽度和高度，保持宽高比，然后将图像居中于该尺寸内，并用图像数据填充空白区域。如果为 crop，则将图像缩放以适应指定的宽度和高度，保持宽高比，然后将图像居中于该尺寸内，并裁剪掉多余部分。请注意，fill 和 crop 这两种 resize_mode 仅支持 PIL 图像输入。

返回值

PIL.Image.Image、np.ndarray 或 torch.Tensor

调整大小后的图像。

调整图像大小。

InpaintProcessor

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

类 diffusers.InpaintProcessor

( do_resize: bool = Truevae_scale_factor: int = 8vae_latent_channels: int = 4resample: str = 'lanczos'reducing_gap: int | None = Nonedo_normalize: bool = Truedo_binarize: bool = Falsedo_convert_grayscale: bool = Falsemask_do_normalize: bool = Falsemask_do_binarize: bool = Truemask_do_convert_grayscale: bool = True )

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

后处理

( image: Tensoroutput_type: str = 'pil'original_image: PIL.Image.Image | None = Noneoriginal_mask: PIL.Image.Image | None = Nonecrops_coords: tuple[int, int, int, int] | None = None )

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

预处理

( image: Imagemask: PIL.Image.Image | None = Noneheight: int | None = Nonewidth: int | None = Nonepadding_mask_crop: int | None = None )

预处理图像和掩码。

VaeImageProcessorLDM3D

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

类 diffusers.VaeImageProcessorLDM3D

( do_resize: bool = Truevae_scale_factor: int = 8resample: str = 'lanczos'do_normalize: bool = True )

参数

do_resize (bool，可选，默认为 True) — 是否将图像的（高度，宽度）维度缩小为 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

( images: list[PIL.Image.Image] | PIL.Image.Image ) → np.ndarray

参数

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

返回值

np.ndarray

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

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

numpy_to_depth

( images: ndarray ) → list[PIL.Image.Image]

参数

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

返回值

list[PIL.Image.Image]

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

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

numpy_to_pil

( images: ndarray ) → list[PIL.Image.Image]

参数

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

返回值

list[PIL.Image.Image]

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

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

预处理

( rgb: typing.Union[torch.Tensor, PIL.Image.Image, numpy.ndarray]depth: typing.Union[torch.Tensor, PIL.Image.Image, numpy.ndarray]height: int | None = Nonewidth: int | None = Nonetarget_res: int | None = None ) → tuple[torch.Tensor, torch.Tensor]

参数

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

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

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

PixArtImageProcessor

class diffusers.PixArtImageProcessor

( do_resize: bool = Truevae_scale_factor: int = 8resample: str = 'lanczos'do_normalize: bool = Truedo_binarize: bool = Falsedo_convert_grayscale: bool = False )

参数

do_resize (bool，可选，默认为 True) — 是否将图像的 (height, width) 维度缩小为 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

( height: intwidth: intratios: dict ) → tuple[int, int]

参数

height (int) — 图像的高度。
width (int) — 图像的宽度。
ratios (dict) — 一个字典，其中键为宽高比，值为 (height, width) 元组。

返回值

tuple[int, int]

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

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

resize_and_crop_tensor

( samples: Tensornew_width: intnew_height: int ) → torch.Tensor

参数

samples (torch.Tensor) — 形状为 (N, C, H, W) 的张量，其中 N 为批处理大小，C 为通道数，H 为高度，W 为宽度。
new_width (int) — 输出图像的期望宽度。
new_height (int) — 输出图像的期望高度。

返回值

torch.Tensor

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

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

IPAdapterMaskProcessor

类 diffusers.IPAdapterMaskProcessor

( do_resize: bool = Truevae_scale_factor: int = 8resample: str = 'lanczos'do_normalize: bool = Falsedo_binarize: bool = Truedo_convert_grayscale: bool = True )

参数

do_resize (bool，可选，默认为 True) — 是否将图像的（高度，宽度）维度缩小为 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 图像蒙版的图像处理器。

下采样

( mask: Tensorbatch_size: intnum_queries: intvalue_embed_dim: int ) → torch.Tensor

参数

mask (torch.Tensor) — 使用 IPAdapterMaskProcessor.preprocess() 生成的输入掩码张量。
batch_size (int) — 批次大小。
num_queries (int) — 查询的数量。
value_embed_dim (int) — 值嵌入的维度。

返回值

torch.Tensor

下采样后的掩码张量。

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

Update on GitHub

←实用工具视频处理器→