File Formats

From d0bb2c55c4a03a07ede942b5c20271cfde060995 Mon Sep 17 00:00:00 2001 From: William Joye Date: Fri, 26 Apr 2019 18:28:46 -0400 Subject: clean up html --- ds9/doc/ref/file.html | 1434 ++++++++++++++++++++++--------------------------- 1 file changed, 645 insertions(+), 789 deletions(-) diff --git a/ds9/doc/ref/file.html b/ds9/doc/ref/file.html index 012bcf0..b3f15dc 100644 --- a/ds9/doc/ref/file.html +++ b/ds9/doc/ref/file.html @@ -1,796 +1,652 @@ - - - - - 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: seeFITS Image +sect: seeFITS 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: seeFITS +Image +sect: seeFITS +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: + +.lut # XImtool, SAOtng +.sao # DS9, SAOImage +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. + +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
+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.`