The Main SICD object

The SICDType definition.

class sarpy.io.complex.sicd_elements.SICD.SICDType(CollectionInfo: CollectionInfoType = None, ImageCreation: ImageCreationType | None = None, ImageData: ImageDataType = None, GeoData: GeoDataType = None, Grid: GridType = None, Timeline: TimelineType = None, Position: PositionType = None, RadarCollection: RadarCollectionType = None, ImageFormation: ImageFormationType = None, SCPCOA: SCPCOAType = None, Radiometric: RadiometricType | None = None, Antenna: AntennaType | None = None, ErrorStatistics: ErrorStatisticsType | None = None, MatchInfo: MatchInfoType | None = None, RgAzComp: RgAzCompType | None = None, PFA: PFAType | None = None, RMA: RMAType | None = None, **kwargs)

Bases: Serializable

Sensor Independent Complex Data object, containing all the relevant data to formulate products.

CollectionInfo: CollectionInfoType

General information about the collection. Required.

Type:

CollectionInfoType

ImageCreation: ImageCreationType | None

General information about the image creation. Optional.

Type:

ImageCreationType

ImageData: ImageDataType

The image pixel data. Required.

Type:

ImageDataType

GeoData: GeoDataType

The geographic coordinates of the image coverage area. Required.

Type:

GeoDataType

Grid: GridType

The image sample grid. Required.

Type:

GridType

Timeline: TimelineType

The imaging collection time line. Required.

Type:

TimelineType

Position: PositionType

The platform and ground reference point coordinates as a function of time. Required.

Type:

PositionType

RadarCollection: RadarCollectionType

The radar collection information. Required.

Type:

RadarCollectionType

ImageFormation: ImageFormationType

The image formation process. Required.

Type:

ImageFormationType

SCPCOA: SCPCOAType

Center of Aperture (COA) for the Scene Center Point (SCP). Required.

Type:

SCPCOAType

Radiometric: RadiometricType | None

The radiometric calibration parameters. Optional.

Type:

RadiometricType

Antenna: AntennaType | None

Parameters that describe the antenna illumination patterns during the collection. Optional.

Type:

AntennaType

ErrorStatistics: ErrorStatisticsType | None

Parameters used to compute error statistics within the SICD sensor model. Optional.

Type:

ErrorStatisticsType

MatchInfo: MatchInfoType | None

Information about other collections that are matched to the current collection. The current collection is the collection from which this SICD product was generated. Optional.

Type:

MatchInfoType

RgAzComp: RgAzCompType | None

Parameters included for a Range, Doppler image. Optional.

Type:

RgAzCompType

PFA: PFAType | None

Parameters included when the image is formed using the Polar Formation Algorithm (PFA). Optional.

Type:

PFAType

RMA: RMAType | None

Parameters included when the image is formed using the Range Migration Algorithm (RMA). Optional.

Type:

RMAType

property coa_projection

The COA Projection object, if previously defined through using define_coa_projection().

Return type:

None|sarpy.geometry.point_projection.COAProjection

property NITF: Dict | None

Optional dictionary of NITF header information, pertains only to subsequent SICD file writing.

Return type:

Dict

property ImageFormType: str

READ ONLY Identifies the specific image formation type supplied. This is determined by returning the (first) attribute among RgAzComp, PFA, RMA which is populated. OTHER will be returned if none of them are populated.

Type:

str

update_scp(point: ndarray | list | tuple, coord_system: str = 'ECF')

Modify the SCP point, and modify the associated SCPCOA fields.

Parameters:

• point (numpy.ndarray|tuple|list) –

• coord_system (str) – Either ‘ECF’ or ‘LLH’, and ‘ECF’ will take precedence.

Return type:

None

is_valid(recursive: bool = False, stack: bool = False) → bool

Returns the validity of this object according to the schema. This is done by inspecting that all required fields (i.e. entries of _required) are not None.

Parameters:

• recursive (bool) – True if we recursively check that child are also valid. This may result in verbose (i.e. noisy) logging.

