ML Community Day is November 9! Join us for updates from TensorFlow, JAX, and more Learn more

tensorflow::ops::StatelessSampleDistortedBoundingBox

#include <image_ops.h>

Generate a randomly distorted bounding box for an image deterministically.

Summary

Bounding box annotations are often supplied in addition to ground-truth labels in image recognition or object localization tasks. A common technique for training such a system is to randomly distort an image while preserving its content, i.e. data augmentation. This Op, given the same seed, deterministically outputs a randomly distorted localization of an object, i.e. bounding box, given an image_size, bounding_boxes and a series of constraints.

The output of this Op is a single bounding box that may be used to crop the original image. The output is returned as 3 tensors: begin, size and bboxes. The first 2 tensors can be fed directly into tf.slice to crop the image. The latter may be supplied to tf.image.draw_bounding_boxes to visualize what the bounding box looks like.

Bounding boxes are supplied and returned as [y_min, x_min, y_max, x_max]. The bounding box coordinates are floats in [0.0, 1.0] relative to the width and the height of the underlying image.

The output of this Op is guaranteed to be the same given the same seed and is independent of how many times the function is called, and independent of global seed settings (e.g. tf.random.set_seed).

Example usage:

image = np.array([[[1], [2], [3]], [[4], [5], [6]], [[7], [8], [9]]]) bbox = tf.constant( ... [0.0, 0.0, 1.0, 1.0], dtype=tf.float32, shape=[1, 1, 4]) seed = (1, 2)

Generate a single distorted bounding box.

bbox_begin, bbox_size, bbox_draw = ( ... tf.image.stateless_sample_distorted_bounding_box( ... tf.shape(image), bounding_boxes=bbox, seed=seed))

Employ the bounding box to distort the image.

tf.slice(image, bbox_begin, bbox_size)

Draw the bounding box in an image summary.

colors = np.array([[1.0, 0.0, 0.0], [0.0, 0.0, 1.0]]) tf.image.draw_bounding_boxes( ... tf.expand_dims(tf.cast(image, tf.float32),0), bbox_draw, colors)

Note that if no bounding box information is available, setting use_image_if_no_bounding_boxes = true will assume there is a single implicit bounding box covering the whole image. If use_image_if_no_bounding_boxes is false and no bounding boxes are supplied, an error is raised.

Arguments:

  • scope: A Scope object
  • image_size: 1-D, containing [height, width, channels].
  • bounding_boxes: 3-D with shape [batch, N, 4] describing the N bounding boxes associated with the image.
  • min_object_covered: The cropped area of the image must contain at least this fraction of any bounding box supplied. The value of this parameter should be non-negative. In the case of 0, the cropped area does not need to overlap any of the bounding boxes supplied.
  • seed: 1-D with shape [2]. The seed to the random number generator. Must have dtype int32 or int64. (When using XLA, only int32 is allowed.)

Optional attributes (see Attrs):

  • aspect_ratio_range: The cropped area of the image must have an aspect ratio = width / height within this range.
  • area_range: The cropped area of the image must contain a fraction of the supplied image within this range.
  • max_attempts: Number of attempts at generating a cropped region of the image of the specified constraints. After max_attempts failures, return the entire image.
  • use_image_if_no_bounding_boxes: Controls behavior if no bounding boxes supplied. If true, assume an implicit bounding box covering the whole input. If false, raise an error.

Returns:

  • Output begin: 1-D, containing [offset_height, offset_width, 0]. Provide as input to tf.slice.
  • Output size: 1-D, containing [target_height, target_width, -1]. Provide as input to tf.slice.
  • Output bboxes: 3-D with shape [1, 1, 4] containing the distorted bounding box. Provide as input to tf.image.draw_bounding_boxes.

Constructors and Destructors

StatelessSampleDistortedBoundingBox(const ::tensorflow::Scope & scope, ::tensorflow::Input image_size, ::tensorflow::Input bounding_boxes, ::tensorflow::Input min_object_covered, ::tensorflow::Input seed)
StatelessSampleDistortedBoundingBox(const ::tensorflow::Scope & scope, ::tensorflow::Input image_size, ::tensorflow::Input bounding_boxes, ::tensorflow::Input min_object_covered, ::tensorflow::Input seed, const StatelessSampleDistortedBoundingBox::Attrs & attrs)

Public attributes

bboxes
begin
operation
size

Public static functions

AreaRange(const gtl::ArraySlice< float > & x)
AspectRatioRange(const gtl::ArraySlice< float > & x)
MaxAttempts(int64 x)
UseImageIfNoBoundingBoxes(bool x)

Structs

tensorflow::ops::StatelessSampleDistortedBoundingBox::Attrs

Optional attribute setters for StatelessSampleDistortedBoundingBox.

Public attributes

bboxes

::tensorflow::Output bboxes

begin

::tensorflow::Output begin

operation

Operation operation

size

::tensorflow::Output size

Public functions

StatelessSampleDistortedBoundingBox

 StatelessSampleDistortedBoundingBox(
  const ::tensorflow::Scope & scope,
  ::tensorflow::Input image_size,
  ::tensorflow::Input bounding_boxes,
  ::tensorflow::Input min_object_covered,
  ::tensorflow::Input seed
)

StatelessSampleDistortedBoundingBox

 StatelessSampleDistortedBoundingBox(
  const ::tensorflow::Scope & scope,
  ::tensorflow::Input image_size,
  ::tensorflow::Input bounding_boxes,
  ::tensorflow::Input min_object_covered,
  ::tensorflow::Input seed,
  const StatelessSampleDistortedBoundingBox::Attrs & attrs
)

Public static functions

AreaRange

Attrs AreaRange(
  const gtl::ArraySlice< float > & x
)

AspectRatioRange

Attrs AspectRatioRange(
  const gtl::ArraySlice< float > & x
)

MaxAttempts

Attrs MaxAttempts(
  int64 x
)

UseImageIfNoBoundingBoxes

Attrs UseImageIfNoBoundingBoxes(
  bool x
)