tfds.features.Image

FeatureConnector for images.

Inherits From: FeatureConnector

During _generate_examples, the feature connector accept as input any of:

  • str: path to a {bmp,gif,jpeg,png} image (ex: /path/to/img.png).
  • np.array: 3d np.uint8 array representing an image.
  • A file object containing the png or jpeg encoded image string (ex: io.BytesIO(encoded_img_bytes))

Output:

tf.Tensor of type tf.uint8 and shape [height, width, num_channels] for BMP, JPEG, and PNG images and shape [num_frames, height, width, 3] for GIF images.

Example:

features=features.FeaturesDict({
    'input': features.Image(),
    'target': features.Image(shape=(None, None, 1),
                               encoding_format='png'),
})
  • During generation:
yield {
    'input': 'path/to/img.jpg',
    'target': np.ones(shape=(64, 64, 1), dtype=np.uint8),
}

shape tuple of ints or None, the shape of decoded image. For GIF images: (num_frames, height, width, channels=3). num_frames, height and width can be None. For other images: (height, width, channels). height and width can be None. See tf.image.encode_* for doc on channels parameter. Defaults to (None, None, 3).
dtype tf.uint16 or tf.uint8 (default). tf.uint16 can be used only with png encoding_format
encoding_format 'jpeg' or 'png' (default). Format to serialize np.ndarray images on disk. If image is loaded from {bmg,gif,jpeg,png} file, this parameter is ignored, and file original encoding is used.

ValueError If the shape is invalid

dtype Return the dtype (or dict of dtype) of this FeatureConnector.
shape Return the shape (or dict of shape) of this FeatureConnector.

Methods

decode_batch_example

View source

Decode multiple features batched in a single tf.Tensor.

This function is used to decode features wrapped in tfds.features.Sequence(). By default, this function apply decode_example on each individual elements using tf.map_fn. However, for optimization, features can overwrite this method to apply a custom batch decoding.

Args
tfexample_data Same tf.Tensor inputs as decode_example, but with and additional first dimension for the sequence length.

Returns
tensor_data Tensor or dictionary of tensor, output of the tf.data.Dataset object

decode_example

View source

Reconstruct the image from the tf example.

decode_ragged_example

View source

Decode nested features from a tf.RaggedTensor.

This function is used to decode features wrapped in nested tfds.features.Sequence(). By default, this function apply decode_batch_example on the flat values of the ragged tensor. For optimization, features can overwrite this method to apply a custom batch decoding.

Args
tfexample_data tf.RaggedTensor inputs containing the nested encoded examples.

Returns
tensor_data The decoded tf.RaggedTensor or dictionary of tensor, output of the tf.data.Dataset object

encode_example

View source

Convert the given image into a dict convertible to tf example.

get_serialized_info

View source

Return the shape/dtype of features after encoding (for the adapter).

The FileAdapter then use those information to write data on disk.

This function indicates how this feature is encoded on file internally. The DatasetBuilder are written on disk as tf.train.Example proto.

Ex:

return {
    'image': tfds.features.TensorInfo(shape=(None,), dtype=tf.uint8),
    'height': tfds.features.TensorInfo(shape=(), dtype=tf.int32),
    'width': tfds.features.TensorInfo(shape=(), dtype=tf.int32),
}

FeatureConnector which are not containers should return the feature proto directly:

return tfds.features.TensorInfo(shape=(64, 64), tf.uint8)

If not defined, the retuned values are automatically deduced from the get_tensor_info function.

Returns
features Either a dict of feature proto object, or a feature proto object

get_tensor_info

View source

Return the tf.Tensor dtype/shape of the feature.

This returns the tensor dtype/shape, as returned by .as_dataset by the tf.data.Dataset object.

Ex:

return {
    'image': tfds.features.TensorInfo(shape=(None,), dtype=tf.uint8),
    'height': tfds.features.TensorInfo(shape=(), dtype=tf.int32),
    'width': tfds.features.TensorInfo(shape=(), dtype=tf.int32),
}

FeatureConnector which are not containers should return the feature proto directly:

return tfds.features.TensorInfo(shape=(256, 256), dtype=tf.uint8)

Returns
tensor_info Either a dict of tfds.features.TensorInfo object, or a tfds.features.TensorInfo

load_metadata

View source

See base class for details.

save_metadata

View source

See base class for details.

set_dtype

View source

Update the dtype.

set_encoding_format

View source

Update the encoding format.

set_shape

View source

Update the shape.