arepytools 1.7.6__py3-none-any.whl

arepytools/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: Aresys S.r.l. <info@aresys.it>
+# SPDX-License-Identifier: MIT
+
+"""
+ArePyTools: the Python toolkit for SAR data processing
+"""
+
+__version__ = "1.7.6"

arepytools/constants.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: Aresys S.r.l. <info@aresys.it>
+# SPDX-License-Identifier: MIT
+
+
+"""
+**Deprecated** Constants module
+-------------------------------
+
+.. deprecated:: v1.7.0
+    Importing constants is deprecated.
+    Use scipy.constants.speed_of_light for LIGHT_SPEED.
+
+Examples
+--------
+>>> import arepytools.constants as cst
+>>> print(cst.LIGHT_SPEED)
+299792458.0
+"""
+import warnings
+
+import scipy
+
+warnings.warn(
+    "arepytools.constants module is deprecated. Instead of importing LIGHT_SPEED use 'from scipy.constants import speed_of_light'",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+SECONDS_IN_A_DAY = 86164.09054
+"""
+Number of seconds in a day
+"""
+
+LIGHT_SPEED = scipy.constants.speed_of_light
+"""
+Speed of light in vacuum (m/s).
+"""
+
+# Units of measure
+SECOND_STR = "s"
+"""
+Second symbol.
+"""
+
+HERTZ_STR = "Hz"
+"""
+Hertz symbol.
+"""
+
+JOULE_STR = "j"
+"""
+Joule symbol.
+"""
+
+DEGREE_STR = "deg"
+"""
+Degree symbol.
+"""
+
+RAD_STR = "rad"
+"""
+Radian symbol.
+"""
+
+UTC_STR = "Utc"
+"""
+Coordinated Universal Time abbreviation.
+"""
+
+METER_STR = "m"
+"""
+Meter symbol.
+"""
+
+# Metric prefixes
+KILO = 1e3
+"""
+Number of units in one kilounit (kilounits-to-units conversion factor).
+"""
+
+MEGA = KILO**2
+"""
+Number of units in one megaunit (megaunits-to-units conversion factor).
+"""
+
+GIGA = KILO**3
+"""
+Number of units in one gigaunit (gigaunits-to-units conversion factor).
+"""
+
+MILLI = KILO**-1
+"""
+Number of units in one milliunit (milliunits-to-units conversion factor).
+"""
+
+MICRO = KILO**-2
+"""
+Number of units in one microunit (microunits-to-units conversion factor).
+"""
+
+NANO = KILO**-3
+"""
+Number of units in one nanounit (nanounits-to-units conversion factor).
+"""
+
+PICO = KILO**-4
+"""
+Number of units in one picounit (picounits-to-units conversion factor).
+"""

arepytools/geometry/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: Aresys S.r.l. <info@aresys.it>
+# SPDX-License-Identifier: MIT
+
+"""
+Geometry management package
+"""

arepytools/geometry/_geodetic.py

@@ -0,0 +1,107 @@
+# SPDX-FileCopyrightText: Aresys S.r.l. <info@aresys.it>
+# SPDX-License-Identifier: MIT
+
+"""
+Geodetic module
+---------------
+"""
+
+import numpy as np
+import numpy.typing as npt
+
+from arepytools.geometry.conversions import llh2xyz, xyz2llh
+from arepytools.geometry.ellipsoid import WGS84
+
+_semi_axis_ratio_sqr = WGS84.semi_axes_ratio_min_max**2
+_major_semi_axis_sqr = WGS84.semi_major_axis**2
+_minor_semi_axis_sqr = WGS84.semi_minor_axis**2
+
+
+def _ze(x: float, y: float) -> float:
+    eps = 1.0e-21
+
+    return np.sqrt(_minor_semi_axis_sqr - _semi_axis_ratio_sqr * (x**2 + y**2)) + eps
+
+
+def _ze_x(x: float, y: float) -> float:
+    return -WGS84.semi_axes_ratio_min_max * x / _ze(x, y)
+
+
+def _ze_xy(x: float, y: float) -> float:
+    # pylint: disable-next=arguments-out-of-order
+    return (_semi_axis_ratio_sqr * x) / _ze(x, y) ** 2 * _ze_x(y, x)
+
+
+def _ze_xx(x: float, y: float) -> float:
+    return -_semi_axis_ratio_sqr / _ze(x, y) + (_semi_axis_ratio_sqr * x) / _ze(x, y) ** 2 * _ze_x(x, y)
+
+
+def _compute_geodetic_jacobian(point: np.ndarray, sensor_position: np.ndarray) -> np.ndarray:
+    jac = np.empty(shape=(3, 3), dtype=float)
+
+    zed_diff = point[2] - sensor_position[2]
+
+    jac[0][0] = 2.0 * point[0] / _major_semi_axis_sqr
+    jac[0][1] = 2.0 * point[1] / _major_semi_axis_sqr
+    jac[0][2] = 2.0 * point[2] / _minor_semi_axis_sqr
+    jac[1][0] = 1.0 + zed_diff * _ze_xx(point[0], point[1])
+    jac[1][1] = zed_diff * _ze_xy(point[0], point[1])
+    jac[1][2] = _ze_x(point[0], point[1])
+    jac[2][0] = jac[1][1]
+    jac[2][1] = 1.0 + zed_diff * _ze_xx(point[1], point[0])
+    jac[2][2] = _ze_x(point[1], point[0])
+
+    return jac
+
+
+def _compute_geodetic_rhs(point: npt.NDArray[np.floating], sensor_position: npt.NDArray[np.floating]) -> np.ndarray:
+    rhs = np.empty(shape=(3,), dtype=float)
+    los = point - sensor_position
+    rhs[0] = (point[0] ** 2 + point[1] ** 2) / _major_semi_axis_sqr + point[2] ** 2 / _minor_semi_axis_sqr - 1
+    rhs[1] = los[0] + los[2] * _ze_x(point[0], point[1])
+    rhs[2] = los[1] + los[2] * _ze_x(point[1], point[0])
+    return rhs
+
+
+def compute_geodetic_point(sensor_positions: npt.ArrayLike) -> np.ndarray:
+    """Compute the geodetic point that corresponds to a sensor position
+
+    :param sensor_position: sensor position array like with shape (3,) or (N, 3)
+
+    :return: geodetic point as a (3,) or (N, 3) numpy array
+    """
+    sensor_positions = np.asarray(sensor_positions)
+
+    if sensor_positions.ndim > 2 or sensor_positions.shape[-1] != 3:
+        raise ValueError(f"sensor_positions has invalid shape: {sensor_positions.shape}, it should be (3,) or (N, 3)")
+
+    sensor_positions = sensor_positions.copy()
+    change_sign = sensor_positions[..., 2] < 0
+    sensor_positions[change_sign, 2] *= -1
+
+    geodetic_points = xyz2llh(sensor_positions.T)
+    geodetic_points[2, ...] = 0
+    geodetic_points = llh2xyz(geodetic_points).T.reshape(sensor_positions.shape)
+
+    for sensor_position, point in zip(
+        sensor_positions.reshape((-1, 3)),
+        geodetic_points.reshape((-1, 3)),
+    ):
+        increment_norm_threshold = 1e-9
+        max_num_iterations = 10
+        for _ in range(max_num_iterations):
+            jacobian = _compute_geodetic_jacobian(point[:], sensor_position)
+            rhs = _compute_geodetic_rhs(point[:], sensor_position)
+
+            increment = -np.linalg.solve(jacobian, rhs)
+
+            increment_norm = np.linalg.norm(increment)
+
+            point[:] += increment
+
+            if increment_norm < increment_norm_threshold:
+                break
+
+    geodetic_points[change_sign, 2] *= -1
+
+    return geodetic_points

arepytools/geometry/_interpolator.py

@@ -0,0 +1,210 @@
+# SPDX-FileCopyrightText: Aresys S.r.l. <info@aresys.it>
+# SPDX-License-Identifier: MIT
+
+"""
+Geometry interpolator module
+----------------------------
+"""
+
+import numpy as np
+
+
+def check_eval_function_input(fun):
+    """
+    Interpolator eval function input checker
+    """
+
+    def decorated_fun(self, *args_f, **kwargs_f):
+        if isinstance(args_f[0], (list, np.ndarray)):
+            interpolation_axis = np.asarray(args_f[0])
+        else:
+            interpolation_axis = np.full((1,), args_f[0])
+        return fun(self, interpolation_axis, *args_f[1:], **kwargs_f)
+
+    return decorated_fun
+
+
+class GeometryInterpolator:
+    """
+    Internal class for handling interpolation in GeneralSarOrbit and in GeneralSarAttitude
+    It interpolates vector-valued functions defined on a given axis
+    """
+
+    _POLYNOMIAL_ORDER = 4
+    _DATA_POINTS_PER_POLY = _POLYNOMIAL_ORDER + 1
+    _POLY_CENTER_REL_INTERVAL_INDEX = _DATA_POINTS_PER_POLY // 2
+
+    @classmethod
+    def get_min_num_of_data_points(cls):
+        """Return the minimum number of data points needed by the interpolator
+
+        :return: minimum number of data points"""
+        return cls._DATA_POINTS_PER_POLY
+
+    @classmethod
+    def get_polynomial_order(cls):
+        """Return the order of the interpolation polynomial
+
+        :return: order of the interpolation polynomial
+        """
+        return cls._POLYNOMIAL_ORDER
+
+    def __init__(self, data_axis, data):
+        """Initialize the object as interpolator of the input data defined on the specified axis
+
+        :param data_axis: the axis of length N on which the data is defined
+        :param data: data defined as MxN array of M-dimensional values (e.g. state vectors or attitude angles)
+        """
+        self._data_axis = data_axis
+        self._num_of_data_components = data.shape[0]
+        self._num_of_polynomials = self._data_axis.size - self._POLYNOMIAL_ORDER
+
+        # Matrix of polynomials
+        self._pos = np.ndarray((self._num_of_polynomials, self._num_of_data_components), dtype=np.poly1d)
+        self._vel = np.ndarray((self._num_of_polynomials, self._num_of_data_components), dtype=np.poly1d)
+        self._acc = np.ndarray((self._num_of_polynomials, self._num_of_data_components), dtype=np.poly1d)
+        # Relative azimuth axis [s]
+        relative_axis = self._data_axis.get_relative_array()
+        self._data_axis_array = self._data_axis.get_array()
+        for poly_index in range(self._num_of_polynomials):
+            # Each polynomial domain is defined by the poly_axis
+            poly_axis = relative_axis[poly_index : poly_index + self._DATA_POINTS_PER_POLY]
+
+            # Each polynomial relative axis starts at the start of the interval:
+            # P(t) = c0 + c1 * (t-poly_time_axis[0]) + ...
+            vandermonde_matrix = np.vander((poly_axis - poly_axis[0]).astype(float))
+
+            # Computation of polynomial coefficients
+            for component_index in range(self._num_of_data_components):
+                values = data[
+                    component_index,
+                    poly_index : poly_index + self._DATA_POINTS_PER_POLY,
+                ]
+                coefficients = np.linalg.solve(vandermonde_matrix, values).tolist()
+                position = np.poly1d(coefficients)
+                self._pos[poly_index, component_index] = position
+                self._vel[poly_index, component_index] = np.polyder(position, 1)
+                self._acc[poly_index, component_index] = np.polyder(position, 2)
+
+    @check_eval_function_input
+    def eval(self, interpolation_axis, interval_indexes, components_to_interpolate=None):
+        """Interpolate the data on the given interpolation axis
+
+        :param interpolation_axis: interpolation axis
+        :param interval_indexes: vector or single scalar or None. Denotes the intervals where the given interpolation
+        points are expected
+        :param components_to_interpolate: list of the components to interpolate, identified by their
+        index [optional]
+
+        :return: CxP array of interpolated values, where C is the number of interpolated components and P is the length
+        of the interpolation axis
+        """
+        return self._eval(interpolation_axis, interval_indexes, self._pos, components_to_interpolate)
+
+    @check_eval_function_input
+    def eval_first_derivative(self, interpolation_axis, interval_indexes, components_to_interpolate=None):
+        """Interpolate the first derivative of the data on the given interpolation axis
+
+        :param interpolation_axis: interpolation axis
+        :param interval_indexes: vector or single scalar or None. Denotes the interval where the given interpolation
+        points are expected
+        :param components_to_interpolate: list of the components to interpolate, identified by their index [optional]
+
+        :return: CxP array of interpolated values, where C is the number of interpolated components and P is the length
+        of the interpolation axis
+        """
+        return self._eval(interpolation_axis, interval_indexes, self._vel, components_to_interpolate)
+
+    @check_eval_function_input
+    def eval_second_derivative(self, interpolation_axis, interval_indexes, components_to_interpolate=None):
+        """Interpolate the second derivative of the data on the given interpolation axis
+
+        :param interpolation_axis: interpolation axis
+        :param interval_indexes: vector or single scalar or None. Denotes the interval where the given interpolation
+        points are expected
+        :param components_to_interpolate: list of the components to interpolate, identified by their index [optional]
+
+        :return: CxP array of interpolated values, where C is the number of interpolated components and P is the length
+        of the interpolation axis
+        """
+
+        return self._eval(interpolation_axis, interval_indexes, self._acc, components_to_interpolate)
+
+    def _eval(
+        self,
+        interpolation_axis,
+        interval_indexes,
+        polynomial,
+        components_to_interpolate=None,
+    ):
+        """Interpolate the data on the given interpolation axis by evaluating interpolation
+        polynomials (or a their modified version) on the interpolation axis
+
+        :param interpolation_axis: interpolation axis
+        :param interval_indexes: vector or single scalar or None. Denotes the interval where the given time is expected
+        :param polynomial: interpolation polynomials to evaluate
+        :param components_to_interpolate: list of the components to interpolate, identified by their index [optional]
+
+        :return: CxP array of interpolated values, where C is the number of interpolated components and P is the length
+        of the interpolation axis
+        """
+
+        if components_to_interpolate is None:
+            components_to_interpolate = range(self._num_of_data_components)
+
+        poly_indexes = self.get_polynomial_index(
+            interpolation_points=interpolation_axis, interval_indexes=interval_indexes
+        )
+
+        interpolation_results = np.zeros((len(components_to_interpolate), interpolation_axis.size))
+
+        for interpolation_point_index, (poly_index, interpolation_point) in enumerate(
+            zip(poly_indexes, interpolation_axis)
+        ):
+            interpolation_point_poly_rel = interpolation_point - self._data_axis_array[poly_index]
+
+            for out_component_index, component_index in enumerate(components_to_interpolate):
+                interpolation_results[out_component_index, interpolation_point_index] = polynomial[
+                    poly_index, component_index
+                ](interpolation_point_poly_rel)
+
+        return interpolation_results
+
+    def get_interval_index(self, interpolation_points):
+        """Get the indexes of the intervals where the interpolation_points lie
+
+        :param interpolation_points: vector of required interpolation points
+
+        :return: array of interval indexes
+        """
+        return self._data_axis.get_interval_id(interpolation_points)
+
+    def get_polynomial_index(self, interpolation_points=None, interval_indexes=None):
+        """Get the indexes of the polynomials to be used for interpolation
+
+        :param interpolation_points: vector of required interpolation points
+        :param interval_indexes: interval indexes of the interpolation points
+
+        :return: array of polynomial indexes
+
+        If interpolation points are specified, the positions on the interpolation axis are computed internally to find
+        the corresponding polynomial indexes;
+        If the interval indexes of the interpolation points on the axis are given, the polynomial indexes are computed
+        directly (ignoring the interpolation points).
+        """
+        if interval_indexes is None:
+            if interpolation_points is not None:
+                interval_indexes = self._data_axis.get_interval_id(interpolation_points)
+            else:
+                raise RuntimeError("Specify either interpolation points or interval indexes")
+        if isinstance(interval_indexes, int):
+            interval_indexes = np.asarray([interval_indexes])
+        return np.clip(
+            interval_indexes - self._POLY_CENTER_REL_INTERVAL_INDEX,
+            0,
+            self._num_of_polynomials - 1,
+        )
+
+    @property
+    def num_of_polynomials(self):
+        return self._num_of_polynomials

arepytools/geometry/anx_time.py

@@ -0,0 +1,134 @@
+# SPDX-FileCopyrightText: Aresys S.r.l. <info@aresys.it>
+# SPDX-License-Identifier: MIT
+
+"""
+ANX Time module
+---------------
+"""
+
+from __future__ import annotations
+
+import functools
+
+import numpy as np
+import scipy.optimize
+
+from arepytools.geometry.curve_protocols import TwiceDifferentiable3DCurve
+
+
+def compute_anx_times_core(
+    trajectory: TwiceDifferentiable3DCurve,
+    time_sampling_step_s: float = 1,
+    max_abs_z_error: float = 1e-3,
+    max_abs_time_error: float = 1e-6,
+    max_search_iterations: float = 100,
+) -> np.ndarray:
+    """Compute ANX times of the specified trajectory.
+
+    Parameters
+    ----------
+    trajectory : TwiceDifferentiable3DCurve
+        sensor's trajectory from which compute the ANX times
+    time_sampling_step_s : float, optional
+        sampling step in seconds for the trajectory time axis, by default 1
+    max_abs_z_error : float, optional
+        maximum absolute error on ANX z coordinate, by default 1e-3
+    max_abs_time_error : float, optional
+        maximum absolute error on ANX time, by default 1e-6
+    max_search_iterations : float, optional
+        maximum number of search iterations per ANX, by default 100
+
+    Returns
+    -------
+    np.ndarray
+        (N,) array of ANX times
+    """
+
+    time_axis_origin = trajectory.domain[0]
+    time_axis_rel = np.arange(0, trajectory.domain[1] - trajectory.domain[0], time_sampling_step_s)
+    evaluated_positions = trajectory.evaluate(time_axis_rel + time_axis_origin)
+
+    anx_time_rel_intervals = _find_anx_time_intervals(time_axis_rel=time_axis_rel, positions=evaluated_positions)
+
+    def get_z_coordinate_bisecting_func(time, origin):
+        return trajectory.evaluate(origin + time)[-1]
+
+    anx_times = []
+    for interval in anx_time_rel_intervals:
+        central_time = interval[0] + (interval[1] - interval[0]) / 2.0
+        velocity_z = trajectory.evaluate_first_derivatives(central_time + time_axis_origin)[-1]
+        x_tol = min(max_abs_time_error, max_abs_z_error / abs(velocity_z))
+
+        get_z_coordinate_bisecting_func = functools.partial(
+            get_z_coordinate_bisecting_func, origin=interval[0] + time_axis_origin
+        )
+
+        relative_interval = [t - interval[0] for t in interval]
+        anx_time_rel = scipy.optimize.bisect(
+            get_z_coordinate_bisecting_func,
+            *relative_interval,
+            xtol=x_tol,
+            maxiter=max_search_iterations,
+        )
+
+        anx_times.append(interval[0] + anx_time_rel)
+
+    return np.array(anx_times) + time_axis_origin
+
+
+def compute_relative_times(time_points: np.ndarray, anx_times: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Return the relative time since the greatest node less or equal to absolute time.
+
+    Parameters
+    ----------
+    time_points : np.ndarray
+        absolute time points, as an array of (N,)
+    anx_times : np.ndarray
+        sorted absolute anx times, as an array of (N,)
+
+    Returns
+    -------
+    tuple[np.ndarray, np.ndarray]
+        a tuple of two 1D numpy arrays of relative times and related time_nodes indices,
+        nan value and not valid index are returned when previous time node is not available
+    """
+    relative_times = np.array(
+        [(t - anx_times[anx_times <= t][-1] if len(anx_times[anx_times <= t]) > 0 else np.nan) for t in time_points]
+    )
+    anx_indices = np.array(
+        [
+            (len(anx_times[anx_times <= t]) - 1 if len(anx_times[anx_times <= t]) > 0 else len(anx_times))
+            for t in time_points
+        ]
+    ).astype(int)
+
+    return relative_times, anx_indices
+
+
+def _find_anx_time_intervals(time_axis_rel: np.ndarray, positions: np.ndarray) -> list[tuple[float, float]]:
+    """Finding ANX time intervals for the input relative time axis and the corresponding sensor's positions.
+
+    Parameters
+    ----------
+    time_axis_rel : np.ndarray
+        relative time axis, as a (N,) array of floats
+    positions : np.ndarray
+        sensor's positions corresponding to the input times, as a (N, 3) array of floats
+
+    Returns
+    -------
+    list[tuple[float, float]]
+        list of ANX time intervals as (starting time, ending time) of the interval crossing ANX
+    """
+    anx_intervals = []
+    for interval_index in range(time_axis_rel.size - 1):
+        interval_begin_index, interval_end_index = interval_index, interval_index + 2
+
+        z_start, z_stop = positions[interval_begin_index:interval_end_index, -1]
+        is_anx_interval = z_start <= 0 < z_stop
+
+        if is_anx_interval:
+            t_start, t_stop = time_axis_rel[interval_begin_index:interval_end_index]
+            anx_intervals.append((t_start, t_stop))
+
+    return anx_intervals

arepytools/geometry/attitude_utils.py

@@ -0,0 +1,88 @@
+# SPDX-FileCopyrightText: Aresys S.r.l. <info@aresys.it>
+# SPDX-License-Identifier: MIT
+
+"""
+Attitude-related utilities
+--------------------------
+"""
+
+import numpy as np
+import numpy.typing as npt
+from scipy.spatial import transform
+
+from arepytools.geometry.rotation import (
+    RotationOrderLike,
+    compute_euler_angles_from_rotation,
+    compute_rotation,
+)
+
+
+def compute_antenna_reference_frame_from_euler_angles(
+    order: RotationOrderLike,
+    initial_reference_frame_axis: np.ndarray,
+    yaw: npt.ArrayLike,
+    pitch: npt.ArrayLike,
+    roll: npt.ArrayLike,
+) -> np.ndarray:
+    """Computing the Antenna Reference Frame (ARF) from euler angles (YAW, PITCH and ROLL) giving a rotation order and
+    a reference frame.
+
+    Parameters
+    ----------
+    order : RotationOrderLike
+        rotation order for the euler angles
+    initial_reference_frame_axis : np.ndarray
+        reference frame axis of the sensor
+    yaw : npt.ArrayLike
+        sensor's yaw
+    pitch : npt.ArrayLike
+        sensor's pitch
+    roll : npt.ArrayLike
+        sensor's roll
+
+    Returns
+    -------
+    np.ndarray
+        antenna reference frame for the sensor
+    """
+
+    rotation = compute_rotation(order=order, yaw=yaw, pitch=pitch, roll=roll)
+
+    return np.matmul(initial_reference_frame_axis, rotation.as_matrix())
+
+
+def compute_euler_angles_from_antenna_reference_frame(
+    initial_reference_frame_axis: np.ndarray,
+    antenna_reference_frame: np.ndarray,
+    order: RotationOrderLike,
+) -> np.ndarray:
+    """Compute euler angles (YAW, PITCH and ROLL) from Antenna Reference Frame (ARF), the initial reference frame and
+    rotation order.
+
+    Parameters
+    ----------
+    initial_reference_frame_axis : np.ndarray
+        initial reference frame axis of the sensor, (3, 3) or (N, 3, 3)
+    antenna_reference_frame : np.ndarray
+        antenna reference frame of the sensor, (3, 3) or (N, 3, 3)
+    order : RotationOrderLike
+        rotation order
+
+    Returns
+    -------
+    np.ndarray
+        euler angles array, (N, 3), columns being in the same rotation order provided as input
+    """
+    if initial_reference_frame_axis.shape != antenna_reference_frame.shape:
+        raise RuntimeError(
+            f"input shape mismatch: init ref frame {initial_reference_frame_axis.shape} != arf "
+            + f"{antenna_reference_frame.shape}"
+        )
+    init_ref_frame = (
+        np.transpose(initial_reference_frame_axis, (0, 2, 1))
+        if initial_reference_frame_axis.ndim == 3
+        else initial_reference_frame_axis.T
+    )
+    rotation = transform.Rotation.from_matrix(np.matmul(init_ref_frame, antenna_reference_frame))
+
+    return compute_euler_angles_from_rotation(order=order, rotation=rotation)