Add sar_bp PixelZIsZero and PixelZIsFixed properties (#1196)

* Add sar_bp PixelZIsZero and PixelZIsFixed properties

The PixelZIsZero and PixelZIsFixed sar_bp properties assert that the image z
locations are either identically zero or all uniformally the same value,
respectively. These properties are asserted by the user and are not verified
at run-time by the operator. Adding these properties enables additional
optimizations in the sar_bp operator by eliding computations involving the
z location or hoisting such computations out of the inner loop.

The performance benefits vary by compute type. On RTX PRO 6000, TaylorFast
and FloatFloat benefit by 3% and 10%, respectively, with PixelZIsZero.

Signed-off-by: Thomas Benson <tbenson@nvidia.com>

Author: tbensonatl

docs_input/api/signalimage/radar/sar_bp.rst

@@ -11,7 +11,10 @@ namespace as its API is subject to change.
 .. doxygenfunction:: sar_bp(const ImageType &initial_image, const RangeProfilesType &range_profiles, const PlatPosType &platform_positions, const VoxLocType &voxel_locations, const RangeToMcpType &range_to_mcp, const SarBpParams &params)
 .. doxygenenum:: matx::SarBpComputeType
 .. doxygenenum:: matx::SarBpFeature
+.. doxygenenum:: matx::SarBpPixelZMode
 .. doxygenstruct:: matx::PropSarBpTaylorFastAddThirdOrder
+.. doxygenstruct:: matx::PropSarBpPixelZIsZero
+.. doxygenstruct:: matx::PropSarBpPixelZIsFixed
 .. doxygenstruct:: matx::SarBpParams
    :members:
 
@@ -366,6 +369,35 @@ a thread block, the third-order term becomes more important. The third-order
 property uses a separate kernel instantiation, which avoids a run-time order
 dispatch inside the backprojection kernel.
 
+Pixel Height (Z) Assumptions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SAR images are frequently formed on a flat focal plane, so every output pixel
+shares the same height (z) coordinate -- very often ``z = 0`` (a ground plane at
+the reference height). When that holds, the per-pulse, per-pixel range
+computation carries a redundant pixel-z term that can be elided. MatX exposes
+this as two opt-in, compile-time properties:
+
+- ``PropSarBpPixelZIsZero`` asserts that every pixel has ``z = 0``. The kernel
+  drops the pixel-z term from the per-pulse range computation.
+- ``PropSarBpPixelZIsFixed`` asserts that every pixel shares one (arbitrary,
+  possibly non-zero) z value. On the shared-cache compute paths the uniform
+  per-pulse z contribution is hoisted out of the per-pixel inner loop.
+
+Both are *compile-time assumptions that are not validated at run time*; set one
+only when it actually holds for the supplied ``voxel_locations``. With neither
+property set (the default), each pixel may have a distinct z coordinate, which is
+the correct choice for terrain- or DEM-based focusing. If both are set,
+``PropSarBpPixelZIsZero`` (the stronger assumption) takes precedence. Callers who
+set neither are unaffected: the default kernel is unchanged, and only the
+variants you opt into are additionally instantiated.
+
+Whether ``z`` is literally ``0``/constant depends on the coordinate frame of
+``voxel_locations``. A flat focal plane expressed in a scene-local East-North-Up
+frame (height along z) satisfies these assumptions, whereas a grid expressed in
+ECEF generally does not, since even a flat plane then has all three coordinates
+varying per pixel.
+
 Examples
 ~~~~~~~~
 
@@ -387,3 +419,19 @@ third-order term to a ``TaylorFast`` launch:
 
 The property only affects ``SarBpComputeType::TaylorFast``. Other compute types
 continue to use their ordinary kernel instantiations.
+
+When the image is formed on the ``z = 0`` plane, the ``PropSarBpPixelZIsZero``
+property lets the kernel skip the pixel-z term in the per-pulse range
+computation. Like ``PropSarBpTaylorFastAddThirdOrder``, it is a compile-time
+property applied to the operator, independent of the compute type selected
+through ``SarBpParams``:
+
+.. literalinclude:: ../../../../test/00_transform/SarBp.cu
+   :language: cpp
+   :start-after: example-begin sar-bp-3
+   :end-before: example-end sar-bp-3
+   :dedent:
+
+``PropSarBpPixelZIsFixed`` is the analogous property for a constant, non-zero
+focal-plane height. These assumptions are not validated at run time, so set them
+only when the supplied voxel z coordinates actually satisfy them.

examples/sarbp/sarbp.cu

@@ -227,6 +227,7 @@ struct BpRunCtx {
   bool is_int16_mode;
   bool apply_window;
   bool taylor_fast_add_third_order;
+  SarBpPixelZMode pixel_z_mode;  // compile-time pixel-z assumption to apply
   int sgn;
   bool do_warmup;
   std::string output_file;
@@ -319,10 +320,25 @@ static int run_bp_device(PosTensor blk_positions, RtmTensor blk_rtm,
         auto cur_voxel_locations = matx::slice(voxel_locations, {y0, x0}, {y1, x1});
         auto bp = matx::experimental::sar_bp(
             cur_image, cur_profiles, cur_positions, cur_voxel_locations, cur_rtm, ctx.params);
+        // Cross product of the optional TaylorFast third-order term and the
+        // compile-time pixel-z assumption (variable / zero / fixed).
+        auto run_with_z = [&](auto bp_props) {
+          switch (ctx.pixel_z_mode) {
+            case SarBpPixelZMode::Zero:
+              (cur_image = bp_props.template props<matx::PropSarBpPixelZIsZero>()).run(ctx.exec);
+              break;
+            case SarBpPixelZMode::Fixed:
+              (cur_image = bp_props.template props<matx::PropSarBpPixelZIsFixed>()).run(ctx.exec);
+              break;
+            case SarBpPixelZMode::Variable:
+              (cur_image = bp_props).run(ctx.exec);
+              break;
+          }
+        };
         if (ctx.taylor_fast_add_third_order) {
-          (cur_image = bp.template props<matx::PropSarBpTaylorFastAddThirdOrder>()).run(ctx.exec);
+          run_with_z(bp.template props<matx::PropSarBpTaylorFastAddThirdOrder>());
         } else {
-          (cur_image = bp).run(ctx.exec);
+          run_with_z(bp);
         }
       }
     }
@@ -684,6 +700,7 @@ int main(int argc, char **argv) {
         << "                          Add the third-order term for --precision taylor_fast\n"
         << "  --warmup               Warmup GPU kernels and FFT plans before timed run\n"
         << "  --precision <type>     Compute precision: double, float, fltflt, mixed, taylor_fast (default: mixed)\n"
+        << "  --pixel-z <mode>       Compile-time pixel-z assumption: variable, zero, fixed (default: variable)\n"
         << "  -h, --help             Print this help message and exit\n";
   };
 
@@ -701,6 +718,8 @@ int main(int argc, char **argv) {
   bool do_warmup = false;
   bool taylor_fast_add_third_order = false;
   std::string precision_type = "mixed";
+  std::string pixel_z_arg = "variable";
+  SarBpPixelZMode pixel_z_mode = SarBpPixelZMode::Variable;
 
   auto needs_value = [&](int i) -> bool {
     if (i + 1 >= argc) {
@@ -742,6 +761,9 @@ int main(int argc, char **argv) {
     } else if (std::strcmp(argv[i], "--precision") == 0) {
       if (!needs_value(i)) return 1;
       precision_type = argv[++i];
+    } else if (std::strcmp(argv[i], "--pixel-z") == 0) {
+      if (!needs_value(i)) return 1;
+      pixel_z_arg = argv[++i];
     } else if (argv[i][0] == '-') {
       std::cerr << "ERROR: unknown option '" << argv[i] << "'" << std::endl;
       print_usage();
@@ -782,6 +804,19 @@ int main(int argc, char **argv) {
     return 1;
   }
 
+  if (pixel_z_arg == "variable") {
+    pixel_z_mode = SarBpPixelZMode::Variable;
+  } else if (pixel_z_arg == "zero") {
+    pixel_z_mode = SarBpPixelZMode::Zero;
+  } else if (pixel_z_arg == "fixed") {
+    pixel_z_mode = SarBpPixelZMode::Fixed;
+  } else {
+    std::cerr << "ERROR: invalid --pixel-z '" << pixel_z_arg
+              << "' (use variable, zero, or fixed)" << std::endl;
+    print_usage();
+    return 1;
+  }
+
   // -------------------------------------------------------------------
   // Read .sarbp file header
   // -------------------------------------------------------------------
@@ -1110,6 +1145,7 @@ int main(int argc, char **argv) {
       .is_int16_mode         = is_int16_mode,
       .apply_window          = apply_window,
       .taylor_fast_add_third_order = taylor_fast_add_third_order,
+      .pixel_z_mode          = pixel_z_mode,
       .sgn                   = sgn,
       .do_warmup             = do_warmup,
       .output_file           = output_file,