SICD reading/writing objects (sarpy.io.complex.sicd)

Module for reading and writing SICD files

class sarpy.io.complex.sicd.AmpLookupFunction(raw_dtype: str | dtype, magnitude_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, band_dimension: int = -1)

Bases: ComplexFormatFunction

property magnitude_lookup_table: ndarray

The magnitude lookup table, for SICD usage with AMP8I_PHS8I pixel type.

Return type:

numpy.ndarray

property band_dimension: int

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

Type:

int

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

The expected output shape basis.

Type:

None|Tuple[int, …]

has_inverse = True

Indicates whether this format function has the inverse call implemented.

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 order: str

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

Type:

str

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, …]

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 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, …]

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.

class sarpy.io.complex.sicd.SICDDetails(file_object: str | BinaryIO)

Bases: NITFDetails

SICD are stored in NITF 2.1 files.

property is_sicd: bool

whether file name corresponds to a SICD file, or not.

Type:

bool

property sicd_meta: SICDType

the sicd meta-data structure.

Type:

SICDType

property des_header: DataExtensionHeader | None

The DES subheader object associated with the SICD.

Return type:

DataExtensionHeader

property file_name: str | None

the file name, which may not be useful if the input was based on a file like object

Type:

None|str

property file_object: BinaryIO

The binary file object

Type:

BinaryIO

get_des_bytes(index: int) → bytes

Fetches the data extension segment bytes at the given index.

Parameters:

index (int) –

Return type:

bytes

get_des_subheader_bytes(index: int) → bytes

Fetches the data extension segment subheader bytes at the given index.

Parameters:

index (int) –

Return type:

bytes

get_graphics_bytes(index: int) → bytes

Fetches the graphics extension segment bytes at the given index (only version 2.1).

Parameters:

index (int) –

Return type:

bytes

get_graphics_subheader_bytes(index: int) → bytes

Fetches the graphics segment subheader at the given index (only version 2.1).

Parameters:

index (int) –

Return type:

bytes

get_headers_json() → dict

Get a json (i.e. dict) representation of the NITF header elements.

Return type:

dict

get_image_bytes(index: int) → bytes

Fetches the image bytes at the given index.

Parameters:

index (int) –

Return type:

bytes

get_image_subheader_bytes(index: int) → bytes

Fetches the image segment subheader at the given index.

Parameters:

index (int) –

Return type:

bytes

get_label_bytes(index: int) → bytes

Fetches the label extension segment bytes at the given index (only version 2.0).

Parameters:

index (int) –

Return type:

bytes

get_label_subheader_bytes(index: int) → bytes

Fetches the label segment subheader at the given index (only version 2.0).

Parameters:

index (int) –

Return type:

bytes

get_res_bytes(index: int) → bytes

Fetches the reserved extension segment bytes at the given index (only version 2.1).

Parameters:

index (int) –

Return type:

bytes

get_res_subheader_bytes(index: int) → bytes

Fetches the reserved extension segment subheader bytes at the given index (only version 2.1).

Parameters:

index (int) –

Return type:

bytes

get_symbol_bytes(index: int) → bytes

Fetches the symbol extension segment bytes at the given index (only version 2.0).

Parameters:

index (int) –

Return type:

bytes

get_symbol_subheader_bytes(index: int) → bytes

Fetches the symbol segment subheader at the given index (only version 2.0).

Parameters:

index (int) –

Return type:

bytes

get_text_bytes(index: int) → bytes

Fetches the text extension segment bytes at the given index.

Parameters:

index (int) –

Return type:

bytes

get_text_subheader_bytes(index: int) → bytes

Fetches the text segment subheader at the given index.

Parameters:

index (int) –

Return type:

bytes

property img_headers: None | List[ImageSegmentHeader] | List[ImageSegmentHeader0]

The image segment headers.

Returns:

Only None in the unlikely event that there are no image segments.

Return type:

None|List[ImageSegmentHeader]|List[ImageSegmentHeader0]

property nitf_header: NITFHeader | NITFHeader0

the nitf header object

Type:

NITFHeader

property nitf_version: str

The NITF version number.

Type:

str

parse_des_subheader(index: int) → DataExtensionHeader | DataExtensionHeader0

Parse the data extension segment subheader at the given index.

Parameters:

index (int) –

Return type:

DataExtensionHeader|DataExtensionHeader0

parse_graphics_subheader(index: int) → GraphicsSegmentHeader

Parse the graphics segment subheader at the given index (only version 2.1).

Parameters:

index (int) –

Return type:

GraphicsSegmentHeader

parse_image_subheader(index: int) → ImageSegmentHeader | ImageSegmentHeader0

