## NAME

         copy_paste - copy a subimage from one image and paste to the
         same or another image

## SYNOPSIS

          #include <CVIPtoolkit.h>
          #include <CVIPimage.h>
          #include <CVIPconvert.h>
          #include <CVIPgeometry.h>

          Image *copy_paste( Image *srcImg, Image *destImg,
            unsigned start_r, unsigned start_c, unsigned height,
            unsigned width, unsigned dest_r, unsigned dest_c,
            CVIP_BOOLEAN transparent);

          <srcImg>  - source image to copy the subimage
          <destImg> - destination image for pasting
          <start_r> - row value of the upper-left corner of the
                      subimage on srcImg
          <start_c> - column value of the upper-left corner of the
                      subimage on srcImg
          <height>  - height of desired subimage
          <width>   - width of desired subimage
          <dest_r>  - row value of the upper-left corner of the
                      destImg  area to paste the subimage
          <dest_c>  - column value of the upper-left corner of the
                      destImg area to paste the subimage
          <transparent> - whether the paste is transparent or not

## PATH

         $CVIPHOME/GEOMETRY/copy_paste.c

## DESCRIPTION

         The copy_paste(3) function copies a subimage from the srcImg
         and  paste  it  to  the  destImg. copy_paste is designed for
         cross-image copy-paste, but it  also  works  for  copy-paste
         within  the  same image, which is indicated by making srcImg
         == destImg.

         If the subimage is too large,  the  size  will  be  adjusted
         automatically  so  the  subimage  can be successfully copied
         from the srcImg and pasted to the destImg. At the same time,
         an  error  message  is put to the standard error to warn the
         user of the event. crop_paste  handles  any  CVIP_TYPE  data
         types  by  first  boosting  both  images  to CVIP_FLOAT; and
         remapping the resulting image to the data type of  the  des-
         tImg.

         When a subimage is copy-pasted from a REAL image to  a  COM-
         PLEX image, the real data on srcImg is also used as the ima-
         ginary data for pasting. When a subimage is copy-pasted from
         a  COMPLEX  image  to a REAL image, the imaginary components
         are discarded.

         When copy-pasting from image of N bands to another image  of
         M bands, band mapping is done in the following way. For band
         band_no in the destImg, band (band_no*N/M) on the srcImg  is
         used.  For example, when copying from single band image (N =
         1) to a color image (M=3), the single band data is used  for
         all  three bands in the resulting image (band_no = 0, 1, 2).
         On the other hand, when copying from a three band image to a
         single band image, only the red band is used.

         For  a non-transparent pasting, the  original  data  in  the
         destImg will be overwritten by the subimage from the srcImg.
         On the other hand, a transparent pasting will add  the  data
         of  the  subimage  to  the  existing destImg data. But other
         region of the destImg might turn out to be relatively darker
         when transparent pasting is used.

## TYPES AND CONSTANTS

         NONE

## RETURN VALUES

         The pasted Image pointer on success; a (Image *)NULL pointer
         on  failure.   In any case, the input Image pointers will be
         released.

## HISTORY

         History information recorded: None

## EXAMPLE

          #include <CVIPtoolkit.h>
          #include <CVIPimage.h>
          #include <CVIPconvert.h>
          #include <CVIPgeometry.h>
          #include <CVIPview.h>

          void main()
          {
          Image *cvipImage, *cvipImage1;
          IMAGE_FORMAT format;
          char *inputfile, *outputfile;

          setDisplay_Image("picture", "Default");

          print_CVIP("\n\t\tEnter the first Input File Name:  ");
          inputfile =(char *) getString_CVIP();
          format = getFormat_CVIP(inputfile);
          cvipImage = read_Image(inputfile, 1);
          view_Image(cvipImage, inputfile);
          free(inputfile);

          print_CVIP("\n\t\tEnter the second Input File Name:  ");
          inputfile =(char *) getString_CVIP();
          format = getFormat_CVIP(inputfile);
          cvipImage1 = read_Image(inputfile, 1);
          view_Image(cvipImage1, inputfile);
          free(inputfile);

          /* the following call  copies a 100x100 area on cvipImage
             beginning from (10, 10), and pastes it to the upper-left
             corner on cvipImage1 non-transparently.
           */
          cvipImage = copy_paste(cvipImage, cvipImage1, 10, 10, 100,
                      100, 0, 0, CVIP_NO);
          print_CVIP("\n\t\tEnter the Output File Name:  ");
          outputfile = getString_CVIP();
          write_Image(cvipImage,outputfile,CVIP_NO,CVIP_NO,format,1);
          view_Image(cvipImage,outputfile);
          free(outputfile);
          }

## SEE ALSO

         crop(3), libgeometry

## AUTHOR

         Copyright (C) 1995 SIUE - by Scott Umbaugh and Yansheng Wei