• stack (bool) – Print a recursive error message?

Returns:

condition for validity of this element

Return type:

bool

define_geo_image_corners(override: bool = False) → None

Defines the GeoData image corner points (if possible), if they are not already defined.

Return type:

None

define_geo_valid_data() → None

Defines the GeoData valid data corner points (if possible), if they are not already defined.

Return type:

None

derive() → None

Populates any potential derived data in the SICD structure. This should get called after reading an XML, or as a user desires.

Return type:

None

get_transmit_band_name() → str

Gets the processed transmit band name.

Return type:

str

get_processed_polarization_abbreviation() → str

Gets the processed polarization abbreviation (two letters).

Return type:

str

get_processed_polarization() → str

Gets the processed polarization.

Return type:

str

apply_reference_frequency(reference_frequency: float) → None

If the reference frequency is used, adjust the necessary fields accordingly.

Parameters:

reference_frequency (float) – The reference frequency.

Return type:

None

classmethod from_dict(input_dict)

For json deserialization, from dict instance.

Parameters:

input_dict (dict) – Appropriate parameters dict instance for deserialization

Return type:

Corresponding class instance

classmethod from_node(node, xml_ns, ns_key=None, kwargs=None)

For XML deserialization.

Parameters:

• node (ElementTree.Element) – dom element for serialized class instance

• xml_ns (None|dict) – The xml namespace dictionary.

• ns_key (None|str) – The xml namespace key. If xml_ns is None, then this is ignored. If None and xml_ns is not None, then the string default will be used. This will be recursively passed down, unless overridden by an entry of the cls._child_xml_ns_key dictionary.

• kwargs (None|dict) – None or dictionary of previously serialized attributes. For use in inheritance call, when certain attributes require specific deserialization.

Return type:

Corresponding class instance

log_validity_error(msg)

Log a validity check error message.

Parameters:

msg (str) –

log_validity_info(msg)

Log a validation info message.

Parameters:

msg (str) –

log_validity_warning(msg)

Log a validity check warning message.

Parameters:

msg (str) –

set_numeric_format(attribute, format_string)

Sets the numeric format string for the given attribute.

Parameters:

• attribute (str) – attribute for which the format applies - must be in _fields.

• format_string (str) – format string to be applied

Return type:

None

to_dict(check_validity=False, strict=False, exclude=())

For json serialization.

Parameters:

• check_validity (bool) – Check whether the element is valid before serializing, by calling is_valid().

• strict (bool) – Only used if check_validity = True. In that case, if True then raise an Exception (of appropriate type) if the structure is not valid, if False then log a hopefully helpful message.

• exclude (tuple) – Attribute names to exclude from this generic serialization. This allows for child classes to provide specific serialization for special properties, after using this super method.

Returns:

dict representation of class instance appropriate for direct json serialization.

Return type:

OrderedDict

to_node(doc, tag, ns_key=None, parent=None, check_validity=False, strict=False, exclude=())

For XML serialization, to a dom element.

Parameters:

• doc (ElementTree.ElementTree) – The xml Document

• tag (None|str) – The tag name. Defaults to the value of self._tag and then the class name if unspecified.

• ns_key (None|str) – The namespace prefix. This will be recursively passed down, unless overridden by an entry in the _child_xml_ns_key dictionary.

• parent (None|ElementTree.Element) – The parent element. Defaults to the document root element if unspecified.

• check_validity (bool) – Check whether the element is valid before serializing, by calling is_valid().

• strict (bool) – Only used if check_validity = True. In that case, if True then raise an Exception (of appropriate type) if the structure is not valid, if False then log a hopefully helpful message.

• exclude (tuple) – Attribute names to exclude from this generic serialization. This allows for child classes to provide specific serialization for special properties, after using this super method.

Returns:

The constructed dom element, already assigned to the parent element.

Return type:

ElementTree.Element

get_ground_resolution() → Tuple[float, float]

Gets the ground resolution for the sicd.

