# dsprites

<br />

- **Description**:

dSprites is a dataset of 2D shapes procedurally generated from 6 ground truth
independent latent factors. These factors are *color* , *shape* , *scale* ,
*rotation* , *x* and *y* positions of a sprite.

All possible combinations of these latents are present exactly once, generating
N = 737280 total images.

### Latent factor values

- Color: white
- Shape: square, ellipse, heart
- Scale: 6 values linearly spaced in \[0.5, 1\]
- Orientation: 40 values in \[0, 2 pi\]
- Position X: 32 values in \[0, 1\]
- Position Y: 32 values in \[0, 1\]

We varied one latent at a time (starting from Position Y, then Position X, etc),
and sequentially stored the images in fixed order. Hence the order along the
first dimension is fixed and allows you to map back to the value of the latents
corresponding to that image.

We chose the latents values deliberately to have the smallest step changes while
ensuring that all pixel outputs were different. No noise was added.

- **Additional Documentation** :
  [Explore on Papers With Code](https://paperswithcode.com/dataset/dsprites)

- **Homepage** :
  <https://github.com/deepmind/dsprites-dataset>

- **Source code** :
  [`tfds.datasets.dsprites.Builder`](https://github.com/tensorflow/datasets/tree/master/tensorflow_datasets/datasets/dsprites/dsprites_dataset_builder.py)

- **Versions**:

  - **`2.0.0`** (default): New split API (<https://tensorflow.org/datasets/splits>)
  - `2.1.0`: No release notes.
- **Download size** : `26.73 MiB`

- **Dataset size** : `Unknown size`

- **Auto-cached**
  ([documentation](https://www.tensorflow.org/datasets/performances#auto-caching)):
  Unknown

- **Splits**:

| Split | Examples |
|---|---|
| `'train'` | 737,280 |

- **Feature structure**:

    FeaturesDict({
        'image': Image(shape=(64, 64, 1), dtype=uint8),
        'label_orientation': ClassLabel(shape=(), dtype=int64, num_classes=40),
        'label_scale': ClassLabel(shape=(), dtype=int64, num_classes=6),
        'label_shape': ClassLabel(shape=(), dtype=int64, num_classes=3),
        'label_x_position': ClassLabel(shape=(), dtype=int64, num_classes=32),
        'label_y_position': ClassLabel(shape=(), dtype=int64, num_classes=32),
        'value_orientation': float32,
        'value_scale': float32,
        'value_shape': float32,
        'value_x_position': float32,
        'value_y_position': float32,
    })

- **Feature documentation**:

| Feature | Class | Shape | Dtype | Description |
|---|---|---|---|---|
|   | FeaturesDict |   |   |   |
| image | Image | (64, 64, 1) | uint8 |   |
| label_orientation | ClassLabel |   | int64 |   |
| label_scale | ClassLabel |   | int64 |   |
| label_shape | ClassLabel |   | int64 |   |
| label_x_position | ClassLabel |   | int64 |   |
| label_y_position | ClassLabel |   | int64 |   |
| value_orientation | Tensor |   | float32 |   |
| value_scale | Tensor |   | float32 |   |
| value_shape | Tensor |   | float32 |   |
| value_x_position | Tensor |   | float32 |   |
| value_y_position | Tensor |   | float32 |   |

- **Supervised keys** (See
  [`as_supervised` doc](https://www.tensorflow.org/datasets/api_docs/python/tfds/load#args)):
  `None`

- **Figure**
  ([tfds.show_examples](https://www.tensorflow.org/datasets/api_docs/python/tfds/visualization/show_examples)):

![Visualization](https://storage.googleapis.com/tfds-data/visualization/fig/dsprites-2.0.0.png)

- **Examples** ([tfds.as_dataframe](https://www.tensorflow.org/datasets/api_docs/python/tfds/as_dataframe)):

<button id="displaydataframe">Display examples...</button>

- **Citation**:

    @misc{dsprites17,
    author = {Loic Matthey and Irina Higgins and Demis Hassabis and Alexander Lerchner},
    title = {dSprites: Disentanglement testing Sprites dataset},
    howpublished= {https://github.com/deepmind/dsprites-dataset/},
    year = "2017",
    }