%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2006 European Southern Observatory
%.IDENT      copy_disp.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, COPY/DISPLAY
%.PURPOSE    On-line help file for the command: COPY/DISPLAY
%.VERSION    1.0  24-JUL-1990 : Creation, KB
%.VERSION    1.1  07-OCT-1992 : Update, KB
% 060413	last modif
%----------------------------------------------------------------
\se
SECTION./DISP
\es\co
COPY/DISPLAY					13-APR-2006  KB
\oc\su
COPY/DISPLAY [out_dev] [stop_flg] [ITTdef] [LUTnam] [prflag] [prmode]
	make a hardcopy of the display on output_device
\us\pu
Purpose: 
          Make a hardcopy of the ImageDisplay on output_device.
\up\sy
Syntax: 
          COPY/DISPLAY [out_dev] [stop_flg] [ITTdef] [LUTnam] [prflag] [prmode]
\ys\pa
          out_dev = generic MIDAS name or host system name of output device,
	     if the printer is a colour printer, `printer_name.c' has
	     to be entered
             defaulted to LASER, the generic MIDAS name for a default
	     black+white Postscript printer
\ap\pa
          stop_flg = if set to STOP, only read the contents of ImageDisplay
              and save them in image frame `screen.ima', but do not create a 
              PostScript file;
              defaulted to NOSTOP
\ap\pa
          ITTdef = N or P for negative or positive conversion of intensity
              or I,ITT_name to indicate special ITT to be applied to the data;
              defaulted to N for grayscale printers, so black -> white and 
              white -> black;
              defaulted to P for colour printers, so the colours on the output
              will be the same as on the image display.
              Note, however, that any ITT already in effect on the display is
              always applied to the image data. So if you want an exact copy
              of the screen, do not enter any ITT (just use N or P if you want
              to exchange black + white in the hardcopy or not).
              If you want a different ITT applied to the hardcopy then disable
              first the ITT on the display, before using COPY/DISPLAY with that
              specific ITT.
\ap\pa
          LUTnam = name of a LUT to be applied to the data;
              if the loaded image has a real descriptor MIDAS_LUT, this data
              is taken, if LUT_name is omitted. Else we default to current LUT.
\ap\pa
          prflag = print_spec,file_spec
              if print_spec = NOPRINT, the PostScript file which is created by
              COPY/DISPLAY is not sent to `out_dev';
              if print_spec = PRINT, the PostScript file is sent to `out_dev';
              if file_spec = SAMEFILE, the PostScript file is named 
              `screenXY.ps' where XY is the Midas unit; 
              if file_spec = NEWFILE, the PostScript file is named 
              `screenXY:hr:min:sec.ps' where hr:min:sec is the current time;
              defaulted to PRINT,SAMEFILE
\ap\pa
          prmode = 5-char. flag:
              (1) = P(ortrait)/L(andscape), (2) C(olor)/B(lack+white),
              (3) = 4/8 bits per pixel on hardcopy,
              (4) = N(o background)/B(ackground in blue);
              (5) = T(ext)/Z(noText) on output 
              default is PC8NT for COLOUR, PC8B for SLIDE,
              for all other devices the default is PB8NT
\ap\sa
See also:
          COPY/PSCR, COPY/ZOOM, COPY/GRAPHICS, ASSIGN/DISPLAY
          HELP [Printers], @a gammacorr
\as\no
Note:
          The parameters may also be referenced via:
          OUT_DEV= STOP_FLG= ITTDEF= LUTNAM= PRFLAG= PRMODE=
          The pixel resolution for the PostScript Laser printers can be 
          controlled by modifying the keyword POSTSCRIPT(1). Default value is
          21.0 (i.e. 21.0*constant pixels per cm). Use HELP/KEYW POSTSCRIPT
          to get an explanation of the different elements of POSTSCRIPT.
          An image frame containing the retrieved info is always created,
          regardless of the stop_flag, its name is the same as the PostScript
          file with a file type `.ima' instead of `.ps' .
          If you work on X11 devices make sure, that the display window is
          completely inside the screen - otherwise you get an error from the
          X11 server (at least until release 11.4). Also, make sure that no
          other window overlaps the display window, else you will find that 
          back on your hardcopy...
          Normally, you have an interest in printing an image as closely as
          possible like it appears on your screen. If your printed output
          seems bleached out or too dark you should probably apply some 
          gamma correction which controls the overall brightness of an image.
          With the help of the Midas application procedure `gammacorr.prg' you
          get a first guess about the gamma value of your display which you
	  can then refine further.

	  In case you want to include the graphics of the output Postscript 
	  file within Latex (via \includegraphics), you have to change the 
	  bounding boxes of the Postscript file:
	  Replace the "%%BoundingBox: (atend)" in the beginning of the
	  Postscript code by the "%%BoundingBox ..." at the very end of the
	  file which has the real coordinates (using any editor, e.g. vi). 

\on\exs
Examples:
\ex
          COPY/DISPLAY ps4ipg0 ittdef=p
            Make hardcopy on grayscale Postscript printer `ps4ipg0'.
            Keep the same gray levels as in the display window, 
	    i.e. no negative conversion of gray levels is done.
\ex
          COPY/DISPLAY pacol4.c ittdef=p
            As above but use Postscript colour printer for the output.
\xe\ex
          COPY/DISPLAY stop_flag=stop 
            Get a copy of display window in Midas image `screen00.ima' but do
            not produce a Postscript file of it (so, also nothing sent to
            the printer).
\xe\ex
          WRITE/KEYW postscript/r/3/3 24,0.1,0.1
          COPY/DISPLAY prmode=pb8nz
            Increase the size of the hardcopy a lot and omit the text output
            at the bottom of the copy.  
            It depends on the specs of the printer used for the output
            if and how that works...
\xe\ex
          COPY/DISPLAY ? ? I,lasritt
            Make hardcopy on default device and use the ITT `lasritt.itt'.
\xe\ex
          COPY/DISPLAY PRFLAG=NO,new
            Store "hardcopy" of image display in image `screen01:11:14:35.ima',
            convert it to PostScript file `screen01:11:14:35.ps', but do not
            print it (assuming that your Midas unit is 01 and the current time
            is 11:14:35).
\xe \sxe