Return type:

(float, float)

can_project_coordinates() → bool

Determines whether the necessary elements are populated to permit projection between image and physical coordinates. If False, then the (first discovered) reason why not will be logged at error level.

Return type:

bool

define_coa_projection(delta_arp: None | ndarray | list | tuple = None, delta_varp: None | ndarray | list | tuple = None, range_bias: float | None = None, adj_params_frame: str = 'ECF', override: bool = True) → None

Define the COAProjection object.

Parameters:

• delta_arp (None|numpy.ndarray|list|tuple) – ARP position adjustable parameter (ECF, m). Defaults to 0 in each coordinate.

• delta_varp (None|numpy.ndarray|list|tuple) – VARP position adjustable parameter (ECF, m/s). Defaults to 0 in each coordinate.

• range_bias (float|int) – Range bias adjustable parameter (m), defaults to 0.

• adj_params_frame (str) – One of [‘ECF’, ‘RIC_ECF’, ‘RIC_ECI’], specifying the coordinate frame used for expressing delta_arp and delta_varp parameters.

• override (bool) – should we redefine, if it is previously defined?

Return type:

None

project_ground_to_image(coords: ndarray | list | tuple, **kwargs) → Tuple[ndarray, ndarray | float, ndarray | int]

Transforms a 3D ECF point to pixel (row/column) coordinates. This is implemented in accordance with the SICD Image Projections Description Document. Really Scene-To-Image projection.”

Parameters:

• coords (numpy.ndarray|tuple|list) – ECF coordinate to map to scene coordinates, of size N x 3.

• kwargs – The keyword arguments for the sarpy.geometry.point_projection.ground_to_image() method.

Returns:

• image_points (numpy.ndarray) – The determined image point array, of size N x 2. Following the SICD convention, he upper-left pixel is [0, 0].

• delta_gpn (numpy.ndarray|float) – Residual ground plane displacement (m).

• iterations (numpy.ndarray|int) – The number of iterations performed.

See also

sarpy.geometry.point_projection.ground_to_image

project_ground_to_image_geo(coords: ndarray | list | tuple, ordering: str = 'latlong', **kwargs) → Tuple[ndarray, ndarray | float, ndarray | int]

Transforms a 3D Lat/Lon/HAE point to pixel (row/column) coordinates. This is implemented in accordance with the SICD Image Projections Description Document. Really Scene-To-Image projection.”

Parameters:

• coords (numpy.ndarray|tuple|list) – ECF coordinate to map to scene coordinates, of size N x 3.

• ordering (str) – If ‘longlat’, then the input is [longitude, latitude, hae]. Otherwise, the input is [latitude, longitude, hae]. Passed through to sarpy.geometry.geocoords.geodetic_to_ecf().

• kwargs – The keyword arguments for the sarpy.geometry.point_projection.ground_to_image_geo() method.

Returns:

• image_points (numpy.ndarray) – The determined image point array, of size N x 2. Following the SICD convention, he upper-left pixel is [0, 0].

• delta_gpn (numpy.ndarray|float) – Residual ground plane displacement (m).

• iterations (numpy.ndarray|int) – The number of iterations performed.

See also

sarpy.geometry.point_projection.ground_to_image_geo

project_image_to_ground(im_points: ndarray | list | tuple, projection_type: str = 'HAE', **kwargs) → ndarray

Transforms image coordinates to ground plane ECF coordinate via the algorithm(s) described in SICD Image Projections document.

Parameters:

• im_points (numpy.ndarray|list|tuple) – the image coordinate array

• projection_type (str) – One of [‘PLANE’, ‘HAE’, ‘DEM’]. Type DEM is a work in progress.

• kwargs – The keyword arguments for the sarpy.geometry.point_projection.image_to_ground() method.

Returns:

Ground Plane Point (in ECF coordinates) corresponding to the input image coordinates.

Return type:

numpy.ndarray

See also

sarpy.geometry.point_projection.image_to_ground

