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

<br />

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.

Args:

- scope: A [Scope](https://www.tensorflow.org/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_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.)

<br />

Optional attributes (see `https://www.tensorflow.org/api_docs/cc/struct/tensorflow/ops/stateless-sample-distorted-bounding-box/attrs#structtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1_1_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.

<br />

Returns:

- `https://www.tensorflow.org/api_docs/cc/class/tensorflow/output#classtensorflow_1_1_output` begin: 1-D, containing `[offset_height, offset_width, 0]`. Provide as input to `tf.slice`.
- `https://www.tensorflow.org/api_docs/cc/class/tensorflow/output#classtensorflow_1_1_output` size: 1-D, containing `[target_height, target_width, -1]`. Provide as input to `tf.slice`.
- `https://www.tensorflow.org/api_docs/cc/class/tensorflow/output#classtensorflow_1_1_output` bboxes: 3-D with shape `[1, 1, 4]` containing the distorted bounding box. Provide as input to `tf.image.draw_bounding_boxes`.

<br />

| ### Constructors and Destructors ||
|---|---|
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1a8e3e1f628542596b40c7007cec751472(const ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope & scope, ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/input#classtensorflow_1_1_input image_size, ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/input#classtensorflow_1_1_input bounding_boxes, ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/input#classtensorflow_1_1_input min_object_covered, ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/input#classtensorflow_1_1_input seed)` ||
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1a2180ee953542277f11b5ff955e5cb31c(const ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/scope#classtensorflow_1_1_scope & scope, ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/input#classtensorflow_1_1_input image_size, ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/input#classtensorflow_1_1_input bounding_boxes, ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/input#classtensorflow_1_1_input min_object_covered, ::https://www.tensorflow.org/api_docs/cc/class/tensorflow/input#classtensorflow_1_1_input seed, const https://www.tensorflow.org/api_docs/cc/struct/tensorflow/ops/stateless-sample-distorted-bounding-box/attrs#structtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1_1_attrs & attrs)` ||

| ### Public attributes ||
|---|---|
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1a3e71c37eb846dfbdc0404d26d2fee2f8` | `::https://www.tensorflow.org/api_docs/cc/class/tensorflow/output#classtensorflow_1_1_output` |
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1a4020c9f475fc53770dbc06d4d95cd630` | `::https://www.tensorflow.org/api_docs/cc/class/tensorflow/output#classtensorflow_1_1_output` |
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1a8286320d0ef4a8425aa51026d34111db` | `https://www.tensorflow.org/api_docs/cc/class/tensorflow/operation#classtensorflow_1_1_operation` |
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1ae04677923f8020c6fb3ebc6385889b3b` | `::https://www.tensorflow.org/api_docs/cc/class/tensorflow/output#classtensorflow_1_1_output` |

| ### Public static functions ||
|---|---|
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1aee10b7401b9d5d2d9ed30193e8bdf5ba(const gtl::ArraySlice< float > & x)` | `https://www.tensorflow.org/api_docs/cc/struct/tensorflow/ops/stateless-sample-distorted-bounding-box/attrs#structtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1_1_attrs` |
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1a5fbb107854b3794319f7663e1f620c57(const gtl::ArraySlice< float > & x)` | `https://www.tensorflow.org/api_docs/cc/struct/tensorflow/ops/stateless-sample-distorted-bounding-box/attrs#structtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1_1_attrs` |
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1a0b5561af6e0244323c479ad610254bdf(int64 x)` | `https://www.tensorflow.org/api_docs/cc/struct/tensorflow/ops/stateless-sample-distorted-bounding-box/attrs#structtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1_1_attrs` |
| `https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1a2edc220c34de1da4ccd8f5ac0aac6f3b(bool x)` | `https://www.tensorflow.org/api_docs/cc/struct/tensorflow/ops/stateless-sample-distorted-bounding-box/attrs#structtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box_1_1_attrs` |

| ### Structs ||
|---|---|
| [tensorflow::ops::StatelessSampleDistortedBoundingBox::Attrs](https://www.tensorflow.org/api_docs/cc/struct/tensorflow/ops/stateless-sample-distorted-bounding-box/attrs) | Optional attribute setters for [StatelessSampleDistortedBoundingBox](https://www.tensorflow.org/api_docs/cc/class/tensorflow/ops/stateless-sample-distorted-bounding-box#classtensorflow_1_1ops_1_1_stateless_sample_distorted_bounding_box). |

## 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
)
```