nvidia.dali.fn.random_bbox_crop#

nvidia.dali.fn.random_bbox_crop(__boxes, __labels=None, /, *, all_boxes_above_threshold=True, allow_no_crop=True, aspect_ratio=[1.0, 1.0], bbox_layout='', bbox_prune_threshold=None, bytes_per_sample_hint=[0], crop_shape=[], input_shape=[], ltrb=True, num_attempts=1, output_bbox_indices=False, preserve=False, scaling=[1.0, 1.0], seed=-1, shape_layout='', threshold_type='iou', thresholds=[0.0], total_num_attempts=-1, device=None, name=None)#

对图像坐标空间应用前瞻性的随机裁剪，同时保持边界框，并可选择保持标签一致。

这意味着在对图像坐标空间应用随机裁剪操作符后，边界框将被调整或过滤掉，以匹配裁剪后的 ROI。应用的随机裁剪操作受提供给操作符的参数约束。

裁剪窗口候选框是随机选择的，直到一个候选框符合由 thresholds 参数指定的重叠限制。thresholds 值表示由 threshold_type 指定的最小重叠度量，例如裁剪窗口和边界框的 intersection-over-union，或作为交集区域与边界框区域之比的相对重叠。

此外，如果 allow_no_crop 为 True，则可以完全跳过裁剪，作为操作符的有效结果之一。

以下是随机裁剪的可用模式

  • 随机形状窗口，随机放置在原始输入空间中。
    随机裁剪窗口尺寸被选择为满足宽高比和相对面积限制。
    如果提供了 input_shape，它将被考虑用于宽高比范围检查。
    否则，宽高比以相对术语计算。
    换句话说，如果没有 input_shape，宽高比 1.0 等效于输入图像的宽高比。
  • 固定大小窗口，随机放置在原始输入空间中。
    随机裁剪窗口尺寸取自 crop_shape 参数，锚点是
    随机选择的。
    当提供 crop_shape 时，还需要 input_shape (这些尺寸是缩放输出边界框所必需的)。
    缩放输出边界框)。

num_attempts 参数可用于控制尝试生成有效裁剪的最大次数，以匹配来自 thresholds 的最小重叠度量值。

警告

当 allow_no_crop 为 False 且 thresholds 不包含 0.0 时，如果您不增加 num_attempts 值，它可能会继续循环很长时间。

输入 0：bboxes，（1：labels）

第一个输入 bboxes 是指作为二维张量提供的边界框，其中第一维是指边界框的索引，第二维是指坐标的索引。

坐标是相对于原始图像尺寸的（这意味着范围为 [0.0, 1.0]），表示区域的开始，以及根据 bbox_layout 的值，区域的结束或开始和形状。例如，bbox_layout=”xyXY” 表示边界框坐标遵循 start_x、start_y、end_x 和 end_y 顺序，而 bbox_layout=”xyWH” 表示顺序为 start_x、start_y、width 和 height。有关更多信息，请参阅 bbox_layout 参数描述。

可以提供可选输入 labels，表示与每个边界框关联的标签。

输出 0：anchor，1：shape，2：bboxes（，3：labels，4：bboxes_indices）

结果裁剪参数作为两个单独的输出提供，anchor 和 shape，可以直接馈送到 nvidia.dali.fn.slice() 操作符，以完成原始图像的裁剪。anchor 和 shape 分别包含 [x, y, (z)] 和 [w, h, (d)] 格式的裁剪的起始坐标和尺寸。坐标可以用绝对或相对术语表示，表示形式取决于是否使用了固定的 crop_shape。

注意

即使 anchor 和 shape 由于提供了 crop_shape 参数而表示绝对坐标，它们也作为 float 返回。为了使 nvidia.dali.fn.slice() 正确解释它们，normalized_anchor 和 normalized_shape 应设置为 False。

第三个输出包含边界框，在通过质心或面积阈值处理（参见 bbox_prune_threshold 参数）过滤掉它们之后，以及坐标映射到新坐标空间之后。

下一个输出是可选的，它表示与过滤后的边界框关联的标签。如果提供了标签输入，则将显示该输出。

最后一个输出也是可选的，对应于通过上述过滤过程并在输出中存在的边界框的原始索引。如果选项 output_bbox_indices 设置为 True，则将显示此输出。

支持的后端

  • ‘cpu’

参数:

  • __boxes (float 的 2D TensorList) – 边界框的相对坐标，表示为 2D 张量，其中第一维是指边界框的索引，第二维是指坐标的索引。

  • __labels (整数的 1D TensorList，可选) – 与每个边界框关联的标签。

关键字参数:

  • all_boxes_above_threshold (bool，可选，默认值 = True) –

    如果设置为 True，则样本中的所有边界框都应与裁剪窗口重叠，如 thresholds 所指定。

    如果边界框不重叠，则裁剪窗口被视为无效。如果设置为 False，并且至少有一个边界框与窗口重叠，则该窗口被视为有效。

  • allow_no_crop (bool，可选，默认值 = True) – 如果设置为 True，则随机过程的可能结果之一将是不裁剪，就好像结果是另一个 thresholds 值可供选择一样。

  • aspect_ratio (float 或 float 列表，可选，默认值 = [1.0, 1.0]) –

    裁剪窗口的有效宽高比范围。

    此参数可以指定为两个值（最小，最大）或六个值（三对），具体取决于输入的维度。

    • 对于 2D 边界框，应提供一个有效宽高比范围 (x/y)（例如 [min_xy, max_xy]）。
    • 对于 3D 边界框，可以为 x/y、x/z 和 y/z 尺寸对指定三个单独的宽高比范围。
      它们按以下顺序提供 [min_xy, max_xy, min_xz, max_xz, min_yz, max_yz]。或者，如果仅提供一个宽高比范围，它将用于所有三对尺寸。

    min 的值应大于 0.0，并且 min 应小于或等于 max 值。默认情况下，生成正方形窗口。

    注意

    提供 aspect_ratio 和 scaling 与显式指定 crop_shape 不兼容。

    注意

    如果提供了 input_shape，它将被考虑用于计算裁剪窗口宽高比。否则，宽高比范围是相对于图像尺寸的。换句话说，当未指定 input_shape 时，宽高比 1.0 等效于图像的原始宽高比。

  • bbox_layout (布局字符串，可选，默认值 = ‘’) –

    确定边界框坐标的含义。

    此参数的值是包含以下字符的字符串

    x (horizontal start anchor), y (vertical start anchor), z (depthwise start anchor),
