Merge branch 'main' into raw_image_fix

dirac-institute · Oct 20, 2023 · 1d2c968 · 1d2c968
2 parents d1c153a + 95f0cc2
commit 1d2c968
Show file tree

Hide file tree

Showing 4 changed files with 241 additions and 28 deletions.
diff --git a/src/kbmod/search/pydocs/image_stack_docs.h b/src/kbmod/search/pydocs/image_stack_docs.h
@@ -3,11 +3,11 @@
 
 namespace pydocs {
   static const auto DOC_ImageStack = R"doc(
-  todo
+  A class for storing a list of LayeredImages at different times.
   )doc";
 
   static const auto DOC_ImageStack_get_images = R"doc(
-  todo
+  Returns a reference to the vector of images.
   )doc";
 
   static const auto DOC_ImageStack_img_count = R"doc(
@@ -33,47 +33,91 @@ namespace pydocs {
   ")doc";
 
   static const auto DOC_ImageStack_apply_mask_flags = R"doc(
-  todo
+  Applies a mask to each image by comparing the given bit vector with the
+  values in the mask layer and marking pixels NO_DATA. Modifies the image in-place.
+
+  Parameters
+  ----------
+  flag : `int`
+      The bit mask of mask flags to use.
+  exceptions : `list` of `int`
+      A list of exceptions (combinations of bits where we do not apply the mask).
   )doc";
 
   static const auto DOC_ImageStack_apply_mask_threshold = R"doc(
-  todo
+  Applies a threshold mask to each image by setting pixel values over
+  a given threshold to NO_DATA. Modifies the images in-place.
+
+  Parameters
+  ----------
+  thresh : `float`
+      The threshold value to use.
   )doc";
 
   static const auto DOC_ImageStack_apply_global_mask = R"doc(
-  todo
+  Createas a global mask an applies it to each image. A global mask
+  masks a pixel if and only if that pixel is masked in at least ``threshold``
+  individual images.  Modifies the images in-place and creates the global mask.
+
+  Parameters
+  ----------
+  flag : `int`
+      The bit mask of mask flags to use.
+  threshold : `int`
+      The minimum number of images in which a pixel must be masked to be
+      part of the global mask.
   )doc";
 
   static const auto DOC_ImageStack_grow_mask = R"doc(
-  todo
+  Expands the NO_DATA tags to nearby pixels for all images.
+  Modifies the images in-place.
+
+  Parameters
+  ----------
+  steps : `int`
+     The number of pixels by which to grow the masked regions.
   )doc";
 
   static const auto DOC_ImageStack_save_global_mask = R"doc(
-  todo
+  Saves the global mask created by apply_global_mask to a FITS file.
+
+  Parameters
+  ----------
+  path : `str`
+      The directory in which to store the global mask file.
   )doc";
 
   static const auto DOC_ImageStack_save_images = R"doc(
-  todo
+  Saves each image in the stack to its own FITS file.
+
+  Saves the file as {path}/{filename}.fits where the path is given
+  and the file name is an object attribute.
+
+  Parameters
+  ----------
+  path : `str`
+      The file path to use. 
   )doc";
 
   static const auto DOC_ImageStack_get_global_mask = R"doc(
-  todo
+  Returns a reference to the global mask created by apply_global_mask.
   )doc";
 
   static const auto DOC_ImageStack_convolve_psf = R"doc(
-  todo
+  Convolves each image (science and variance layers) with the PSF
+  stored in the LayeredImage object.
   )doc";
 
   static const auto DOC_ImageStack_get_width = R"doc(
-  todo
+  Returns the width of the images in pixels.
   )doc";
 
   static const auto DOC_ImageStack_get_height = R"doc(
-  todo
+  Returns the height of the images in pixels.
   )doc";
 
   static const auto DOC_ImageStack_get_npixels = R"doc(
-  todo
+  Returns the number of pixels per image.
   )doc";
 
 } /* pydocs */

diff --git a/src/kbmod/search/pydocs/layered_image_docs.h b/src/kbmod/search/pydocs/layered_image_docs.h
@@ -55,20 +55,44 @@ namespace pydocs {
   Returns the PSF object.
   )doc";
 
