Deprecate tophat kernel. Warn about flux not being conserved with som…

…e kernels

CHANGES.rst

@@ -4,13 +4,20 @@
 Release Notes
 =============
 
-1.15.0 (unreleased)
+1.15.0 (2024-02-15)
 ===================
 
 - Dropped Python 3.8. [#128]
 
 - Fixed a bug in the pixmap coordinate inversion routine. [#137]
 
+- Deprecated "tophat" kernel which will be remover in the next release. It is
+  not working correctly and should not be used. [#140]
+
+- Added warnings that "gaussian", "lanczos2", and "lanczos3" kernels are not
+  flux conserving. [#140]
+
+
 1.14.4 (2023-11-15)
 ===================
 

drizzle/dodrizzle.py

@@ -112,8 +112,11 @@ def dodrizzle(insci, input_wcs, inwht,
     kernel: str, optional
         The name of the kernel used to combine the input. The choice of
         kernel controls the distribution of flux over the kernel. The kernel
-        names are: "square", "gaussian", "point", "tophat", "turbo", "lanczos2",
-        and "lanczos3". The square kernel is the default.
+        names are: "square", "turbo", "point", "gaussian", "lanczos2",
+        and "lanczos3".
+
+        .. warning::
+            The "gaussian" and "lanczos2/3" kernels **DO NOT** conserve flux.
 
     fillval: str, optional
         The value a pixel is set to in the output if the input image does

drizzle/drizzle.py

@@ -60,8 +60,11 @@ def __init__(self, infile="", outwcs=None,
         kernel : str, optional
             The name of the kernel used to combine the inputs. The choice of
             kernel controls the distribution of flux over the kernel. The kernel
-            names are: "square", "gaussian", "point", "tophat", "turbo", "lanczos2",
-            and "lanczos3". The square kernel is the default.
+            names are: "square", "turbo", "point", "gaussian", "lanczos2",
+            and "lanczos3".
+
+            .. warning::
+              The "gaussian" and "lanczos2/3" kernels **DO NOT** conserve flux.
 
         fillval : str, otional
             The value a pixel is set to in the output if the input image does

src/cdrizzleapi.c

@@ -84,6 +84,7 @@ tdriz(PyObject *obj UNUSED_PARAM, PyObject *args, PyObject *keywords)
   struct driz_error_t error;
   struct driz_param_t p;
   integer_t isize[2], psize[2], wsize[2];
+  char warn_msg[96];
 
   driz_log_handle = driz_log_init(driz_log_handle);
   driz_log_message("starting tdriz");
@@ -182,6 +183,22 @@ tdriz(PyObject *obj UNUSED_PARAM, PyObject *args, PyObject *keywords)
     goto _exit;
   }
 
+  if (kernel == kernel_tophat) {
+      if (sprintf(warn_msg,
+            "Kernel '%s' has been deprecated and it will be removed in a future release.",
+            kernel_str) < 1) {
+          strcpy(warn_msg, "Selected kernel has been deprecated and it will be removed in a future release.");
+      }
+      PyErr_WarnEx(PyExc_DeprecationWarning, warn_msg, 1);
+  } else if (kernel == kernel_gaussian || kernel == kernel_lanczos2 || kernel == kernel_lanczos3) {
+      if (sprintf(warn_msg,
+            "Kernel '%s' is not a flux-conserving kernel.",
+            kernel_str) < 1) {
+          strcpy(warn_msg, "Selected kernel '%s' is not a flux-conserving kernel.");
+      }
+      PyErr_WarnEx(PyExc_DeprecationWarning, warn_msg, 1);
+  }
+
   if (pfract <= 0.001){
     printf("kernel reset to POINT due to pfract being set to 0.0...\n");
     kernel_str2enum("point", &kernel, &error);