Tickets/dm 4102

doc/iteratorsAndLocators.dox

@@ -71,7 +71,7 @@ Set the %image to a ramp
 That didn't gain us much, did it?  The code's a little messier than using
 \c x_iterator.   But now we can add code to calculate the smoothed
 %image.  First make an output image, and copy the input pixels:
-\until <<=
+\until out.assign
 (we didn't need to copy all of them, just the ones around the edge
 that we won't smooth, but this is an easy way to do it).
 
@@ -147,7 +147,7 @@ Set the %image (but not the mask or variance) to a ramp
 That didn't gain us much, did it?  The code's a little messier than using
 \c x_iterator.   But now we can add code to calculate the smoothed
 %image.  First make an output image, and copy the input pixels:
-\until <<=
+\until out2.assign
 (we didn't need to copy all of them, just the ones around the edge
 that we won't smooth, but this is an easy way to do it).
 

examples/image.cc

@@ -185,7 +185,7 @@ int main() {
     {
         afwImage::Image<float> nimg(afwGeom::Extent2I(5, 2));
         nimg = 1;
-        simg <<= nimg;
+        simg.assign(nimg);
     }
 
     print(simg, "simg");

examples/image2.cc

@@ -42,7 +42,7 @@ int main() {
     // Convolve with a pseudo-Gaussian kernel ((1, 2, 1), (2, 4, 2), (1, 2, 1))
     //
     ImageT out(in.getDimensions()); // Make an output image the same size as the input image
-    out <<= in;
+    out.assign(in);
     for (int y = 1; y != in.getHeight() - 1; ++y) {
         for (ImageT::xy_locator ptr =  in.xy_at(1, y), end = in.xy_at(in.getWidth() - 1, y),
                                optr = out.xy_at(1, y); ptr != end; ++ptr.x(), ++optr.x()) {
@@ -55,7 +55,7 @@ int main() {
     // Do the same thing a faster way, using cached_location_t
     //
     ImageT::Ptr out2(new ImageT(in.getDimensions()));
-    *out2 <<= in;
+    out2->assign(in);
 
     typedef ImageT::const_xy_locator xy_loc;
 

examples/imageBackground.cc

@@ -96,7 +96,7 @@ int main() {
 
     // create a background-subtracted image
     ImageF sub(img.getDimensions());
-    sub <<= img;
+    sub.assign(img);
     sub -= *bg;
 
     // output what we've made

examples/mask.cc

@@ -73,7 +73,7 @@ int main() {
     {
         afwImage::Mask<afwImage::MaskPixel> nimg(simg.getDimensions());
         nimg = 1;
-        simg <<= nimg;
+        simg.assign(nimg);
     }
 
     for (int r = 0; r != img.getHeight(); ++r) {

examples/maskedImage.cc

@@ -116,7 +116,7 @@ int main() {
 
     {
         float const gain = 2;
-        *img.getVariance() <<= image::Image<image::VariancePixel>(*img.getImage(), true);
+        img.getVariance()->assign(image::Image<image::VariancePixel>(*img.getImage(), true));
         *img.getVariance() /= gain;
     }
 

examples/maskedImage2.cc

@@ -41,7 +41,7 @@ int main() {
     // Convolve with a pseudo-Gaussian kernel ((1, 2, 1), (2, 4, 2), (1, 2, 1))
     //
     ImageT out(in.getDimensions()); // Make an output image the same size as the input image
-    out <<= in;
+    out.assign(in);
     for (int y = 1; y != in.getHeight() - 1; ++y) {
         for (ImageT::xy_locator ptr =  in.xy_at(1, y), end = in.xy_at(in.getWidth() - 1, y),
                                optr = out.xy_at(1, y); ptr != end; ++ptr.x(), ++optr.x()) {
@@ -54,7 +54,7 @@ int main() {
     // Do the same thing a faster way, using cached_location_t
     //
     ImageT::Ptr out2(new ImageT(in.getDimensions()));
-    *out2 <<= in;
+    out2->assign(in);
 
     typedef ImageT::const_xy_locator xy_loc;
 

include/lsst/afw/image/Image.h

@@ -212,6 +212,8 @@ namespace image {
         ImageBase& operator=(const ImageBase& rhs);
         ImageBase& operator=(const PixelT rhs);
         void operator<<=(const ImageBase& rhs);
+
+        void assign(ImageBase const &rsh, geom::Box2I const &bbox = geom::Box2I(), ImageOrigin origin=PARENT);
         //
         // Operators etc.
         //

include/lsst/afw/image/MaskedImage.h

@@ -744,6 +744,8 @@ class MaskedImage : public lsst::daf::base::Persistable,
 
     void operator<<=(MaskedImage const& rhs);
 
+    void assign(MaskedImage const &rsh, geom::Box2I const &bbox = geom::Box2I(), ImageOrigin origin=PARENT);
+
     void operator+=(ImagePixelT const rhs);
     void operator+=(MaskedImage const& rhs);
     void operator+=(lsst::afw::image::Image<ImagePixelT> const& rhs) {

python/lsst/afw/image/imageLib.i

@@ -214,10 +214,11 @@ def __setitem__(self, imageSlice, rhs):
     """
     __setitem__(self, imageSlice, value)
     """
-    lhs = self.Factory(self, _getBBoxFromSliceTuple(self, imageSlice), LOCAL)
+    bbox = _getBBoxFromSliceTuple(self, imageSlice)
     try:
-        lhs <<= rhs
-    except TypeError:
+        self.assign(rhs, bbox, LOCAL)
+    except NotImplementedError:
+        lhs = self.Factory(self, bbox, LOCAL)
         lhs.set(rhs)
 
 def __float__(self):

src/image/DecoratedImage.cc

@@ -97,7 +97,7 @@ image::DecoratedImage<PixelT>::DecoratedImage(
 /**
  * Assignment operator
  *
- * N.b. this is a shallow assignment; use operator<<=() if you want to copy the pixels
+ * N.b. this is a shallow assignment; use set(src) if you want to copy the pixels
  */
 template<typename PixelT>
 image::DecoratedImage<PixelT>& image::DecoratedImage<PixelT>::operator=(const DecoratedImage& src) {

src/image/Image.cc

@@ -129,7 +129,7 @@ image::ImageBase<PixelT>::ImageBase(
  * Copy constructor.
  *
  * \note Unless \c deep is \c true, the new %image will share the old %image's pixels;
- * this may not be what you want.  See also operator<<=() to copy pixels between Image%s
+ * this may not be what you want.  See also assign(rhs) to copy pixels between Image%s
  */
 template<typename PixelT>
 image::ImageBase<PixelT>::ImageBase(
@@ -144,7 +144,7 @@ image::ImageBase<PixelT>::ImageBase(
 {
     if (deep) {
         ImageBase tmp(getBBox());
-        tmp <<= *this;                  // now copy the pixels
+        tmp.assign(*this);                  // now copy the pixels
         swap(tmp);
     }
 }
@@ -172,7 +172,7 @@ image::ImageBase<PixelT>::ImageBase(
 {
     if (deep) {
         ImageBase tmp(getBBox());        
-        tmp <<= *this;                  // now copy the pixels
+        tmp.assign(*this);                  // now copy the pixels
         swap(tmp);
     }
 }
@@ -208,7 +208,7 @@ image::ImageBase<PixelT>::ImageBase(Array const & array, bool deep, geom::Point2
 /// Shallow assignment operator.
 ///
 /// \note that this has the effect of making the lhs share pixels with the rhs which may
-/// not be what you intended;  to copy the pixels, use operator<<=()
+/// not be what you intended;  to copy the pixels, use assign(rhs)
 ///
 /// \note this behaviour is required to make the swig interface work, otherwise I'd
 /// declare this function private
@@ -221,14 +221,39 @@ image::ImageBase<PixelT>& image::ImageBase<PixelT>::operator=(ImageBase const& r
 }
 
 /// Set the lhs's %pixel values to equal the rhs's
+///
+/// \deprecated use assign(rhs) instead
 template<typename PixelT>
 void image::ImageBase<PixelT>::operator<<=(ImageBase const& rhs) {
-    if (getDimensions() != rhs.getDimensions()) {
+    assign(rhs);
+}
+
+/**
+ * Copy pixels from another image to a specified subregion of this image.
+ *
+ * \param[in] rhs  source image whose pixels are to be copied into this image (the destination)
+ * \param[in] bbox  subregion of this image to set; if empty (the default) then all pixels are set
+ * \param[in] origin  origin of bbox: if PARENT then the lower left pixel of this image is at xy0
+ *                    if LOCAL then the lower left pixel of this image is at 0,0
+ *
+ * \throw lsst::pex::exceptions::LengthError if the dimensions of rhs and the specified subregion of
+ * this image do not match.
+ */
+template<typename PixelT>
+void image::ImageBase<PixelT>::assign(ImageBase const &rhs, geom::Box2I const &bbox, ImageOrigin origin) {
+    auto lhsDim = bbox.isEmpty() ? getDimensions() : bbox.getDimensions();
+    if (lhsDim != rhs.getDimensions()) {
         throw LSST_EXCEPT(lsst::pex::exceptions::LengthError,
                           (boost::format("Dimension mismatch: %dx%d v. %dx%d") %
-                              getWidth() % getHeight() % rhs.getWidth() % rhs.getHeight()).str());
+                              lhsDim.getX() % lhsDim.getY() % rhs.getWidth() % rhs.getHeight()).str());
+    }
+    if (bbox.isEmpty()) {
+        copy_pixels(rhs._gilView, _gilView);
+    } else {
+        auto lhsOff = (origin == PARENT) ? bbox.getMin() - _origin : geom::Extent2I(bbox.getMin());
+        auto lhsGilView = _makeSubView(lhsDim, lhsOff, _gilView);
+        copy_pixels(rhs._gilView, lhsGilView);
     }
-    copy_pixels(rhs._gilView, _gilView);
 }
 
 /// Return a reference to the pixel <tt>(x, y)</tt>
@@ -449,7 +474,7 @@ image::Image<PixelT>::Image(geom::Box2I const & bbox, ///< dimensions and origin
  * Copy constructor.
  *
  * \note Unless \c deep is \c true, the new %image will share the old %image's pixels;
- * this may not be what you want.  See also operator<<=() to copy pixels between Image%s
+ * this may not be what you want.  See also assign(rhs) to copy pixels between Image%s
  */
 template<typename PixelT>
 image::Image<PixelT>::Image(Image const& rhs, ///< Right-hand-side Image
@@ -486,7 +511,7 @@ image::Image<PixelT>& image::Image<PixelT>::operator=(PixelT const rhs) {
 /// Assignment operator.
 ///
 /// \note that this has the effect of making the lhs share pixels with the rhs which may
-/// not be what you intended;  to copy the pixels, use operator<<=()
+/// not be what you intended;  to copy the pixels, use assign(rhs)
 ///
 /// \note this behaviour is required to make the swig interface work, otherwise I'd
 /// declare this function private

src/image/MaskedImage.cc

@@ -322,7 +322,7 @@ image::MaskedImage<ImagePixelT, MaskPixelT, VariancePixelT>::MaskedImage(
  *
  * If you are copying a scalar value, a simple <tt>lhs = scalar;</tt> is OK, but
  * this is probably not the function that you want to use with an %image. To copy pixel values
- * from the rhs use operator<<=()
+ * from the rhs use assign(rhs)
  */
 template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
 image::MaskedImage<ImagePixelT, MaskPixelT, VariancePixelT>& image::MaskedImage<ImagePixelT, MaskPixelT, VariancePixelT>::operator=(image::MaskedImage const& rhs ///< Right hand side
@@ -371,13 +371,32 @@ image::MaskedImage<ImagePixelT, MaskPixelT, VariancePixelT>::operator=(MaskedIma
 /**
  * Copy the pixels from the rhs to the lhs
  *
+ * \deprecated use assign(rhs) instead
+ *
  * \note operator=() is not equivalent to this command
  */
 template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
 void image::MaskedImage<ImagePixelT, MaskPixelT, VariancePixelT>::operator<<=(MaskedImage const& rhs) {
-    *_image <<= *rhs.getImage();
-    *_mask <<= *rhs.getMask();
-    *_variance <<= *rhs.getVariance();
+    assign(rhs);
+}
+
+/**
+ * Copy pixels from another masked image to a specified subregion of this masked image.
+ *
+ * \param[in] rhs  source image whose pixels are to be copied into this image (the destination)
+ * \param[in] bbox  subregion of this image to set; if empty (the default) then all pixels are set
+ * \param[in] origin  origin of bbox: if PARENT then the lower left pixel of this image is at xy0
+ *                    if LOCAL then the lower left pixel of this image is at 0,0
+ *
+ * \throw lsst::pex::exceptions::LengthError if the dimensions of rhs and the specified subregion of
+ * this image do not match.
+ */
+template<typename ImagePixelT, typename MaskPixelT, typename VariancePixelT>
+void image::MaskedImage<ImagePixelT, MaskPixelT, VariancePixelT>::assign(MaskedImage const &rhs,
+    geom::Box2I const &bbox, ImageOrigin origin) {
+    _image->assign(*rhs.getImage(), bbox, origin);
+    _mask->assign(*rhs.getMask(), bbox, origin);
+    _variance->assign(*rhs.getVariance(), bbox, origin);
 }
 
 /// Add a MaskedImage rhs to a MaskedImage

src/math/ConvolveImage.cc

@@ -111,9 +111,9 @@ namespace {
         ) {
             OutImageT outView(outImage, *bboxIter, afwImage::LOCAL);
             if (doCopyEdge) {
-                // note: <<= only works with data of the same type
+                // note: set only works with data of the same type
                 // so convert the input image to output format
-                outView <<= OutImageT(InImageT(inImage, *bboxIter, afwImage::LOCAL), true);
+                outView.assign(OutImageT(InImageT(inImage, *bboxIter, afwImage::LOCAL), true));
             } else {
                 outView = edgePixel;
             }
@@ -185,9 +185,9 @@ namespace {
             bboxIter != bboxList.end(); ++bboxIter) {
             OutImageT outView(outImage, *bboxIter, afwImage::LOCAL);
             if (doCopyEdge) {
-                // note: <<= only works with data of the same type
+                // note: set only works with data of the same type
                 // so convert the input image to output format
-                outView <<= OutImageT(InImageT(inImage, *bboxIter, afwImage::LOCAL), true);
+                outView.assign(OutImageT(InImageT(inImage, *bboxIter, afwImage::LOCAL), true));
                 *(outView.getMask()) |= edgeMask;
             } else {
                 outView = edgePixel;

src/math/detail/ConvolveWithInterpolation.cc

@@ -142,9 +142,9 @@ void mathDetail::convolveRegionWithInterpolation(
 
     CONST_PTR(afwMath::Kernel) kernelPtr = region.getKernel();
     geom::Extent2I const kernelDimensions(kernelPtr->getDimensions());
-    workingImages.leftImage <<= *region.getImage(KernelImagesForRegion::BOTTOM_LEFT);
-    workingImages.rightImage <<= *region.getImage(KernelImagesForRegion::BOTTOM_RIGHT);
-    workingImages.kernelImage <<= workingImages.leftImage;
+    workingImages.leftImage.assign(*region.getImage(KernelImagesForRegion::BOTTOM_LEFT));
+    workingImages.rightImage.assign(*region.getImage(KernelImagesForRegion::BOTTOM_RIGHT));
+    workingImages.kernelImage.assign(workingImages.leftImage);
 
     afwGeom::Box2I const goodBBox = region.getBBox();
     afwGeom::Box2I const fullBBox = kernelPtr->growBBox(goodBBox);
@@ -189,7 +189,7 @@ void mathDetail::convolveRegionWithInterpolation(
         }
         workingImages.leftImage += workingImages.leftDeltaImage;
         workingImages.rightImage += workingImages.rightDeltaImage;
-        workingImages.kernelImage <<= workingImages.leftImage;
+        workingImages.kernelImage.assign(workingImages.leftImage);
         inLocator += lsst::afw::image::detail::difference_type(-goodBBox.getWidth(), 1);
         outLocator += lsst::afw::image::detail::difference_type(-goodBBox.getWidth(), 1);
     }

src/math/offsetImage.cc

@@ -71,8 +71,7 @@ typename ImageT::Ptr offsetImage(ImageT const& inImage,  ///< The %image to offs
         typename ImageT::Ptr buffered(new ImageT(dims.getX() + 2 * buffer, dims.getY() + 2 * buffer));
         buffImage = buffered;
         afwGeom::Box2I box(afwGeom::Point2I(buffer, buffer), dims);
-        typename ImageT::Ptr buffSmall(new ImageT(*buffImage, box, afwImage::LOCAL, false));
-        *buffSmall <<= inImage;
+        buffImage->assign(inImage, box);
     } else {
         buffImage = boost::make_shared<ImageT>(inImage);
     }