Format function definition (sarpy.io.general.format_function)

Stateful functions for use in format operations for data segments.

This module introduced in version 1.3.0.

sarpy.io.general.format_function.reformat_slice(sl_in: slice, limit_in: int, mirror: bool) → slice

Reformat the slice, with optional reverse operation.

Note that the mirror operation doesn’t run the slice backwards across the same elements, but rather creates a mirror image of the slice. This is to properly accommodate the data segment reverse symmetry transform.

Parameters:

• sl_in (slice) – From prior processing, it is expected that sl_in.step is populated, and sl_in.start is non-negative, and sl_in.stop is non-negative or None (only in th event that sl_in.step < 0.

• limit_in (int) – The upper limit for the axis to which this slice pertains.

• mirror (bool) – Create the mirror image slice?

Return type:

slice

class sarpy.io.general.format_function.FormatFunction(raw_shape: Tuple[int, ...] | None = None, formatted_shape: Tuple[int, ...] | None = None, reverse_axes: Tuple[int, ...] | None = None, transpose_axes: Tuple[int, ...] | None = None)

Bases: object

Stateful function for data orientation and formatting operations associated with reading data. This is specifically intended for use in conjunction with `DataSegment`.

This allows mapping from raw data to formatted data, for reading data from a file and converting it to the form of intended use.

If the reverse process is implemented, it enables converting from formatted data to raw data, for taking common use data and converting it to the raw form, for writing data to a file.

Introduced in version 1.3.0.

has_inverse = False

Indicates whether this format function has the inverse call implemented.

property raw_shape: Tuple[int, ...] | None

The expected full possible raw shape.

Type:

None|Tuple[int, …]

property formatted_shape: Tuple[int, ...] | None

The expected output shape basis.

Type:

None|Tuple[int, …]

property reverse_axes: Tuple[int, ...] | None

The collection of axes (with respect to raw order) along which we will reverse as part of transformation to output data order. If not None, then this will be a tuple in strictly increasing order.

Type:

None|Tuple[int, …]

property transpose_axes: Tuple[int, ...]

The transpose order for switching from raw order to output order, prior to applying any format function.

Type:

None|Tuple[int, …]

inverse(array: ndarray, subscript: Tuple[slice, ...]) → ndarray

Inverse operation which takes in formatted data, and returns corresponding raw data.

Parameters:

• array (numpy.ndarray) – The input formatted data.

• subscript (Tuple[slice, ...]) – The slice definition which yielded the formatted data.

Return type:

numpy.ndarray

Raises:

ValueError – A value error should be raised if inverse=True and has_inverse=False.

validate_shapes() → None

Validates that the provided raw_shape and formatted_shape are sensible.

This should be called only after setting the appropriate values for the raw_shape, formatted_shape, reverse_axes and transpose_axes properties.

Raises:

ValueError – Raises a ValueError if the shapes are not compatible according to this function and the transpose axes argument.

transform_formatted_slice(subscript: Tuple[slice, ...]) → Tuple[slice, ...]

Transform from the subscript definition in formatted coordinates to subscript definition with respect to raw coordinates.

Parameters:

subscript (Tuple[slice, ...]) –

Return type:

Tuple[slice, …]

Raises:

ValueError – Raised if the desired requirement cannot be met.

transform_raw_slice(subscript: Tuple[slice, ...]) → Tuple[slice, ...]

Transform from the subscript definition in raw coordinates to subscript definition with respect to formatted coordinates.

Parameters:

subscript (Tuple[slice, ...]) –

Return type:

Tuple[slice, …]

Raises:

ValueError – Raised if the desired requirement cannot be met.

class sarpy.io.general.format_function.IdentityFunction(raw_shape: Tuple[int, ...] | None = None, formatted_shape: Tuple[int, ...] | None = None, reverse_axes: Tuple[int, ...] | None = None, transpose_axes: Tuple[int, ...] | None = None)

Bases: FormatFunction

A format function allowing only reversing and transposing operations, the actual functional step is simply the identity function.

Introduced in version 1.3.0.

has_inverse = True

Indicates whether this format function has the inverse call implemented.

validate_shapes() → None

Validates that the provided raw_shape and formatted_shape are sensible.

This should be called only after setting the appropriate values for the raw_shape, formatted_shape, reverse_axes and transpose_axes properties.

Raises:

ValueError – Raises a ValueError if the shapes are not compatible according to this function and the transpose axes argument.

transform_formatted_slice(subscript: Tuple[slice, ...]) → Tuple[slice, ...]

Transform from the subscript definition in formatted coordinates to subscript definition with respect to raw coordinates.

Parameters:

subscript (Tuple[slice, ...]) –

Return type:

Tuple[slice, …]

Raises:

ValueError – Raised if the desired requirement cannot be met.

transform_raw_slice(subscript: Tuple[slice, ...]) → Tuple[slice, ...]

Transform from the subscript definition in raw coordinates to subscript definition with respect to formatted coordinates.

Parameters:

subscript (Tuple[slice, ...]) –

Return type:

Tuple[slice, …]

Raises:

ValueError – Raised if the desired requirement cannot be met.

property formatted_shape: Tuple[int, ...] | None

The expected output shape basis.

Type:

None|Tuple[int, …]

inverse(array: ndarray, subscript: Tuple[slice, ...]) → ndarray

Inverse operation which takes in formatted data, and returns corresponding raw data.

Parameters:

• array (numpy.ndarray) – The input formatted data.

• subscript (Tuple[slice, ...]) – The slice definition which yielded the formatted data.

Return type:

numpy.ndarray

Raises:

ValueError – A value error should be raised if inverse=True and has_inverse=False.

property raw_shape: Tuple[int, ...] | None

The expected full possible raw shape.

Type:

None|Tuple[int, …]

property reverse_axes: Tuple[int, ...] | None

The collection of axes (with respect to raw order) along which we will reverse as part of transformation to output data order. If not None, then this will be a tuple in strictly increasing order.

Type:

None|Tuple[int, …]

property transpose_axes: Tuple[int, ...]

The transpose order for switching from raw order to output order, prior to applying any format function.

Type:

None|Tuple[int, …]

class sarpy.io.general.format_function.ComplexFormatFunction(raw_dtype: str | dtype, order: str, raw_shape: Tuple[int, ...] | None = None, formatted_shape: Tuple[int, ...] | None = None, reverse_axes: Tuple[int, ...] | None = None, transpose_axes: Tuple[int, ...] | None = None, band_dimension: int = -1)

Bases: FormatFunction

Reformats data from real/imaginary dimension pairs to complex64 output, assuming that the raw data has fixed dimensionality and the real/imaginary pairs fall along a given band dimension.

Introduced in version 1.3.0.

has_inverse = True

Indicates whether this format function has the inverse call implemented.

property band_dimension: int

The band dimension, in raw data after the transpose operation.

Type:

int

property order: str

The order string, once of (‘IQ’, ‘QI’, ‘MP’, ‘PM’).

Type:

str

validate_shapes() → None

Validates that the provided raw_shape and formatted_shape are sensible.

This should be called only after setting the appropriate values for the raw_shape, formatted_shape, reverse_axes and transpose_axes properties.

Raises:

ValueError – Raises a ValueError if the shapes are not compatible according to this function and the transpose axes argument.

transform_formatted_slice(subscript: Tuple[slice, ...]) → Tuple[slice, ...]

Transform from the subscript definition in formatted coordinates to subscript definition with respect to raw coordinates.

Parameters:

subscript (Tuple[slice, ...]) –

Return type:

Tuple[slice, …]

Raises:

ValueError – Raised if the desired requirement cannot be met.

transform_raw_slice(subscript: Tuple[slice, ...]) → Tuple[slice, ...]

Transform from the subscript definition in raw coordinates to subscript definition with respect to formatted coordinates.

Parameters:

subscript (Tuple[slice, ...]) –

Return type:

Tuple[slice, …]

Raises:

ValueError – Raised if the desired requirement cannot be met.

property formatted_shape: Tuple[int, ...] | None

The expected output shape basis.

Type:

None|Tuple[int, …]

inverse(array: ndarray, subscript: Tuple[slice, ...]) → ndarray

Inverse operation which takes in formatted data, and returns corresponding raw data.

Parameters:

• array (numpy.ndarray) – The input formatted data.

• subscript (Tuple[slice, ...]) – The slice definition which yielded the formatted data.

Return type:

numpy.ndarray

Raises:

ValueError – A value error should be raised if inverse=True and has_inverse=False.

property raw_shape: Tuple[int, ...] | None

The expected full possible raw shape.

Type:

None|Tuple[int, …]

property reverse_axes: Tuple[int, ...] | None

The collection of axes (with respect to raw order) along which we will reverse as part of transformation to output data order. If not None, then this will be a tuple in strictly increasing order.

Type:

None|Tuple[int, …]

property transpose_axes: Tuple[int, ...]

The transpose order for switching from raw order to output order, prior to applying any format function.

Type:

None|Tuple[int, …]

class sarpy.io.general.format_function.SingleLUTFormatFunction(lookup_table: ndarray, raw_shape: Tuple[int, ...] | None = None, formatted_shape: Tuple[int, ...] | None = None, reverse_axes: Tuple[int, ...] | None = None, transpose_axes: Tuple[int, ...] | None = None)

Bases: FormatFunction

Reformat the raw data according to the use of a single 8-bit lookup table. In the case of a 2-d LUT, and effort to slice on the final dimension (from the LUT) is not supported.

Introduced in version 1.3.0.

has_inverse = False

Indicates whether this format function has the inverse call implemented.

validate_shapes() → None

Validates that the provided raw_shape and formatted_shape are sensible.

This should be called only after setting the appropriate values for the raw_shape, formatted_shape, reverse_axes and transpose_axes properties.

Raises:

ValueError – Raises a ValueError if the shapes are not compatible according to this function and the transpose axes argument.

transform_formatted_slice(subscript: Tuple[slice, ...]) → Tuple[slice, ...]

Transform from the subscript definition in formatted coordinates to subscript definition with respect to raw coordinates.

Parameters:

subscript (Tuple[slice, ...]) –

Return type:

Tuple[slice, …]

Raises:

ValueError – Raised if the desired requirement cannot be met.

transform_raw_slice(subscript: Tuple[slice, ...]) → Tuple[slice, ...]

Transform from the subscript definition in raw coordinates to subscript definition with respect to formatted coordinates.

Parameters:

subscript (Tuple[slice, ...]) –

Return type:

Tuple[slice, …]

Raises:

ValueError – Raised if the desired requirement cannot be met.

property formatted_shape: Tuple[int, ...] | None

The expected output shape basis.

Type:

None|Tuple[int, …]

inverse(array: ndarray, subscript: Tuple[slice, ...]) → ndarray

Inverse operation which takes in formatted data, and returns corresponding raw data.

Parameters:

• array (numpy.ndarray) – The input formatted data.

• subscript (Tuple[slice, ...]) – The slice definition which yielded the formatted data.

Return type:

numpy.ndarray

Raises:

ValueError – A value error should be raised if inverse=True and has_inverse=False.

property raw_shape: Tuple[int, ...] | None

The expected full possible raw shape.

Type:

None|Tuple[int, …]

property reverse_axes: Tuple[int, ...] | None

The collection of axes (with respect to raw order) along which we will reverse as part of transformation to output data order. If not None, then this will be a tuple in strictly increasing order.

Type:

None|Tuple[int, …]

property transpose_axes: Tuple[int, ...]

The transpose order for switching from raw order to output order, prior to applying any format function.

Type:

None|Tuple[int, …]