Point projection methodology (sarpy.geometry.point_projection)

Functions to map between the coordinates in image pixel space and geographical coordinates.

Examples

from sarpy.geometry import point_projection
from sarpy.io.complex.sicd import SICDReader

reader = SICDReader('<path to sicd file>')
structure = reader.sicd_meta
# or reader.reader.get_sicds_as_tuple()[0]

# you can also use a SIDD structure, obtained from a product type reader

# assume that ecf_coords is some previously defined numpy array of
# shape (..., 3), with final dimension [X, Y, Z]
image_coords = point_projection.ground_to_image(ecf_coords, structure)
# image_coords will be a numpy array of shape (..., 2),
# with final dimension [row, column]

# assume that geo_coords is some previously defined numpy array of
# shape (..., 3), with final dimension [lat, lon, hae]
image_coords = point_projection.ground_to_image_geo(geo_coords, structure)
# image_coords will be a numpy array of shape (..., 2),
# with final dimension [row, column]

# assume that image_coords is some previously defined numpy array of
# shape (..., 2) with final dimension [row, column]
ecf_coords_fixed_hae = point_projection.image_to_ground(image_coords, structure, projection_type='HAE')
ecf_coords_plane = point_projection.image_to_ground(image_coords, structure, projection_type='PLANE')
geo_coords_fixed_hae = point_projection.image_to_ground_geo(image_coords, structure, projection_type='HAE')
geo_coords_plane = point_projection.image_to_ground_geo(image_coords, structure, projection_type='PLANE')
# these outputs will be numpy arrays of shape (..., 3)

# alternatively, these are also methods of the sicd/sidd structure
image_coords = structure.project_ground_to_image(ecf_coords)
image_coords = structure.project_ground_to_image_geo(geo_coords)
ecf_coords_fixed_hae = structure.project_image_to_ground(image_coords, projection_type='HAE')
ecf_coords_plane = structure.project_image_to_ground(image_coords, projection_type='PLANE')
geo_coords_fixed_hae = structure.project_image_to_ground_geo(image_coords, projection_type='HAE')
geo_coords_plane = structure.project_image_to_ground_geo(image_coords, projection_type='PLANE')

Note

It should be explicitly pointed out that these methods are essentially all inexact iterative methods which depend on convergence parameters. Changing these parameters will yield different numerically similar, but different results.

Under the right assumptions involving the projection_type parameter value and the correct structure of the physical coordinates array, then the methods ground_to_image() and image_to_ground() are approximate inverses of one another. Being iterative methods, they can not generally be made numerically exact inverses, but the tolerance can be adjusted to yield very small differences.

Note

Virtually any SIDD/SICD structure which follows the standard will have an appropriate metadata populated to permit these projection methods. In the case that your structure does not have sufficient metadata populated, as may happen during research experimentation, an exception will be raised with hopefully helpful details about what information is missing.

class sarpy.geometry.point_projection.COAProjection(time_coa_poly: Poly2DType, arp_poly: XYZPolyType, method_projection: Callable, row_shift: int | float = 0, row_mult: int | float = 1, col_shift: int | float = 0, col_mult: int | float = 1, delta_arp: None | ndarray | list | tuple = None, delta_varp: None | ndarray | list | tuple = None, range_bias: float | None = None)

Bases: object

The Center of Aperture projection object, which provides common projection functionality for all image to R/Rdot projection. This is a helper class, and generally not intended for direct usage.

property delta_arp: ndarray

The delta arp adjustable parameter

Type:

numpy.ndarray

property delta_varp: ndarray

The delta varp adjustable parameter

Type:

numpy.ndarray

property range_bias: float

The range bias adjustable parameter

Type:

float

property delta_range: float

Alias to the range bias adjustable parameter

Type:

float

classmethod from_sicd(sicd, delta_arp: None | ndarray | list | tuple = None, delta_varp: None | ndarray | list | tuple = None, range_bias: float | None = None, adj_params_frame: str = 'ECF')

Construct from a SICD structure.

Parameters:

  • sicd (sarpy.io.complex.sicd_elements.SICD.SICDType) – The SICD metadata structure.

  • 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_ECI’, ‘RIC_ECF’).