X (horizontal end anchor),   Y (vertical end anchor),   Z (depthwise end anchor),
W (width),                   H (height),                D (depth).

    注意

    如果此值留空，则根据维度数量，假定为 “xyXY” 或 “xyzXYZ”。

  • bbox_prune_threshold (float，可选) –

    控制何时将 bboxes 视为在 ROI 之外并被修剪。如果设置此参数，则当框的区域在 ROI 内的比例大于或等于指定的阈值 [0.0,1.0] 时，将保留这些框。如果 未 设置此参数，则当框的质心在 ROI 之外时，将修剪这些框。

    例如，当 bbox_prune_threshold=0.2 时，至少有 20% 的原始区域在 ROI 内的 bboxes 将被保留，小于或等于此值的 bboxes 将被修剪。如果 bbox_prune_threshold=0.0，则 ROI 中存在的所有框都将被保留。

  • bytes_per_sample_hint (int 或 int 列表，可选，默认值 = [0]) –

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

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

  • crop_shape (int 或 int 列表 或 int 的 TensorList，可选，默认值 = []) –

    如果提供，则随机裁剪窗口尺寸将固定为此形状。

    尺寸的顺序由 shape_layout 中提供的布局确定。

    注意

    当提供 crop_shape 时，也应提供 input_shape。提供显式 crop_shape 与使用 scaling 和 aspect_ratio 参数不兼容。

  • input_shape (int 或 int 列表 或 int 的 TensorList，可选，默认值 = []) –

    指定原始输入图像的形状。

    尺寸的顺序由 shape_layout 中提供的布局确定。

  • ltrb (bool，可选，默认值 = True) –

    如果设置为 True，则 bboxes 将作为 [left, top, right, bottom] 返回；否则，它们将作为 [left, top, width, height] 提供。

    警告

    此参数已弃用。要指定 bbox 编码，请使用 bbox_layout 参数代替。例如，ltrb=True 等同于 bbox_layout=”xyXY”，而 ltrb=False 对应于 bbox_layout=”xyWH”。

  • num_attempts (int, optional, default = 1) –

    尝试获取与 aspect_ratio 宽高比和从 thresholds 中选择的值相匹配的裁剪窗口的次数。

    每次尝试 num_attempts 次后，将选择不同的阈值，直到阈值达到最大值 total_num_attempts (如果提供) 或无限期地进行下去。

  • output_bbox_indices (bool, optional, default = False) – 如果设置为 True，则会返回一个额外的输出，其中包含通过质心过滤器并在输出边界框中存在的原始边界框的索引。

  • preserve (bool, optional, default = False) – 阻止运算符从图中移除，即使其输出未使用。

  • scaling (float or list of float, optional, default = [1.0, 1.0]) –

    裁剪尺寸相对于原始图像尺寸的范围 [min, max]。

    min 和 max 的值必须满足条件 0.0 <= min <= max。

    注意

    当显式指定 crop_shape 值时，提供 aspect_ratio 和 scaling 是不兼容的。

  • seed (int, optional, default = -1) – 随机种子；如果未设置，将自动分配一个。

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

    确定 crop_shape 和 input_shape 中提供的维度的含义。

    这些值是

    • W (宽度)

    • H (高度)

    • D (深度)

    注意

    如果留空，则根据维度的数量，将假定为 "WH" 或 "WHD"。

  • threshold_type (str, optional, default = ‘iou’) –

    确定 thresholds 的含义。

    默认情况下，阈值指的是边界框相对于裁剪窗口的交并比 (IoU)。或者，可以将阈值设置为 “overlap” 以指定将落入裁剪窗口内的边界框的面积比例。例如，阈值 1.0 表示整个边界框必须包含在结果裁剪窗口中。

  • thresholds (float or list of float, optional, default = [0.0]) –

    边界框相对于裁剪窗口的最小 IoU 或不同的度量标准（如果由 threshold_type 指定）。

    每个样本随机选择一个 thresholds，并且运算符将完成最多指定次数的尝试，以生成一个随机裁剪窗口，使其所选度量标准高于该阈值。有关配置尝试次数的更多信息，请参阅 num_attempts。

  • total_num_attempts (int, optional, default = -1) –

    如果提供，则表示获取与 aspect_ratio 宽高比和从 thresholds 中选择的任何值相匹配的裁剪窗口的最大尝试总次数。

    在 total_num_attempts 次尝试后，将选择最佳候选项。

    如果未指定此值，裁剪搜索将无限期地继续，直到找到有效的裁剪为止。

    警告

    如果您不提供 total_num_attempts 值，如果参数施加的条件无法满足，则可能导致无限循环。

在本页中