-  static const auto DOC_LayeredImage_apply_mask_flags = R"doc(
-  No idea
+  static const auto DOC_LayeredImage_apply_mask_flags  = R"doc(
+  Applies a mask to each image by comparing the given bit vector with the
+  values in the mask layer and marking pixels NO_DATA. 
+  Modifies the science and variance layers in-place.
+
+  Parameters
+  ----------
+  flag : `int`
+      The bit mask of mask flags to use.
+  exceptions : `list` of `int`
+      A list of exceptions (combinations of bits where we do not apply the mask).
   )doc";
 
   static const auto DOC_LayeredImage_apply_mask_threshold = R"doc(
-  No idea
+  Applies a threshold mask by setting pixel values over a given threshold
+  to NO_DATA. Modifies the science and variance layers in-place.
+
+  Parameters
+  ----------
+  thresh : `float`
+      The threshold value to use.
   )doc";
 
   static const auto DOC_LayeredImage_sub_template = R"doc(
   Subtract given image template
   )doc";
 
   static const auto DOC_LayeredImage_save_layers = R"doc(
-  Save image?
+  Saves the LayeredImage to a FITS file with layers for the science,
+  mask, and variance.
+
+  Saves the file as {path}/{filename}.fits where the path is given
+  and the file name is an object attribute.
+
+  Parameters
+  ----------
+  path : `str`
+      The file path to use. 
   )doc";
 
   static const auto DOC_LayeredImage_get_science = R"doc(
@@ -96,15 +120,28 @@ namespace pydocs {
   )doc";
 
   static const auto DOC_LayeredImage_convolve_psf = R"doc(
-  todo
+  Convolves the PSF stored within the LayeredImage with the science and variance
+  layers (uses the PSF-squared for the variance). Modifies the layers in place.
   )doc";
 
   static const auto DOC_LayeredImage_convolve_given_psf = R"doc(
-  todo
+  Convolves a given PSF with the science and variance layers
+  (uses the PSF-squared for the variance). Modifies the layers in place.
+
+  Parameters
+  ----------
+  psf : `PSF`
+      The PSF to use.
   )doc";
 
   static const auto DOC_LayeredImage_grow_mask = R"doc(
-  todo
+  Expands the NO_DATA tags to nearby pixels in the science and variance layers.
+  Modifies the images in-place.
+
+  Parameters
+  ----------
+  steps : `int`
+     The number of pixels by which to grow the masked regions.
   )doc";
 
   static const auto DOC_LayeredImage_get_name = R"doc(

diff --git a/src/kbmod/search/pydocs/raw_image_docs.h b/src/kbmod/search/pydocs/raw_image_docs.h
@@ -51,7 +51,26 @@ namespace pydocs{
   )doc";
 
   static const auto DOC_RawImage_create_stamp = R"doc(
-  Create stamp.
+  Create an image stamp around a given region.
+
+  Parameters
+  ----------
+  x : `float`
+      The x value of the center of the stamp.
+  y : `float`
+      The y value of the center of the stamp.
+  radius : `int`
+      The stamp radius. Width = 2*radius+1.
+  interpolate : `bool`
+      A Boolean indicating whether to interpolate pixel values.
+  keep_no_data : `bool`
+      A Boolean indicating whether to preserve NO_DATA tags or to
+      replace them with 0.0.
+  
+  Returns
+  -------
+  `RawImage`
+      The stamp.
   )doc";
 
   static const auto DOC_RawImage_set_pixel = R"doc(
@@ -68,11 +87,26 @@ namespace pydocs{
   )doc";
 
   static const auto DOC_RawImage_apply_mask = R"doc(
-  applies mask
+  Applies a mask to the RawImage by comparing the given bit vector with the
+  values in the mask layer and marking pixels NO_DATA. Modifies the image in-place.
+
+  Parameters
+  ----------
+  flag : `int`
+      The bit mask of mask flags to use.
+  exceptions : `list` of `int`
+      A list of exceptions (combinations of bits where we do not apply the mask).
+  mask : `RawImage`
+      The image of pixel mask values.
   )doc";
 
   static const auto DOC_RawImage_grow_mask = R"doc(