Parse the image segment subheader at the given index.

Parameters:

index (int) –

Return type:

ImageSegmentHeader|ImageSegmentHeader0

parse_label_subheader(index: int) → LabelSegmentHeader

Parse the label segment subheader at the given index (only version 2.0).

Parameters:

index (int) –

Return type:

LabelSegmentHeader

parse_res_subheader(index: int) → ReservedExtensionHeader | ReservedExtensionHeader0

Parse the reserved extension subheader at the given index (only version 2.1).

Parameters:

index (int) –

Return type:

ReservedExtensionHeader|ReservedExtensionHeader0

parse_symbol_subheader(index: int) → SymbolSegmentHeader

Parse the symbol segment subheader at the given index (only version 2.0).

Parameters:

index (int) –

Return type:

SymbolSegmentHeader

parse_text_subheader(index: int) → TextSegmentHeader | TextSegmentHeader0

Parse the text segment subheader at the given index.

Parameters:

index (int) –

Return type:

TextSegmentHeader|TextSegmentHeader0

class sarpy.io.complex.sicd.SICDReader(nitf_details)

Bases: NITFReader, SICDTypeReader

A SICD reader implementation - file is NITF container following specified rules.

Changed in version 1.3.0 for reading changes.

property nitf_details: SICDDetails

The SICD NITF details object.

Type:

SICDDetails

get_nitf_dict() → Dict

Populate a dictionary with the pertinent NITF header information. This is for use in more faithful preservation of NITF header information in copying or rewriting sicd files.

Return type:

dict

populate_nitf_information_into_sicd()

Populate some pertinent NITF header information into the SICD structure. This provides more faithful copying or rewriting options.

depopulate_nitf_information()

Eliminates the NITF information dict from the SICD structure.

find_image_segment_collections() → Tuple[Tuple[int, ...]]

Determines the image segments, other than those specifically excluded in unsupported_segments property value. It is implicitly assumed that the elements of a given entry are ordered so that IALVL values are sensible.

Note that in the default implementation, every image segment is simply considered separately.

Return type:

Tuple[Tuple[int]]

can_use_memmap() → bool

Can a memmap be used? This is only supported and/or sensible in the case that the file-like object represents a local file.

Return type:

bool

check_for_compliance() → Tuple[int, ...]

Gets indices of image segments that cannot (or should not) be opened.

Return type:

Tuple[int, …]

close() → None

This should perform any necessary clean-up operations, like closing open file handles, deleting any temp files, etc.

property closed: bool

Is the reader closed? Reading will result in a ValueError

Type:

bool

create_data_segment_for_collection_element(collection_index: int) → DataSegment

Creates the data segment overarching the given segment collection.

Parameters:

collection_index (int) –

Return type:

DataSegment

create_data_segment_for_image_segment(image_segment_index: int, apply_format: bool) → DataSegment

Creates the data segment for the given image segment.

For consistency of simple usage, any bands will be presented in the final formatted/output dimension, regardless of the value of apply_format or IMODE.

For compressed image segments, the IMODE has been abstracted away, and the data segment will be consistent with the raw shape having bands in the final dimension (analogous to IMODE=P).

Note that this also stores a reference to the produced data segment in the _image_segment_data_segments dictionary.

Parameters:

• image_segment_index (int) –

• apply_format (bool) – Leave data raw (False), or apply format function and global reverse_axes and transpose_axes values?

Return type:

DataSegment

property data_segment: DataSegment | Tuple[DataSegment, ...]

The data segment collection.

Type:

DataSegment|Tuple[DataSegment, …]

property data_size: Tuple[int, ...] | Tuple[Tuple[int, ...]]

the output/formatted data size(s) of the data segment(s). If there is a single data segment, then this will be Tuple[int, …], otherwise it will be Tuple[Tuple, int, …], …].

Type:

Tuple[int, …]|Tuple[Tuple[int, …], …]

property file_name: str | None

Defined as a convenience property.

Type:

None|str

property file_object: BinaryIO

the binary file like object from which we are reading

Type:

BinaryIO

property files_to_delete_on_close: List[str]

A collection of files to delete on the close operation.

Type:

List[str]

get_data_segment_as_tuple() → Tuple[DataSegment, ...]

Get the data segment collection as a tuple, to avoid the need for redundant checking issues.

Return type:

Tuple[DataSegment, …]

get_data_segments() → List[DataSegment]

Gets a data segment for each of these image segment collection.

Return type:

List[DataSegment]

get_data_size_as_tuple() → Tuple[Tuple[int, ...], ...]

Get the data size collection as a tuple of tuples, to avoid the need for redundant checking issues.

