fovdsp (2004 Oct)                      ftools                        fovdsp (2004 Oct)

NAME            
		fovdsp

                Display ISDC format reference catalog overlaid by
                INTEGRAL,  Swift or Suzaku field of view on either Galactic or 
                Equatorial coordinates, aitoff or tangential projections.
                Also, FITS images may be displayed.

USAGE           
                fovdsp mission="Suzaku" TGT_RA=281.00 TGT_DEC=-4.07 TGT_NAME="Galactic Ridge"\
                Euler1=281.00 Euler2=94.07 Euler3=184.47 \
                 catalog=gnrl_refr_cat_0022.fits gdevice="/xs"

                fovdsp mission="Swift" RA_SCX=266 DEC_SCX=-30 ROLL=0 \
                    catalog=gnrl_refr_cat_0014.fits gdevice="/xs"

DESCRIPTION     
		fovdsp displays INTEGRAL general reference catalog (FITS file) and
                INTEGRAL, Swift or Suzaku instrument field of view.  Also, fovdsp
		can display several FITS images, event if they have different binsizes.
                Either single FITS image or multiple images may be specified
                to display.

                The INTEGRAL general reference catalog can be downloaded from
                http://isdc.unige.ch/index.cgi?Data+catalogs
                Please obtain the latest one, and specify with the parameter
                "catalog".
		The catalog sources are displayed with different symbol sizes and
		the color-codes depending on the expected fluxes and spectral
		hardnesses.

		For INTEGRAL fields of view, both the central fully coded 
		region and the outer zero-response boundary are displayed for
		each detector.  The side drawn with broken-line of the
		field of view is in the Z-axis direction, which points to the Sun.
              
	        For Swift BAT field of view, contours are drawn for 95 % (dotted line), 
                50 % (broken line) and  5 % (solid line) transmissions.
              
                For Suzaku, XIS, HXD-PIN and HXD_GSO FOVs are shown. Also, the HXD
                nominal position is indicated with a small rectangle.

                Users can interactively change image display environment,
                such as region of the sky to display , coordinates (Galactic or
                equatorial),  and projection (aitoff or tangential).
                Interactive menu will appear on the screen.  Put cursor on the
                PGPLOT window, and hit a key to enter commands.  Available commands 
                are displayed on the screen.

                INTEGRAL FOV may be read from an input attitude file, or Science
                Window index file, or specified from parameters.  

		fovdsp uses PGPLOT library for display.  Please make sure that the
		following environmental variables are appropriately definied
		(usually set with LHEASOFT initialization):
		PGPLOT_FONT
		PGPLOT_RGB
		PGPLOT_DIR


PARAMETERS      
                mission         INTEGRAL, Swift or Suzaku

		catalog	        ISDC reference catalog.  Obtain the latest FITS file
                                from http://isdc.unige.ch/index.cgi?Data+catalogs

		imagelist	Either a FITS image file, or ASCII list of
				FITS image files.

		gdevice		Output graphic device for pgplot.
				'/xs' is recommended for interactive session.

                TGT_RA          Target RA.  A symbol is marked on the targe position.
            
                TGT_DEC         Target DEC.  A symbol is marked on the targe position.

                TGT_NAME        Target name, which is written at the target position.
 
                Euler1          The first Euler angle. Used only for Suzaku.

                Euler2          The second Euler angle. Used only for Suzaku.

                Euler3          The third Euler angle. Used only for Suzaku.

		RA_SCX		X-axis RA.  Used only for Swift and INTEGRAL.

		DEC_SCX		X-axis DEC. Used only for Swift and INTEGRAL.

		RA_SCZ		Z-axis RA.  Used only for INTEGRAL.

		RA_SCZ		Z-axis RA.  Used only for INTEGRAL.

		Roll            Roll angle around X-axis. Used only for Swift.

		attinput	Read attitude from the attitude file (1) or not	(0).
                                Only prompted when mission=INTEGRAL

		attfile		ISDC format attitude file or ScW index file. 
                                Prompted only when mission=INTEGRAL and attinput=1.

		(VPcentRA)	Viewport center coordinate (RA). Prompted when tangential=1.

		(VPcentDEC)	Viewport center coordinate (DEC). Prompted when tangential=1.

		(VPwidth)	Vewport width (degree). Prompted when tangential=1.

		(tangential)	Display tangential (1) or aitoff (0) projection initially.

		(coordinates)   Initially display equatorial [J2000] (0) or
                                Galactic (1) coordinates

		(plotsource)	Initially plot source positions (0) or not (1).

		(plotname)	Initially show source names (0) or not (1) 
		                when source positions are plotted.

		(plotfov)       Plot insrument FOV (0) or not (1).

		(pixeldist)	Redistribute image pixel values or not.
				If yes, original pixel values are redistributed
				when new image is internally generated.
				This is more precise, but takes time.

                (fontsize)      Control the fontsize of the source names.
                                Default size is 1.0.

		(toplabel)	Top label to be written on the output figure

                (whichinst)     Control the INTEGRAL instrument FOV to
		                display (from 0 to 15) 
                                0 -- all the instrument with Pointing ID
                                1 -- all the instruments without Pointing ID
                                2 -- IBIS and SPI with Pointing ID
                                3 -- IBIS and SPI without Pointing ID
                                4 -- JEMX and SPI with Pointing ID
                                5 -- JEMX and SPI without Pointing ID
                                6 -- SPI with Pointing ID
                                7 -- SPI without Pointing ID
                                8 -- IBIS and JEMX with Pointing ID
                                9 -- IBIS and JEMX without Pointing ID
                               10 -- IBIS with Pointing ID
                               11 -- IBIS without Pointing ID
                               12 -- JEMX with Pointing ID
                               13 -- JEMX without Pointing ID
                               14 -- Only Pointing ID
                               15 -- No FOV displayed


EXAMPLES        
                fovdsp mission="Swift" RA_SCX=266 DEC_SCX=-30 ROLL=0 \
                    catalog=gnrl_refr_cat_0014.fits gdevice="/xs"

                Display Swift FOV pointing (266, -30), and the roll is zero.
                Swift roll is defined as the angle between North and satellite Z-axis,
                measured counterclockwise.

		fovdsp mission=INTEGRAL attitude="Galactic_Plane_Scan.fits[AUXL-ATTI-PRE]"\
			imagelist="GCDE_PISA_mosaic.fits"\
			gdevice="/xs"

		Display the catalog (specified with the catalog
		hidden parameter) with the FOVs in the attitude
		file "Galactic_Plane_Scan.fits".  Image file
		"GCDE_PISA_mosaic.fits" may be displayed.

                fovdsp mission=INTEGRAL "${ISDC_REF_CAT}[JEMX_FLUX_1>100.0]" attinput=1 \
		        attfile=none plotname=0 fontsize=0.3

                Display the catalog sources brither than JEMX_FLUX_1=100.0
                (3-10 keV JEMX counting rates). No FOV is shown, and the 
                source name font size is 30 % of the default.
               

BUGS            
		fovdsp assumes that input image files have
		RA and DEC coordinates (cannot display
		images written with Galactic coordinates).  

AUTHOR          
		Author:            Ken Ebisawa
                E-Mail:            ebisawa@isas.jaxa.jp
		address:	   JAXA/ISAS
				   Yoshinodai 3-1-1
				   Sagamihara, Kanagawa, 229-8510, Japan
               				   
COMMENTS        
		Originally, written for INTEGRAL in the ISDC environment
                (using f90 and DAL), and named as "fovdisp". Converted to an 
                ftool using f77 and fitsio, and the Swift FOV is implemented.