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