Return type:

Tuple[Tuple[int, …], …]

get_image_header(index: int) → ImageSegmentHeader | ImageSegmentHeader0

Gets the image subheader at the specified index.

Parameters:

index (int) –

Return type:

ImageSegmentHeader|ImageSegmentHeader0

get_raw_data_size_as_tuple() → Tuple[Tuple[int, ...], ...]

Get the raw data size collection as a tuple of tuples, to avoid the need for redundant checking issues.

Return type:

Tuple[Tuple[int, …], …]

get_sicd_bands() → Tuple[str, ...]

Gets the list of bands for each sicd.

Return type:

Tuple[str, …]

get_sicd_partitions(match_function: ~typing.Callable = <function is_general_match>) → Tuple[Tuple[int, ...], ...]

Partition the sicd collection into sub-collections according to match_function, which is assumed to establish an equivalence relation.

Parameters:

match_function (callable) – This match function must have call signature (SICDType, SICDType) -> bool, and defaults to sarpy.io.complex.sicd_elements.utils.is_general_match(). This function is assumed reflexive, symmetric, and transitive.

Return type:

Tuple[Tuple[int, …], …]

get_sicd_polarizations() → Tuple[str, ...]

Gets the list of polarizations for each sicd.

Return type:

Tuple[str]

get_sicds_as_tuple() → None | Tuple[SICDType, ...]

Get the sicd or sicd collection as a tuple - for simplicity and consistency of use.

Return type:

None|Tuple[SICDType, …]

property image_count: int

The number of images/data segments from which to read.

Type:

int

property image_segment_collections: Tuple[Tuple[int, ...]]

The definition for how image segments are grouped together to form the output image collection.

Each entry corresponds to a single output image, and the entry defines the image segment indices which are combined to make up the output image.

Return type:

Tuple[Tuple[int, …]]

property raw_data_size: Tuple[int, ...] | Tuple[Tuple[int, ...]]

the raw data size(s) of the data segment(s). If there is a single data segment, then this will be Tuple[int, …], otherwise it will be Tuple[Tuple, int, …], …].

Type:

Tuple[int, …]|Tuple[Tuple[int, …], …]

read(*ranges: None | int | Tuple[int, ...] | slice, index: int = 0, squeeze: bool = True) → ndarray

Read formatted data from the given data segment. Note this is an alias to the __call__() called as reader(*ranges, index=index, raw=False, squeeze=squeeze).

Parameters:

• ranges (Sequence[Union[None, int, Tuple[int, ...], slice]]) – The slice definition appropriate for data_segment[index].read() usage.

• index (int) – The data_segment index. This is ignored if image_count== 1.

• squeeze (bool) – Squeeze length 1 dimensions out of the shape of the return array?

Return type:

numpy.ndarray

See also

See

meth:sarpy.io.general.data_segment.DataSegment.read.

read_chip(*ranges: Sequence[None | int | Tuple[int, ...] | slice], index: int = 0, squeeze: bool = True) → ndarray

This is identical to read(), and presented for backwards compatibility.

Parameters:

• ranges (Sequence[Union[None, int, Tuple[int, ...], slice]]) –

• index (int) –

• squeeze (bool) –

Return type:

numpy.ndarray

See also

read()

read_raw(*ranges: None | int | Tuple[int, ...] | slice, index: int = 0, squeeze: bool = True) → ndarray

Read raw data from the given data segment. Note this is an alias to the __call__() called as reader(*ranges, index=index, raw=True, squeeze=squeeze).

Parameters:

• ranges (Sequence[Union[None, int, Tuple[int, ...], slice]]) – The slice definition appropriate for data_segment[index].read() usage.

• index (int) – The data_segment index. This is ignored if image_count== 1.

• squeeze (bool) – Squeeze length 1 dimensions out of the shape of the return array?

Return type:

numpy.ndarray

See also

See

meth:sarpy.io.general.data_segment.DataSegment.read_raw.

property reader_type: str

A descriptive string for the type of reader

Type:

str

property sicd_meta: None | SICDType | Tuple[SICDType, ...]

the sicd meta_data or meta_data collection.

Type:

None|SICDType|Tuple[SICDType, …]

property unsupported_segments: Tuple[int, ...]

The image segments deemed not supported.

Type:

Tuple[int, …]

verify_collection_compliance() → None

Verify that image segments collections are compatible.

Raises:

ValueError –

sarpy.io.complex.sicd.is_a(file_name: str | BinaryIO) → SICDReader | None

Tests whether a given file_name corresponds to a SICD file, and returns a reader instance, if so.

Parameters:

file_name (str) – the file_name to check

Return type:

