mlair.model_modules.advanced_paddings

Collection of customised padding layers.

Module Contents

Classes

PadUtils

Helper class for advanced padding.

InputSpec

Specifies the ndim, dtype and shape of every input to a layer.

_ZeroPadding

Abstract nD ZeroPadding layer (private, used as implementation base).

ReflectionPadding2D

Reflection padding layer for 2D input.

SymmetricPadding2D

Symmetric padding layer for 2D input.

Padding2D

Combine all implemented padding methods.

Functions

transpose_shape(shape, target_format, spatial_axes)

Converts a tuple or a list to the correct data_format.

normalize_data_format(value)

Checks that the value correspond to a valid data format.

Attributes

__author__

__date__

kernel_1

mlair.model_modules.advanced_paddings.__author__ = Felix Kleinert
mlair.model_modules.advanced_paddings.__date__ = 2020-03-02
mlair.model_modules.advanced_paddings.transpose_shape(shape, target_format, spatial_axes)

Converts a tuple or a list to the correct data_format. It does so by switching the positions of its elements. # Arguments

shape: Tuple or list, often representing shape,

corresponding to ‘channels_last’.

target_format: A string, either ‘channels_first’ or ‘channels_last’. spatial_axes: A tuple of integers.

Correspond to the indexes of the spatial axes. For example, if you pass a shape representing (batch_size, timesteps, rows, cols, channels), then spatial_axes=(2, 3).

# Returns

A tuple or list, with the elements permuted according to target_format.

# Example ```python

>>> # from keras.utils.generic_utils import transpose_shape
>>> transpose_shape((16, 128, 128, 32),'channels_first', spatial_axes=(1, 2))
(16, 32, 128, 128)
>>> transpose_shape((16, 128, 128, 32), 'channels_last', spatial_axes=(1, 2))
(16, 128, 128, 32)
>>> transpose_shape((128, 128, 32), 'channels_first', spatial_axes=(0, 1))
(32, 128, 128)

``` # Raises

ValueError: if value or the global data_format invalid.

mlair.model_modules.advanced_paddings.normalize_data_format(value)

Checks that the value correspond to a valid data format. # Arguments

value: String or None. ‘channels_first’ or ‘channels_last’.

# Returns

A string, either ‘channels_first’ or ‘channels_last’

# Example ```python

>>> from tensorflow.keras import backend as K
>>> K.normalize_data_format(None)
'channels_first'
>>> K.normalize_data_format('channels_last')
'channels_last'

