JP-3035: Fix computation of the photometric keywords PIXAR_* and scal…

…e resampled intensities according to actual pixel scale ratio. (#7894)

Co-authored-by: Howard Bushouse <[email protected]>

CHANGES.rst

@@ -6,6 +6,21 @@ general
 
 - Increase asdf maximum version to 4 [#8018]
 
+resample
+--------
+
+- Recognize additional keys in ASDF files that provide ``output_wcs`` for the
+  resample step. [#7894]
+
+- Set output image size when ``output_wcs`` is provided based on the largest
+  coordinates in the bounding box of the ``output_wcs``. [#7894]
+
+- Completely re-designed computation of the pixel area keywords
+  ``PIXAR_SR`` and ``PIXAR_A2`` for the resampled image. This change also
+  results in modified values in the resampled images. New computations
+  significantly reduce photometric errors. [#7894]
+
+
 1.12.5 (2023-10-19)
 ===================
 

docs/jwst/resample/arguments.rst

@@ -62,7 +62,23 @@ image.
     under the root of the file. The output image size is determined from the
     bounding box of the WCS (if any). Argument ``output_shape`` overrides
     computed image size and it is required when output WCS does not have
-    ``bounding_box`` property set.
+    ``bounding_box`` property set or if ``pixel_shape`` or ``array_shape`` keys
+    (see below) are not provided.
+
+    Additional information may be stored under
+    other keys under the root of the file. Currently, the following keys are
+    recognized:
+
+    - ``pixel_area``: Indicates average pixel area of the output WCS in
+      units of steradians. When provided, this value will be used for updating
+      photometric quantities  ``PIXAR_SR`` and ``PIXAR_A2`` of the output image.
+      If ``pixel_area`` is not provided, the code will attempt to estimate
+      this value from the WCS.
+
+    - ``pixel_shape``: dimensions of the output image in the order (nx, ny).
+      Overrides the value of ``array_shape`` if provided.
+
+    - ``array_shape``: shape of the output image in ``numpy`` order: (ny, nx).
 
     .. note::
         When ``output_wcs`` is specified, WCS-related arguments such as

jwst/model_blender/blendmeta.py

@@ -25,7 +25,7 @@
 # Primary functional interface for the code
 
 
-def blendmodels(product, inputs=None, output=None, verbose=False):
+def blendmodels(product, inputs=None, output=None, ignore=None, verbose=False):
     """
     Run main interface for blending metadata from multiple models.
 
@@ -73,6 +73,10 @@ def blendmodels(product, inputs=None, output=None, verbose=False):
         If provided, update `meta.filename` in the blended `product`
         to define what file this model will get written out to.
 
+    ignore : list of str, None, optional
+        A list of string the meta attribute names which, if provided,
+        will show which attributes should not be blended.
+
     verbose : bool, optional [Default: False]
         Print out additional messages during processing when specified.
 
@@ -122,6 +126,8 @@ def blendmodels(product, inputs=None, output=None, verbose=False):
     # Start by identifying elements of the model which need to be ignored
     ignore_list = _build_schema_ignore_list(newmeta._schema)
     ignore_list += ['meta.wcs']  # Necessary since meta.wcs is not in schema
+    if ignore:
+        ignore_list.extend(ignore)
 
     # Now assign values from new_hdrs to output_model.meta
     flat_new_metadata = newmeta.to_flat_dict()

jwst/resample/gwcs_drizzle.py

@@ -120,7 +120,7 @@ def outcon(self, value):
         self._product.con = value
 
     def add_image(self, insci, inwcs, inwht=None, xmin=0, xmax=0, ymin=0, ymax=0,
-                  expin=1.0, in_units="cps", wt_scl=1.0):
+                  expin=1.0, in_units="cps", wt_scl=1.0, iscale=1.0):
         """
         Combine an input image with the output drizzled image.
 
@@ -185,6 +185,11 @@ def add_image(self, insci, inwcs, inwht=None, xmin=0, xmax=0, ymin=0, ymax=0,
             initialized with wt_scl set to "exptime" or "expsq", the exposure time
             will be used to set the weight scaling and the value of this parameter
             will be ignored.
+
+        iscale : float, optional
+            A scale factor to be applied to pixel intensities of the
+            input image before resampling.
+
         """
         if self.wt_scl == "exptime":
             wt_scl = expin
@@ -197,7 +202,8 @@ def add_image(self, insci, inwcs, inwht=None, xmin=0, xmax=0, ymin=0, ymax=0,
         dodrizzle(insci, inwcs, inwht, self.outwcs, self.outsci, self.outwht,
                   self.outcon, expin, in_units, wt_scl, uniqid=self.uniqid,
                   xmin=xmin, xmax=xmax, ymin=ymin, ymax=ymax,
-                  pixfrac=self.pixfrac, kernel=self.kernel, fillval=self.fillval)
+                  iscale=iscale, pixfrac=self.pixfrac, kernel=self.kernel,
+                  fillval=self.fillval)
 
     def increment_id(self):
         """
@@ -227,7 +233,7 @@ def increment_id(self):
 
 def dodrizzle(insci, input_wcs, inwht, output_wcs, outsci, outwht, outcon,
               expin, in_units, wt_scl, uniqid=1, xmin=0, xmax=0, ymin=0, ymax=0,
-              pixfrac=1.0, kernel='square', fillval="INDEF"):
+              iscale=1.0, pixfrac=1.0, kernel='square', fillval="INDEF"):
     """
     Low level routine for performing 'drizzle' operation on one image.
 
@@ -303,6 +309,10 @@ def dodrizzle(insci, input_wcs, inwht, output_wcs, outsci, outwht, outcon,
         no maximum will be set in the y dimension (all pixels in a column
         of the input image will be resampled).
 
+    iscale : float, optional
+        A scale factor to be applied to pixel intensities of the
+        input image before resampling.
+
     pixfrac : float, optional
         The fraction of a pixel that the pixel flux is confined to. The
         default value of 1 has the pixel flux evenly spread across the image.
@@ -389,6 +399,7 @@ def dodrizzle(insci, input_wcs, inwht, output_wcs, outsci, outwht, outcon,
         uniqid=uniqid,
         xmin=xmin, xmax=xmax,
         ymin=ymin, ymax=ymax,
+        scale=iscale,
         pixfrac=pixfrac,
         kernel=kernel,
         in_units=in_units,