-  grows mask
+  Expands the NO_DATA tags to nearby pixels. Modifies the image in-place.
+
+  Parameters
+  ----------
+  steps : `int`
+     The number of pixels by which to grow the masked regions.
   )doc";
 
   static const auto DOC_RawImage_pixel_has_data = R"doc(

diff --git a/src/kbmod/search/pydocs/stamp_creator_docs.h b/src/kbmod/search/pydocs/stamp_creator_docs.h
@@ -3,23 +3,121 @@
 
 namespace pydocs {
   static const auto DOC_StampCreator = R"doc(
-  todo
+  A class for creating a set of stamps or a co-added stamp
+  from an ImageStack and Trajectory.
+  )doc";
+
+  static const auto DOC_StampCreator_create_stamps = R"doc(
+  Create a vector of stamps centered on the predicted position
+  of an Trajectory at different times.
+
+  Parameters
+  ----------
+  stack : `ImageStack`
+      The stack of images to use.
+  trj : `Trajectory`
+      The trajectory to project to each time.
+  radius : `int`
+      The stamp radius. Width = 2*radius+1.
+  interpolate : `bool`
+      A Boolean indicating whether to interpolate pixel values.
+  keep_no_data : `bool`
+      A Boolean indicating whether to preserve NO_DATA tags or to
+      replace them with 0.0.
+  use_index : `list` of `bool`
+      A list (vector) of Booleans indicating whether or not to use each time step.
+      An empty (size=0) vector will use all time steps.
+  
+  Returns
+  -------
+  `std::vector<RawImage>`
+      The stamps.
   )doc";
 
   static const auto DOC_StampCreator_get_stamps = R"doc(
-  todo
+  Create a vector of stamps centered on the predicted position
+  of an Trajectory at different times. Replaces NO_DATA with 0.0
+  and returns stamps for all time steps.
+
+  Parameters
+  ----------
+  stack : `ImageStack`
+      The stack of images to use.
+  trj : `Trajectory`
+      The trajectory to project to each time.
+  radius : `int`
+      The stamp radius. Width = 2*radius+1.
+  
+  Returns
+  -------
+  `list` of `RawImage`
+      The stamps.
   )doc";
 
   static const auto DOC_StampCreator_get_median_stamp = R"doc(
-  todo
+  Create the median co-added stamp centered on the predicted position
+  of an Trajectory at different times. Preserves NO_DATA tag.
+
+  Parameters
+  ----------
+  stack : `ImageStack`
+      The stack of images to use.
+  trj : `Trajectory`
+      The trajectory to project to each time.
+  radius : `int`
+      The stamp radius. Width = 2*radius+1.
+  use_index : `list` of `bool`
+      A list (vector) of Booleans indicating whether or not to use each time step.
+      An empty (size=0) vector will use all time steps.
+
+  Returns
+  -------
+  `RawImage`
+      The co-added stamp.
   )doc";
 
   static const auto DOC_StampCreator_get_mean_stamp = R"doc(
-  todo
+  Create the mean co-added stamp centered on the predicted position
+  of an Trajectory at different times. Preserves NO_DATA tag.
+
+  Parameters
+  ----------
+  stack : `ImageStack`
+      The stack of images to use.
+  trj : `Trajectory`
+      The trajectory to project to each time.
+  radius : `int`
+      The stamp radius. Width = 2*radius+1.
+  use_index : `list` of `bool`
+      A list (vector) of Booleans indicating whether or not to use each time step.
+      An empty (size=0) vector will use all time steps.
+
+  Returns
+  -------
+  `RawImage`
+      The co-added stamp.
   )doc";
 
   static const auto DOC_StampCreator_get_summed_stamp = R"doc(
-  todo
+  Create the summed co-added stamp centered on the predicted position
+  of an Trajectory at different times. Replaces NO_DATA tag with 0.0.
+
+  Parameters
+  ----------
+  stack : `ImageStack`
+      The stack of images to use.
+  trj : `Trajectory`
+      The trajectory to project to each time.
+  radius : `int`
+      The stamp radius. Width = 2*radius+1.
+  use_index : `list` of `bool`
+      A list (vector) of Booleans indicating whether or not to use each time step.
+      An empty (size=0) vector will use all time steps.
+
+  Returns
+  -------
+  `RawImage`
+      The co-added stamp.
   )doc";
 
 } /* pydocs */