# StatelessSampleDistortedBoundingBox

public final class **StatelessSampleDistortedBoundingBox** 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`](https://www.tensorflow.org/api_docs/python/tf/slice) to crop the
image. The latter may be supplied to [`tf.image.draw_bounding_boxes`](https://www.tensorflow.org/api_docs/python/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`](https://www.tensorflow.org/api_docs/python/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.

<br />

<br />

<br />

<br />

<br />

<br />

<br />

### Nested Classes

|---|---|---|---|
| class | [StatelessSampleDistortedBoundingBox.Options](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options) || Optional attributes for `https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox` |

### Public Methods

|---|---|
| static [StatelessSampleDistortedBoundingBox.Options](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options) | [areaRange](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox#areaRange(java.util.List<java.lang.Float>))(List\<Float\> areaRange) |
| static [StatelessSampleDistortedBoundingBox.Options](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options) | [aspectRatioRange](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox#aspectRatioRange(java.util.List<java.lang.Float>))(List\<Float\> aspectRatioRange) |
| [Output](https://www.tensorflow.org/api_docs/java/org/tensorflow/Output)\<Float\> | [bboxes](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox#bboxes())() 3-D with shape \`\[1, 1, 4\]\` containing the distorted bounding box. |
| [Output](https://www.tensorflow.org/api_docs/java/org/tensorflow/Output)\<T\> | [begin](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox#begin())() 1-D, containing \`\[offset_height, offset_width, 0\]\`. |
| static \<T extends Number, U extends Number\> [StatelessSampleDistortedBoundingBox](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox)\<T\> | [create](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox#create(org.tensorflow.op.Scope,%20org.tensorflow.Operand<T>,%20org.tensorflow.Operand<java.lang.Float>,%20org.tensorflow.Operand<java.lang.Float>,%20org.tensorflow.Operand<U>,%20org.tensorflow.op.core.StatelessSampleDistortedBoundingBox.Options...))([Scope](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/Scope) scope, [Operand](https://www.tensorflow.org/api_docs/java/org/tensorflow/Operand)\<T\> imageSize, [Operand](https://www.tensorflow.org/api_docs/java/org/tensorflow/Operand)\<Float\> boundingBoxes, [Operand](https://www.tensorflow.org/api_docs/java/org/tensorflow/Operand)\<Float\> minObjectCovered, [Operand](https://www.tensorflow.org/api_docs/java/org/tensorflow/Operand)\<U\> seed, [Options...](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options) options) Factory method to create a class wrapping a new StatelessSampleDistortedBoundingBox operation. |
| static [StatelessSampleDistortedBoundingBox.Options](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options) | [maxAttempts](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox#maxAttempts(java.lang.Long))(Long maxAttempts) |
| [Output](https://www.tensorflow.org/api_docs/java/org/tensorflow/Output)\<T\> | [size](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox#size())() 1-D, containing \`\[target_height, target_width, -1\]\`. |
| static [StatelessSampleDistortedBoundingBox.Options](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options) | [useImageIfNoBoundingBoxes](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox#useImageIfNoBoundingBoxes(java.lang.Boolean))(Boolean useImageIfNoBoundingBoxes) |

### Inherited Methods

From class [org.tensorflow.op.PrimitiveOp](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/PrimitiveOp)

|---|---|
| final boolean | [equals](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/PrimitiveOp#equals(java.lang.Object))(Object obj) |
| final int | [hashCode](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/PrimitiveOp#hashCode())() |
| [Operation](https://www.tensorflow.org/api_docs/java/org/tensorflow/Operation) | [op](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/PrimitiveOp#op())() Returns the underlying `https://www.tensorflow.org/api_docs/java/org/tensorflow/Operation` |
| final String | [toString](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/PrimitiveOp#toString())() |

From class java.lang.Object

|---|---|
| boolean | equals(Object arg0) |
| final Class\<?\> | getClass() |
| int | hashCode() |
| final void | notify() |
| final void | notifyAll() |
| String | toString() |
| final void | wait(long arg0, int arg1) |
| final void | wait(long arg0) |
| final void | wait() |

## Public Methods

#### public static [StatelessSampleDistortedBoundingBox.Options](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options)
**areaRange**
(List\<Float\> areaRange)

<br />

##### Parameters

| areaRange | The cropped area of the image must contain a fraction of the supplied image within this range. |
|---|---|

#### public static [StatelessSampleDistortedBoundingBox.Options](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options)
**aspectRatioRange**
(List\<Float\> aspectRatioRange)

<br />

##### Parameters

| aspectRatioRange | The cropped area of the image must have an aspect ratio = width / height within this range. |
|---|---|

#### public [Output](https://www.tensorflow.org/api_docs/java/org/tensorflow/Output)\<Float\>
**bboxes**
()

3-D with shape \`\[1, 1, 4\]\` containing the distorted bounding box.
Provide as input to [`tf.image.draw_bounding_boxes`](https://www.tensorflow.org/api_docs/python/tf/image/draw_bounding_boxes).

#### public [Output](https://www.tensorflow.org/api_docs/java/org/tensorflow/Output)\<T\>
**begin**
()

1-D, containing \`\[offset_height, offset_width, 0\]\`. Provide as input to
[`tf.slice`](https://www.tensorflow.org/api_docs/python/tf/slice).

#### public static [StatelessSampleDistortedBoundingBox](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox)\<T\>
**create**
([Scope](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/Scope) scope, [Operand](https://www.tensorflow.org/api_docs/java/org/tensorflow/Operand)\<T\> imageSize, [Operand](https://www.tensorflow.org/api_docs/java/org/tensorflow/Operand)\<Float\> boundingBoxes, [Operand](https://www.tensorflow.org/api_docs/java/org/tensorflow/Operand)\<Float\> minObjectCovered, [Operand](https://www.tensorflow.org/api_docs/java/org/tensorflow/Operand)\<U\> seed, [Options...](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.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](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options)
**maxAttempts**
(Long maxAttempts)

<br />

##### 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](https://www.tensorflow.org/api_docs/java/org/tensorflow/Output)\<T\>
**size**
()

1-D, containing \`\[target_height, target_width, -1\]\`. Provide as input to
[`tf.slice`](https://www.tensorflow.org/api_docs/python/tf/slice).

#### public static [StatelessSampleDistortedBoundingBox.Options](https://www.tensorflow.org/api_docs/java/org/tensorflow/op/core/StatelessSampleDistortedBoundingBox.Options)
**useImageIfNoBoundingBoxes**
(Boolean useImageIfNoBoundingBoxes)

<br />

##### 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. |
|---|---|