DM-16208: Add position-dependent magnitudeToInstFlux()

include/lsst/afw/image/PhotoCalib.h

@@ -341,12 +341,19 @@ class PhotoCalib : public table::io::PersistableFacade<PhotoCalib>, public table
     MaskedImage<float> calibrateImage(MaskedImage<float> const &maskedImage) const;
 
     /**
-     * Convert AB magnitude to instFlux (ADU), using the mean instFlux/magnitude scaling factor.
+     * Convert AB magnitude to instFlux (ADU).
+     *
+     * If passed point, use the exact calculation at that point, otherwise, use the mean scaling factor.
+     *
+     * Useful for inserting fake sources into an image.
      *
      * @param[in]  magnitude  The AB magnitude to convert.
+     * @param[in]  point      The position that magnitude is to be converted at.
      *
      * @returns    Source instFlux in ADU.
      */
+    double magnitudeToInstFlux(double magnitude, lsst::geom::Point<double, 2> const &point) const;
+    /// @overload magnitudeToInstFlux(double, lsst::geom::Point<double, 2> const &) const;
     double magnitudeToInstFlux(double magnitude) const;
 
     /**

python/lsst/afw/image/photoCalib.cc

@@ -133,14 +133,19 @@ PYBIND11_MODULE(photoCalib, mod) {
                     PhotoCalib::instFluxToMagnitude,
             "sourceCatalog"_a, "instFluxField"_a, "outField"_a);
 
+    /* from magnitude. */
+    cls.def("magnitudeToInstFlux",
+            py::overload_cast<double, lsst::geom::Point<double, 2> const &>(&PhotoCalib::magnitudeToInstFlux,
+                                                                            py::const_),
+            "instFlux"_a, "point"_a);
+    cls.def("magnitudeToInstFlux", py::overload_cast<double>(&PhotoCalib::magnitudeToInstFlux, py::const_),
+            "instFlux"_a);
+
     /* utilities */
     cls.def("getCalibrationMean", &PhotoCalib::getCalibrationMean);
     cls.def("getCalibrationErr", &PhotoCalib::getCalibrationErr);
     cls.def("getInstFluxMag0", &PhotoCalib::getInstFluxMag0);
 
-    cls.def("magnitudeToInstFlux", (double (PhotoCalib::*)(double) const) & PhotoCalib::magnitudeToInstFlux,
-            "magnitude"_a);
-
     cls.def("computeScaledCalibration", &PhotoCalib::computeScaledCalibration);
     cls.def("computeScalingTo", &PhotoCalib::computeScalingTo);
 

src/image/PhotoCalib.cc

@@ -49,6 +49,8 @@ double toMaggies(double instFlux, double scale) { return instFlux * scale; }
 
 double toMagnitude(double instFlux, double scale) { return -2.5 * log10(instFlux * scale); }
 
+double fromMagnitude(double magnitude, double scale) { return pow(10, magnitude / -2.5) / scale; }
+
 double toMaggiesErr(double instFlux, double instFluxErr, double scale, double scaleErr, double maggies) {
     return maggies * hypot(instFluxErr / instFlux, scaleErr / scale);
 }
@@ -193,7 +195,11 @@ void PhotoCalib::instFluxToMagnitude(afw::table::SourceCatalog &sourceCatalog,
 // ------------------- other utility methods -------------------
 
 double PhotoCalib::magnitudeToInstFlux(double magnitude) const {
-    return pow(10, magnitude / -2.5) / _calibrationMean;
+    return fromMagnitude(magnitude, _calibrationMean);
+}
+
+double PhotoCalib::magnitudeToInstFlux(double magnitude, lsst::geom::Point<double, 2> const &point) const {
+    return fromMagnitude(magnitude, evaluate(point));
 }
 
 std::shared_ptr<math::BoundedField> PhotoCalib::computeScaledCalibration() const {

tests/test_photoCalib.py

@@ -187,6 +187,13 @@ def _testPhotoCalibCenter(self, photoCalib, calibrationErr):
         self.assertFloatsAlmostEqual(self.instFlux, photoCalib.magnitudeToInstFlux(0))
         self.assertFloatsAlmostEqual(self.instFlux*1e-9, photoCalib.magnitudeToInstFlux(22.5))
 
+        # test round-tripping
+        mag = photoCalib.instFluxToMagnitude(self.instFlux, self.pointXShift)
+        self.assertFloatsAlmostEqual(self.instFlux, photoCalib.magnitudeToInstFlux(mag, self.pointXShift))
+        mag = photoCalib.instFluxToMagnitude(self.instFlux*1e-9, self.pointXShift)
+        self.assertFloatsAlmostEqual(self.instFlux*1e-9,
+                                     photoCalib.magnitudeToInstFlux(mag, self.pointXShift))
+
     def _testSourceCatalog(self, photoCalib, catalog, expectMaggies, expectMag):
         """Test passing in a sourceCatalog."""