Merge pull request isce-framework#1 from isce-3/develop

sync test

.ci/jenkins/workflow-mintests/Jenkinsfile

@@ -129,13 +129,27 @@ pipeline {
       echo 'I succeeded!'
     }
     unstable {
-      echo 'I am unstable :/'
+      echo 'I am unstable :/ Emailing PR author and one of the ISCE3 maintainers.'
+      emailStatus()      
     }
     failure {
-      echo 'I failed :('
+      echo 'I failed :( Emailing PR author and one of the ISCE3 maintainers.'
+      emailStatus()
     }
     changed {
       echo 'Things were different before...'
     }
   }
 }
+
+def emailStatus() {
+      mail to: '[email protected]',
+          subject: "ISCE3 build ${currentBuild.result}: ${currentBuild.fullDisplayName}",
+          body: "Minimum workflow test ${currentBuild.result}: ${env.BUILD_URL}" 
+      emailext(
+          subject: "ISCE3 build ${currentBuild.result}: ${currentBuild.fullDisplayName}",
+          body: "Minimum workflow test ${currentBuild.result}: ${env.BUILD_URL}",
+          recipientProviders: [[$class: 'DevelopersRecipientProvider']]
+      )
+}
+

VERSION.txt

@@ -1 +1 @@
-0.3.0-dev
+0.4.0-dev

cxx/isce3/Headers.cmake

