File Formats

From dbd067d96dff4739d516c0bc6d048f60c655c771 Mon Sep 17 00:00:00 2001 From: William Joye Date: Fri, 21 Dec 2018 11:51:26 -0500 Subject: fix doc link --- ds9/doc/ref/file.html | 1464 ++++++++++++++++++++++++++----------------------- 1 file changed, 789 insertions(+), 675 deletions(-) diff --git a/ds9/doc/ref/file.html b/ds9/doc/ref/file.html index b1aebc8..012bcf0 100644 --- a/ds9/doc/ref/file.html +++ b/ds9/doc/ref/file.html @@ -1,682 +1,796 @@ - - - - -File Formats - - -

File Formats

FITS
-FITS Image
-FITS Binary Events Table
-FITS HEALPIX Table
-FITS Data Cube
-FITS Multiple Extension -Data Cube
-FITS Multiple -Extension Multiple Frames
-FITS Mosaic
-FITS Mosaic Data Cube
-FITS RGB
-Split FITS
-Array
-NRRD
-ENVI
-GIF
-TIFF
-JPEG
-PNG
-External Format Support
-External Analysis -Support
-Region Files
-Contour Files
-Color Lookup Table
-WCS
-Preference File
-Startup File
-TCL
-
FITS
-DS9 supports FITS images and FITS binary tables. The following -algorithm is used to locate and to load the FITS image or table if -no additional information is provide: -
-
-
Examine primary HDU, if IMAGE, load.
-
Examine each extension HDU
-
-
-
If IMAGE, load.
-
If BINARY TABLE, create IMAGE if the following is -true:
-
-
-
FITS COMPRESSED: keyword ZIMAGE is T.
-
FITS EVENTS: keyword EXTNAME is EVENTS,STDEVT, or RAYEVENT, -column names X and Y are present.
-
FITS HEALPIX: keyword PIXTYPE is HEALPIX.
-
-
-
-
-
If DS9 traverses the entire FITS file without satisfying -one of the above, an error is generated.
-
-
-FITS keyword inheritance is supported. All valid FITS -BITPIX values are supported, along with -16, for -UNSIGNED SHORT. The following FITS keywords are supported: -
OBJECT -UNITS -BSCALE / BZERO -BLANK -DATASEC -LTV / LTM for physical coords -DTV / DTM for detector coords -ATV / ATM for amplifier coords -WCS keywords -WCS# keywords
-
FITS Image
-At load time, the user may provide just a file name or a file name -along with FITS extension name/number and image section -specification. FITS extension names are case insensitive. When -specifying an extension, be sure to quote strings correctly to pass -both the shell and DS9 parser. A image section specification is -used to specify the x,y limits of an image subsection. By default, -x and y coordinates are in IMAGE, use a 'p' as -the last character to indicate PHYSICAL coordinates. A -'*' indicates use the default for that axis only. Block is -optional and defaults to 1.
-
Syntax: -filename -filename[ext] -filename[ext][sect] -filename[sect] -filename[ext,sect] - -where- -ext: -[extension name | extension #] - -sect: -[x0:x1,y0:y1[p]] -[x0:x1,y0:y1,block[p]] - -[x0:x1,y0:y1,z0:z1[p]] - -[x0:x1,y0:y1,block,z0:z1[p]]
- -[*,y0:y1[p]] -[*,y0:y1,block[p]] - -[*,y0:y1,z0:z1[p]] - -[*,y0:y1,block,z0:z1[p]]
- -[x0:x1,*[p]] - -[x0:x1,*,block[p]] - -[x0:x1,*,z0:z1[p]] - -[x0:x1,*,block,z0:z1[p]]
- -[*,*,block] - -[*,*,z0:z1] - -[*,*,block,z0:z1] - - -[dim1@xcen,dim2@ycen[p]] - -[dim1@xcen,dim2@ycen,block[p]] - -[dim1@xcen,dim2@ycen,dim3@zcen[p]] - -[dim1@xcen,dim2@ycen,block,dim3@zcen[p]]
- -[*,dim2@ycen[p]] - -[*,dim2@ycen,block[p]] - -[*,dim2@ycen,dim3@zcen[p]] - -[*,dim2@ycen,block,dim3@zcen[p]]
- -[dim1@xcen,*[p]] - -[dim1@xcen,*,block[p]] - -[dim1@xcen,*,dim3@zcen[p]] - -[dim1@xcen,*,block,dim3@zcen[p]]
- -[*,*,block] - [*,*,dim3@zcen] -[*,*,block,dim3@zcen] - - -[dim@xcen@ycen] -[dim@xcen@ycen,block]
-[dim@xcen@ycen,zdim@zcen]
-[dim@xcen@ycen,block,zdim@zcen]- - -Example: -$ds9 foo.fits # default load -$ds9 foo.fits[1] # load first extension -$ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD' -$ds9 foo.fits[10:200,40:100] # image section $ds9 -foo.fits[10:200,40:100,2] # image section, blocked by 2 -$ds9 foo.fits[*,40:100] # only section y axis -$ds9 foo.fits[256@512@512] # section box at 512,512 -$ds9 foo.fits[2][100:200,100:200] # second extension, image -section $ds9 foo.fits[2][100:200,100:200,2] # -second extension, image section, blocked by 2 $ds9 -foo.fits[10:200,40:100,5:20] # cube section -$ds9 foo.fits[*,40:100,5:20] # only section y and z axes -$ds9 foo.fits[256@512@512] # section cube at 512,512 -$ds9 foo.fits[2][100:200,100:200,5:20] # second extension, cube -section
-$ds9 foo.fits[2][100:200,100:200,2,5:20] # second extension, -cube section, blocked by 2
-FITS Binary Events Table
-
At load time, the user may provide just a file name or a -file name along with FITS extension name/number, image section -specification, and binnng parameters. DS9 will automatically -convert an FITS binary events table into a 2D image for display. -FITS extension names and parameters are case insensitive. The users -may specify a number of parameters on how to construct the image -and how to filter data. When specifying a filter, be sure to quote -strings correctly to pass both the shell and DS9 -parser.

-
Syntax: -filename -filename[ext] -filename[ext][sect] -filename[sect] -filename[ext,sect] -filename[ext][bin] -filename[ext][bin][sect] -filename[ext][sect][bin] -filename[bin] -filename[bin][sect] -filename[sect][bin] filename[ext,bin] - where: -ext: see FITS Image -sect: see FITS Image - -bin: -[bin=colx,coly] # bin counts -[bin=colx,coly,filter] # bin counts with filter -[bin=colx,coly,colz] # bin on colz -[bin=colx,coly,colz,filter] # bin on colz with -filter [bin=colz] # bin cols 'x', 'y', and -colz [bin=colz,filter] # bin cols 'x', 'y', -and colz with filter [key=colx,coly] -[binkey=colx,coly]
-(see Introduction -to Filtering)
-
-Example:
-$ds9 foo.fits # default load
-$ds9 foo.fits[1] # load first extension
-$ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD'
-$ds9 foo.fits[bin=detx,dety] # bin on detx,dety
-$ds9 foo.fits[2][bin=rawx,rawy] # load ext 2, cols -rawx,rawy
-$ds9 foo.fits[bg_events,bin=rawx,rawy] # load ext bg_events, -cols rawx,rawy
-$ds9 foo.fits[bin=x,y,pha] # bin on x,y,pi
-$ds9 foo.fits[bin=pi] # bin on x,y,pi
-$ds9 'foo.fits[ccd_id==3&&energy>4000]' # quoted -filter
-$ds9 '"foo.fits[ccd_id==3 && energy>4000]"' # double -quoted filter
-$ds9 'foo.fits[events][pha>5,pi<2]' # load extension -'events' and filter
-

-
The shell environment variable DS9_BINKEY may be used -to specify default bin cols for FITS bin tables. Example:
-
$ export DS9_BINKEY='[bin=rawx,rawy]'
-$ ds9 foo.fits # load FITS bin table, bin on rawx, -rawy
-
FITS -HEALPIX Table
-At load time, the user may provide just a file name or a file name -along with FITS extension name/number, image section specification, -and Healpix parameters. DS9 will automatically convert a FITS -HEALPIX binary or ascii table into a 2D image for display. FITS -extension names and parameters are case insensitive. The users may -specify a number of parameters on how to construct the image. Any -table with keyword PIXTYPE=HEALPIX or NSIDE=x will be processed as -an HEALPIX image. The following FITS keywords will be used if -present and not overwritten by a command line option: NSIDE, -COORDSYS, ORDER.
-
Syntax: -filename -filename[ext] -filename[ext][sect] -filename[sect] -filename[ext,sect] - filename[ext][hpx] -filename[ext][hpx][sect] -filename[ext][sect][hpx] -filename[hpx] -filename[hpx][sect] -filename[sect][hpx] filename[ext,hpx] - where: ext: see -FITS -Image sect: see FITS -Image - -hpx: [order=ring|nested] # default ring -[layout=equatorial|north|south] # default equatorial -[col=<column number>] # defaut 1 -[quad=<quadurant number>] # (1-4) default 1 -[system=equatorial|galactic|ecliptic|unknown] # default -unknown
-
-Example: -$ds9 foo.fits # default load -$ds9 foo.fits[1] # load first extension -$ds9 + + + + + File Formats + + + File Formats + FITS + FITS Image + FITS Binary Events Table + FITS HEALPIX Table + FITS Data Cube + FITS Multiple Extension + Data Cube + FITS Multiple + Extension Multiple Frames + FITS Mosaic + FITS Mosaic Data Cube + FITS RGB + Split FITS + Array + NRRD + ENVI + GIF + TIFF + JPEG + PNG + External Format Support + External Analysis + Support + Region Files + Contour Files + Color Lookup Table + WCS + Preference File + Startup File + TCL + FITS + DS9 supports FITS images and FITS binary tables. The following + algorithm is used to locate and to load the FITS image or table if + no additional information is provide: + + + Examine primary HDU, if IMAGE, load. + + Examine each extension HDU + + + If IMAGE, load. + + If BINARY TABLE, create IMAGE if the following is + true: + + + FITS COMPRESSED: keyword ZIMAGE is T. + FITS EVENTS: keyword EXTNAME is EVENTS,STDEVT, + or RAYEVENT, + column names X and Y are present. + FITS HEALPIX: keyword PIXTYPE is HEALPIX. + + + + + + If DS9 traverses the entire FITS file without + satisfying + one of the above, an error is generated. + + + FITS keyword inheritance is supported. All valid FITS + BITPIX values are supported, along with -16, + for + UNSIGNED SHORT. The following FITS keywords are + supported: + OBJECT + UNITS + BSCALE / BZERO + BLANK + DATASEC + LTV / LTM for physical coords + DTV / DTM for detector coords + ATV / ATM for amplifier coords + WCS keywords + WCS# keywords + FITS Image + At load time, the user may provide just a file name or a file name + along with FITS extension name/number and image section + specification. FITS extension names are case insensitive. When + specifying an extension, be sure to quote strings correctly to + pass + both the shell and DS9 parser. A image section specification is + used to specify the x,y limits of an image subsection. By default, + x and y coordinates are in IMAGE, use a 'p' as + the last character to indicate PHYSICAL coordinates. A + '*' indicates use the default for that axis only. Block + is + optional and defaults to 1. + Syntax: + filename + filename[ext] + filename[ext][sect] + filename[sect] + filename[ext,sect] + + where + + ext: + [extension name | extension #] + + sect: + [x0:x1,y0:y1[p]] + + [x0:x1,y0:y1,block[p]] + + [x0:x1,y0:y1,z0:z1[p]] + + [x0:x1,y0:y1,block,z0:z1[p]] + [*,y0:y1[p]] + + [*,y0:y1,block[p]] + + [*,y0:y1,z0:z1[p]] + + [*,y0:y1,block,z0:z1[p]] + [x0:x1,*[p]] + + [x0:x1,*,block[p]] + + [x0:x1,*,z0:z1[p]] + + [x0:x1,*,block,z0:z1[p]] + [*,*,block] + + [*,*,z0:z1] + + [*,*,block,z0:z1] + + + [dim1@xcen,dim2@ycen[p]] + + [dim1@xcen,dim2@ycen,block[p]] + + [dim1@xcen,dim2@ycen,dim3@zcen[p]] + + [dim1@xcen,dim2@ycen,block,dim3@zcen[p]] + [*,dim2@ycen[p]] + + [*,dim2@ycen,block[p]] + + [*,dim2@ycen,dim3@zcen[p]] + + [*,dim2@ycen,block,dim3@zcen[p]] + [dim1@xcen,*[p]] + + [dim1@xcen,*,block[p]] + + [dim1@xcen,*,dim3@zcen[p]] + + [dim1@xcen,*,block,dim3@zcen[p]] + [*,*,block] + [*,*,dim3@zcen] + + [*,*,block,dim3@zcen] + + + [dim@xcen@ycen] + + [dim@xcen@ycen,block] + [dim@xcen@ycen,zdim@zcen] + [dim@xcen@ycen,block,zdim@zcen] + + Example: + $ds9 foo.fits # default load + $ds9 foo.fits[1] # load first extension + $ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD' + $ds9 foo.fits[10:200,40:100] # image section + $ds9 + foo.fits[10:200,40:100,2] # image section, blocked by 2 + + $ds9 foo.fits[*,40:100] # only section y axis + $ds9 foo.fits[256@512@512] # section box at 512,512 + $ds9 foo.fits[2][100:200,100:200] # second extension, image + section + $ds9 foo.fits[2][100:200,100:200,2] # + second extension, image section, blocked by 2 + $ds9 + foo.fits[10:200,40:100,5:20] # cube section + $ds9 foo.fits[*,40:100,5:20] # only section y and z axes + $ds9 foo.fits[256@512@512] # section cube at 512,512 + $ds9 foo.fits[2][100:200,100:200,5:20] # second extension, + cube + section + $ds9 foo.fits[2][100:200,100:200,2,5:20] # second extension, + cube section, blocked by 2 + FITS + Binary Events Table + + At load time, the user may provide just a file name or a + file name along with FITS extension name/number, image section + specification, and binnng parameters. DS9 will automatically + convert an FITS binary events table into a 2D image for display. + FITS extension names and parameters are case insensitive. The + users + may specify a number of parameters on how to construct the image + and how to filter data. When specifying a filter, be sure to quote + strings correctly to pass both the shell and DS9 + parser. + + Syntax: + + filename + filename[ext] + filename[ext][sect] + filename[sect] + filename[ext,sect] + + filename[ext][bin] + + filename[ext][bin][sect] + + filename[ext][sect][bin] + + filename[bin] + + filename[bin][sect] + + filename[sect][bin] + filename[ext,bin] + + where: + ext: see FITS Image + sect: see FITS Image + + bin: + [bin=colx,coly] # bin counts + + [bin=colx,coly,filter] # bin counts with filter + + [bin=colx,coly,colz] # bin on colz + + [bin=colx,coly,colz,filter] # bin on colz with + filter + [bin=colz] # bin cols 'x', 'y', and + colz + [bin=colz,filter] # bin cols 'x', 'y', + and colz with filter + [key=colx,coly] + [binkey=colx,coly] + + (see Introduction +to + Filtering) + + Example: + $ds9 foo.fits # default load + $ds9 foo.fits[1] # load first extension + $ds9 foo.fits[BCKGRD] # load extension named 'BCKGRD' + $ds9 foo.fits[bin=detx,dety] # bin on detx,dety + $ds9 foo.fits[2][bin=rawx,rawy] # load ext 2, cols + rawx,rawy + $ds9 foo.fits[bg_events,bin=rawx,rawy] # load ext bg_events, + cols rawx,rawy + $ds9 foo.fits[bin=x,y,pha] # bin on x,y,pi + $ds9 foo.fits[bin=pi] # bin on x,y,pi + $ds9 'foo.fits[ccd_id==3&&energy>4000]' # quoted + filter + $ds9 '"foo.fits[ccd_id==3 && energy>4000]"' # + double + quoted filter + $ds9 'foo.fits[events][pha>5,pi<2]' # load extension + 'events' and filter + + + The shell environment variable DS9_BINKEY may be used + to specify default bin cols for FITS bin tables. Example: + $ export DS9_BINKEY='[bin=rawx,rawy]' + $ ds9 foo.fits # load FITS bin table, bin on rawx, + rawy + + FITS + HEALPIX Table + + At load time, the user may provide just a file name or a file name + along with FITS extension name/number, image section + specification, + and Healpix parameters. DS9 will automatically convert a FITS + HEALPIX binary or ascii table into a 2D image for display. FITS + extension names and parameters are case insensitive. The users may + specify a number of parameters on how to construct the image. Any + table with keyword PIXTYPE=HEALPIX or NSIDE=x will be processed as + an HEALPIX image. The following FITS keywords will be used if + present and not overwritten by a command line option: NSIDE, + COORDSYS, ORDER. + Syntax: + + filename + filename[ext] + filename[ext][sect] + filename[sect] + filename[ext,sect] + + filename[ext][hpx] + + filename[ext][hpx][sect] + + filename[ext][sect][hpx] + + filename[hpx] + + filename[hpx][sect] + + filename[sect][hpx] + filename[ext,hpx] + + where: + ext: see + FITS + Image + sect: see FITS + Image + + hpx: + [order=ring|nested] # default ring + [layout=equatorial|north|south] # default equatorial + [col=<column number>] # defaut 1 + [quad=<quadurant number>] # (1-4) default 1 + [system=equatorial|galactic|ecliptic|unknown] # default + unknown + + Example: + $ds9 foo.fits # default load + $ds9 foo.fits[1] # load first extension + $ds9 foo.fits[order=ring,layout=equatorial,col=1,quad=1,system=unknown] - $ds9 foo.fits[1,order=nested] # first extension, nested -order -FITS -Cube -A FITS Cube is a FITS image which contains more than 2 axes -(NAXES>2). DS9 will automatically detect if a cube is present -and will load all additional images. In addition, individual images -can be loaded one at a time into a cube. DS9 will display the Cube -dialog box which allows the user to select which 2 image to be -displayed. -FITS Multiple Extension -Cube -A FITS Multiple Extension Data Cube file is a FITS file with one or -more extensions, that is to be displayed as a data cube. Each image -does not have to be the same size, however, only the coordinate -systems from the first extension will be used for contours and -grids. -Example: -$ds9 -mecube foo.fits # load multiple extension fits file as -data cube -FITS Multiple Extension -Multiple Frames -Load a multiple extension FITS file into multiple frames. Please -note that files loaded via standard-in or the xpa fits command can -not be displayed using this method. -Example: -$ds9 -multiframe foo.fits # load multiple extension fits file -as multiple frames -FITS Mosaic -A FITS mosaic image may exist as a series of FITS files, or as one -FITS file with many extensions. A FITS mosaic may be loaded all a -one time, or by the segment. Once loaded, the multiple FITS images -are treated as one FITS image. - -DS9 supports three forms of mosaics: - - - - - - - - - - - - - - - - -IRAF contains the DETSEC and DETSIZE keywords. -See NOAO -IRAF Mosaic Data Structures WCS each FITS image contains a valid -WCS. HST WFPC2 valid HST WFPC2 data cube, -consisting of 4 planes, along with a fits ascii table containing -wcs information. - -Example: -$ds9 -mosaicimage iraf foo.fits # load mosaic iraf from one -fits file with multiple exts -$ds9 -mosaic iraf foo.fits bar.fits wow.fits # load mosaic iraf -from 3 files -$ds9 -mosaicimage wcs foo.fits # load mosaic wcs from one fits -file with multiple exts -$ds9 -mosaic wcs foo.fits bar.fits wow.fits # load mosaic wcs -from 3 files -$ds9 -mosaicimage wfpc2 bar.fits # load wfpc2 mosaic -$ds9 -mosaic foo.fits bar.fits wow.fits # load mosaic (wcs) -from 3 files -FITS -Mosaic Data Cube -A FITS Mosaic Data Cube is a FITS mosaic image which contains more -than 2 axes (NAXES>2). DS9 will automatically detect if a mosaic -data cube is present and will load all additional images. At the -same time, DS9 will display the data cube dialog box which allows -the user to select which 2 image to be displayed. -FITS RGB -A FITS RGB image may exist as three of FITS images, one FITS file -with three extensions, or as a FITS 3D Data cube, with three -slices, each representing the red, green, and blue channel. A FITS -RGB image may be loaded all a one time, or by the channel. Once -loaded, the multiple FITS images are treated as one FITS image. -Example: -$ds9 -rgbimage rgb.fits # load rgb image consisting of one fits -file with 3 image exts -$ds9 -rgbcube cube.fits # load rgb image consisting of one fits -data cube -$ds9 -rgb -red foo.fits -green bar.fits -blue wow.fits # rgb -image from 3 fits images -Split FITS -A split fits is a valid fits file in which two files contain the -header and data segments. -Array -Raw data arrays are supported. To load an array, the user must -provide the dimensions, pixel depth, and optional header size and -architecture type. -Syntax: -filename[arr] -filename[arr][sect] filename[sect][arr] - -where -sect: see FITS -Image arr: -xdim=value -ydim=value -zdim=value # default is a depth of 1 -dim=value -dims=value -bitpix=[8|16|-16|32|64|-32|-64] -skip=value # must be even, most must be factor of 4 -arch|endian=[big|bigendian|little|littleendian] -Example: -$ds9 -array bar.arr[xdim=512,ydim=512,zdim=1,bitpix=16] # load -512x512 short -$ds9 -array bar.arr[dim=256,bitpix=-32,skip=4] # load 256x256 float -with 4 byte head -$ds9 -array bar.arr[dim=512,bitpix=32,arch=little] # load 512x512 -long, intel -or alternate format: -filename[array(<type><dim><:skip><endian>)] - - -where: -type: -'b' 8 -bit unsigned char -'s' 16-bit short int -'u' 16-bit unsigned short int -'i' 32-bit int -'l' 64-bit int -'r' 32-bit float -'f' 32-bit float -'d' 64-bit float -dim: -int # x,y dim -int.int # x,y dim -int.int.int # x,y,z dim -skip: -int # number of bytes to -skip -endian: -'l' little endian -'b' big endian -Example: -$ds9 -array bar.arr[array(s512)] # load 512x512 -short -$ds9 -array bar.arr[array(r256:4)] # load 256x256 float with 4 byte -head -$ds9 -array bar.arr[array(i512l)] # load 512x512 long, -intel -The shell environment variable DS9_ARRAY may be used to -specify default array parameters. -Example: -$export DS9_ARRAY='[dim=256,bitpix=-32]' -$ds9 -array foo.arr # load 256x256 float -NRRD (Nearly Raw Raster -Data) -Images in NRRD are supported directly. Encodings supported: -raw, gzip -Syntax: -filename -filename[sect] -where: -sect: see FITS -Image -Example: -$ds9 -nrrd foo.nrrd -$ds9 -nrrd foo.nrrd[100:200,100:200] # cropped -ENVI -Images in ENVI are supported directly. Encodings supported: -BIL, BIP, BSQ. -Syntax: -filename -filename[sect] - -where: -sect: see FITS -Image -Example: -$ds9 -envi foo.hdr foo.bsq -$ds9 -envi foo.hdr foo.bsq[100:200,100:200] # cropped -GIF -Images in GIF are supported directly. For a Frame, the -average of the luminosity is used. For Frame RGB, each -channel is loaded directly. - -Syntax: -filename - -Example: $ ds9 -gif foo.gif -TIFF -Images in TIFF are supported directly. For a Frame, the -average of the luminosity is used. For Frame RGB, each -channel is loaded directly. - -Syntax: -filename - -Example: -$ ds9 -tiff foo.tiff -JPEG -Images in JPEG are supported directly. For a Frame, the -average of the luminosity is used. For Frame RGB, each -channel is loaded directly. - -Syntax: -filename - -Example: -$ ds9 -jpeg foo.jpeg -PNG -Images in PNG are supported directly. For a Frame, the -average of the luminosity is used. For Frame RGB, each -channel is loaded directly. - -Syntax: -filename - -Example: -$ ds9 -png foo.png -External File Support -DS9 supports external file formats via an ASCII description file. -When loading a file into DS9, these descriptions are referenced for -instructions for loading the file, based on the file extension. If -found, the command is executed and the result, a FITS image or FITS -Binary Table, is read into DS9 via stdin. -At start-up, DS9 first searches for the ASCII file, named -.ds9.filin the local directory, then in the users home -directory. -The file command first is macro-expanded to fill in user-defined -arguments and then is executed externally. -The ASCII file that defines the known image files consists of one -or more file descriptors, each of which has the following format: -Help description -A space-separated list of templates -A space-separated list of file types (not currently used) -The command line for the loading this file -type -Note that blank lines separate the file descriptions and should not -be used as part of a description. Also, the '#' character is a -comment character. - -The following macros are supported: $filename -For Example: -# File access descriptions: -# help explanation -# file template -# file type -# access command -IRAF IMH files -*.imh -IMH -i2f -s $filename -External Analysis Support -For more information about external analysis support files, see -Analysis. -Region -Files -DS9 can read and write a number of region file formats. See -Regions documentation for more -information. -DS9 -FUNTools -Ciao -SAOimage -IRAF PROS -FITS REGION Binary -Table -X Y -Contour -Files -See Contours -documentation for more information. -Color -Lookup Table -DS9 has a number of default colormaps available to the user. DS9 -also supports reading and writing color lookup table formats from -the following programs: - -SAOimage -SAOtng - -XImtool -DS9 uses the file extension to determine the color table format: - - - - - - - - - - - - - - - - - - - - - -Ext - -Format - .lut XImtool, SAOtng .sao DS9, SAOimage any other DS9 - -WCS -A new WCS specification can be loaded and used by the current image -regardless of the WCS that was contained in the image file. WCS -specification can be sent to DS9 as an ASCII file via XPA. The -format of the specification is a set of valid FITS keywords that -describe a WCS. -Example: - CRPIX1 + $ds9 foo.fits[1,order=nested] # first extension, + nested + order + + FITS + Cube + A FITS Cube is a FITS image which contains more than 2 axes + (NAXES>2). DS9 will automatically detect if a cube is present + and will load all additional images. In addition, individual + images + can be loaded one at a time into a cube. DS9 will display the Cube + dialog box which allows the user to select which 2 image to be + displayed. + FITS Multiple + Extension + Cube + A FITS Multiple Extension Data Cube file is a FITS file with one + or + more extensions, that is to be displayed as a data cube. Each + image + does not have to be the same size, however, only the coordinate + systems from the first extension will be used for contours and + grids. + Example: + $ds9 -mecube foo.fits # load multiple extension fits file as + data cube + FITS Multiple + Extension + Multiple Frames + Load a multiple extension FITS file into multiple frames. Please + note that files loaded via standard-in or the xpa fits command can + not be displayed using this method. + Example: + $ds9 -multiframe foo.fits # load multiple extension fits + file + as multiple frames + FITS Mosaic + A FITS mosaic image may exist as a series of FITS files, or as one + FITS file with many extensions. A FITS mosaic may be loaded all a + one time, or by the segment. Once loaded, the multiple FITS images + are treated as one FITS image. + + DS9 supports three forms of mosaics: + + + + + + + + + + + + + + + + + IRAF + contains the DETSEC and DETSIZE + keywords. + See NOAO +IRAF + Mosaic Data Structures + WCS + each FITS image contains + a valid + WCS. + HST WFPC2 + valid HST WFPC2 data + cube, + consisting of 4 planes, along with a fits ascii table + containing + wcs information. + + Example: + $ds9 -mosaicimage iraf foo.fits # load mosaic iraf from one + fits file with multiple exts + $ds9 -mosaic iraf foo.fits bar.fits wow.fits # load mosaic + iraf + from 3 files + $ds9 -mosaicimage wcs foo.fits # load mosaic wcs from one + fits + file with multiple exts + $ds9 -mosaic wcs foo.fits bar.fits wow.fits # load mosaic + wcs + from 3 files + $ds9 -mosaicimage wfpc2 bar.fits # load wfpc2 mosaic + $ds9 -mosaic foo.fits bar.fits wow.fits # load mosaic (wcs) + from 3 files + + FITS +Mosaic + Data Cube + A FITS Mosaic Data Cube is a FITS mosaic image which contains more + than 2 axes (NAXES>2). DS9 will automatically detect if a + mosaic + data cube is present and will load all additional images. At the + same time, DS9 will display the data cube dialog box which allows + the user to select which 2 image to be displayed. + FITS RGB + A FITS RGB image may exist as three of FITS images, one FITS file + with three extensions, or as a FITS 3D Data cube, with three + slices, each representing the red, green, and blue channel. A FITS + RGB image may be loaded all a one time, or by the channel. Once + loaded, the multiple FITS images are treated as one FITS image. + Example: + $ds9 -rgbimage rgb.fits # load rgb image consisting of one + fits + file with 3 image exts + $ds9 -rgbcube cube.fits # load rgb image consisting of one + fits + data cube + $ds9 -rgb -red foo.fits -green bar.fits -blue wow.fits # rgb + image from 3 fits images + + Split FITS + A split fits is a valid fits file in which two files contain the + header and data segments. + Array + Raw data arrays are supported. To load an array, the user must + provide the dimensions, pixel depth, and optional header size and + architecture type. + Syntax: + + filename[arr] + + filename[arr][sect] + filename[sect][arr] + + where + sect: see FITS + Image + arr: + + xdim=value + ydim=value + zdim=value # default is a depth of 1 + dim=value + dims=value + bitpix=[8|16|-16|32|64|-32|-64] + skip=value # must be even, most must be factor of 4 + arch|endian=[big|bigendian|little|littleendian] + + Example: + $ds9 -array bar.arr[xdim=512,ydim=512,zdim=1,bitpix=16] # load + 512x512 short + $ds9 -array bar.arr[dim=256,bitpix=-32,skip=4] # load 256x256 + float + with 4 byte head + $ds9 -array bar.arr[dim=512,bitpix=32,arch=little] # load + 512x512 + long, intel + + or alternate format: + filename[array(<type><dim><:skip><endian>)] + + where: + type: + 'b' 8 -bit unsigned char + 's' 16-bit short int + 'u' 16-bit unsigned short int + 'i' 32-bit int + 'l' 64-bit int + 'r' 32-bit float + 'f' 32-bit float + 'd' 64-bit float + dim: + int # x,y dim + int.int # x,y dim + int.int.int # x,y,z dim + + skip: + int # number of bytes to + skip + endian: + 'l' little endian + 'b' big endian + + Example: + $ds9 -array bar.arr[array(s512)] # load 512x512 + short + $ds9 -array bar.arr[array(r256:4)] # load 256x256 float with 4 + byte + head + $ds9 -array bar.arr[array(i512l)] # load 512x512 long, + intel + The shell environment variable DS9_ARRAY may be + used to + specify default array parameters. + Example: + $export DS9_ARRAY='[dim=256,bitpix=-32]' + $ds9 -array foo.arr # load 256x256 float + + NRRD (Nearly Raw Raster + Data) + + Images in NRRD are supported directly. Encodings supported: + raw, gzip + + Syntax: + + filename + + filename[sect] + + where: + sect: see FITS + Image + + + Example: + $ds9 -nrrd foo.nrrd + $ds9 -nrrd foo.nrrd[100:200,100:200] # cropped + ENVI + + Images in ENVI are supported directly. Encodings supported: + BIL, BIP, BSQ. + + Syntax: + + filename + + filename[sect] + + where: + sect: see FITS + Image + + + Example: + $ds9 -envi foo.hdr foo.bsq + $ds9 -envi foo.hdr foo.bsq[100:200,100:200] # cropped + + GIF + + Images in GIF are supported directly. For a Frame, the + average of the luminosity is used. For Frame RGB, each + channel is loaded directly. + + Syntax: + + filename + + Example: + $ ds9 -gif foo.gif + TIFF + + Images in TIFF are supported directly. For a Frame, the + average of the luminosity is used. For Frame RGB, each + channel is loaded directly. + + Syntax: + + filename + + Example: + $ ds9 -tiff foo.tiff + JPEG + + Images in JPEG are supported directly. For a Frame, the + average of the luminosity is used. For Frame RGB, each + channel is loaded directly. + + Syntax: + + filename + + Example: + $ ds9 -jpeg foo.jpeg + PNG + + Images in PNG are supported directly. For a Frame, the + average of the luminosity is used. For Frame RGB, each + channel is loaded directly. + + Syntax: + + filename + + Example: + $ ds9 -png foo.png + External + File Support + DS9 supports external file formats via an ASCII description file. + When loading a file into DS9, these descriptions are referenced + for + instructions for loading the file, based on the file extension. If + found, the command is executed and the result, a FITS image or + FITS + Binary Table, is read into DS9 via stdin. + At start-up, DS9 first searches for the ASCII file, named + .ds9.filin the local directory, then in the users home + directory. + The file command first is macro-expanded to fill in user-defined + arguments and then is executed externally. + The ASCII file that defines the known image files consists of one + or more file descriptors, each of which has the following format: + Help description + A space-separated list of templates + A space-separated list of file types (not currently used) + The command line for the loading this file + type + + Note that blank lines separate the file descriptions and should + not + be used as part of a description. Also, the '#' character is a + comment character. + + The following macros are supported: $filename + For Example: + # File access descriptions: + # help explanation + # file template + # file type + # access command + IRAF IMH files + *.imh + IMH + i2f -s $filename + External Analysis Support + For more information about external analysis support files, see + Analysis. + Region + Files + DS9 can read and write a number of region file formats. See + Regions documentation for more + information. + DS9 + FUNTools + Ciao + SAOimage + IRAF PROS + FITS REGION Binary + Table + X Y + + Contour + Files + See Contours + documentation for more information. + Color + Lookup Table + DS9 has a number of default colormaps available to the user. DS9 + also supports reading and writing color lookup table formats from + the following programs: + + SAOimage + SAOtng + XImtool + + DS9 uses the file extension to determine the color table format: + + + + + + + + + + + + + + + + + + + + + + Ext + + Format + .lut XImtool, SAOtng .sao DS9, SAOimage any other DS9 + + WCS + A new WCS specification can be loaded and used by the current + image + regardless of the WCS that was contained in the image file. WCS + specification can be sent to DS9 as an ASCII file via XPA. The + format of the specification is a set of valid FITS keywords that + describe a WCS. + Example: + CRPIX1 = -257.75 - CRPIX2 + 257.75 + CRPIX2 = -258.93 - CRVAL1 = --201.94541667302 - CRVAL2 + 258.93 + CRVAL1 + = + -201.94541667302 + CRVAL2 = --47.45444 - CDELT1 -= -2.1277777E-4 - CDELT2 -= 2.1277777E-4 - CTYPE1 = 'RA---TAN' - CTYPE2 = 'DEC--TAN' -Note that the WCS definitions can contain standard FITS 80 -character WCS card images, as shown above, or free-form name/value -pairs without the intervening "=" sign: - CRPIX1 -257.75 - CRPIX2 258.93 - CRVAL1 -201.94541667302 - CRVAL2 -47.45444 - CDELT1 -2.1277777E-4 - CDELT2 2.1277777E-4 - CTYPE1 'RA---TAN' - CTYPE2 'DEC--TAN' -Preference -File -A preference file is a valid tcl script generated by DS9 to save -the current preference items. See Preferences for more information. -Startup -File -If a startup file $HOME/ds9.ini is available, it is -sourced as the last step in initialization. The file permissions -must be group/world readonly. -Users may have several different startup files. DS9 looks for a -startup file with its own name. By default, if the application is -named ds9, it will look for .ds9.ini. However, if -the DS9 application is named foo, then DS9 will look for -.foo.ini. In this manner, the user can have several -predefined startup files that are activated by invoking DS9 with a -different application names. -TCL -TCL/TK script file. Users may customize the appearance and enhance -the capabilities of DS9 by sourcing their own TCL -scripts. - + -47.45444 + CDELT1 + = -2.1277777E-4 + CDELT2 + = 2.1277777E-4 + CTYPE1 = 'RA---TAN' + CTYPE2 = 'DEC--TAN' +
+ Note that the WCS definitions can contain standard FITS 80 + character WCS card images, as shown above, or free-form name/value + pairs without the intervening "=" sign: +
CRPIX1 + 257.75 + CRPIX2 258.93 + CRVAL1 -201.94541667302 + CRVAL2 -47.45444 + CDELT1 -2.1277777E-4 + CDELT2 2.1277777E-4 + CTYPE1 'RA---TAN' + CTYPE2 'DEC--TAN'
+
Preference + File
+ A preference file is a valid tcl script generated by DS9 to save + the current preference items. See Preferences + for more information. +
Startup + File
+ If a startup file $HOME/ds9.ini is available, it is + sourced as the last step in initialization. The file permissions + must be group/world readonly.
+ Users may have several different startup files. DS9 looks for a + startup file with its own name. By default, if the application is + named ds9, it will look for .ds9.ini. However, + if + the DS9 application is named foo, then DS9 will look for + .foo.ini. In this manner, the user can have several + predefined startup files that are activated by invoking DS9 with a + different application names.
+
TCL
+ TCL/TK script file. Users may customize the appearance and enhance + the capabilities of DS9 by sourcing their own TCL + scripts.

+ -- cgit v0.12

`IRAF`	`contains the DETSEC and DETSIZE keywords. -See NOAO -IRAF Mosaic Data Structures`
`WCS`	`each FITS image contains a valid -WCS.`
`HST WFPC2`	`valid HST WFPC2 data cube, -consisting of 4 planes, along with a fits ascii table containing -wcs information.`

-`Ext` -	-`Format` -
`.lut`	`XImtool, SAOtng`
`.sao`	`DS9, SAOimage`
`any other`	`DS9`

`IRAF` +	`contains the DETSEC and DETSIZE + keywords. + See NOAO +IRAF + Mosaic Data Structures` +
`WCS` +	`each FITS image contains + a valid + WCS.` +
`HST WFPC2` +	`valid HST WFPC2 data + cube, + consisting of 4 planes, along with a fits ascii table + containing + wcs information.`

+ `Ext` +	+ `Format` +
`.lut`	`XImtool, SAOtng`
`.sao`	`DS9, SAOimage`
`any other`	`DS9`