SICDReader|None

sarpy.io.complex.sicd.validate_sicd_for_writing(sicd_meta: SICDType) → SICDType

Helper method which ensures the provided SICD structure provides enough information to support file writing, as well as ensures a few basic items are populated as appropriate.

Parameters:

sicd_meta (SICDType) –

Returns:

This returns a deep copy of the provided SICD structure, with any necessary modifications.

Return type:

SICDType

sarpy.io.complex.sicd.extract_clas(sicd: SICDType) → str

Extract the classification string from a SICD as appropriate for NITF Security tags CLAS attribute.

Parameters:

sicd (SICDType) –

Return type:

str

class sarpy.io.complex.sicd.SICDWritingDetails(sicd_meta: SICDType, row_limit: int | None = None, additional_des: Sequence[DESSubheaderManager] | None = None, text_managers: Tuple[TextSubheaderManager, ...] | None = None, res_managers: Tuple[RESSubheaderManager, ...] | None = None, check_older_version: bool = False)

Bases: NITFWritingDetails

Manager for all the NITF subheader information associated with the SICD.

Introduced in version 1.3.0.

property sicd_meta: SICDType

The sicd metadata

Type:

SICDType

property requires_version: Tuple[int, int, int]

What is the required (at minimum) sicd version?

Type:

Tuple[int, int, int]

property security_tags: NITFSecurityTags

The default NITF security tags for use.

Type:

NITFSecurityTags

property header: NITFHeader

The main NITF header. Note that doing anything that changes the size of that header (i.e. adding TREs) after initialization will result in a broken state.

Type:

NITFHeader

property image_segment_collections: Tuple[Tuple[int, ...]]

The definition for how image segments are grouped together to form the aggregate images.

Each entry corresponds to a single aggregate image, and the entry defines the image segment indices which are combined to make up the aggregate image.

This must be an ordered partitioning of the set (0, …, len(image_managers)-1).

Return type:

Tuple[Tuple[int, …]]

property image_segment_coordinates: Tuple[Tuple[Tuple[int, ...], ...], ...]

The image bounds for the segment collection. This is associated with the image_segment_collection property.

Entry image_segment_coordinates[i] is associated with the ith aggregate image. We have image_segment_coordinates[i] is a tuple of tuples of the form `((row_start, row_end, col_start, col_end)_j,

(row_start, row_end, col_start, col_end)_{j+1}, …)`.

This indicates that the first image segment associated with ith aggregate image is at index j covering the portion of the aggregate image determined by bounds (row_start, row_end, col_start, col_end)_j, the second image segment is at index j+1 covering the portion of the aggregate determined by bounds (row_start, row_end, col_start, col_end)_{j+1}, and so on.

Return type:

Tuple[Tuple[Tuple[int, …], …], …]

set_all_sizes(require: bool = False) → None

This sets the nominal size information in the nitf header, and optionally verifies that all the item_size values are set.

Parameters:

require (bool) – Require all sizes to be set? 0 will be used as a placeholder for header information population.

Return type:

None

set_first_image_offset() → None

Sets the first image offset from the header length.

Return type:

None

set_header_clevel() → None

Sets the appropriate CLEVEL. This requires that header.FL (file size) has been previously populated correctly (using verify_all_offsets()).

Return type:

None

verify_all_offsets(require: bool = False) → bool

This sets and/or verifies all offsets.

Parameters:

require (bool) – Require all offsets to be set?

Return type:

bool

verify_images_have_no_compression() → bool

Verify that there is no compression set for every image manager. That is, we are going to directly write a NITF file.

Return type:

bool

write_all_populated_items(file_object: BinaryIO) → None

Write everything populated. This assumes that the header will start at the beginning (position 0) of the file-like object.

Parameters:

file_object (BinaryIO) –

Return type:

None

write_header(file_object: BinaryIO, overwrite: bool = False) → None

Write the main NITF header.

Parameters:

• file_object (BinaryIO) –

• overwrite (bool) – Overwrite, if previously written?

Return type:

None

class sarpy.io.complex.sicd.SICDWriter(file_object: str | BinaryIO, sicd_meta: SICDType | None = None, sicd_writing_details: SICDWritingDetails | None = None, check_older_version: bool = False, check_existence: bool = True)

Bases: NITFWriter

Writer class for a SICD file - a NITF file containing complex radar data and SICD data extension.

Changed in version 1.3.0 to reflect NITFWriter changes.

property nitf_writing_details: SICDWritingDetails

The SICD/NITF subheader details.

Type:

SICDWritingDetails

close() → None

This should perform any necessary final steps, like closing open file handles, deleting any temp files, etc. Trying to read newly created file without closing may raise a ValueError.

