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，并且最小值应小于或等于 max 值。默认情况下，生成正方形窗口。

    注意

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

    注意

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

  • bbox_layout (layout str, 可选, 默认值 = ‘’) –

    确定边界框坐标的含义。

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

    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 时，在 ROI 内至少有 20% 原始面积的 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, 可选, 默认值 = 1) –

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

    在每次 num_attempts 之后，将选择不同的阈值，直到阈值达到最大值 total_num_attempts（如果提供），否则无限期地进行。

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

  • preserve (bool, 可选, 默认值 = False) – 即使操作符的输出未使用，也阻止从图中删除该操作符。

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

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

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

    注意

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

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

  • shape_layout (layout str, 可选, 默认 = ‘’) –

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

    值包括

    • W (宽度)

    • H (高度)

    • D (深度)

    注意

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

  • threshold_type (str, 可选, 默认 = ‘iou’) –

    确定 thresholds 的含义。

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

  • thresholds (float 或 float 列表, 可选, 默认 = [0.0]) –

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

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

  • total_num_attempts (int, 可选, 默认 = -1) –

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

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

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

    警告

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

在本页中