@@ -1,5 +1,8 @@
 set(HEADERS
+antenna/detail/WinChirpRgCompPow.h
+antenna/detail/WinChirpRgCompPow.icc
 antenna/forward.h
+antenna/ElPatternEst.h
 antenna/geometryfunc.h
 antenna/Frame.h
 antenna/Frame.icc
@@ -133,8 +136,10 @@ matchtemplate/ampcor/dom/SLC.h
 matchtemplate/ampcor/dom/SLC.icc
 math/Bessel.h
 math/ComplexMultiply.h
+math/polyfunc.h
 math/Sinc.h
 math/Sinc.icc
+polsar/symmetrize.h
 product/forward.h
 product/GeoGridParameters.h
 product/Metadata.h

cxx/isce3/Sources.cmake

@@ -1,4 +1,5 @@
 set(SRCS
+antenna/ElPatternEst.cpp
 antenna/geometryfunc.cpp
 core/Attitude.cpp
 core/Baseline.cpp
@@ -47,6 +48,7 @@ geocode/GeocodePolygon.cpp
 geometry/geometry.cpp
 geometry/RTC.cpp
 geometry/Topo.cpp
+geometry/TopoLayers.cpp
 geometry/metadataCubes.cpp
 image/ResampSlc.cpp
 io/gdal/Dataset.cpp
@@ -70,6 +72,8 @@ matchtemplate/ampcor/correlators/tgtStats.cpp
 matchtemplate/ampcor/dom/Raster.cc
 matchtemplate/ampcor/dom/SLC.cc
 math/Bessel.cpp
+math/polyfunc.cpp
+polsar/symmetrize.cpp
 product/GeoGridParameters.cpp
 product/Product.cpp
 product/RadarGridParameters.cpp

cxx/isce3/antenna/ElPatternEst.cpp

@@ -0,0 +1,108 @@
+#include "ElPatternEst.h"
+
+#include <cmath>
+
+#include <isce3/core/Constants.h>
+#include <isce3/except/Error.h>
+#include <isce3/geometry/geometry.h>
+#include <isce3/math/polyfunc.h>
+
+#include "detail/WinChirpRgCompPow.h"
+
+namespace isce3 { namespace antenna {
+
+ElPatternEst::ElPatternEst(double sr_start, const isce3::core::Orbit& orbit,
+        int polyfit_deg, const isce3::geometry::DEMInterpolator& dem_interp,
+        double win_ped, const isce3::core::Ellipsoid& ellips,
+        bool center_scale_pf)
+    : _sr_start(sr_start), _orbit(orbit), _polyfit_deg(polyfit_deg),
+      _dem_interp(dem_interp), _win_ped(win_ped), _ellips(ellips),
+      _center_scale_pf(center_scale_pf)
+{
+    if (!(sr_start > 0.0))
+        throw isce3::except::InvalidArgument(ISCE_SRCINFO(),
+                "Requires positive value for starting slant range!");
+    if (polyfit_deg < 2)
+        throw isce3::except::InvalidArgument(
+                ISCE_SRCINFO(), "The degree of poly fit shall be at least 2!");
+    if (win_ped < 0.0 || win_ped > 1.0)
+        throw isce3::except::InvalidArgument(ISCE_SRCINFO(),
+                "The raised-cosine window pedestal shall be within [0, 1]!");
+}
+
+typename ElPatternEst::tuple5_t ElPatternEst::powerPattern2way(
+        const Eigen::Ref<const RowMatrixXcf>& echo_mat, double sr_spacing,
+        double chirp_rate, double chirp_dur, std::optional<double> az_time,
+        int size_avg, bool inc_corr)
+{
+    // get calibrated avreaged two-way power pattern
+    auto [cal_pow, slant_range, look_ang, inc_ang] =
+            _getCalibPowLinear(echo_mat, sr_spacing, chirp_rate, chirp_dur,
+                    az_time, size_avg, inc_corr);
+    // convert to dB
+    cal_pow = 10 * Eigen::log10(cal_pow);
+    // polyfit pow in dB as a function of look angles in rad with centering and
+    // scaling!
+    auto poly1d_obj = isce3::math::polyfitObj(
+            look_ang, cal_pow, _polyfit_deg, _center_scale_pf);
+    // return time-series power in dB scale
+    return {cal_pow, slant_range, look_ang, inc_ang, poly1d_obj};
+}
+
+typename ElPatternEst::tuple5_t ElPatternEst::powerPattern1way(
+        const Eigen::Ref<const RowMatrixXcf>& echo_mat, double sr_spacing,
+        double chirp_rate, double chirp_dur, std::optional<double> az_time,
+        int size_avg, bool inc_corr)
+{
+    // get calibrated avreaged one-way power pattern
+    auto [cal_pow, slant_range, look_ang, inc_ang] =
+            _getCalibPowLinear(echo_mat, sr_spacing, chirp_rate, chirp_dur,
+                    az_time, size_avg, inc_corr);
+    // convert sqrt value to dB
+    cal_pow = 5 * Eigen::log10(cal_pow);
+    // polyfit pow in dB as a function of look angles in rad with centering and
+    // scaling!
+    auto poly1d_obj = isce3::math::polyfitObj(
+            look_ang, cal_pow, _polyfit_deg, _center_scale_pf);
+    // return time-series power in dB scale
+    return {cal_pow, slant_range, look_ang, inc_ang, poly1d_obj};
+}
+
+typename ElPatternEst::tuple4_t ElPatternEst::_getCalibPowLinear(
+        const Eigen::Ref<const RowMatrixXcf>& echo_mat, double sr_spacing,
+        double chirp_rate, double chirp_dur, std::optional<double> az_time,
+        int size_avg, bool inc_corr)
+
+{
+    // get range sampling frequency
+    const double sample_freq {isce3::core::speed_of_light / (2 * sr_spacing)};
+    // form the reference weighted unit-energy complex chirp
+    auto chirp_ref = detail::genRcosWinChirp(
+            sample_freq, chirp_rate, chirp_dur, _win_ped);
+    // calculate the mean echo power by averaging over multiple range compressed
+    // range lines
+    auto mean_echo_pow = detail::meanRgCompEchoPower(echo_mat, chirp_ref);
+    // perform averaging over multiple range bins and partially perform relative
+    // radiometric cal by compensating for 2-way range path loss
+    auto [cal_avg_pow, sr] = detail::rangeCalibAvgEchoPower(
+            mean_echo_pow, _sr_start, sr_spacing, size_avg);
+    // estimate look angle and incidence angles per geometry/orbit at az_time
+    auto [look_ang, inc_ang] = isce3::geometry::lookIncAngFromSlantRange(
+            sr, _orbit, az_time, _dem_interp, _ellips);
+    // as part of relative radiometric cal ,perform incidence angle correction
+    // if requested
+    if (inc_corr) {
+        cal_avg_pow *= Eigen::tan(inc_ang);
+        if (inc_ang(0) > 0.0)
+            cal_avg_pow /= std::tan(inc_ang(0));
+    }
+    // peak normalize to get relative variation
+    auto peak_pow {cal_avg_pow.maxCoeff()};
+    if (peak_pow > 0.0)
+        cal_avg_pow /= peak_pow;
+    auto slant_range = Linspace_t(
+            sr(0), sr_spacing * size_avg, static_cast<int>(sr.size()));
+    return {cal_avg_pow, slant_range, look_ang, inc_ang};
+}
+
+}} // namespace isce3::antenna

cxx/isce3/antenna/ElPatternEst.h

@@ -0,0 +1,202 @@
+#pragma once
+
+#include <tuple>
+#include <vector>
+
+#include <Eigen/Dense>
+
+#include <isce3/core/EMatrix.h>
+#include <isce3/core/Ellipsoid.h>
+#include <isce3/core/Linspace.h>
+#include <isce3/core/Orbit.h>
+#include <isce3/core/Poly1d.h>
+#include <isce3/geometry/DEMInterpolator.h>
+
+namespace isce3 { namespace antenna {
+
+/**
+ * A class for estimating one-way or two-way elevation (EL) power
+ * pattern from 2-D raw echo data over quasi-homogenous scene
+ * and provide approximate look (off-nadir or EL) angle  and
+ * ellipsoidal incidence angle (no local slope).
+ * The final power in dB scale is fit into N-order polynomials
+ * as a function of look angle in radians.
+ * Required relative radiometric calibration from \f$\beta^{0}\f$ to
+ * \f$\gamma^{0}\f$ is done approximately by using slant ranges and
+ * ellipsoidal incidence angle.
+ */
+class ElPatternEst {
+    // aliases
+public:
+    using RowMatrixXcf = isce3::core::EMatrix2D<std::complex<float>>;
+
+protected:
+    using Linspace_t = isce3::core::Linspace<double>;
+    using tuple4_t = std::tuple<Eigen::ArrayXd, isce3::core::Linspace<double>,
+            Eigen::ArrayXd, Eigen::ArrayXd>;
+    using tuple5_t = std::tuple<Eigen::ArrayXd, isce3::core::Linspace<double>,
+            Eigen::ArrayXd, Eigen::ArrayXd, isce3::core::Poly1d>;
+
+public:
+    // constructors
+    /**
+     * A constructor with full input arguments.
+     * @param[in] sr_start start slant range in (m)
+     * @param[in] orbit isce3 Orbit object
+     * @param[in] polyfit_deg (optional) polyfit degree of polynomial
+     * for polyfitting estimated power patterns. The value must be > 1.
+     * Default is 6.
+     * @pram[in] dem_interp (optional) isce3 DEMInterpolator object.
+     * Default is global 0.0 (m) height (reference ellipsoid).
+     * Note that simply averaged DEM will be used. No local slope is taken into
+     * account!
+     * @param[in] win_ped (optional) Raised-cosine window pedestal. A value
+     * within [0, 1]. Default is Hann
+     * window.https://en.wikipedia.org/wiki/Hann_function <a
+     * href="https://en.wikipedia.org/wiki/Hann_function" target="_blank">See
+     * raised cosine window</a>.
+     * @param[in] ellips (optional) isce3 Ellipsoid object. Default is WGS84.
+     * @param[in] center_scale_pf (optional) whether or not use center and
+     * scaling in polyfit. Default is false.
+     * @exception InvalidArgument
+     */
+    ElPatternEst(double sr_start, const isce3::core::Orbit& orbit,
+            int polyfit_deg = 6,
+            const isce3::geometry::DEMInterpolator& dem_interp = {},
+            double win_ped = 0.0, const isce3::core::Ellipsoid& ellips = {},
+            bool center_scale_pf = false);
+
+    /**
+     * A more concise constructor of key inputs.
+     * @param[in] sr_start  start slant range in (m)
+     * @param[in] orbit  isce3 Orbit object
+     * @param[in] dem_interp  isce3 DEMInterpolator object.
+     * @exception InvalidArgument
+     */
+    ElPatternEst(double sr_start, const isce3::core::Orbit& orbit,
+            const isce3::geometry::DEMInterpolator& dem_interp)
+        : ElPatternEst(sr_start, orbit, 6, dem_interp, 0.0,
+                  isce3::core::Ellipsoid(), false)
+    {}
+
+    // methods
+    /**
+     * Estimated averaged two-way time-series power pattern in Elevation from
+     * 2-D raw echo data uniformly sampled in slant range direction. Uniform
+     * sampling in azimuth direction is not required! Note that it is assumed
+     * the data either has no TX gap (bad values) or its TX gap (bad values)
+     * have been already replaced by meaningful data.
+     * @param[in] echo_mat raw echo matrix, a row-major Eigen matrix of type
+     * complex float. The rows represent range lines. The matrix shape is pulses
+     * (azimuth bins) by range bins.
+     * @param[in] sr_spacing slant range spacing in (m).
+     * @param[in] chirp_rate transmit chirp rate in (Hz/sec).
+     * @param[in] chirp_dur transmit chirp duration in (sec).
+     * @param[in] az_time (optional) relative azimuth time in seconds w.r.t
+     * reference epoch time of orbit object. Default is the mid orbit time if
+     * not specified or if set to {} or std::nullopt.
+     * @param[in] size_avg (optional) the block size for averaging in slant
+     * range direction. Default is 8.
+     * @param[in] inc_corr (optional) whether or not apply correction for
+     * incidence angles calculated at a certain mean DEM height wrt reference
+     * ellipsoid w/o taking into account any local slope! Default is true.
+     * @return eigen vector of times-series range-averaged peak-normalized
+     * 2-way power pattern in (dB) which is uniformly sampled in slant range
+     * with new range spacing defined by "sr_spacing * size_avg".
+     * @return slant ranges in meters in the form of isce3 Linspace object
+     * @return look angles vector in radians.
+     * @return ellipsoidal incidence angles vector in radians.
+     * @return isce3 Poly1d object mapping power in dB as a function
+     * look angle in radians
+     * @exception InvalidArgument, RuntimeError
+     * @see powerPattern1way()
+     */
+    tuple5_t powerPattern2way(const Eigen::Ref<const RowMatrixXcf>& echo_mat,
+            double sr_spacing, double chirp_rate, double chirp_dur,
+            std::optional<double> az_time = {}, int size_avg = 8,
+            bool inc_corr = true);
+
+    /**
+     * Estimated averaged one-way time-series power pattern in Elevation from
+     * 2-D raw echo data uniformly sampled in slant range direction. Uniform
+     * sampling in azimuth direction is not required! Note that  it is assumed
+     * the data either has no TX gap (bad values) or its TX gap (bad values)
+     * have been already replaced by meaningful data.
+     * @param[in]  echo_mat raw echo matrix, a row-major Eigen matrix of type
+     * complex float. The rows represent range lines. The matrix shape is pulses
+     * (azimuth bins) by range bins.
+     * @param[in] sr_spacing slant range spacing in (m).
+     * @param[in] chirp_rate transmit chirp rate in (Hz/sec).
+     * @param[in] chirp_dur transmit chirp duration in (sec).
+     * @param[in] az_time (optional) relative azimuth time in seconds w.r.t
+     * reference epoch time of orbit object. Default is the mid orbit time if
+     * not specified or if set to {} or std::nullopt.
+     * @param[in] size_avg (optional) the block size for averaging in slant
+     * range direction. Default is 8.
+     * @param[in] inc_corr (optional) whether or not apply correction for
+     * incidence angles calculated at a certain mean DEM height wrt reference
+     * ellipsoid w/o taking into account any local slope! Default is true.
+     * @return eigen vector of times-series range-averaged peak-normalized
+     * 1-way power pattern in (dB) which is uniformly sampled in slant range
+     * with new range spacing defined by "sr_spacing * size_avg".
+     * @return slant ranges in meters in the form of isce3 Linspace object
+     * @return look angles vector in radians.
+     * @return ellipsoidal incidence angles vector in radians.
+     * @return isce3 Poly1d object mapping power in dB as a function
+     * look angle in radians
+     * @exception InvalidArgument, RuntimeError
+     * @see powerPattern2way()
+     */
+    tuple5_t powerPattern1way(const Eigen::Ref<const RowMatrixXcf>& echo_mat,
+            double sr_spacing, double chirp_rate, double chirp_dur,
+            std::optional<double> az_time = {}, int size_avg = 8,
+            bool inc_corr = true);
+
+    /**
+     * Get raised-cosine window pedestal set at the constructor.
+     * @return window pedestal used for weighting ref chirp in
+     * range compression.
+     */
+    double winPed() const { return _win_ped; }
+
+    /**
+     * Get degree of polyfit set at the constructor.
+     * @return degree of polyfit used for 1-way or 2-way power pattern (dB)
+     * as a function of look angles (rad).
+     */
+    int polyfitDeg() const { return _polyfit_deg; }
+
+    /**
+     * Check whether the polyfit process is centeralized and scaled.
+     * @return bool
+     */
+    bool isCenterScalePolyfit() const { return _center_scale_pf; }
+
+private:
+    /**
+     * Helper method for public methods "powPat1w" and "powPat2w"
+     * @return peak-normalized calibrated averaged 2-way power pattern vector
+     * in linear scale
+     * @return slant ranges in meters in the form of isce3 Linspace object
+     * @return look angles vector in radians.
+     * @return ellipsoidal incidence angles vector in radians.
+     * look angle in radians
+     * @see powerPattern2way(), powerPattern1way()
+     */
+    tuple4_t _getCalibPowLinear(const Eigen::Ref<const RowMatrixXcf>& echo_mat,
+            double sr_spacing, double chirp_rate, double chirp_dur,
+            std::optional<double> az_time, int size_avg, bool inc_corr);
+
+    // members
+protected:
+    // input common parameters
+    double _sr_start;
+    isce3::core::Orbit _orbit;
+    double _polyfit_deg;
+    isce3::geometry::DEMInterpolator _dem_interp;
+    double _win_ped;
+    isce3::core::Ellipsoid _ellips;
+    bool _center_scale_pf;
+};
+
+}} // namespace isce3::antenna