nvidia.dali.fn.decoders.image_slice

nvidia.dali.fn.decoders.image_slice(__data, __anchor=None, __shape=None, /, *, affine=True, axes=[1, 0], axis_names='WH', bytes_per_sample_hint=[0], device_memory_padding=16777216, device_memory_padding_jpeg2k=0, end=None, host_memory_padding=8388608, host_memory_padding_jpeg2k=0, hw_decoder_load=0.65, hybrid_huffman_threshold=1000000, jpeg_fancy_upsampling=False, memory_stats=False, normalized_anchor=True, normalized_shape=True, output_type=DALIImageType.RGB, preallocate_height_hint=0, preallocate_width_hint=0, preserve=False, rel_end=None, rel_shape=None, rel_start=None, shape=None, start=None, use_fast_idct=False, device=None, name=None)

解码图像并提取感兴趣区域。

切片可以通过提供起始和结束坐标，或起始坐标和切片形状来指定。坐标和形状都可以以绝对或相对方式提供。

切片参数可以通过以下命名参数指定

1. start：切片起始坐标（绝对）

2. rel_start：切片起始坐标（相对）

3. end：切片结束坐标（绝对）

4. rel_end：切片结束坐标（相对）

5. shape：切片形状（绝对）

6. rel_shape：切片形状（相对）

切片可以通过提供起始和结束坐标或起始和形状来配置。相对和绝对参数可以混合使用（例如，rel_start 可以与 shape 一起使用），只要起始和形状或结束被唯一地定义。

或者，可以提供两个额外的位置输入，指定 __anchor 和 __shape。当使用位置输入时，可以使用两个额外的布尔参数 normalized_anchor/normalized_shape 来指定所提供参数的性质。使用 anchor 和 shape 的位置输入与上面指定的命名参数不兼容。

切片参数应提供与 axis_names 或 axes 参数指定的维度一样多的维度。

默认情况下，nvidia.dali.fn.decoders.image_slice() 操作符对切片参数使用归一化坐标和 “WH” 顺序。

如果可能，该参数使用 ROI 解码 API（例如，libjpeg-turbo 和 nvJPEG）来优化解码时间和内存使用。当给定图像格式不支持 ROI 解码时，它将解码整个图像并裁剪选定的 ROI。

解码器的输出采用 HWC 布局。

支持的格式：JPG、BMP、PNG、TIFF、PNM、PPM、PGM、PBM、JPEG 2000、WebP。

注意

JPEG 2000 感兴趣区域 (ROI) 解码在 GPU 上未加速，并且无论选择哪个后端都将使用 CPU 实现。对于 GPU 加速实现，请考虑使用单独的 decoders.image 和 slice 操作符。

注意

EXIF 方向元数据被忽略。

支持的后端

• ‘cpu’

• ‘mixed’

参数:

• __data (TensorList) – 包含输入数据的批次。

• __anchor (1D TensorList of float or int, optional) –

  包含切片起始点（x0、x1、x2 等）的归一化或绝对坐标的输入。

  整数坐标被解释为绝对坐标，而浮点坐标可以解释为绝对或相对坐标，具体取决于 normalized_anchor 的值。

• __shape (1D TensorList of float or int, optional) –

  包含切片维度（s0、s1、s2 等）的归一化或绝对坐标的输入。

  整数坐标被解释为绝对坐标，而浮点坐标可以解释为绝对或相对坐标，具体取决于 normalized_shape 的值。

关键字参数:

• affine (bool, optional, default = True) –

  仅适用于 mixed 后端类型。

  如果设置为 True，则内部线程池中的每个线程将绑定到特定的 CPU 核心。否则，线程可以由操作系统重新分配给任何 CPU 核心。

• axes (int or list of int or TensorList of int, optional, default = [1, 0]) –

  用作维度索引的锚点和形状切片输入的维度顺序。

  负值被解释为从后面计数维度。有效范围：[-ndim, ndim-1]，其中 ndim 是输入数据中的维度数。

• axis_names (layout str, optional, default = ‘WH’) –

  用于锚点和形状切片输入的维度顺序，如布局中所述。

  如果提供了值，则 axis_names 的优先级高于 axes。

