From afadb7ab3d41f2eb64a0582db3aa3feb3c0712b7 Mon Sep 17 00:00:00 2001 From: William Joye Date: Tue, 30 Apr 2019 15:44:23 -0400 Subject: clean up doc --- ds9/doc/ref/file.html | 284 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 259 insertions(+), 25 deletions(-) diff --git a/ds9/doc/ref/file.html b/ds9/doc/ref/file.html index ba76cfa..32fda5a 100644 --- a/ds9/doc/ref/file.html +++ b/ds9/doc/ref/file.html @@ -58,32 +58,176 @@ DS9 supports FITS images and FITS binary tables. The following algorithm is used 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
+
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
+
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]

+
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
+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
+
$ 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
+
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
+
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
+
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.

@@ -107,57 +251,131 @@ See NOA -
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
+
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
+
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]
+
Syntax:
+filename[arr]
+filename[arr][sect]
+filename[sect][arr]

+where
+sect: seeFITS 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
+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
+
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 +
'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
+Syntax:
+filename
+filename[sect]
+
+where:
+sect: seeFITS 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
+Syntax:
+filename
+filename[sect]
+
+where:
+sect: seeFITS 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
+
+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
+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
+
+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
+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.
@@ -170,7 +388,16 @@ 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
+
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

@@ -228,7 +455,14 @@ A new WCS specification can be loaded and used by the current image regardless o     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'
+
    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

-- cgit v0.12