Debug and document the better API for bar offsets

docs/jwst.rst

@@ -142,6 +142,28 @@ can still be used, but the same masks can also be referred to as "MASKRND" and
 "MASKSWB" or "MASKLWB", the nomenclature that was eventually adopted for use in
 APT and other JWST documentation. Both ways work and will continue to do so.
 
+**Offsets along the MASKLWB and MASKSWB masks**:
+
+Each allowable filter has its own default location along one of these masks. The appropriate offset is automatically selected
+in WebbPSF based on the currently selected filter name. If you want to do something different, you can
+set the ``bar_offset`` option::
+
+   >>> nc.options['bar_offset'] = 2.0    # Offsets 2 arcseconds in +X along the mask
+   or
+   >>> nc.options['bar_offset'] = 'F480M'  # Use the position for F480M regardless of the currently selected filter
+
+Note that just because you can simulate such arbitrary position in WebbPSF does not mean you can
+easily actually achieve that pointing with the flight hardware.
+
+
+.. image:: ./fig_maskswb_offsets_v3.png
+    :scale: 50%
+    :alt: MASKSWB Offsets
+
+.. image:: ./fig_masklwb_offsets_v3.png
+    :scale: 50%
+    :alt: MASKLWB Offsets
+
 
 
 Weak Lenses for Wavefront Sensing

webbpsf/optics.py

@@ -748,7 +748,7 @@ def __init__(self, name="unnamed BLC", kind='nircamcircular',  module='A', nd_sq
             offsets = self.offset_swb if self.name.lower()=='maskswb' else self.offset_lwb
             try:
                 bar_offset = offsets[auto_offset]
-                _log.debug("Automatically set bar offset to {} for filter {} on {}.".format(bar_offset, auto_offset, self.name))
+                _log.debug("Set bar offset to {} based on requested filter {} on {}.".format(bar_offset, auto_offset, self.name))
             except:
                 raise ValueError("Filter {} does not have a defined nominal offset position along {}".format(auto_offset,self.name))
 

webbpsf/webbpsf_core.py

@@ -1059,7 +1059,22 @@ def _addAdditionalOptics(self,optsys, oversample=2):
             SAM_box_size = 5.0
         elif ((self.image_mask == 'MASKSWB') or (self.image_mask == 'MASKLWB')):
             bar_offset = self.options.get('bar_offset',None)
-            auto_offset = self.filter if bar_offset is None else None
+            # If the bar offset is not provided, use the filter name to lookup the default
+            # position. If an offset is provided and is a floating point value, use that
+            # directly as the offset. Otherwise assume it's a filter name and try passing
+            # that in to the auto offset. (that allows for selecting the narrow position, or
+            # for simulating using a given filter at some other filter's position.)
+            if bar_offset is None:
+                auto_offset = self.filter
+            else:
+                try:
+                    _ = float(bar_offset)
+                    auto_offset = None
+                except ValueError:
+                    # If the "bar_offset" isn't a float, pass it to auto_offset instead
+                    auto_offset = bar_offset
+                    bar_offset = None
+
             optsys.add_image( NIRCam_BandLimitedCoron(name=self.image_mask, module=self.module,
                     nd_squares=nd_squares, bar_offset=bar_offset, auto_offset=auto_offset),
                     index=2)