Return type:

COAProjection

classmethod from_sidd(sidd, delta_arp: None | ndarray | list | tuple = None, delta_varp: None | ndarray | list | tuple = None, range_bias: float | None = None, adj_params_frame: str = 'ECF')

Construct from the SIDD structure.

Parameters:

  • sidd (sarpy.io.product.sidd1_elements.SIDD.SIDDType1|sarpy.io.product.sidd2_elements.SIDD.SIDDType2) –

  • 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_ECI’, ‘RIC_ECF’).

Return type:

COAProjection

projection(im_points: ndarray) → Tuple[ndarray, ndarray, ndarray, ndarray, ndarray]

Perform the projection from image coordinates to R/Rdot coordinates.

Parameters:

im_points (numpy.ndarray) – This array of image point coordinates, expected to have shape (N, 2).

Returns:

  • r_tgt_coa (numpy.ndarray) – range to the ARP at COA

  • r_dot_tgt_coa (numpy.ndarray) – range rate relative to the ARP at COA

  • time_coa (numpy.ndarray) – center of aperture time since CDP start for input ip

  • arp_coa (numpy.ndarray) – aperture reference position at time_coa

  • varp_coa (numpy.ndarray) – velocity at time_coa

sarpy.geometry.point_projection.ground_to_image(coords: ndarray | list | tuple, structure, tolerance: float = 0.01, max_iterations: int = 10, block_size: int | None = 50000, use_structure_coa: bool = True, **coa_args) → 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.

  • structure (sarpy.io.complex.sicd_elements.SICD.SICDType|sarpy.io.product.sidd2_elements.SIDD.SIDDType|sarpy.io.product.sidd1_elements.SIDD.SIDDType) – The SICD or SIDD data structure.

  • tolerance (float|int) – Ground plane displacement tol (m).

  • max_iterations (int) – maximum number of iterations to perform

  • block_size (int|None) – size of blocks of coordinates to transform at a time

  • use_structure_coa (bool) – If sicd.coa_projection is populated, use that one ignoring the COAProjection parameters.

  • coa_args – The keyword arguments from the COAProjection.from_sicd class method.

Returns:

  • image_points (numpy.ndarray) – The determined image point array. Following the SICD convention, t the upper-left pixel is [0, 0].

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

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