property closed: bool

Is the writer closed? Reading file after writing can result in a ValueError if writer was not closed.

Type:

bool

create_data_segment_for_collection_element(collection_index: int) → DataSegment

Creates the data segment overarching the given segment collection.

Parameters:

collection_index (int) –

Return type:

DataSegment

create_data_segment_for_image_segment(image_segment_index: int, apply_format: bool) → DataSegment

Creates the data segment for the given image segment.

For consistency of simple usage, any bands will be presented in the final formatted/output dimension, regardless of the value of apply_format or IMODE.

For compressed image segments, the IMODE has been abstracted away, and the data segment will be consistent with the raw shape having bands in the final dimension (analogous to IMODE=P).

Note that this also stores a reference to the produced data segment in the _image_segment_data_segments list.

This will raise an exception if not performed in the order presented in the writing manager.

Parameters:

• image_segment_index (int) –

• apply_format (bool) – Leave data raw (False), or apply format function and global reverse_axes and transpose_axes values?

Return type:

DataSegment

property data_segment: Tuple[DataSegment, ...]

The data segment collection.

Type:

Tuple[DataSegment, …]

property data_size: Tuple[Tuple[int, ...]]

the formatted data sizes of the data segments.

Type:

Tuple[Tuple[int, …], …]

property file_name: str | None

Defined as a convenience property.

Type:

None|str

flush(force: bool = False) → None

Try to perform any necessary steps to flush written data to the disk/buffer.

Parameters:

force (bool) – Try force flushing, even for incompletely written data.

Return type:

None

get_data_segments() → List[DataSegment]

Gets a data segment for each of these image segment collection.

Return type:

List[DataSegment]

get_image_header(index: int) → ImageSegmentHeader

Gets the image subheader at the specified index.

Parameters:

index (int) –

Return type:

ImageSegmentHeader

property image_count: int

The number of overall images/data segments.

Type:

int

property image_segment_collections: Tuple[Tuple[int, ...]]

The definition for how image segments are grouped together to form the aggregate image.

Each entry corresponds to a single output image, and the entry defines the image segment indices which are combined to make up the output image.

Return type:

Tuple[Tuple[int, …]]

property raw_data_size: Tuple[int, ...] | Tuple[Tuple[int, ...]]

the raw data sizes of the data segments.

Type:

Tuple[Tuple[int, …], …]

verify_collection_compliance() → None

Verify that image segments collections are compatible.

Raises:

ValueError –

write(data: ndarray, start_indices: int | Tuple[int, ...] | None = None, subscript: Tuple[slice, ...] | None = None, index: int = 0) → None

Write the data to the appropriate data segment. This is an alias to writer(data, start_indices=start_indices, subscript=subscript, index=index, raw=False).

Only one of `start_indices` and `subscript` should be specified.

Parameters:

• data (numpy.ndarray) – The data to write.

• start_indices (None|int|Tuple[int, ...]) – Assuming a contiguous chunk of data, this provides the starting indices of the chunk. Any missing (tail) coordinates will be filled in with 0’s.

• subscript (None|Tuple[slice, ...]) – In contrast to providing start_indices, the slicing definition in formatted coordinates pertinent to the specified data segment.

• index (int) – The index of the

See also

See

meth:sarpy.io.general.data_segment.DataSegment.write.

write_chip(data: ndarray, start_indices: int | Tuple[int, ...] | None = None, subscript: Tuple[slice, ...] | None = None, index: int = 0) → None

This is identical to write(), and presented for backwards compatibility.

Parameters:

• data (numpy.ndarray) –

• start_indices (None|int|Tuple[int, ...]) –

• subscript (None|Tuple[slice, ...]) –

• index (int) –

See also

See

meth:sarpy.io.general.data_segment.DataSegment.write.

write_raw(data: ndarray, start_indices: int | Tuple[int, ...] | None = None, subscript: Tuple[slice, ...] | None = None, index: int = 0) → None

Write the raw data to the file(s). This is an alias to writer(data, start_indices=start_indices, subscript=subscript, index=index, raw=True).

Only one of `start_indices` and `subscript` should be specified.

Parameters:

• data (numpy.ndarray) – The data to write.

• start_indices (None|int|Tuple[int, ...]) – Assuming a contiguous chunk of data, this provides the starting indices of the chunk. Any missing (tail) coordinates will be filled in with 0’s.

• subscript (None|Tuple[slice, ...]) – In contrast to providing start_indices, the slicing definition in raw coordinates pertinent to the specified data segment.

• index (int) –

See also

See

meth:sarpy.io.general.data_segment.DataSegment.write_raw.