• bytes_per_sample_hint (int or list of int, optional, default = [0]) –

  每个样本的输出大小提示（以字节为单位）。

  如果指定，则位于 GPU 或页锁定主机内存中的操作符输出将被预先分配，以容纳此大小的样本批次。

• device_memory_padding (int, optional, default = 16777216) –

  仅适用于 mixed 后端类型。

  nvJPEG 设备内存分配的填充，以字节为单位。此参数有助于避免在遇到更大的图像时 nvJPEG 中的重新分配，并且需要重新分配内部缓冲区以解码图像。

  如果提供的值大于 0，则操作符为每个线程预先分配一个请求大小的设备缓冲区。如果正确选择了值，则在 pipeline 执行期间不会发生额外的分配。查找理想值的一种方法是使用设置为 True 的 memory_stats 参数对数据集进行完整运行，然后复制统计信息中打印的最大分配值。

• device_memory_padding_jpeg2k (int, optional, default = 0) –

  仅适用于 mixed 后端类型。

  nvJPEG2k 设备内存分配的填充，以字节为单位。此参数有助于避免在遇到更大的图像时 nvJPEG2k 中的重新分配，并且需要重新分配内部缓冲区以解码图像。

  如果提供的值大于 0，则操作符根据提供的提示预先分配必要数量的缓冲区。如果正确选择了值，则在 pipeline 执行期间不会发生额外的分配。查找理想值的一种方法是使用设置为 True 的 memory_stats 参数对数据集进行完整运行，然后复制统计信息中打印的最大分配值。

• end (int or list of int or TensorList of int, optional) –

  切片的结束坐标。

  注意：提供命名参数 start、end、shape、rel_start、rel_end、rel_shape 与提供位置输入 anchor 和 shape 不兼容。

• host_memory_padding (int, optional, default = 8388608) –

  仅适用于 mixed 后端类型。

  nvJPEG 主机内存分配的填充，以字节为单位。此参数有助于防止在遇到更大的图像时 nvJPEG 中的重新分配，并且需要重新分配内部缓冲区以解码图像。

  如果提供的值大于 0，则操作符为每个线程预先分配两个（由于双缓冲）请求大小的主机固定缓冲区。如果选择正确，则在 pipeline 执行期间不会发生额外的分配。查找理想值的一种方法是使用设置为 True 的 memory_stats 参数对数据集进行完整运行，然后复制统计信息中打印的最大分配值。

• host_memory_padding_jpeg2k (int, optional, default = 0) –

  仅适用于 mixed 后端类型。

  nvJPEG2k 主机内存分配的填充，以字节为单位。此参数有助于防止在遇到更大的图像时 nvJPEG2k 中的重新分配，并且需要重新分配内部缓冲区以解码图像。

  如果提供的值大于 0，则运算符会根据提供的提示预先分配所需数量的缓冲区。如果正确选择该值，则在管道执行期间不会发生额外的分配。 找到理想值的一种方法是使用设置为 True 的 memory_stats 参数对数据集进行完整运行，然后复制统计信息中打印的最大分配值。

• hw_decoder_load (float, 可选, 默认值 = 0.65) –

  由硬件 JPEG 解码器处理的图像数据百分比。

  仅适用于 NVIDIA Ampere GPU 和更新架构中的 mixed 后端类型。

  确定在硬件解码器可用时，将卸载到硬件解码器的工作负载百分比。最佳工作负载取决于提供给 DALI 管道的线程数，应通过经验找到。更多详细信息请参见 https://developer.nvidia.com/blog/loading-data-fast-with-dali-and-new-jpeg-decoder-in-a100

• hybrid_huffman_threshold (int, 可选, 默认值 = 1000000) –

  仅适用于 mixed 后端类型。

  像素总数（height * width）高于此阈值的图像将使用 nvJPEG 混合 Huffman 解码器。像素较少的图像将使用 nvJPEG 主机端 Huffman 解码器。

  注意

  混合 Huffman 解码器仍然主要使用 CPU。

