Generate a randomly distorted bounding box for an image deterministically.
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)
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.
Nested Classes
class | StatelessSampleDistortedBoundingBox.Options | Optional attributes for StatelessSampleDistortedBoundingBox
|
Public Methods
static StatelessSampleDistortedBoundingBox.Options |
areaRange(List<Float> areaRange)
|
static StatelessSampleDistortedBoundingBox.Options |
aspectRatioRange(List<Float> aspectRatioRange)
|
Output<Float> |
bboxes()
3-D with shape `[1, 1, 4]` containing the distorted bounding box.
|
Output<T> |
begin()
1-D, containing `[offset_height, offset_width, 0]`.
|
static <T extends Number, U extends Number> StatelessSampleDistortedBoundingBox<T> | |
static StatelessSampleDistortedBoundingBox.Options |
maxAttempts(Long maxAttempts)
|
Output<T> |
size()
1-D, containing `[target_height, target_width, -1]`.
|
static StatelessSampleDistortedBoundingBox.Options |
useImageIfNoBoundingBoxes(Boolean useImageIfNoBoundingBoxes)
|
Inherited Methods
Public Methods
public static StatelessSampleDistortedBoundingBox.Options areaRange (List<Float> areaRange)
Parameters
areaRange | The cropped area of the image must contain a fraction of the supplied image within this range. |
---|
public static StatelessSampleDistortedBoundingBox.Options aspectRatioRange (List<Float> aspectRatioRange)
Parameters
aspectRatioRange | The cropped area of the image must have an aspect ratio = width / height within this range. |
---|
public Output<Float> bboxes ()
3-D with shape `[1, 1, 4]` containing the distorted bounding box.
Provide as input to tf.image.draw_bounding_boxes
.
public Output<T> begin ()
1-D, containing `[offset_height, offset_width, 0]`. Provide as input to
tf.slice
.
public static StatelessSampleDistortedBoundingBox<T> create (Scope scope, Operand<T> imageSize, Operand<Float> boundingBoxes, Operand<Float> minObjectCovered, Operand<U> seed, Options... options)
Factory method to create a class wrapping a new StatelessSampleDistortedBoundingBox operation.
Parameters
scope | current scope |
---|---|
imageSize | 1-D, containing `[height, width, channels]`. |
boundingBoxes | 3-D with shape `[batch, N, 4]` describing the N bounding boxes associated with the image. |
minObjectCovered | 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.) |
options | carries optional attributes values |
Returns
- a new instance of StatelessSampleDistortedBoundingBox
public static StatelessSampleDistortedBoundingBox.Options maxAttempts (Long maxAttempts)
Parameters
maxAttempts | Number of attempts at generating a cropped region of the image of the specified constraints. After `max_attempts` failures, return the entire image. |
---|
public Output<T> size ()
1-D, containing `[target_height, target_width, -1]`. Provide as input to
tf.slice
.
public static StatelessSampleDistortedBoundingBox.Options useImageIfNoBoundingBoxes (Boolean useImageIfNoBoundingBoxes)
Parameters
useImageIfNoBoundingBoxes | Controls behavior if no bounding boxes supplied. If true, assume an implicit bounding box covering the whole input. If false, raise an error. |
---|