satsim.tfa.image package — SatSim 0.20.1 documentation

# satsim.tfa.image package

Additional image manipulation ops.

## Submodules

## satsim.tfa.image.transform_ops module

Image transform ops.

satsim.tfa.image.transform_ops.angles_to_projective_transforms(angles: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, image_height: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, image_width: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, name: str | None = None) → Tensor

  Returns projective transform(s) for the given angle(s).

  Parameters:

    - angles – A scalar angle to rotate all images by, or (for batches of images) a vector with an angle to rotate each image in the batch. The rank must be statically known (the shape is not TensorShape(None).

    - image_height – Height of the image(s) to be transformed.

    - image_width – Width of the image(s) to be transformed.

  Returns:

    A tensor of shape (num_images, 8). Projective transforms which can be given to transform op.

satsim.tfa.image.transform_ops.compose_transforms(transforms: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, name: str | None = None) → Tensor

  Composes the transforms tensors.

  Parameters:

    - transforms – List of image projective transforms to be composed. Each transform is length 8 (single transform) or shape (N, 8) (batched transforms). The shapes of all inputs must be equal, and at least one input must be given.

    - name – The name for the op.

  Returns:

    A composed transform tensor. When passed to transform op,

      equivalent to applying each of the given transforms to the image in order.

satsim.tfa.image.transform_ops.flat_transforms_to_matrices(transforms: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, name: str | None = None) → Tensor

  Converts projective transforms to affine matrices.

  Note that the output matrices map output coordinates to input coordinates. For the forward transformation matrix, call tf.linalg.inv on the result.

  Parameters:

    - transforms – Vector of length 8, or batches of transforms with shape (N, 8).

    - name – The name for the op.

  Returns:

    3D tensor of matrices with shape (N, 3, 3). The output matrices map the

      output coordinates (in homogeneous coordinates) of each transform to the corresponding input coordinates.

  Raises:

    ValueError – If transforms have an invalid shape.

satsim.tfa.image.transform_ops.matrices_to_flat_transforms(transform_matrices: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, name: str | None = None) → Tensor

  Converts affine matrices to projective transforms.

  Note that we expect matrices that map output coordinates to input coordinates. To convert forward transformation matrices, call tf.linalg.inv on the matrices and use the result here.

  Parameters:

    - transform_matrices – One or more affine transformation matrices, for the reverse transformation in homogeneous coordinates. Shape (3, 3) or (N, 3, 3).

    - name – The name for the op.

  Returns:

    2D tensor of flat transforms with shape (N, 8), which may be passed into transform op.

  Raises:

    ValueError – If transform_matrices have an invalid shape.

satsim.tfa.image.transform_ops.rotate(images: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, angles: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, interpolation: str = 'nearest', fill_mode: str = 'constant', name: str | None = None, fill_value: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor = 0.0) → Tensor

  Rotate image(s) counterclockwise by the passed angle(s) in radians.

  Parameters:

    - images – A tensor of shape (num_images, num_rows, num_columns, num_channels) (NHWC), (num_rows, num_columns, num_channels) (HWC), or (num_rows, num_columns) (HW).

    - angles – A scalar angle to rotate all images by, or (if images has rank 4) a vector of length num_images, with an angle for each image in the batch.

    - interpolation – Interpolation mode. Supported values: “nearest”, “bilinear”.

    - fill_mode –

      Points outside the boundaries of the input are filled according to the given mode (one of {‘constant’, ‘reflect’, ‘wrap’, ‘nearest’}). - reflect: (d c b a | a b c d | d c b a)

      > The input is extended by reflecting about the edge of the last pixel.

      - constant: (k k k k | a b c d | k k k k) The input is extended by filling all values beyond the edge with the same constant value k = 0.

      - wrap: (a b c d | a b c d | a b c d) The input is extended by wrapping around to the opposite edge.

      - nearest: (a a a a | a b c d | d d d d) The input is extended by the nearest pixel.

    - fill_value – a float represents the value to be filled outside the boundaries when fill_mode is “constant”.

    - name – The name of the op.

  Returns:

    Image(s) with the same type and shape as images, rotated by the given angle(s). Empty space due to the rotation will be filled with zeros.

  Raises:

    TypeError – If images is an invalid type.

satsim.tfa.image.transform_ops.shear_x(image: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, level: float, replace: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor) → List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor

  Perform shear operation on an image (x-axis).

  Parameters:

    - image – A 3D image Tensor.

    - level – A float denoting shear element along y-axis

    - replace – A one or three value 1D tensor to fill empty pixels.

  Returns:

    Transformed image along X or Y axis, with space outside image filled with replace.

satsim.tfa.image.transform_ops.shear_y(image: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, level: float, replace: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor) → List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor

  Perform shear operation on an image (y-axis).

  Parameters:

    - image – A 3D image Tensor.

    - level – A float denoting shear element along x-axis

    - replace – A one or three value 1D tensor to fill empty pixels.

  Returns:

    Transformed image along X or Y axis, with space outside image filled with replace.

satsim.tfa.image.transform_ops.transform(images: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, transforms: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, interpolation: str = 'nearest', fill_mode: str = 'constant', output_shape: list | None = None, name: str | None = None, fill_value: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor = 0.0) → Tensor

  Applies the given transform(s) to the image(s).

  Parameters:

    - images – A tensor of shape (num_images, num_rows, num_columns, num_channels) (NHWC), (num_rows, num_columns, num_channels) (HWC), or (num_rows, num_columns) (HW).

    - transforms – Projective transform matrix/matrices. A vector of length 8 or tensor of size N x 8. If one row of transforms is [a0, a1, a2, b0, b1, b2, c0, c1], then it maps the output point (x, y) to a transformed input point (x’, y’) = ((a0 x + a1 y + a2) / k, (b0 x + b1 y + b2) / k), where k = c0 x + c1 y + 1. The transforms are inverted compared to the transform mapping input points to output points. Note that gradients are not backpropagated into transformation parameters.

    - interpolation – Interpolation mode. Supported values: “nearest”, “bilinear”.

    - fill_mode –

      Points outside the boundaries of the input are filled according to the given mode (one of {‘constant’, ‘reflect’, ‘wrap’, ‘nearest’}). - reflect: (d c b a | a b c d | d c b a)

      > The input is extended by reflecting about the edge of the last pixel.

      - constant: (k k k k | a b c d | k k k k) The input is extended by filling all values beyond the edge with the same constant value k = 0.

      - wrap: (a b c d | a b c d | a b c d) The input is extended by wrapping around to the opposite edge.

      - nearest: (a a a a | a b c d | d d d d) The input is extended by the nearest pixel.

    - fill_value – a float represents the value to be filled outside the boundaries when fill_mode is “constant”.

    - output_shape – Output dimesion after the transform, [height, width]. If None, output is the same size as input image.

    - name – The name of the op.

  Returns:

    Image(s) with the same type and shape as images, with the given transform(s) applied. Transformed coordinates outside of the input image will be filled with zeros.

  Raises:

    - TypeError – If image is an invalid type.

    - ValueError – If output shape is not 1-D int32 Tensor.

## satsim.tfa.image.translate_ops module

Image translate ops.

satsim.tfa.image.translate_ops.translate(images: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, translations: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, interpolation: str = 'nearest', fill_mode: str = 'constant', name: str | None = None, fill_value: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor = 0.0) → Tensor

  Translate image(s) by the passed vectors(s).

  Parameters:

    - images – A tensor of shape (num_images, num_rows, num_columns, num_channels) (NHWC), (num_rows, num_columns, num_channels) (HWC), or (num_rows, num_columns) (HW). The rank must be statically known (the shape is not TensorShape(None)).

    - translations – A vector representing [dx, dy] or (if images has rank 4) a matrix of length num_images, with a [dx, dy] vector for each image in the batch.

    - interpolation – Interpolation mode. Supported values: “nearest”, “bilinear”.

    - fill_mode –

      Points outside the boundaries of the input are filled according to the given mode (one of {‘constant’, ‘reflect’, ‘wrap’, ‘nearest’}). - reflect: (d c b a | a b c d | d c b a)

      > The input is extended by reflecting about the edge of the last pixel.

      - constant: (k k k k | a b c d | k k k k) The input is extended by filling all values beyond the edge with the same constant value k = 0.

      - wrap: (a b c d | a b c d | a b c d) The input is extended by wrapping around to the opposite edge.

      - nearest: (a a a a | a b c d | d d d d) The input is extended by the nearest pixel.

    - fill_value – a float represents the value to be filled outside the boundaries when fill_mode is “constant”.

    - name – The name of the op.

  Returns:

    Image(s) with the same type and shape as images, translated by the

      given vector(s). Empty space due to the translation will be filled with zeros.

  Raises:

    TypeError – If images is an invalid type.

satsim.tfa.image.translate_ops.translate_xy(image: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, translate_to: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, replace: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor) → List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor

  Translates image in X or Y dimension.

  Parameters:

    - image – A 3D image Tensor.

    - translate_to – A 1D Tensor to translate [x, y].

    - replace – A one or three value 1D Tensor to fill empty pixels.

  Returns:

    Translated image along X or Y axis, with space outside image

      filled with replace.

  Raises:

    ValueError – if axis is neither 0 nor 1.

satsim.tfa.image.translate_ops.translations_to_projective_transforms(translations: List[float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | list] | tuple | float | int | float16 | float32 | float64 | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | ndarray | Tensor | SparseTensor | Variable | KerasTensor, name: str | None = None) → Tensor

  Returns projective transform(s) for the given translation(s).

  Parameters:

    - translations – A 2-element list representing [dx, dy] or a matrix of 2-element lists representing [dx, dy] to translate for each image (for a batch of images). The rank must be statically known (the shape is not TensorShape(None)).

    - name – The name of the op.

  Returns:

    A tensor of shape (num_images, 8) projective transforms which can be given to tfa.image.transform.

## satsim.tfa.image.utils module

Image util ops.

satsim.tfa.image.utils.from_4D_image(image, ndims)

  Convert back to an image with ndims rank.

  Parameters:

    - image – 4D Tensor.

    - ndims – The original rank of the image.

  Returns:

    ndims-D Tensor with the same type.

satsim.tfa.image.utils.get_ndims(image)

satsim.tfa.image.utils.to_4D_image(image)

  Convert 2/3/4D image to 4D image.

  Parameters:

    image – 2/3/4D Tensor.

  Returns:

    4D Tensor with the same type.

satsim.tfa.image.utils.unwrap(image, replace)

  Unwraps an image produced by wrap.

  Where there is a 0 in the last channel for every spatial position, the rest of the three channels in that spatial dimension are grayed (set to 128). Operations like translate and shear on a wrapped Tensor will leave 0s in empty locations. Some transformations look at the intensity of values to do preprocessing, and we want these empty pixels to assume the ‘average’ value, rather than pure black.

  Parameters:

    - image – A 3D image Tensor with 4 channels.

    - replace – A one or three value 1D Tensor to fill empty pixels.

  Returns:

    A 3D image Tensor with 3 channels.

  Return type:

    image

satsim.tfa.image.utils.wrap(image)

  Returns image with an extra channel set to all 1s.