sarpy.geometry.point_projection.ground_to_image_geo(coords, structure, ordering='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.

Parameters:
Returns:

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

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

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

sarpy.geometry.point_projection.image_to_ground(im_points: ndarray | list | tuple, structure, block_size: int | None = 50000, projection_type: str = 'HAE', use_structure_coa: bool = True, **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) – (row, column) coordinates of N points in image (or subimage if FirstRow/FirstCol are nonzero). Following SICD convention, the upper-left pixel is [0, 0].

  • structure (sarpy.io.complex.sicd_elements.SICD.SICDType|sarpy.io.product.sidd2_elements.SIDD.SIDDType|sarpy.io.product.sidd1_elements.SIDD.SIDDType) – The SICD or SIDD structure.

  • block_size (None|int) – Size of blocks of coordinates to transform at a time. The entire array will be transformed as a single block if None.

  • projection_type (str) – One of [‘PLANE’, ‘HAE’, ‘DEM’].

  • use_structure_coa (bool) – If structure.coa_projection is populated, use that one ignoring the COAProjection parameters.

  • kwargs – keyword arguments relevant for the given projection type. See image_to_ground_plane/hae/dem methods.

Returns:

Physical coordinates (in ECF) corresponding input image coordinates. The interpretation or meaning of the physical coordinates depends on projection_type chosen.

Return type:

numpy.ndarray

sarpy.geometry.point_projection.image_to_ground_geo(im_points: ndarray | list | tuple, structure, ordering: str = 'latlong', block_size: int | None = 50000, projection_type: str = 'HAE', use_structure_coa: bool = True, **kwargs) → ndarray

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

Parameters:
Returns:

Ground Plane Point (in Lat/Lon/HAE coordinates) along the R/Rdot contour.

Return type:

numpy.ndarray

sarpy.geometry.point_projection.image_to_ground_plane(im_points: ndarray | list | tuple, structure, block_size: int | None = 50000, gref: None | ndarray | list | tuple = None, ugpn: None | ndarray | list | tuple = None, use_structure_coa: bool = True, **coa_args)

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

  • structure (sarpy.io.complex.sicd_elements.SICD.SICDType|sarpy.io.product.sidd2_elements.SIDD.SIDDType|sarpy.io.product.sidd1_elements.SIDD.SIDDType) – The SICD or SIDD structure.

  • block_size (None|int) – Size of blocks of coordinates to transform at a time. The entire array will be transformed as a single block if None.

  • gref (None|numpy.ndarray|list|tuple) – Ground plane reference point ECF coordinates (m). The default is the SCP or Reference Point.

  • ugpn (None|numpy.ndarray|list|tuple) – Vector normal to the plane to which we are projecting.

  • use_structure_coa (bool) – If structure.coa_projection is populated, use that one ignoring the COAProjection parameters.

  • coa_args – keyword arguments for COAProjection.from_sicd class method.

Returns:

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

Return type:

numpy.ndarray

sarpy.geometry.point_projection.image_to_ground_hae(im_points: ndarray | list | tuple, structure, block_size: int | None = 50000, hae0: float | None = None, tolerance: float = 0.001, max_iterations: int = 10, use_structure_coa: bool = True, **coa_args) → 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

  • structure (sarpy.io.complex.sicd_elements.SICD.SICDType|sarpy.io.product.sidd2_elements.SIDD.SIDDType|sarpy.io.product.sidd1_elements.SIDD.SIDDType) – The SICD or SIDD structure.

  • block_size (None|int) – Size of blocks of coordinates to transform at a time. The entire array will be transformed as a single block if None.

  • hae0 (None|float|int) – Surface height (m) above the WGS-84 reference ellipsoid for projection point. Defaults to HAE at the SCP or Reference Point.

  • tolerance (float|int) – Height threshold for convergence of iterative constant HAE computation (m).

  • max_iterations (int) – Maximum number of iterations allowed for constant hae computation.

  • use_structure_coa (bool) – If structure.coa_projection is populated, use that one ignoring the COAProjection parameters.

  • coa_args – keyword arguments for COAProjection.from_sicd class method.

Returns:

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

Return type:

numpy.ndarray

sarpy.geometry.point_projection.image_to_ground_dem(im_points: ndarray | list | tuple, structure, block_size: int | None = 50000, dem_interpolator: str | DEMInterpolator = None, dem_type: None | str | List[str] = None, geoid_file: None | str | GeoidHeight = None, pad_value: float = 0.2, vertical_step_size: int | float = 10, use_structure_coa: bool = True, **coa_args) → 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

  • structure (sarpy.io.complex.sicd_elements.SICD.SICDType|sarpy.io.product.sidd2_elements.SIDD.SIDDType|sarpy.io.product.sidd1_elements.SIDD.SIDDType) – The SICD or SIDD structure.

  • block_size (None|int) – Size of blocks of coordinates to transform at a time. The entire array will be transformed as a single block if None.

  • dem_interpolator (str|DEMInterpolator) – The DEMInterpolator. If this is a string, then a DTEDInterpolator will be constructed assuming that this is the DTED root search directory.

  • dem_type (None|str|List[str]) – The DEM type or list of DEM types in order of priority. Only used if dem_interpolator is the search path.

  • geoid_file (None|str|GeoidHeight) – The GeoidHeight object, an egm file name, or root directory containing one of the egm files in the subdirectory “geoid”. If None, then default to the root directory of dted_list. Only used if dem_interpolator is the search path.

  • pad_value (float) – The degree value to pad by for the dem interpolator. Only used if dem_interpolator is the search path.

  • vertical_step_size (float|int) – Sampling along HAE altitude at the given resolution in meters. Bounds of [0.1, 100] will be enforced by replacement.

  • use_structure_coa (bool) – If structure.coa_projection is populated, use that one ignoring the COAProjection parameters.

  • coa_args – keyword arguments for COAProjection.from_sicd class method.

Returns:

Physical coordinates (in ECF coordinates) with corresponding to the input image coordinates, assuming detected features actually correspond to the DEM.

Return type:

numpy.ndarray