DM-35895: Use band for the dataId not filter

doc/lsst.afw.multiband/multiband.rst

@@ -480,17 +480,14 @@ to load an exposure from a file:
 .. code-block:: python
 
     from lsst.afw.image import MultibandExposure
-    from lsst.daf.persistence import Butler
+    from lsst.daf.butler import Butler
 
-    # This is an example dataset on lsstdev which may be out of date,
-    # replace with a local dataset
-    DATA_DIR = "/datasets/hsc/repo/rerun/RC/w_2018_22/DM-14547"
-    butler = Butler(inputs=DATA_DIR)
+    DATA_DIR = "/repo/main"
+    butler = Butler(DATA_DIR)
 
-    filters = ["G", "R","I"]
-    hscFilters = ["HSC-"+f for f in filters]
-    mExposure = MultibandExposure.fromButler(butler, hscFilters, None, "deepCoadd_calexp",
-                                             patch="1,1", tract=9813)
+    bands = ["g", "r", "i"]
+    mExposure = MultibandExposure.fromButler(butler, bands, None, "deepCoadd_calexp",
+                                             patch=42, tract=9813)
 
 MultibandFootprint
 ==================
@@ -739,7 +736,7 @@ band `HeavyFootprint` objects:
 
     # Output
     # id f_x f_y i_x i_y peakValue
-    #    pix pix pix pix     ct   
+    #    pix pix pix pix     ct
     #--- --- --- --- --- ---------
     # 16 1.0 1.0   1   1       1.0
     # 17 3.0 3.0   3   3       2.0

python/lsst/afw/cameraGeom/utils.py

@@ -401,8 +401,10 @@ class ButlerImage(FakeImageDataSource):
 
     Parameters
     ----------
-    butler : `lsst.daf.persistence.Butler` or `None`
-        The butler to use. If `None`, an empty image is returned.
+    butler : `lsst.daf.butler.Butler` or `None`
+        The butler to use. If `None`, an empty image is returned. Assumes that
+        the instrument was specified during butler construction or is included
+        in the ``kwargs`` parameter.
     type : `str`
         The type of image to read (e.g. raw, bias, flat, calexp).
     isTrimmed : `bool`
@@ -412,11 +414,11 @@ class ButlerImage(FakeImageDataSource):
     background : `float`
         The value of any pixels that lie outside the CCDs.
     callback : callable
-        A function called with (image, ccd, butler) for every image, which
+        A function called with (image, detector, butler) for every image, which
         returns the image to be displayed (e.g. rawCallback). The image must
         be of the correct size, allowing for the value of isTrimmed.
     *args : `list`
-        Passed to the butler.
+        Passed to the base class constructor.
     **kwargs : `dict`
         Passed to the butler.
 
@@ -430,7 +432,7 @@ def callback(im, ccd, imageSource):
     def __init__(self, butler=None, type="raw",
                  isTrimmed=True, verbose=False, background=numpy.nan,
                  callback=None, *args, **kwargs):
-        super(ButlerImage, self).__init__(*args)
+        super().__init__(*args)
         self.isTrimmed = isTrimmed
         self.type = type
         self.butler = butler
@@ -463,19 +465,14 @@ def getCcdImage(self, ccd, imageFactory=afwImage.ImageF, binSize=1, asMaskedImag
         im = None
         if self.butler is not None:
             err = None
-            for dataId in [dict(detector=ccd.getId()), dict(ccd=ccd.getId()), dict(ccd=ccd.getName())]:
-                try:
-                    im = self.butler.get(self.type, dataId, **self.kwargs)
-                except FitsError as e:  # no point trying another dataId
-                    err = IOError(e.args[0].split('\n')[0])  # It's a very chatty error
-                    break
-                except Exception as e:  # try a different dataId
-                    if err is None:
-                        err = e
-                    continue
-                else:
-                    ccd = im.getDetector()  # possibly modified by assembleCcdTask
-                    break
+            try:
+                im = self.butler.get(self.type, detector=ccd.getId(), **self.kwargs)
+            except FitsError as e:
+                err = IOError(e.args[0].split('\n')[0])  # It's a very chatty error
+            except Exception as e:  # try a different dataId
+                err = e
+            else:
+                ccd = im.getDetector()  # possibly modified by assembleCcdTask
 
             if im:
                 if asMaskedImage:

python/lsst/afw/image/exposure/_multiband.py

@@ -114,11 +114,11 @@ def fromButler(butler, filters, filterKwargs, *args, **kwargs):
 
         Parameters
         ----------
-        butler: `Butler`
+        butler: `lsst.daf.butler.Butler`
             Butler connection to use to load the single band
             calibrated images
         filters: `list` or `str`
-            List of filter names for each band
+            List of bands.
         filterKwargs: `dict`
             Keyword arguments to pass to the Butler
             that are different for each filter.
@@ -143,7 +143,7 @@ def fromButler(butler, filters, filterKwargs, *args, **kwargs):
             if filterKwargs is not None:
                 for key, value in filterKwargs:
                     kwargs[key] = value[f]
-            exposures.append(butler.get(*args, filter=f, **kwargs))
+            exposures.append(butler.get(*args, band=f, **kwargs))
         return MultibandExposure.fromExposures(filters, exposures)
 
     def computePsfKernelImage(self, position=None):