• jpeg_fancy_upsampling (bool, 可选, 默认值 = False) –

  使 mixed 后端使用与 cpu 后端相同的色度上采样方法。

  此选项对应于 libjpegturbo 或 ImageMagick 中提供的 JPEG 精细上采样。

• memory_stats (bool, 可选, 默认值 = False) –

  仅适用于 mixed 后端类型。

  打印有关 nvJPEG 分配的调试信息。有关最大分配的信息可能有助于确定数据集的 device_memory_padding 和 host_memory_padding 的合适值。

  注意

  统计信息是针对整个进程全局的，而不是每个运算符实例，并且包括在构造期间进行的分配（如果填充提示为非零）。

• normalized_anchor (bool, 可选, 默认值 = True) –

  确定锚点位置输入应解释为归一化坐标（范围 [0.0, 1.0]）还是绝对坐标。

  注意

  此参数仅在锚点数据类型为 float 时相关。对于整数类型，坐标始终是绝对坐标。

• normalized_shape (bool, 可选, 默认值 = True) –

  确定形状位置输入应解释为归一化坐标（范围 [0.0, 1.0]）还是绝对坐标。

  注意

  此参数仅在锚点数据类型为 float 时相关。对于整数类型，坐标始终是绝对坐标。

• output_type (nvidia.dali.types.DALIImageType, 可选, 默认值 = DALIImageType.RGB) –

  输出图像的色彩空间。

  注意：当解码为 YCbCr 时，图像将先解码为 RGB，然后转换为 YCbCr，遵循 ITU-R BT.601 中的 YCbCr 定义。

• preallocate_height_hint (int, 可选, 默认值 = 0) –

  图像宽度提示。

  仅适用于 NVIDIA Ampere GPU 和更新架构中的 mixed 后端类型。

  该提示用于为 HW JPEG 解码器预分配内存。

• preallocate_width_hint (int, 可选, 默认值 = 0) –

  图像宽度提示。

  仅适用于 NVIDIA Ampere GPU 和更新架构中的 mixed 后端类型。

  该提示用于为 HW JPEG 解码器预分配内存。

• preserve (bool, 可选, 默认值 = False) – 阻止运算符从图中删除，即使其输出未使用。

• rel_end (float 或 float 列表或 TensorList of float, 可选) –

  切片的相对结束坐标（范围 [0.0 - 1.0]）。

  注意：提供命名参数 start、end、shape、rel_start、rel_end、rel_shape 与提供位置输入 anchor 和 shape 不兼容。

• rel_shape (float 或 float 列表或 TensorList of float, 可选) –

  切片的相对形状（范围 [0.0 - 1.0]）。

  提供命名参数 start, end, shape, rel_start, rel_end, rel_shape 与提供位置输入 anchor 和 shape 不兼容。

• rel_start (float 或 float 列表或 TensorList of float, 可选) –

  切片的相对起始坐标（范围 [0.0 - 1.0]）。

  注意：提供命名参数 start、end、shape、rel_start、rel_end、rel_shape 与提供位置输入 anchor 和 shape 不兼容。

• shape (int 或 int 列表或 TensorList of int, 可选) –

  切片的形状。

  提供命名参数 start, end, shape, rel_start, rel_end, rel_shape 与提供位置输入 anchor 和 shape 不兼容。

• split_stages (bool) –

  警告

  参数 split_stages 已不再使用，并将在未来的版本中移除。

• start (int 或 int 列表或 TensorList of int, 可选) –

  切片的起始坐标。

  注意：提供命名参数 start/end 或 start/shape 与提供位置输入 anchor 和 shape 不兼容。

• use_chunk_allocator (bool) –

  警告

  参数 use_chunk_allocator 已不再使用，并将在未来的版本中移除。

• use_fast_idct (bool, 可选, 默认值 = False) –

  在基于 libjpeg-turbo 的 CPU 解码器中启用快速 IDCT，当 device 设置为 “cpu” 时，或者当它设置为 “mixed” 但特定图像无法由 GPU 实现处理时使用。

  根据 libjpeg-turbo 文档，解压缩性能最多可提高 14%，而质量几乎没有降低。

另请参阅

• 图像解码器示例