``` # Raises

ValueError: if value or the global data_format invalid.

class mlair.model_modules.advanced_paddings.PadUtils

Helper class for advanced padding.

static get_padding_for_same(kernel_size: Tuple[int], strides: int = 1) → Tuple[int]

Calculate padding size to keep input and output dimensions equal for a given kernel size.

Hint

custom paddings are currently only implemented for strides = 1

Parameters
  • kernel_size – size of padding kernel size

  • strides – number of strides (default 1, currently only strides=1 supported)

Returns

padding size

static spatial_2d_padding(padding=1, 1, 1, 1, data_format=None)

Pad the 2nd and 3rd dimensions of a 4D tensor.

# Arguments

x: Tensor or variable. padding: Tuple of 2 tuples, padding pattern. data_format: string, “channels_last” or “channels_first”.

# Returns

A padded 4D tensor.

# Raises

ValueError: if data_format is neither “channels_last” or “channels_first”.

static check_padding_format(padding)

Check padding format (int, 1D or 2D, >0).

class mlair.model_modules.advanced_paddings.InputSpec(dtype=None, shape=None, ndim=None, max_ndim=None, min_ndim=None, axes=None)

Bases: object

Specifies the ndim, dtype and shape of every input to a layer. Every layer should expose (if appropriate) an input_spec attribute: a list of instances of InputSpec (one per input tensor). A None entry in a shape is compatible with any dimension, a None shape is compatible with any shape. # Arguments

dtype: Expected datatype of the input. shape: Shape tuple, expected shape of the input

(may include None for unchecked axes).

ndim: Integer, expected rank of the input. max_ndim: Integer, maximum rank of the input. min_ndim: Integer, minimum rank of the input. axes: Dictionary mapping integer axes to

a specific dimension value.

__repr__(self)

Return repr(self).

class mlair.model_modules.advanced_paddings._ZeroPadding(padding, data_format=None, **kwargs)

Bases: tensorflow.keras.layers.Layer

Abstract nD ZeroPadding layer (private, used as implementation base). # Arguments

padding: Tuple of tuples of two ints. Can be a tuple of ints when

rank is 1.

data_format: A string,

one of “channels_last” or “channels_first”. The ordering of the dimensions in the inputs. “channels_last” corresponds to inputs with shape (batch, …, channels) while “channels_first” corresponds to inputs with shape (batch, channels, …). It defaults to the image_data_format value found in your Keras config file at ~/.keras/keras.json. If you never set it, then it will be “channels_last”.

abstract call(self, inputs)

This is where the layer’s logic lives.

Note here that call() method in tf.keras is little bit different from keras API. In keras API, you can pass support masking for layers as additional arguments. Whereas tf.keras has compute_mask() method to support masking.

Parameters
  • inputs

    Input tensor, or dict/list/tuple of input tensors. The first positional inputs argument is subject to special rules: - inputs must be explicitly passed. A layer cannot have zero

    arguments, and inputs cannot be provided via the default value of a keyword argument.

    • NumPy array or Python scalar values in inputs get cast as tensors.

    • Keras mask metadata is only collected from inputs.

    • Layers are built (build(input_shape) method) using shape info from inputs only.

    • input_spec compatibility is only checked against inputs.

    • Mixed precision input casting is only applied to inputs. If a layer has tensor arguments in *args or **kwargs, their casting behavior in mixed precision should be handled manually.

    • The SavedModel input specification is generated using inputs only.

    • Integration with various ecosystem packages like TFMOT, TFLite, TF.js, etc is only supported for inputs and not for tensors in positional and keyword arguments.

  • *args – Additional positional arguments. May contain tensors, although this is not recommended, for the reasons above.

  • **kwargs

    Additional keyword arguments. May contain tensors, although this is not recommended, for the reasons above. The following optional keyword arguments are reserved: - training: Boolean scalar tensor of Python boolean indicating

    whether the call is meant for training or inference.

    • mask: Boolean input mask. If the layer’s call() method takes a mask argument, its default value will be set to the mask generated for inputs by the previous layer (if input did come from a layer that generated a corresponding mask, i.e. if it came from a Keras layer with masking support).

Returns

A tensor or list/tuple of tensors.

compute_output_shape(self, input_shape)

Computes the output shape of the layer.

If the layer has not been built, this method will call build on the layer. This assumes that the layer will later be used with inputs that match the input shape provided here.

Parameters

input_shape – Shape tuple (tuple of integers) or list of shape tuples (one per output tensor of the layer). Shape tuples can include None for free dimensions, instead of an integer.

Returns

An input shape tuple.

get_config(self)

Returns the config of the layer.

A layer config is a Python dictionary (serializable) containing the configuration of a layer. The same layer can be reinstantiated later (without its trained weights) from this configuration.

The config of a layer does not include connectivity information, nor the layer class name. These are handled by Network (one layer of abstraction above).

Note that get_config() does not guarantee to return a fresh copy of dict every time it is called. The callers should make a copy of the returned dict if they want to modify it.

Returns

Python dictionary.

class mlair.model_modules.advanced_paddings.ReflectionPadding2D(padding=1, 1, data_format=None, **kwargs)

Bases: _ZeroPadding

Reflection padding layer for 2D input.

This custom padding layer is built on keras’ zero padding layers. Doc is copy and pasted from the original functions/methods:

This layer can add rows and columns of reflected values at the top, bottom, left and right side of an image like tensor.

Example

6, 5, 4, 5, 6, 5, 4

1, 2, 3 RefPad(padding=[[1, 1,], [2, 2]]) 3, 2,| 1, 2, 3,| 2, 1 4, 5, 6 =============================>>>> 6, 5,| 4, 5, 6,| 5, 4

3, 2, 1, 2, 3, 2, 1

# Arguments
padding: int, or tuple of 2 ints, or tuple of 2 tuples of 2 ints.
  • If int: the same symmetric padding

    is applied to height and width.

  • If tuple of 2 ints:

    interpreted as two different symmetric padding values for height and width: (symmetric_height_pad, symmetric_width_pad).

  • If tuple of 2 tuples of 2 ints:

    interpreted as ((top_pad, bottom_pad), (left_pad, right_pad))

data_format: A string,

one of “channels_last” or “channels_first”. The ordering of the dimensions in the inputs. “channels_last” corresponds to inputs with shape (batch, height, width, channels) while “channels_first” corresponds to inputs with shape (batch, channels, height, width). It defaults to the image_data_format value found in your Keras config file at ~/.keras/keras.json. If you never set it, then it will be “channels_last”.

# Input shape

4D tensor with shape: - If data_format is “channels_last”:

(batch, rows, cols, channels)

  • If data_format is “channels_first”:

    (batch, channels, rows, cols)

# Output shape

4D tensor with shape: - If data_format is “channels_last”:

(batch, padded_rows, padded_cols, channels)

  • If data_format is “channels_first”:

    (batch, channels, padded_rows, padded_cols)

call(self, inputs, mask=None)

Call ReflectionPadding2D.

class mlair.model_modules.advanced_paddings.SymmetricPadding2D(padding=1, 1, data_format=None, **kwargs)

Bases: _ZeroPadding

Symmetric padding layer for 2D input.

This custom padding layer is built on keras’ zero padding layers. Doc is copy pasted from the original functions/methods:

This layer can add rows and columns of symmetric values at the top, bottom, left and right side of an image like tensor.

Example:
2, 1, 1, 2, 3, 3, 2

1, 2, 3 SymPad(padding=[[1, 1,], [2, 2]]) 2, 1,| 1, 2, 3,| 3, 2 4, 5, 6 =============================>>>> 5, 4,| 4, 5, 6,| 6, 5

5, 4, 4, 5, 6, 6, 5

‘# Arguments
padding: int, or tuple of 2 ints, or tuple of 2 tuples of 2 ints.
  • If int: the same symmetric padding

    is applied to height and width.

  • If tuple of 2 ints:

    interpreted as two different symmetric padding values for height and width: (symmetric_height_pad, symmetric_width_pad).

  • If tuple of 2 tuples of 2 ints:

    interpreted as ((top_pad, bottom_pad), (left_pad, right_pad))

data_format: A string,

one of “channels_last” or “channels_first”. The ordering of the dimensions in the inputs. “channels_last” corresponds to inputs with shape (batch, height, width, channels) while “channels_first” corresponds to inputs with shape (batch, channels, height, width). It defaults to the image_data_format value found in your Keras config file at ~/.keras/keras.json. If you never set it, then it will be “channels_last”.

# Input shape

4D tensor with shape: - If data_format is “channels_last”:

(batch, rows, cols, channels)

  • If data_format is “channels_first”:

    (batch, channels, rows, cols)

# Output shape

4D tensor with shape: - If data_format is “channels_last”:

(batch, padded_rows, padded_cols, channels)

  • If data_format is “channels_first”:

    (batch, channels, padded_rows, padded_cols)

call(self, inputs, mask=None)

Call SymmetricPadding2D.

class mlair.model_modules.advanced_paddings.Padding2D(padding_type: Union[str, Padding2D.__init__.padding_type])

Combine all implemented padding methods.

You can call this method by defining a specific padding type. The __call__ method will return the corresponding Padding layer.

input_x = ... #  your input data
kernel_size = (5, 1)
padding_size = PadUtils.get_padding_for_same(kernel_size)

tower = layers.Conv2D(...)(input_x)
tower = layers.Activation(...)(tower)
tower = Padding2D('ZeroPad2D')(padding=padding_size, name=f'Custom_Pad')(tower)

Padding type can either be set by a string or directly by using an instance of a valid padding class.

allowed_paddings
padding_type
_check_and_get_padding(self)
__call__(self, *args, **kwargs)

Call padding.

mlair.model_modules.advanced_paddings.kernel_1 = [3, 3]