depsi.transformations

depsi.transformations.radar_to_latlonh(azimuth_coords, range_coords, elevation, metadata)

Convert radar coordinates (azimuth, range) to WGS84 Lat/lon/h coordinates.

Parameters:

Name	Type	Description	Default
azimuth_coords	ndarray	Azimuth pixel radar coordinates.	required
range_coords	ndarray	Range pixel radar coordinates.	required
elevation	ndarray	Ellipsoidal elevation.	required
metadata	dict	Image metadata, at least scene_centre_longitude, scene_centre_latitude, pulse_repetition_frequency, first_azimuth_time, range_sampling_rate, first_range_time, and (orbit_txyz OR orbit_time, orbit_position), optionally orbit_velocity	required

Returns:

Type	Description
(ndarray, tuple)	Return latitude/longitude/height coordinates

Source code in depsi/transformations.py

def radar_to_latlonh(
    azimuth_coords: numpy.ndarray,
    range_coords: numpy.ndarray,
    elevation: numpy.ndarray,
    metadata: dict,
) -> numpy.ndarray:
    """Convert radar coordinates (azimuth, range) to WGS84 Lat/lon/h coordinates.

    Parameters
    ----------
    azimuth_coords: numpy.ndarray
        Azimuth pixel radar coordinates.
    range_coords: numpy.ndarray
        Range pixel radar coordinates.
    elevation: numpy.ndarray
        Ellipsoidal elevation.
    metadata: dict
        Image metadata, at least `scene_centre_longitude`, `scene_centre_latitude`,
        `pulse_repetition_frequency`, `first_azimuth_time`, `range_sampling_rate`, `first_range_time`, and
        (`orbit_txyz` OR `orbit_time`, `orbit_position`), optionally `orbit_velocity`

    Returns
    -------
    numpy.ndarray, tuple
        Return latitude/longitude/height coordinates

    """
    metadata_validated = validate_geocoding_metadata(metadata, mode="radar_to_latlonh", orbit_required=True)
    xyz = radar_to_xyz(azimuth_coords, range_coords, elevation, metadata_validated, return_satellite_vector=False)
    latlonh = xyz_to_latlonh(xyz.T)
    return latlonh

depsi.transformations.latlonh_to_radar(latlonh, metadata)

Transform WGS84 coordinates to radar coordinates (azimuth, range).

Transformation of ellipsoidal geodetic coordinates to radar coordinates (azimuth,range), without auxuliary corrections.

Parameters:

Name	Type	Description	Default
latlonh	ndarray	Ellipsoidal geodetic coordinates (latitude, longitude, ellipsoidal height) in radians and meters.	required
metadata	dict	Image metadata, at least orbit_time, orbit_position, orbit_velocity, first_azimuth_time, number_of_rows and pulse_repetition_frequency	required

Returns:

Type	Description
tuple	Radar coordinates (azimuth, range).

Source code in depsi/transformations.py

def latlonh_to_radar(latlonh: numpy.ndarray, metadata: dict) -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]:
    """Transform WGS84 coordinates to radar coordinates (azimuth, range).

    Transformation of ellipsoidal geodetic coordinates to radar coordinates
    (azimuth,range), without auxuliary corrections.

    Parameters
    ----------
    latlonh: numpy.ndarray
        Ellipsoidal geodetic coordinates (latitude, longitude, ellipsoidal height)
        in radians and meters.
    metadata: dict
        Image metadata, at least `orbit_time`, `orbit_position`, `orbit_velocity`, `first_azimuth_time`,
        `number_of_rows` and `pulse_repetition_frequency`

    Returns
    -------
    tuple
        Radar coordinates (azimuth, range).

    """
    metadata_validated = validate_geocoding_metadata(metadata, mode="latlonh_to_radar", orbit_required=True)

    xyz = latlonh_to_xyz(latlonh)

    # get time coords
    azimuth_time, range_time, satellite_vector = xyz_to_time(xyz, metadata_validated)

    # convert to pixels
    return time_to_radar(azimuth_time, range_time, metadata_validated)

depsi.transformations.validate_geocoding_metadata(metadata, mode, orbit_required)

Validate that all fields necessary for the geocoding are present, and regulate the orbit metadata.

Since DORIS v5 outputs orbit_txyz instead of orbit_time, orbit_position, and orbit_velocity, this function will assign the correct columns of orbit_txyz to the correct expected fields.

Parameters:

Name	Type	Description	Default
metadata	dict	Metadata readout as per sarxarray.read_metadata (>=v1.2.2)	required
mode	Literal['latlonh_to_radar', 'radar_to_latlonh']	Which keys to check that exist	required
orbit_required	bool	Whether or not to construct orbit_time, orbit_position and orbit_velocity if they don't exist	required

Returns:

Type	Description
dict	The validated and corrected metadata dictionary

Source code in depsi/transformations.py

def validate_geocoding_metadata(
    metadata: dict, mode: Literal["latlonh_to_radar", "radar_to_latlonh"], orbit_required: bool
) -> dict:
    """Validate that all fields necessary for the geocoding are present, and regulate the orbit metadata.

    Since DORIS v5 outputs `orbit_txyz` instead of orbit_time, orbit_position, and orbit_velocity, this function will
    assign the correct columns of `orbit_txyz` to the correct expected fields.

    Parameters
    ----------
    metadata: dict
        Metadata readout as per `sarxarray.read_metadata` (>=v1.2.2)
    mode: Literal["latlonh_to_radar", "radar_to_latlonh"]
        Which keys to check that exist
    orbit_required: bool
        Whether or not to construct `orbit_time`, `orbit_position` and `orbit_velocity` if they don't exist

    Returns
    -------
    dict
        The validated and corrected metadata dictionary

    """
    assert mode in VALIDATION_NONORBIT_KEYS.keys(), f"Unknown mode {mode}, known are {VALIDATION_NONORBIT_KEYS.keys()}"
    for key in VALIDATION_NONORBIT_KEYS[mode]:
        assert key in metadata.keys(), f"Key {key} is missing from metadata, cannot proceed!"

    if orbit_required:
        # Orbit info from DORIS5 is read in in orbit_txyz instead of orbit_time and orbit_position -->
        # needs to be split up
        if "orbit_time" not in metadata.keys():
            if "orbit_txyz" in metadata.keys():
                metadata["orbit_time"] = metadata["orbit_txyz"][:, 0]
            else:
                raise ValueError("Key orbit_time is missing and cannot be reconstructed from orbit_txyz!")

        if "orbit_position" not in metadata.keys():
            if "orbit_txyz" in metadata.keys():
                metadata["orbit_position"] = metadata["orbit_txyz"][:, 1:]
            else:
                raise ValueError("Key orbit_position is missing and cannot be reconstructed from orbit_txyz!")

        if "orbit_velocity" not in metadata.keys():
            metadata["orbit_velocity"] = None  # this one can be reconstructed when necessary

    return metadata