'**SUMMARY**
Blit aka bit blit - which in ye olden days was an acronym for bit-block transfer. In other words blit is
when you want to smash two images together, or add one image to another. This method takes in a second
SimpleCV image, and then allows you to add to some point on the calling image. A general blit command
will just copy all of the image. You can also copy the image with an alpha value to the source image
is semi-transparent. A binary mask can be used to blit non-rectangular image onto the souce image.
An alpha mask can be used to do and arbitrarily transparent image to this image. Both the mask and
alpha masks are SimpleCV Images.
**PARAMETERS**
* *img* - an image to place ontop of this image.
* *pos* - an (x,y) position tuple of the top left corner of img on this image. Note that these values
can be negative.
* *alpha* - a single floating point alpha value (0=see the bottom image, 1=see just img, 0.5 blend the two 50/50).
* *mask* - a binary mask the same size as the input image. White areas are blitted, black areas are not blitted.
* *alphaMask* - an alpha mask where each grayscale value maps how much of each image is shown.
**RETURNS**
A SimpleCV Image. The size will remain the same.
**EXAMPLE**
>>> topImg = Image("top.png")
>>> bottomImg = Image("bottom.png")
>>> mask = Image("mask.png")
>>> aMask = Image("alpphaMask.png")
>>> bottomImg.blit(top,pos=(100,100)).show()
>>> bottomImg.blit(top,alpha=0.5).show()
>>> bottomImg.blit(top,pos=(100,100),mask=mask).show()
>>> bottomImg.blit(top,pos=(-10,-10)alphaMask=aMask).show()
**SEE ALSO**
:py:meth:`createBinaryMask`
:py:meth:`createAlphaMask`'

def blit(self, img, pos=None, alpha=None, mask=None, alphaMask=None):

    retVal = Image(self.getEmpty())
    cv.Copy(self.getBitmap(), retVal.getBitmap())
    w = img.width
    h = img.height
    if (pos is None):
        pos = (0, 0)
    (topROI, bottomROI) = self._rectOverlapROIs((img.width, img.height), (self.width, self.height), pos)
    if (alpha is not None):
        cv.SetImageROI(img.getBitmap(), topROI)
        cv.SetImageROI(retVal.getBitmap(), bottomROI)
        a = float(alpha)
        b = float((1.0 - a))
        g = float(0.0)
        cv.AddWeighted(img.getBitmap(), a, retVal.getBitmap(), b, g, retVal.getBitmap())
        cv.ResetImageROI(img.getBitmap())
        cv.ResetImageROI(retVal.getBitmap())
    elif (alphaMask is not None):
        if ((alphaMask is not None) and ((alphaMask.width != img.width) or (alphaMask.height != img.height))):
            logger.warning("Image.blit:    your    mask    and    image    don't    match    sizes,    if    the    mask    doesn't    fit,    you    can    not    blit!    Try    using    the    scale    function.")
            return None
        cImg = img.crop(topROI[0], topROI[1], topROI[2], topROI[3])
        cMask = alphaMask.crop(topROI[0], topROI[1], topROI[2], topROI[3])
        retValC = retVal.crop(bottomROI[0], bottomROI[1], bottomROI[2], bottomROI[3])
        r = cImg.getEmpty(1)
        g = cImg.getEmpty(1)
        b = cImg.getEmpty(1)
        cv.Split(cImg.getBitmap(), b, g, r, None)
        rf = cv.CreateImage((cImg.width, cImg.height), cv.IPL_DEPTH_32F, 1)
        gf = cv.CreateImage((cImg.width, cImg.height), cv.IPL_DEPTH_32F, 1)
        bf = cv.CreateImage((cImg.width, cImg.height), cv.IPL_DEPTH_32F, 1)
        af = cv.CreateImage((cImg.width, cImg.height), cv.IPL_DEPTH_32F, 1)
        cv.ConvertScale(r, rf)
        cv.ConvertScale(g, gf)
        cv.ConvertScale(b, bf)
        cv.ConvertScale(cMask._getGrayscaleBitmap(), af)
        cv.ConvertScale(af, af, scale=(1.0 / 255.0))
        cv.Mul(rf, af, rf)
        cv.Mul(gf, af, gf)
        cv.Mul(bf, af, bf)
        dr = retValC.getEmpty(1)
        dg = retValC.getEmpty(1)
        db = retValC.getEmpty(1)
        cv.Split(retValC.getBitmap(), db, dg, dr, None)
        drf = cv.CreateImage((retValC.width, retValC.height), cv.IPL_DEPTH_32F, 1)
        dgf = cv.CreateImage((retValC.width, retValC.height), cv.IPL_DEPTH_32F, 1)
        dbf = cv.CreateImage((retValC.width, retValC.height), cv.IPL_DEPTH_32F, 1)
        daf = cv.CreateImage((retValC.width, retValC.height), cv.IPL_DEPTH_32F, 1)
        cv.ConvertScale(dr, drf)
        cv.ConvertScale(dg, dgf)
        cv.ConvertScale(db, dbf)
        cv.ConvertScale(cMask.invert()._getGrayscaleBitmap(), daf)
        cv.ConvertScale(daf, daf, scale=(1.0 / 255.0))
        cv.Mul(drf, daf, drf)
        cv.Mul(dgf, daf, dgf)
        cv.Mul(dbf, daf, dbf)
        cv.Add(rf, drf, rf)
        cv.Add(gf, dgf, gf)
        cv.Add(bf, dbf, bf)
        cv.ConvertScaleAbs(rf, r)
        cv.ConvertScaleAbs(gf, g)
        cv.ConvertScaleAbs(bf, b)
        cv.Merge(b, g, r, None, retValC.getBitmap())
        cv.SetImageROI(retVal.getBitmap(), bottomROI)
        cv.Copy(retValC.getBitmap(), retVal.getBitmap())
        cv.ResetImageROI(retVal.getBitmap())
    elif (mask is not None):
        if ((mask is not None) and ((mask.width != img.width) or (mask.height != img.height))):
            logger.warning("Image.blit:    your    mask    and    image    don't    match    sizes,    if    the    mask    doesn't    fit,    you    can    not    blit!    Try    using    the    scale    function.    ")
            return None
        cv.SetImageROI(img.getBitmap(), topROI)
        cv.SetImageROI(mask.getBitmap(), topROI)
        cv.SetImageROI(retVal.getBitmap(), bottomROI)
        cv.Copy(img.getBitmap(), retVal.getBitmap(), mask.getBitmap())
        cv.ResetImageROI(img.getBitmap())
        cv.ResetImageROI(mask.getBitmap())
        cv.ResetImageROI(retVal.getBitmap())
    else:
        cv.SetImageROI(img.getBitmap(), topROI)
        cv.SetImageROI(retVal.getBitmap(), bottomROI)
        cv.Copy(img.getBitmap(), retVal.getBitmap())
        cv.ResetImageROI(img.getBitmap())
        cv.ResetImageROI(retVal.getBitmap())
    return retVal