project_image_to_ground_geo(im_points: ndarray | list | tuple, ordering: str = 'latlong', projection_type: str = 'HAE', **kwargs) → ndarray

Transforms image coordinates to ground plane WGS-84 coordinate via the algorithm(s) described in SICD Image Projections document.

Parameters:

• im_points (numpy.ndarray|list|tuple) – the image coordinate array

• projection_type (str) – One of [‘PLANE’, ‘HAE’, ‘DEM’]. Type DEM is a work in progress.

• ordering (str) – Determines whether return is ordered as [lat, long, hae] or [long, lat, hae]. Passed through to sarpy.geometry.geocoords.ecf_to_geodetic().

• kwargs – The keyword arguments for the sarpy.geometry.point_projection.image_to_ground_geo() method.

Returns:

Ground Plane Point (in ECF coordinates) corresponding to the input image coordinates.

Return type:

numpy.ndarray

See also

sarpy.geometry.point_projection.image_to_ground_geo

populate_rniirs(signal: float | None = None, noise: float | None = None, override: bool = False) → None

Given the signal and noise values (in sigma zero power units), calculate and populate an estimated RNIIRS value.

Parameters:

• signal (None|float) –

• noise (None|float) –

• override (bool) – Override the value, if present.

Return type:

None

get_suggested_name(product_number: int = 1) → str

Get the suggested name stem for the sicd and derived data.

Parameters:

product_number (int) –

Return type:

str

version_required() → Tuple[int, int, int]

What SICD version is required for valid support?

Return type:

tuple

get_des_details(check_older_version: bool = False) → Dict

Gets the correct current SICD DES subheader details.

Parameters:

check_older_version (bool) – If True and compatible, then version 1.1.0 information will be returned. Otherwise, the most recent supported version will be returned.

Return type:

dict

copy()

Provides a deep copy.

Return type:

SICDType

to_xml_bytes(urn=None, tag='SICD', check_validity=False, strict=False)

Gets a bytes array, which corresponds to the xml string in utf-8 encoding, identified as using the namespace given by urn (if given).

Parameters:

• urn (None|str|dict) – The xml namespace string or dictionary describing the xml namespace.

• tag (None|str) – The root node tag to use. If not given, then the class name will be used.

• check_validity (bool) – Check whether the element is valid before serializing, by calling is_valid().

• strict (bool) – Only used if check_validity = True. In that case, if True then raise an Exception (of appropriate type) if the structure is not valid, if False then log a hopefully helpful message.

Returns:

bytes array from ElementTree.tostring() call.

Return type:

bytes

to_xml_string(urn=None, tag='SICD', check_validity=False, strict=False)

Gets a xml string with utf-8 encoding, identified as using the namespace given by urn (if given).

Parameters:

• urn (None|str|dict) – The xml namespace or dictionary describing the xml namespace.

• tag (None|str) – The root node tag to use. If not given, then the class name will be used.

• check_validity (bool) – Check whether the element is valid before serializing, by calling is_valid().

• strict (bool) – Only used if check_validity = True. In that case, if True then raise an Exception (of appropriate type) if the structure is not valid, if False then log a hopefully helpful message.

Returns:

xml string from ElementTree.tostring() call.

Return type:

str

create_subset_structure(row_bounds: Tuple[int, int] | None = None, column_bounds: Tuple[int, int] | None = None)

Create a version of the SICD structure for a given subset.

Parameters:

• row_bounds (None|tuple) –

• column_bounds (None|tuple) –

Returns:

• sicd (SICDType) – The sicd

• row_bounds (tuple) – Vetted tuple of the form (min row, max row).

• column_bounds (tuple) – Vetted tuple of the form (min column, max column).

classmethod from_xml_file(file_path)

Construct the sicd object from a stand-alone xml file path.

Parameters:

file_path (str) –

Return type:

SICDType

classmethod from_xml_string(xml_string)

Construct the sicd object from a xml string.

Parameters:

xml_string (str|bytes) –

Return type:

SICDType