SIDD reading/writing elements (sarpy.io.product.sidd)¶
Module for reading and writing SIDD files
- class sarpy.io.product.sidd.SIDDDetails(file_object: str | BinaryIO)¶
Bases:
NITFDetails
SIDD are stored in NITF 2.1 files.
- property is_sidd: bool¶
whether file name corresponds to a SIDD file, or not.
- Type:
bool
- property sidd_meta: SIDDType | SIDDType | SIDDType | List[SIDDType] | List[SIDDType] | List[SIDDType]¶
the sidd meta-data structure(s).
- Type:
None|SIDDType3|SIDDType2|SIDDType1|List[SIDDType3]|List[SIDDType2]|List[SIDDType1]
- property sicd_meta: List[SICDType] | None¶
the sicd meta-data structure(s).
- Type:
None|List[SICDType]
- 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:
- 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:
- parse_graphics_subheader(index: int) GraphicsSegmentHeader ¶
Parse the graphics segment subheader at the given index (only version 2.1).
- Parameters:
index (int) –
- Return type:
- parse_image_subheader(index: int) ImageSegmentHeader | ImageSegmentHeader0 ¶
Parse the image segment subheader at the given index.
- Parameters:
index (int) –
- Return type:
- parse_label_subheader(index: int) LabelSegmentHeader ¶
Parse the label segment subheader at the given index (only version 2.0).
- Parameters:
index (int) –
- Return type:
- 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:
- parse_symbol_subheader(index: int) SymbolSegmentHeader ¶
Parse the symbol segment subheader at the given index (only version 2.0).
- Parameters:
index (int) –
- Return type:
- parse_text_subheader(index: int) TextSegmentHeader | TextSegmentHeader0 ¶
Parse the text segment subheader at the given index.
- Parameters:
index (int) –
- Return type:
- class sarpy.io.product.sidd.SIDDReader(nitf_details)¶
Bases:
NITFReader
,SIDDTypeReader
A reader object for a SIDD file (NITF container with SIDD contents)
- property nitf_details: SIDDDetails¶
The SIDD NITF details object.
- Type:
- 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:
- 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:
- 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:
- 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_sidds_as_tuple() None | Tuple[SIDDType, ...] | Tuple[SIDDType, ...] | Tuple[SIDDType, ...] ¶
Get the sidd collection as a tuple - for simplicity and consistency of use.
- Return type:
None|Tuple[SIDDType1, …]|Tuple[SIDDType2, …]|Tuple[SIDDType3, …]
- 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 asreader(*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_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 asreader(*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: Tuple[SICDType, ...] | None¶
the sicd meta_data collection.
- Type:
None|Tuple[SICDType, …]
- property sidd_meta: None | SIDDType | SIDDType | SIDDType | Tuple[SIDDType, ...] | Tuple[SIDDType, ...] | Tuple[SIDDType, ...]¶
the sidd meta_data collection.
- Type:
None|SIDDType1|SIDDType2|SIDDType3|Tuple[SIDDType1, …]|Tuple[SIDDType2, …]|Tuple[SIDDType3, …]
- 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.product.sidd.is_a(file_name: str | BinaryIO) SIDDReader | None ¶
Tests whether a given file_name corresponds to a SIDD file. Returns a reader instance, if so.
- Parameters:
file_name (str) – the file_name to check
- Returns:
SIDDReader instance if SIDD file, None otherwise
- Return type:
SIDDReader|None
- sarpy.io.product.sidd.validate_sidd_for_writing(sidd_meta: SIDDType | SIDDType | SIDDType | List[SIDDType] | List[SIDDType] | List[SIDDType]) Tuple[SIDDType, ...] | Tuple[SIDDType, ...] | Tuple[SIDDType, ...] ¶
Helper method which ensures the provided SIDD structure is appropriate.
- Parameters:
sidd_meta (SIDDType3|List[SIDDType3]|SIDDType2|List[SIDDType2]|SIDDType1|List[SIDDType1]) –
- Return type:
Tuple[SIDDType3, …]|Tuple[SIDDType2, …]|Tuple[SIDDType1, …]
- sarpy.io.product.sidd.validate_sicd_for_writing(sicd_meta: SICDType | Sequence[SICDType]) Tuple[SICDType, ...] | None ¶
Helper method which ensures the provided SICD structure is appropriate.
- sarpy.io.product.sidd.extract_clas(the_sidd: SIDDType | SIDDType | SIDDType) str ¶
Extract the classification string from a SIDD as appropriate for NITF Security tags CLAS attribute.
- Parameters:
the_sidd (SIDDType3|SIDDType2|SIDDType1) –
- Return type:
str
- sarpy.io.product.sidd.extract_clsy(the_sidd: SIDDType | SIDDType | SIDDType) str ¶
Extract the ownerProducer string from a SIDD as appropriate for NITF Security tags CLSY attribute.
- Parameters:
the_sidd (SIDDType3|SIDDType2|SIDDType1) –
- Return type:
str
- class sarpy.io.product.sidd.SIDDWritingDetails(sidd_meta: SIDDType | SIDDType | SIDDType | Sequence[SIDDType] | Sequence[SIDDType] | Sequence[SIDDType], sicd_meta: SICDType | Sequence[SICDType] | None, row_limit: int | None = None, additional_des: Sequence[DESSubheaderManager] | None = None, graphics_managers: Tuple[GraphicsSubheaderManager, ...] | None = None, text_managers: Tuple[TextSubheaderManager, ...] | None = None, res_managers: Tuple[RESSubheaderManager, ...] | None = None)¶
Bases:
NITFWritingDetails
- property sidd_meta: Tuple[SIDDType, ...] | Tuple[SIDDType, ...] | Tuple[SIDDType, ...]¶
The sidd metadata.
- Type:
Tuple[SIDDType3, …]
- 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:
- 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.product.sidd.SIDDWriter(file_object: str | BinaryIO, sidd_meta: SIDDType | SIDDType | SIDDType | Sequence[SIDDType] | Sequence[SIDDType] | Sequence[SIDDType] | None = None, sicd_meta: SICDType | Sequence[SICDType] | None = None, sidd_writing_details: SIDDWritingDetails | None = None, check_existence: bool = True)¶
Bases:
NITFWriter
Writer class for a SIDD file - a NITF file following certain rules.
Changed in version 1.3.0 to reflect NITFWriter changes.
- 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:
- 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:
- 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:
- 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 nitf_writing_details: SIDDWritingDetails¶
The SIDD/NITF subheader details.
- Type:
- 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.