SkyView-in-a-Jar provides users with a local SkyView system on their own machines. Users can generate FITS, GIF, JPEG, … images from major surveys in any requested geometry, resample and mosaic their own data, overlay grids and catalog positions, and create their own surveys. SkyView-in-a-Jar comes completely ready to use as a single file.

In this default configuration all surveys accessible through the SkyView web pages are available. It is easy to add new surveys using local files or the Virtual Observatory Simple Image Access protocol. Images can be converted to standard data formats and overlaid with coordinate grids or catalogs object locations. Any HEASARC, Vizier or VO-Cone-Search compliant catalog can be queried.

The code itself is itself extensible. Users can add new samplers, projections, and coordinate systems. Even the classes which define the basic algorithms for finding surveys, selecting images within the survey, and mosaicking the images can be overridden. Users can insert their own pre- and post- processing functions to modify the input data or the resulting image.

Although there are many options available to the user, there are very few required inputs. Users need only specify the position around which they would like an image, and the survey from which the image is to be extracted. SkyView will take care of the rest.

This document provides a comprehensive user’s guide to SkyView-in-a-Jar.

This software is used as the basis for the SkyView web site http://skyview.gsfc.nasa.gov. Many, though not all, of the options can be used through the Web site and web users should use this document to understand the server side processing that the Web site perform.

1.1 Setup

SkyView-in-a-Jar is self contained within a single executable jar (short for Java ARchive) file. Jar files are a modified version of zip files used to store Java code. Jars can include data and program control files as well as the Java code. SkyView-in-a-Jar contains all of the control files needed to access the surveys available from SkyView’s standard Web interface. For a few surveys the survey data itself is included. For these surveys not even network connections are required. The input data from other surveys is accessed through HTTP and FTP protocols. Even when the underlying survey data is accessed over the Web, all processing and resampling is done on the local machine.

Users can download the jar file from

http://skyview.gsfc.nasa.gov/jar/skyview.jar

The same jar file is used for all operating systems. The file can be placed in any convenient directory.

SkyView requires at least a Java 1.5 (sometimes called Java 5.0) environment to run. Java distributions for most major operating systems are available at

http://www.java.sun.com

Java should be pre-installed on MacIntosh machines.

1.2 Running SkyView in a Jar

To run the SkyView program a user simply enters

java -jar path/skyview.jar command-line-arguments

Here path is the directory in which you have placed the SkyView jar file. The next chapter will describe the command line arguments (settings) in detail, but we will give a few examples below. You can use alias or macro capabilities in your native operating system to make the command more convenient. E.g., for in the sh or bash Unix shells you can define an alias with

alias skyview='java -jar mypath/skyview.jar'

and later just enter

skyview command-line-arguments

to run a query.

Suppose you would like to get a image of the quasar 3c273 in the optical and radio. The Digitized Sky Survey (DSS) is a popular all-sky optical survey. The FIRST (Faint Images of the Radio Sky at Twenty-one centimeters) radio survey also has coverage in this region. The first line (in bold) in the box above is all you need to enter to get FITS and JPEG images from both of these surveys.

The output shows that the program looks at 7 candidate source files for the DSS but uses only one of them in generating the output. It uses 1 of 5 for the FIRST survey. If the quicklook argument had been omitted, no JPEGs would have been produced, just FITS files.

The resulting images are also shown in the box. The jet is barely visible in the optical, but in the radio the source is double: the central AGN and the jet are both bright radio sources. [Note that the scale of the images is not the same. We did not specify either the size of the image or of the pixels, so the default pixel resolution for each survey was used, 1.7" and 1" respectively.]

The SkyView Java classes in the jar file can be used in other applications as well. Simply include the JAR file in your CLASSPATH. The only difference between a regular and executable jar file is that the later contains a manifest file that indicates how to start up when the -jar option is used in the java command. The SkyView Java application could also be started up with

java -cp pathto/skyview.jar skyview.executive.Imager key1=arg1...

If you want to use the Imager class or any of the other software packaged in the jar in other Java applications go right ahead. There are no limitations on the use of this software.

1.3 Simple Examples

A few examples of how to generate images using SkyView are given here. A detailed discussion of the meaning of the arguments is given in the next chapter.

java -jar skyview.jar position=3c273 survey=2mass-j,2mass-k,2mass-h

This returns three 300x300 [default size] pixel images named output1.fits, output2.fits, and output3.fits with the survey default pixel size for the three surveys selected.

java -jar skyview.jar position=3c273 survey=2mass-j,2mass-k,2mass-h \

quicklook=jpg nofits

Get the same images but only as JPEGs

java -jar skyview.jar position=3c273 survey=2mass-j,2mass-k,2mass-h \

quicklook=jpg scaling=sqrt

Get the same images as both FITS and JPEGs. Scale the JPEG brightness according to the square root of the intensity of the pixel.

java -jar skyview.jar position=3c273 survey=2mass-j,2mass-k,2mass-h rgb

Get the FITS images along with a 3-color JPEG where the rgb planes are from the three surveys.

java -jar skyview.jar position=3c273 survey=2mass-j \

scale=.0005 pixels=1200

This returns a single file 1200x1200 pixel file named output.fits with pixels of 1.8”.

java -jar skyview.jar position=3c273 survey=user \

userfile=ff1.fits,ff2.fits,ff3.fits scale=.003 \

sampler=Lanczos4 deedger=skyview.process.Deedger

This request looks at the three local files ff[1-3].fits and tries to create a mosaic from them using a fourth order Lanczos resampler. Boundaries between the input images are to be masked using the standard deedger class.

java -jar skyview.jar position=’horsehead nebula’ survey=dss \

postprocessor=null output=horsehead \

float coordinates=B1950

This asks for a DSS image of the Horsehead nebula but turns de-edging off. The output image should use 4-byte reals and be in B1950 coordinates. The output file will be named ‘horsehead.fits’

1.4 Incorporating ImageJ

Starting with version 1.9, the SkyView jar also contains a complete distribution of the ImageJ image display and analysis tool. ImageJ is a very powerful public domain software package developed by Wayne Rasband (wsr@nih.gov) at the National Institutes of Health. SkyView currently uses ImageJ functions for creating quicklook images in GIF, JPEG and other formats, including various scaling and color table operations. ImageJ has many other capabilities for users may to analyze images created by SkyView. Hundreds of plug-in modules are also available that provide powerful functionality in diverse areas.

Users should be able to start ImageJ itself with the SkyView jar using the command

java -cp skyview.jar ij.ImageJ [other arguments]

or they can download the ImageJ jar file at http://rsb.info.nih.info/ij. Much more information on ImageJ is available at that site. Future versions of the SkyView are likely to use additional ImageJ functionality. The SkyView jar includes both the ImageJ class and source code. Version 2.3 of SkyView-in-a-Jar includes version 1.38k of ImageJ. A few modifications to this version were made primarily to support drawing to text at angles and addition of specified colors to the current look up table.

You can start an ImageJ session to analyze SkyView images generated by this application by specifying the ImageJ setting.

1.5 Other included software.

Spline sampler.

The Spline sampler included here is a translation from C of the spline sampler of Philippe Thévanez (EPFL). Later versions of the C code are available at http://bigwww.epfl.ch/thevenaz/interpolation/.

DSS Decompression

The DSS Decompression (skyview.survey.HDecomp) class is based upon the Java code of Pierre Fernique (CDS) which is in turn based upon the C routines of R. White (ST ScI). Significant changes were made to the code before inclusion in SkyView.

FITS Library

SkyView uses the nom.tam.fits FITS library of Tom McGlynn (NASA/HEASARC). The complete library is included although no use is made of the methods to read or write tables.

1.6 Dependencies on Remote Systems

While all data processing occurs in the local system, the SkyView-in-a-Jar application may fail if remote resources are not available. The underlying data for a few low resolution surveys are included inside the jar file (e.g., 408 MHz and EGRET. The application will fail if it is unable to retrieve data for other surveys. For many surveys that data is fetched from the SkyView server at skyview.gsfc.nasa.gov. However the FIRST survey links to archives at the Space Telescope Science Institute. The 2MASS and NEAT surveys use archives at JPL. A number of other surveys, e.g., the SDSS, now use the VO Simple Image Access protocol, and link to URLs described in the survey descriptions. The <Images> area of the survey description will generally indicate the dependencies.

Catalog queries normally involve links to remote catalog sites and will fail if those sites are unavailable.

The other remote dependency for the application is in the resolution of target names. If the user specifies a target rather than a pair of coordinates, the coordinate converter service at the HEASARC is used to resolve this name into coordinates. The HEASARC service in turn calls the SIMBAD and NED name resolvers. The HEASARC service may also be used if the user enters the coordinates using characters other than numerics, signs, colons, commas and decimal points (e.g, 10h30m10.3s).

1.7 Batch processing.

In version 2.3 of the jar a beta-version of a new class skyview.executive.Batch was added to allow users to run a series of image requests in a single Java session. If this class is invoked the first argument is a special requests file and while subsequent arguments are standard settings. The first argument may be '-' to use the standard input for the requests file.

Each line of the requests file may contain one or more settings which will be concatenated to the settings given on the command line. Any number of requests can be made. E.g., suppose we have a requests file. myrequests.fil, containing

survey=dss,dss2r position=3c273

position=3c279

position=3c279 quicklook=gif pixels=600

position=Abell1656 output=special

If we try

java –cp .../skyview.jar skyview.executive.Batch myrequests.fil survey=dss2b quicklook=jpg

we will run four Imager requests. The first will create two output images output1_1.fits and output1_2.fits (and .jpg). The second will create a single output image. The thrird a larger output image and use the GIF format for the quicklook image. The last will create files names special4.fits and special4.jpg since the output stem was specified explicitly. The row number is concatenated to the stem to distinguish the outputs.

Note that settings in the request file override those specified on the command line.

2 Settings and Program Arguments

The operation of the program is controlled by settings. Settings are simply key-value string pairs, similar to Java Properties or Preferences, specified as an equation, e.g., survey=dss or position=3c273. When a value contains a comma, it is treated as an array of values, e.g., survey=dss,heao1 indicates that there are two values for the survey, dss and heao1. For some settings the value is not used, only that the setting is present. In this case the value need not be specified, e.g., the user can specify NoFITS=1 or just NoFITS to suppress FITS output. The keywords for settings are case-insensitive, but the values may not be, especially when they refer to files or class names. E.g., output=test is equivalent to OUTPUT=test but not to output=TEST [unless the underlying file system is case-insensitive]. In this document we tend to use mixed capitalization of the keywords that helps make their meaning clearer but we have not attempted to be rigorously consistent.

The special string "null" can be used as the value for a setting. This unsets a previously set setting. E.g., Deedger=null may turn off de-edging for a survey which enables it by default. A system setting of _NullSettings is used to track settings that have been explicitly nulled so that they are not inadvertently turned back on.

The user can set settings on the command line, but they are also set in several other ways. Settings are processed in the following order:

At startup the application attempts to find a system settings file. This establishes base defaults for the system. The application also ensures that values are set for critical system settings (e.g., the class names for key processing objects). These default settings are normally read in through the system resource skyview.settings. If users wish to provide their own default settings, they can override the settings provided in the jar file by creating a skyview.settings file in the current directory, or by pointing to a file in any location (and of any name) using the environment variable SKYVIEW_SETTINGS.
Users can specify settings on the command line. Any number of settings can be given on the command line. If the value for a setting includes a blank or character that will be treated specially by the shell processing the command, then setting may need to be enclosed in quotes or the special characters may need to be escaped in some fashion. E.g., typically you will need position=’3C 273.
The user can specify one or more files of settings using the eponymously named setting 'Settings'. These are parsed immediately after the command line arguments. Note that if you want to process two settings files use "settings=file1,file2" not "settings=file1 settings=file2". The latter will only read file2.
After the user specified settings are retrieved, one or more SettingsUpdater classes may be called depending upon the value of the SettingsUpdaters setting. These classes may look at the current settings and modify them. This can be used, e.g., to support obsolete settings or to fill in defaults for new featus.
As each survey is processed, the <Settings> element in the survey definition file is parsed for survey specific settings. These settings will not override any settings already in place. These are used for survey defaults like image scaling, or de-edging.
Later in survey processing, settings may also be set in the <Images> element. These will override any user specified settings. Any XML element found other than the <Image> elements inside the <Images> element specifies a setting. These are intended to define and communicate with the classes that are used to build survey images but users are free to exploit this behavior to set settings that the user cannot override (at least without editing the survey description).
Settings are also specified and consumed internally by various classes but normally this is invisible to the user. The keys for such internal settings are usually prefixed with a “_”.

When a setting is set multiple times, only the last value is effective. Some settings, especially the internal settings, may change as the program continues processing. E.g., if the user does not define the size or pixel scale of the image to be output, then the pixel scale will normally be taken from a default established for each survey. If the user asks for multiple surveys, the pixel scale (and hence the total size of the image) could be different for each.

2.1 Settings Files

Both system and user settings files are simple ASCII files. Each line can be a blank, a comment line (first character of the line is ‘#’) or specify a single setting. This example might be used as the systems settings:

# An example skyview.settings file.

Pixels=500

Projection=Sin

Coordinates=J2000

Sampler=Lanczos

Equinox=2000

Resolver=NED-SIMBAD

XMLroot=$SKYVIEW_XMLROOT

Mosaicker=skyview.process.Mosaicker

SurveyFinder=skyview.survey.XMLSurveyFinder

ImageFinder=skyview.process.imagefinder.RecursiveImageFinder

SettingsUpdaters=skyview.executive.BatchCompatibility,skyview.ij.IJProcessor

System environment variables can be used within settings. In this example an environment variable is used to set the XMLRoot (the directory where survey XML files may be found). When a value begins with a $ the value of the corresponding environment variable will be used but the line will be ignored if the environment variable is not defined. This allows users to override the default settings using environment variables using two lines in the settings file, e.g.,

Projection=Sin

Projection=$PROJ

will use a Sine projection unless the user overrides it by specifying the PROJ environment variable or on the command line.

While a user can specify any number of settings on the command line, only one setting may be given on each line in a Settings file.

2.2 Settings Summary

The following table gives a complete listing of all settings currently used in SkyView and where they are discussed in this document. A few settings that most users will want to be sure to understand are highlighted in bold type. Settings beginning with an underscore are used internally by the program but are not normally visible to users.

`
*Keyword*	*Discussed*	*Short Description*

Cache	2.3.4.5	Directory[ies] to save remote files for later reuse.
_CachedFile	4	List of files downloaded for current survey
Catalog	2.3.9.1	Catalog[s] queried for objects in output image
CatalogFile	2.3.9.2	File to save catalog data in
CatalogFilter	2.3.9.4	Constraint to be applied to catalog data
CatalogIDs	2.3.9.6	Plot catalog identifier numbers
CatalogRadius	2.3.9.3	Set the maximum radius for searching for catalog data.
COLTAB	2.4	Batch compatibility synonym for LUT
ComboSamplers	2.3.3.2	Paired set of samplers to do sampling
Compress	2.3.4.2	Compress FITS output (gzip)
Contour	2.3.6.1	Survey for which a contour map is to be generated
ContourSmooth	2.3.6.2	Smoothing applied to contour images
Coordinates	2.3.2.7	Coordinate system used in output image
_CoordinateSystem	4	Coordinate system name suitable for HTML output
CopyWCS	2.3.2.5	Use frame of this file for output image
CornersOnly	2.3.10.7	Check only corners when selecting images
_CurrentSurvey	4	Name of survey currently being processed
Deedger	2.3.10.14	Deedging class to match backgrounds of images
DefaultSIASurveys	4.3	Surveys to be searched by default in SIA request
DescriptionXSLT	2.3.11.7	XSLT for transforming survey descriptions to HTML
Draw	2.3.8.1	One or more drawing commands
DrawAngle	2.3.8.2	Initial rotation angle for drawing
DrawFile	2.3.8.3	Draw file[s] to be read and executed.
DSS2Prefix	5.1.4	Prepended to cached files from DSS2 style surveys
Ebins	2.3.3.3	Specify the energy binning of 3-d images.
Equinox	2.3.2.9	Equinox of the coordinate system
EQUINX	2.4	Batch compatibility synonym for Equinox
ErrorMsg	4	The last error encountered by the program
ExposureFileGen	2.3.10.13	Replace string used to generate exposure file names
ExposureFileMatch	2.3.10.12	Matching string used in generating exposure files
ExposureFinder	2.3.10.11	Class to find exposure for input images
ExposureKeyword	2.3.10.8	FITS keyword containing exposure value
File	2.4	Batch compatibility synonym for Output
FilePrefix	5.1.8.1	String prepended to file names in Image elements
FindRetry	2.3.10.6	Retry with all candidates when no source pixel found
FITS	5.1.7	Content to be included in FITS files
Float	2.3.4.3	Use 4-byte rather than 8-byte floating point FITS
FooterTemplate	2.3.11.5	Template file for bottom of HTML pages
GeometryTwin	5.1.4	Surveys with the same geometry as current survey
Grid	2.3.7.1	Include coordinate grid on output image
GridLabels	2.3.7.2	Label coordinate grid with coordinate values
HeaderTemplate	2.3.11.3	Template file for top of HTML pages
HTMLWriter	2.3.11.1	Class that writes HTML wrapper
ImageFactory	5.1.8	Class that creates images from a given survey
ImageFinder	2.3.10.3	Class to find best candidate image for each pixel
ImageGenerator	5.1.8.2	Class that finds candidate images from a given survey
ImageJ	2.3.5.12	Keep the ImageJ user interface running
_ImageMax	4	Maximum value in output image
_ImageMin	4	Mininum value in output image
ImageSize	5.1.8	A typical size for images in the survey
_ImageXPixel	4	Width of output image in pixels
_ImageXSize	4	Width of output image in degrees
_ImageYPixel	4	Height of output image in pixels
_ImageYSize	4	Height of output image in degrees
Invert	2.3.5.5	Invert the specified lookup table.
ISCALE	2.4	Batch compatibility synonym for Scaling
Lat	2.3.2.4	Dec/Latitude coordinate of center of image
Level	2.3.2.8.1	TOAST Grid Parameter
LocalURL	2.3.4.8	Translate a URL to a local file
Lon	2.3.2.3	RA/Longitude coordinate of center of image
LUT	2.4	Load the specified lookup table.
MAPROJ	2.4	Batch compatibility synonym for Projection
Max	2.3.5.7	Maximum value to use for output quicklook images
_Meta_xxxx	5.1.5	Standard metadata regarding the survey.
Min	2.3.5.6	Minimum value to use for output quicklook images
Mosaicker	2.3.10.10	Class to be used to resample and combine images
Name	5.1.2	The full name of the survey
NoExit	2.3.10.1	Do not exit after completing image generation
NoFITS	2.3.4.4	Suppress output FITS image
_NullSettings	2	Settings explicitly deleted by user
Offset	2.3.2.14	Offset of the image center from specified position
OnlineText	5.1.6	Text to include in HTML output
Output	2.3.4.1	Stem for output files
_Output1 (2,3)	4	The output FITS name for the n’th survey
_Output_FITS	4	Name of output FITS file
_Output_QL	4	Name of output quicklook image file
_Output_RGB	4	Name of output RGB image
OutputRoot	2.3.11.6	Root for output images in CGI request handling
Pixels	2.3.2.11	Number of pixels in the output image
PIXELX,PIXELY	2.4	Batch compatibility synonym for Pixels
PlotColor	2.3.5.10	Color of overlays in plots
PlotFontSize	2.3.5.11	Size of the font for plot overlays
PlotScale	2.3.5.9	Scale for symbols in overlays
Position	2.3.2.1	Target name or coordinates of center of image
PostProcessor	2.3.10.15	Class[es] processing output image after mosaicking.
PreProcessor	2.3.10.9	Class[es] processing input images
Projection	2.3.2.8	Map projection used in image
_Projection	4	Projection name in format suitable for HTML output
PurgeCache	2.3.4.7	Delete survey files downloaded in request
Quicklook	2.3.5.1	Format for quicklook image data
RefCooords	2.3.2.6	Non-standard center for coordinate transformation
Resolver	2.3.2.13	Name resolver to convert target names to coordinates
RETURN	2.4	Format of HTML output (batch compatibility)
RGB	2.3.5.2	Create an RGB composite from three input surveys
RGBSmooth	2.3.5.3	Smoothings applied to components of RGB image
RGBWriter	2.3.11.2	Class that writes HTML for RBG image generation
Rotation	2.3.2.12	Angle of rotation of output image
Sampler	2.3.3.1	Set the sampling algorithm to be used
_Sampler	4	Sampler in format suitable for HTML output
SaveBySurvey	2.3.4.6	Save cached files sorted into survey directories
Scale	2.3.2.10	Size of the output pixels in degrees
Scaling	2.3.5.8	Scaling between pixel values and quicklook intensities
SCOORD	2.4	Batch compatibility synonym for Coordinates
Settings	2.3.1.2	File[s] from which to read settings
SettingsUpdaters	2.3.10.16	Class[es] that may update settings
SFACTR	2.4	Batch compatibility synonym for Size
ShortName	5.1.1	The short name[s] of a survey
SIAPCoordinates	5.1.8.2	Default coordinate system for SIAP based survey
SIAPFilter	5.1.8.2	String to compare filter field to for filtering files
SIAPFilterField	5.1.8.2	Field name to use in filtering files
SIAPMaxImages	5.1.8.2	Maximum number of SIAP images to use
SIAPNaxis	5.1.8.2	Default sizes of images returned in SIAP survey
SIAPProjection	5.1.8.2	Default projection for SIAP survey
SIAPScaling	5.1.8.2	Default size of pixels for SIAP survey
SiapUrl	5.1.8.2	Base URL for SIAP service for survey
Size	2.3.2.2	Size of the output image in degrees
Smooth	2.3.3.4	Smoothing to be applied to output image
SpellPrefix	5.1.8.2	String prepended to all spells of a given survey
SpellSuffix	5.1.8.2	String appened to all spells of a given survey
StrictGeometry	2.3.10.4	More stringent checking of geometry
Subdiv	2.3.2.8.1	TOAST Grid parameter
Survey	2.3.1.1	Surveys used to generate images
_SurveyCount	4	The index of the current survey
SurveyFinder	2.3.10.2	Class that finds all available surveys
SurveyManifest	2.3.1.5	Override default manifest file of default surveys
SurveysHeader	4.2	Text to proceed description of all surveys
SurveysTrailer	4.2	Text to follow description of all surveys
SurveyTemplate	2.3.11.4	Template file used for HTML for one survey's image
SurveyXML	2.3.1.3	File[s] contain survey descriptions
TileX	2.3.2.8.1	TOAST Projection grid parameter
TileY	2.3.2.8.1	TOAST Projection grid parameter
TOASTGrid	2.3.2.8.1	TOAST Projection grid properties
_TotalCatalogCount	4	Number of rows returned in catalog queries
UserFile	2.3.1.6	File[s] defining the components of the User survey.
VCOORD	2.4	Batch compatibility synonym for Position
XMLRoot	2.3.1.4	Directory containing survey description files

2.3 Detailed Settings

This subsections of this section discuss in detail all of the settings that are normally used on the command line. Settings that are normally set in the survey description files are discussed later.

2.3.1 Survey definition settings

These settings define the surveys that are available for processing and which surveys the user wishes to use to generate images.

2.3.1.1 Survey

The survey setting indicates which survey or surveys the user wishes to generate an image for. If more than one survey is desired, the values should be separated by commas. The list of all surveys known (by default) to the program can be generated by invoking the application with no arguments. This will give a quick description of the arguments and a list of known surveys. Survey names are case insensitive. A survey setting is required to generate an image.

The survey user is special. It indicates that one or more files indicated in the userfile argument are to be used as the survey. Using the survey=user and userfile=file1,file2,... arguments, users can resample and mosaic local data files.

Over 80 wavebands/surveys are accessible through the standard distributions. Detailed

Information on all surveys in the jar can be found using the skyview.survey.XMLSurveyDescription class or on line at the SkyView Web site at http://skyview.gsfc.nasa.gov/cgi-bin/survey.pl.

Example:

Survey=DSS,2MASS-K

2.3.1.2 Settings

This setting may be used to specify one or more files that are to be read for settings. The files specified here are processed after the system settings file (if any) but before any survey specific settings are extracted. If the same setting is set in multiple locations, only the last setting is used. The format of settings files is discussed above in section 2.1.

Example:

settings=dir/mydefaults.set,thisrequest.set

2.3.1.3 SurveyXML

This argument allows the user to specify one or more survey XML descriptors that users can generate images from (see below for details of the format). Use this argument to specify individual files and the XmlRoot argument to specify an entire directory.

Example:

SurveyXML=surveys/mysurv1.xml,surveys/mysurv2.xml

2.3.1.4 XMLRoot

This argument gives a directory where survey XML files are to be found. Each ‘.xml’ file in the directory will be treated as a survey descriptor file.

Example:

XMLRoot=/survey/docs/xml

2.3.1.5 SurveyManifest

The Survey manifest is a file (or Java resource) that lists survey XML files. By default the Survey Manifest is given in the system resource surveys/survey.manifest that is included in the jar. Each line in the manifest is the name of a file or resource (i.e., file inside the jar) that is a survey description file.

Example:

SurveyManifest=mysurvey/docs/mysurvey.manifest

2.3.1.6 UserFile

This argument is used to specify one or more files that are treated as the constituent image files of the ‘user’ survey. Users can resample and mosaic local files easily using this argument and the user survey.

Example:

Userfile=myfile1.fits,myfile2.fits

2.3.2 Geometry settings

These settings define the configuration of the output image.

2.3.2.1 Position

The position argument gives the center position for which images are requested. It may be either a coordinate pair, or a target name. One of Position, the Lon/Lat pair or the CopyWCS settings is required.

Examples:

Position=3c273

Position=’10 20 30, -15 16 22’

2.3.2.2 Size

This gives of the entire image in degrees. The size may be specified as one or two values. If only one value is specified the image height and width are the same. Note users can specify either the size of the entire image using this setting, or the size of an individual pixel using Scale. If both are specified the Scale setting is ignored. The size refers to the nominal size of the image in the projection plane, not the actual distance between points at corners of the image which is affected by the distortions of the projection. I.e., for a given image Size=Pixels*Scale.

Examples:

size=0.25 An image 0.25 degrees on a side

size=360,180 An all-sky image

2.3.2.3 Lon

This argument gives the Longitude or right ascension of the center of the image. Lon/Lat arguments supersede the position if both are specified.

2.3.2.4 Lat

This argument gives the Latitude or declination of the center of the image.

2.3.2.5 CopyWCS

If you wish to duplicate the geometry of a given FITS file, specify the file with the desired geometry here. Other output geometry arguments will be ignored.

Example:

CopyWCS=myfile.fits

2.3.2.6 RefCoords

Fixed projections (Ait, Car, Toa, Sfl) are normally constructed around some standard position in the sky (the origin of coordinates or the pole). Use RefCoords to change this standard location. E.g., an Aitoff projection is normally projected with the center of the projection at the coordinate origin, even if the image is centered at some other coordinate. The actual center of the projection is changed by RefCoords. Thus to create an Aitoff projection centered on the north pole use:

Projection=Ait RefCoords=0.,90. Position=0.,0.

2.3.2.7 Coordinates

This argument gives the coordinate system used for the output image. The first letter in the value gives the type of coordinates. If a number is appended then this is the epoch of the equinox of the coordinate system.

Recognized values include

J Julian equatorial coordinates based on the FK5 catalog

B Besselian equatorial coordinates based on the FK4 catalog

ICRS International Coordinate Reference System coordinates these differ by of order 100 milliarcseconds from J2000 coordinates.

Gal Galactic coordinates (L_ii, B_ii)

H Helioecliptic coordinates. These are ecliptic coordinates with longitude=0 set to the position of the sun. The equinox of the coordinates are used for the epoch.

E Ecliptic coordinates.

The single letter values may be combined with an epoch, e.g., J2000, B1950, E2020.123

The default coordinate system is J2000.

Examples:

Coordinates=J2000

Coordinates=Galactic

2.3.2.8 Projection

The three letter designation used to specify the projection of the output image. This uses the three letter suffix in the FITS CTYPE keywords as the setting value (with the first letter capitalized and the others lower case). Supported projections include:

Cartesian or Plate Caree (Car): The Cartesian projection transforms coordinates directly into an RA/Dec plane. This projection is normally centered on the coordinate origin and has extreme distortions near the pole. It is often used for all-sky maps but can be used for limited regions so long as they are not near the pole.

Sanson-Flamsteed or Global-Sinusoidal (Sfl): This is an all-sky projection similar to the Car projection, but where the horizontal extent at each latitude is reduced by the cosine of the latitude, resulting in an equal-area projection. The suffix GLS is also recognized in FITS files for this projection. This projection is normally used in all sky projections.

Tangent plane or gnomonic (Tan): The gnomonic projection can be visualized by placing a plane tangent to the celestial sphere and drawing lines from the center of the sphere, through the point to be projected and extending the line till it intersects the plane. The point of tangency is the reference point of the projection. Normally this is at (or near) the center of the image. The gnomonic projection is probably the most common projection used for small astronomical images. It can only represent half the sky and has significant distortions for fields larger than a few degrees. The circle 90 degrees from the tangent point projects to infinity in the projection plane. Great circles in the celestial sphere (e.g., lines of constant right ascension) transform to straight lines in the projection plane.

Stereographic (Stg): This projection is similar to the Tan projection except that instead of drawing lines from the center of the sphere, we draw lines from the point opposite the tangent plane. The entire sky projects to the full plane. Circles on the sphere project to circles in the projection plane. However the center of the circle on the sphere will not project to the center of the corresponding circle in the plane.

Sine or Orthographic (Sin): The sine projection is commonly used for small scale images in astronomy especially for images in the radio. This projection can be visualized in a fashion similar to the gnomonic projection with a plane tangent to the celestial sphere. However in this case the line is drawn from the plane to the point on the sphere perpendicular to the plane. As with the gnomonic projection only half the sphere can be represented in the projection plane, but the projection is finite. A full sine projection looks like the sphere seen from a distance. The NCP projection is a special case of the Sine projection where tangent point is fixed at the pole.

The Hammer-Aitoff or Aitoff (Ait): The Aitoff projection is an equal-area projection that transforms the sky into a elliptical region. The Aitoff projection is usually used for all sky projections around the origin. Maximum distortions are much less severe than for the Cartesian projection.

Zenithal equal area projection (Zea): This equal area projection transforms rings around a given reference point into rings in the projection varying the width of the rings in the projection plane to conserve area. The point opposite the reference point is transformed into a bounding circle in the projection plane. This equal area projection allows the user to select the region of minimum distortion unlike the Aitoff projection.

The COBE Quadralaterized Spherical Cube (Csc) projection is a peculiar beast. The celestial sphere is projected onto the six faces of a cube. The projection on each face is non-standard but intended to minimize distortions. The advantage of the Csc projection is that one can pick how to join the faces so that any given region can be studied distant from the edges of the projection. Currently only the standard COBE sidewise T is used. The four equatorial faces are attached in a line and the two polar faces are attached to the top and bottom of the right most face which includes the coordinate origin.

The Toa (Tessellated Octahedron Adaptive Spherical Transformation or TOAST) projection is described in more detail below. This new projection, developed by Jonathan Fay (Microsoft) as part of the WorldWideTelescope (WWT) project, is specifically intended to support an image hierarchy where an all-sky image is divided recursively into sub-tiles. The TOAST projection is an all-sky projection into a square. Thus unlike the Aitoff projection there are no ‘beyond the edge’ pixels and unlike the Cartesian projection there are no singularities. The projection is not equal-area and cannot be represented as an analytic transformation (the transformation is continuous but not differentiable) between grid and spatial coordinates, however it can be rapidly and efficiently computed for all pixels in one of the recursive tile elements discussed above. The TOAST projection uses the ToastGrid setting when creating such tiles.

The default projection is Tan.

Example:

projection=Tan

Global geometry of projections

Tan	Sin	Ait

Zea	Car	Csc

Sfl	Arc	Stg
(Images generated with: survey=408mhz Projection=Xxx position=0,0 size=360,180 pixels=100,50 coordinates=g grid)

2.3.2.8.1 The TOAST Projection

Since the Tessellated Octahedron Adaptive Spherical Transformation (TOAST) is not yet described in the general literature elsewhere, it is described below in some detail.

Consider a sphere enclosed in an octahedron. We can ‘project’ each octant of the sphere onto one plane of the octahedron. The TOAST projection does such a transformation where the poles are projected to two opposite vertices of the octahedron and the points at 0, 90, 180 and 270 degrees of longitude along the equator are projected to the middle four vertices. Superficially this is similar to the CSC projection with an octahedron as the solid rather than a cube. However, as shown below the details of the projection are very different and TOAST uses a geometric construction rather than an analytic transformation to define the mapping of individual points.

TOAST makes a topological transformation of the triangles of the tetrahedron to a square in the plane. In the tetrahedron take the four triangles that meet at the North Pole. Stretch each of these triangles expanding the vertex that touches the pole from 60 to 90 degrees. The triangles transform from equilateral to right isosceles. As the triangles stretch the pyramid they formed collapses into a plane. The four triangles now combine to make the diamond shown on the left below. We do the same for the four triangles which meet at the South Pole. We have two diamonds overlaying one another. To complete the topological transformation we treat the equator as a hinge and flip the four southern triangles. They blossom outwards and complete the square of the TOAST projection shown below to the right.

Transforming a tetrahedron to a square.

Left: northern hemisphere; right: all-sky.

The four squares in the right outline are four base pixels for the TOAST projection. Each pixel is comprised of two triangles and represents one quarter of the sky. In the CSC projection and similar ones used in astronomy, the geometry within the planes is done by using some analytic transformation from sky coordinates to positions within the planes. In TOAST the projection is defined by recursively specifying the transformation between individual points on the plane and gradually building a dense grid mapping between the celestial sphere and the TOAST square.

Subdividing tiles in HTM and TOAST

TOAST maps directly to the Hierarchical Triangular Mesh (HTM) pixelization of the sky. HTM (see http://www.sdss.jhu.edu/htm whence the top figures above are derived) is used extensively in creating efficient indices for large catalogs, notably the Sloan Digital Sky Survey. HTM takes the vertices of the 8 base triangles and uses them to define spherical triangles (i.e., by joining the vertices with arcs of great circles). New triangles are formed recursively from these base triangles. At each level of the recursion each spherical triangle is split into four sub-triangles by joining the midpoints of each of the edges. The full transformation between the sky and the TOAST plane is specified by similarly splitting the corresponding triangles in the TOAST projection and associating the vertices of these triangles with the vertices in the HTM decomposition. Thus in the table above there is a one-to-one mapping between the vertices in the successive levels of the HTM decomposition and the TOAST planes below with the exception that the South Pole projects to all four corners of the TOAST projection and southern points (latitude<0) on the great circles that go through 0 and 90 degrees longitude are show up twice on one of the sides of the square.

Note that in each quadrant only one of the sinister or dexter diagonals is used in subdividing the TOAST pixels.

To transform between the TOAST projection plane to or from the celestial sphere for some arbitrary point requires recursion until a point is found sufficiently close, within some epsilon, to the point we wish to transform. In the figure below, successive triangles get closer and closer to the desired point. This recursion can be relatively inefficient compared to other projections. SkyView supports it using an epsilon of about 10^-12degrees. In practice one need only calculate the transformations for the region of any one of the original triangles since the transformation in any of the others can then easily be computed by exploiting the symmetries of the transformation.

Localizing a point recursively

The TOAST projection can be used very efficiently if we restrict the points of interest to positions that match the vertices of the higher level triangles. We can consider the TOAST projection to comprise a hierarchy of pixels. The single Level 0 pixel is the entire sky considered as a single pixel. We divide that into the four quadrants of longitude to get the four Level 1 pixels. Subdividing these we get 16 level 2 pixels and so forth. At each level pairs of the HTM triangles are joined to comprise the TOAST pixels. Note that while all the pixels at a given level have the same area in the TOAST projection by construction, they do not correspond to equal area pixels on the sky.

A powerful technique for allowing users to browse large images or surveys is to send the user progressively more refined images as they zoom in. The TOAST hierarchy naturally supports this. A user can request a given data within a given bounding pixel and ask to have that bounding pixel subdivided into a number of sub-pixels. E.g., the user might start with a 256x256 all-sky image. This has a level 0 bounding pixel, and level 8 individual pixels. If the user is interested in an object that happens to be in a pixel (10,128), they might ask for a higher resolution image that includes the same region, but does not cover the entire sky. Since TOAST does not have the singularities associated with other common all-sky projections it can do this particularly well.

ToastGrid

SkyView supports computing efficient transformations for such grids using the ToastGrid setting. This setting has four parameters: l, X,Y and s. The level l is 0 or a positive integer and gives the level of the bounding pixel, e.g., 0 for an all-sky image, 1 for a quarter of the sky and so forth. The size of the output the image is roughly 180/2^l degrees. X and Y are the coordinates of the bounding pixel within the pixels of that level, 0 ≤ X < 2^l(and the same for Y). The number of pixels into which the bounding pixel is to be divided in each dimension is set by the subdivision exponent, S, to 2^s [+1]. The number is 1 greater than the power of 2 if any sampler other than the clip sampler is used. This is because the gridding algorithm essentially gives us the corners of the pixels, not their centers. To fully sample the grid we need an odd number of pixels. The Clip sampler naturally uses the corners rather than the centers so it gives one fewer pixel in each dimension.

The ToastGrid setting completely specifies the output geometry of the image except for the coordinate system used. Users should be careful to ensure that the specifications are consistent or use the ToastGridder class discussed below. If projection is not set to Toa the ToastGrid setting is ignored.

To work with the WorldWideTelescope, SkyView also supports some alternate syntax for specifying the TOAST Grid. The class skyview.request.ToastGridder is a SettingsUpdater that allows the user to specify the elements of the TOAST Grid using the parameters Level, TileX, TileY and Subdiv. It then sets the appropriate values for ToastGrid, Pixels, Offset, Position and Scale.

Example:

ToastGrid=3,1,7,8

Extending the TOAST projection

The simple TOAST projection is finite with square edges. Users may occasionally wish to extend the projection beyond these edges (e.g., for the benefit of resamplers or just for appearance). The projection can be extended without discontinuities by repeating the map while inverting it along the axis we are extending. E.g., the fiducial center square may be flanked on each side by squares flipped horizontally, with squares flipped vertically above and below and squares inverted in both dimensions on the diagonals. Currently SkyView does not support this extension.

2.3.2.9 Equinox

If the coordinate system only specified a coordinate type, the equinox can be specified separately. If an equinox was specified in the coordinates settings it overrides the equinox keyword.

Example:

Equinox=1980

2.3.2.10 Scale

Scale gives the size of pixels in the output image and corresponds to the FITS CDELT keywords. Scale may be specified as a scalar, in which case the pixels are square, or two values may be given if rectangular pixels are desired. The scale is always positive but output images follow the astronomical convention where the longitude decreases along a horizontal line. The scale is specified in degrees per pixel.

The default scale depends upon the survey. If you do not specify an explicit scale, and you choose more than one survey, then the scale may differ among the images generated in single request.

If there is no survey defined default, then the default scale is 1” per pixel. A user may specify the scale of individual pixels, or the size of the image as a whole, but if both are specified the size of the image takes precedence.

Examples:

Scale=0.0025

Scale=0.0002777777

Scale=0.0002777777,0.0005

Using scale on DSS cutouts near 3c273

scale=0.0003	scale=0.0003,0.0001

2.3.2.11 Pixels

This gives the number of pixels in the output image. If specified as a single value, the number of pixels will be the same in both dimensions.

The default is 300.

Examples:

Pixels=500

Pixels=1280,640

2.3.2.12 Rotation

The argument indicates that the output image is rotated by the specified angle in the rotation plane. The units are degrees.

By default there is no rotation of the image.

Rotation=45.0

Rotating 3c273

No rotation	Rotation=30

2.3.2.13 Resolver

When a target name is specified rather than specific coordinates, the name must be ‘resolved’ into coordinates. There are two widely used name resolvers available: NED and SIMBAD. The application invokes these through a HEASARC web service. This argument can be used to specify which resolver or resolvers are to be used. If both resolvers are specified, then the second is checked only if the object is not found at the first. Values are: SIMBAD, NED, NED-SIMBAD and SIMBAD-NED. The default is SIMBAD-NED.

Example:

Resolver=NED

2.3.2.14 Offset

The offset is used to specify that the center of the image will be offset from the position specified in the Position or Lat/Lon settings by the given number of pixels. Users can tile very large images by creating a number of separate tiles and using the offsets. Offsets may be used in any output projection.

The apparent differences between the combined and tiled images below arise from the quicklook scalings of the tiles' images being done independently for each tile: the pixel values for the four tiles exactly replicate those of the combined image.

position=3c273 pixels=300 survey=dss

The image above broken into 4 tiles position=3c273 survey=dss pixels=150

offset=-75,75	offset=75,75

offset=-75,-75	offset=75,-75

Offsets need not be integral.

Example:

Offset=-300,300

2.3.3 Sampling settings

These keywords control how pixels are resampled.

2.3.3.1 Sampler

This argument specifies the sampling method to be used. The value consists of an algorithm designator which may in some cases be suffixed with an integer giving the order of the sampler. Currently supported samplers include:

Nearest Neighbor (NN): Nearest neighbor sampling projects the center of the output pixel into the input image and uses the value of the pixel whose center is nearest the projected position. Nearest neighbor resampling is simple and fast but does a poor job in preserving positional and flux information for a source. For images where non-integral values are inappropriate (e.g., if the pixel values of the input image are integers that represent classes like vegetation, buildings, water, etc.) then nearest neighbor resampling may be the only reasonable choice.

Bi-linear interpolation (LI): As its name implies does a linear interpolation in both directions. This interpolation is also very fast and simple to understand. It tends to blur images somewhat.

Splines from 2-5 order (Spline or Spline3, Spline2, Spline4, Spline5): Spline interpolation does a more global calculation of the interpolation which allows the spline to rapidly compute interpolants which are continuous and differentiable at all points. Spline resamplers cannot currently be used with 3-D output images. They often do well as fast resamplers of well-sampled images where they do a good job of preserving both flux and retaining resolution. They may be less appropriate for undersampled images or images with many edges.

Lanczos interpolation with a specified kernel size (Lanczos, or LanczosN where N >= 2, the default is 3): Lanczos samplers use a smoothly truncated version of the optimal sampling sinc function to sample the neighborhood of an interpolation point. The Lanczos resamplers do well in preserving information and resolution of well-sampled images but as with the spline samplers they may not be appropriate for undersampled data or data with edges and missing pixels.

Exact-area resampling using Sutherland-Hodges clipping (Clip): This resampler treats the output pixel grid as a window over the input images grid and integrates the flux within each output pixel exactly. The flux within each input pixel is normally considered to be distributed uniformly within a pixel, but the Clip resampling can implement drizzling where the flux of the input pixels is considered to be confined to an interior rectangle within the pixel. See the Drizzle setting.

The default is nearest neighbor.

Users can add their own samplers which should extend the skyview.geometry.Sampler class. The supplied samplers are given as classes skyview.geometry.sampler.XXX. When users specify a value for this setting, the program looks for a class replacing the XXX with the specified value. If this fails it looks for a class in the sampler package with the given name and finally tries to see if the user has specified the full class name of the sampler. If the setting ends with an integer, this value is stripped from the name before searching for the class, and used to set the order of the resulting sampler.

A special Combo sampler is also supplied. If there are NaNs present in the boundaries of the input data, then high-order samplers may return NaN as they near the edges. The Combo sampler uses its primary sampler so long as the returned value is not a NaN, but tries the secondary sampler (usually a low-order sampler like Nearest Neighbor) when a NaN is found. The two samplers used for the Combo are specified in the ComboSamplers setting.

For well sampled images the Lanczos of Spline resamplers work well. The Spline resampler cannot however be used if a 3-d image is to be generated. The third order method of each is fine. For poorly sampled images the nearest neighbor and linear interpolation methods are more stable than the higher order samples, but the Clip resampler is generally to be preferred. The Clip resampler will also conserve flux exactly if the input images are linear in flux.

Example:

Sampler=Lanczos5

Sampler=SplineSampler

Sampler=myclasses.samplers.NewSampler

Sampler=Combo ComboSamplers=Lanczos,NN

2.3.3.2 ComboSamplers

This setting defines a pair of samplers where the first is used normally, and the second is used when high-order resampling returns a floating point NaN value. See Sampler.

Example:

ComboSamplers=Lanczos,NN

2.3.3.3 Ebins

This argument is used only when sampling three-dimensional images which have a set of ‘energy’ values at each pixel. It must have three comma separated numeric values. The first gives the offset of the first output energy bin, the second gives the width of the output bins in terms of the original bins, and the third gives the number of output bins. E.g., suppose we have 10 channels in the input data. We wish to skip the bottom 2 channels and the top half channel and rebin the remaining 7.5 channels into 3 output bins in the output image. Then we have

Ebins=2,2.5,3

The offset is 0-based. The bin size does not need to be an integer, the output bins will be integrated over the input bins assuming flux to be uniformly distributed over the energy bin. In the example given, the first bin in the output will be the total of the third and fourth and half the fifth bin of the input.

In SkyView, 3-D surveys normally specify a default for the Ebins value which gives a 2-D output image. This is given in the <Settings> element of the survey description file.

Example:

Ebins=3,10,7

2.3.3.4 Smooth

Smoothing is available as a post-processing step after the initial generation of the output image. Currently only a simple box-car smoothing is available. The user may specify the height and width of the boxcar in pixels. If only a single value is specified a square box is used. Only odd integer values are allowed. If an even value is specified, it is incremented by one.

In the example below the pixels where no X-rays were found confuse the logarithmic scaling so that most of the detail of the image is lost. Smoothing fills in these holes so that the real structure is visible. Using the Clip sampler with smoothing often makes sense since it does a smoothing over the area of the output pixel.

The Galactic center in X-rays

survey=pspc2int position=0.,0. coordinates=galactic sampler=Clip quicklook=jpg

No smoothing

smooth=5

Example:

Smooth=5,3

2.3.3.5 ClipDrizzle

This setting is used to specify that in resampling input pixels using the clip sampler the flux in the input pixel is not uniformly distributed through the pixel, but is concentrated in a central rectangle. Normally it is specified as a real number 0<x<1. A value of 0 may be used to indicate that all of the flux is to be treated as being at a point at the center of the pixel. Values greater than 1 may be used to provide a continuous variable smoothing over the input input (in contrast to the Smooth setting which does boxcar smoothing for integer sized boxcars over the output image).

Example:

To confine the flux to the inner 25% of the pixel (by area):

ClipDrizzle=0.5

2.3.3.6 ClipIntensive

By default the Clip sampler simply adds the flux values over the output pixel. This is appropriate where the measured values are some extensive quantity (e.g., number of photons) but it means that the values for the output pixels are roughly proportional to their areas. ClipIntensive is appropriate when the images are of some intensive quantity and divides the output pixel by the area of the output pixels (as measured in units of input pixels). This setting takes no value.

Example:

ClipIntensive

2.3.4 File and caching settings

2.3.4.1 Output

The name (or stem) of the output image or images. The user may specify the full path of the output image x.fits or just a stem x. If more than one image is being produced, then ordinal numbers will be added so that the output files will be x_1.fits, x_2.fits. If compression is requested the .gz extension should not be specified, it will be added automatically. The default is output.

Example:

Output=~/myoutputs/test.fits

Output=c:\datafiles\3c273

2.3.4.2 Compression

This flag indicates that the output files are to be gzip compressed. The default is not to compress the data. The content of the value is ignored and the value can be omitted.

Examples:

Compression=T

Compression

2.3.4.3 Float

This flag indicates the output files should be 4 byte reals. The default is 8 byte reals. The content of the value is ignored and can be omitted.

Examples:

Float=T

Float

2.3.4.4 NoFITS

Suppress the FITS output. The value of the argument is ignored and may be elided. This argument may be used in conjunction with graphics arguments if only a quicklook (e.g., GIF or JPEG) is desired.

Example:

Nofits

2.3.4.5 Cache

When a user requests an image from a survey whose source files are on another computer, the application first downloads source files onto the local computer and then resamples the data. By default the downloaded files are copied into the skycache subdirectory of the current directory and are left there when the application is complete. They serve as a cache for subsequent requests. Often users make several requests near a given location, perhaps changing the pixel size, resampling method or some aspect of the graphic overlay. When these subsequent requests are made, the application notes that the needed files are already downloaded and immediately begins resampling.

If a user is sure that a survey file is not going to be needed again, or if space is at a premium, the user can request that the survey files be deleted by specifying the PurgeCache setting. This will delete all files downloaded for a given survey in the current request. However if multiple files are needed for a given survey, then all files for the survey will be downloaded and the output image produced before the downloaded files are deleted.

Users who create their own survey data sets (or who modify the XML survey files distributed with the application) can create different cache directories for each survey. By setting the cache directory in the <Settings> area of the survey description the user specifies a default cache directory which can be overridden on the command line. If the user specifies a cache in the <Images> area, then this setting cannot be overridden by the user. Note that more than one cache directory can be specified. All of the cache directories are searched when looking to see if a file is already available, however any files that are downloaded will be placed in the first directory.

Example:

Cache=/surveycache/cache1,/surveycache/cache2

2.3.4.6 SaveBySurvey

When this argument is specified cache files will be looked for not only in the cache directories, but also in subdirectories with using the name of the current survey. E.g., if the cache directory is ./mycache and the user is retrieving a file from the DSS2B survey, then the cache files will be looked for in both ./mycache and ./mycache/DSS2B . The name used for the subdirectory is the first short name specified in the survey description not the survey name as entered by the user. Special characters in the survey name will be replaced by underscores (_).

The current survey subdirectory of the first cache directory will be used to store any files downloaded during the request.

Example:

SaveBySurvey

2.3.4.7 PurgeCache

This argument indicates that cache files are to be purged after the processing of that survey is completed. Only survey files actually downloaded in this request will be deleted. Other files in the cache are left unchanged even files used in processing. The value of the argument is not used. All files needed for a given image will be downloaded before any files are purged.

Examples:

PurgeCache=T

PurgeCache

2.3.4.8 LocalURL

This setting enables services which provide SkyView resources through a Web interface to use the same survey description file internally as it provides to outside users. When a survey URL begins with the first value of this setting the program looks to see if it can find a local file available where the URL prefix is replaced by the file prefix. So, e.g., if SkyView has data for an EGRET survey available online in a file /www/htdocs/survey/EGRET/egretdata.fits, it might provide these data to remote users under the URL http://skyview.gsfc.nasa.gov/survey/EGRET/egretdata.fits. The survey description file given to users would point to this URL. However when running a CGI service locally that provides EGRET data, the LocalURL setting is used to recognize that this survey data is available locally and no Web access is required.

The settings should always have two fields, the URL prefix and the file prefix.

Example:

LocalURL=http://skyview.gsfc.nasa.gov/survey,/www/htdocs/survey

2.3.5 Quicklook/graphics settings

These settings control the appearance and format of quicklook imges.

2.3.5.1 Quicklook

This argument is used to give the format for quicklook/graphic outputs. The supported formats are: GIF, JPEG (or JPG), TIFF, PNG and BMP. A value of JPG is assumed if there are other graphic keywords and this argument is not specified. The output format for three color images (see RGB below) is always JPG. The argument value is not case sensitive.

Example:

Quicklook=gif

2.3.5.2 RGB

Create a color image from three surveys using the first as the red color, the second as green and the third as blue. The output image is always created as a JPEG, e.g. output_rgb.jpg. The value of the argument is ignored and may be elided.

RGB

The IRAS Galactic center (R=100μm, G=25 μm, B=12 μm)

(survey=iras100,iras25,iras12 position=0,0 coordinates=g scaling=log size=15,7.5 pixels=600,300 rgb)

2.3.5.3 RBGSmooth

Smooth the RGB planes before combining into an RGB image. This setting normally has 3 integer values giving the smoothing for each image. Note that this smoothing happens after any smoothing defined in the Smooth setting. This allows the images with different noise characteristics to be smoothed independently.

Example:

survey=IRAS12,SHASSA,PSPC2INT rgb rgbsmooth=1,5,3

2.3.5.4 LUT

The argument allows the user to read in a lookup table which will be used to translate pixels values to color. There are three sources for look up tables. ImageJ defines the following lookup tables internally:

Fire, Ice, Red, Yellow, Green, Blue, Cyan, Magenta, Grays, Spectrum, Red/Green, and 3-3-2 RGB.

There are also a set of lookup tables distributed with the jar file to mimic standard IDL color tables. These may be specified using the file name colortables/xxx.bin where xxx is the IDL color table name with spaces replaced by hyphens. (These are also available using the syntax as the old SkyView Batch interface using the Batch Compatibility feature).

Users may also create their own color tables. The only format currently supported is a 768 byte file comprising the 256 red values followed by 256 green and 256 blue.

DSS image of M81 (size=0.5 lut=Fire)

When using the internally defined color tables, the case does not matter, but for many operating systems if mixed case files names are used, the argument must be in the correct case. Note that the program will always check for files with the argument in lower-case first. If you have two LUTs xxx.lut and xXx.lut, then the program will always choose the former even when the user specifies lut=xXx.lut.

If no color table is specified a gray scale image is produced.

Examples:

lut=’3-3-2 RGB’

lut=colortables/Stern-Special.bin

lut=mylutDirectory/myLUT.lut

2.3.5.5 Invert

Invert the output color table. The value of this argument is ignored and may be elided. The output image is given with the color table used in inverse order (or with a white rather than black background if no color table is specified).

Example:

Invert

Inverted Gray Scale DSS image of M81 (size=0.5 invert)

2.3.5.6 Min

Set the minimum value for the output image. Before scaling, all values below the minimum will be set to the minimum. This affects only the graphic image, not any FITS data. In the example below a few very small positive values make a simple log-scaled image look peculiar.

Example:

min=0.

Galactic center in hard X-rays

(survey=integralspi_gc size=50 pixels=400 scaling=log projection=Car coordinates=G position=0,0)

No minimum specified

min=0.1

2.3.5.7 Max

Set the maximum value of the output image. Before scaling, all values above the maximum will be set to the maximum. This affects only the graphic image, not any FITS data. This can be useful if a few very bright pixels are making it difficult to scale the rest of the image properly.

If both Min and Max are specified, then the image intensity scaling will be done over the range they specify regardless of the actual pixel values. However if only one is specified, then the actual pixel Max (Min) will be used if it is less (more) than the specified Max (Min).

Example:

max=256

2.3.5.8 Scaling

This argument controls the scaling between the data and the displayed images.

Recognized values include:

Linear The output pixels are linearly scaled from the input.

Sqrt Output scaled as the square root of the input pixels. Negative pixels are scaled to the minimum.

Log Output scaled logarithmically from the input. Negative pixels scaled to the minimum. This is the default.

HistEq Output scaled so that each output bin has the same number of pixels.

When Sqrt or Log scaling is done, negative and 0 values in the image are normally treated as either the smallest positive value or 0.001% of the maximum value of the image whichever is greater. If the user specifies a min setting this special handling is turned off.

Example:

scaling=Sqrt

Image scaling for 3c273

Linear	Sqrt	Log	HistEq

2.3.5.9 PlotScale

Sets the scale for symbols in plot overlays. A scale of 1 gives the standard size symbols.

Example:

PlotScale=2

2.3.5.10 PlotColor

Sets the color for plot overlays. The plot color should be the name of a Color as defined in the java.awt.Color class. The program looks for the color by looking for a field of the Color class with the given name using Java's reflection capabilities. Plot colors do not work with RGB images. Many common English names for colors are supported where the color is given in all caps.

Example:

PlotColor=GREEN

2.3.5.11 PlotFontSize

Sets the font size of text in plot overlays. The size is given in points.

Example:

PlotFontSize=20

2.3.5.12 ImageJ

This option starts an ImageJ application and feeds the survey images being produced into it. The main ImageJ control window is a simple menubar. For each survey there will also be a window. You can click on a survey window to make it active and use the functions in the ImageJ control window to manipulate it. ImageJ has dozens of powerful functions and is described in detail at http://rsb.info.nih.gov/ij. To leave the ImageJ application use the Quit option of the File menu.

Example:

ImageJ

ImageJ Control Window

Typical ImageJ image window

2.3.6 Contour settings

2.3.6.1 Contour

Draw image contours from one survey on top of another. A value of the contour setting may comprise up to 5 colon separated fields. The first is the survey from which the contours are to be drawn. The second is the scaling of the contours, either 'Log', 'Sqrt' or 'Linear' (default Linear). The third value is the number of contours (default 4) which is followed by values for the first and last contours. One, two, three or all five values may be specified.

More than one survey can be contoured by using comma as a separator.

You may get a quicklook image of the contour only by setting the Min value to something larger than the maximum expected in the underlying image. In this case you will likely want to make the underlying image the same as the contour image. The program does caching so that only one image will be computed.

In the example below some artificial contours are drawn at the boundary of the Aitoff projection. The contour routine does not recognized that images may be bounded. The data outside the Aitoff bounds are set to 0.

Radio contours on an X-ray image.

survey=heao1 position=0.,0. pixels=600,300 size=360,180 projection=Ait

... contour=408mhz:Log:6:1:1000

... contour=408mhz:Log:6:1:1000 contourSmooth=5

... contour=408mhz:Log:6:1:1000 min=1.e20

Examples:

Draw contours from two IRAS surveys on top of the image.

contour=iras100,iras12

Draw the X-ray contour on top of the optical image at the values 0.00005, 0.0005, 0.005, 0.05 and 0.5.

contour=pspc2int:log:5:0.00005:0.5

Draw the contours on top of the data from the same survey.

survey=pspc2int contour=pspc2int

2.3.6.2 ContourSmooth

Smooth the image from which the contour is to be drawn before contouring the image.

Example:

ContourSmooth=6

2.3.7 Grid settings

2.3.7.1 Grid

This option requests a coordinate grid to be overlaid on the quicklook image. The user may request a coordinate grid in a different coordinate system than that used in the image by specifying the value for this setting.

Examples:

Grid Overlay with a grid in the image's own coordinate system.

Grid=G Overlay with a Galactic coordinate grid.


grid	grid gridlabels

grid=g	grid=g gridlabels
(survey=1420mhz position=0,0 size=360,180 projection=Ait pixels=400,400)

2.3.7.2 GridLabels

Label the grid lines with coordinate values. Equatorial coordinates use sexagesimal values, but other coordinate systems use labels in decimal degrees.

Example:

Gridlabels

2.3.8 Drawing

Starting with version 2.5, SkyView supports a powerful drawing capability for drawing arbitrary overlays in the quick look images. Drawing commands can be specified either using settings directly or in draw files.

2.3.8.1 Draw

The Draw setting is used to specify one or more drawing commands. Commands are separated with commas, thus it is not possible to draw text that includes commas using this setting. Draw commands almost always have embedded blanks which may need to be escaped if this setting is used on the command line. When both Draw and DrawFile settings are provided, the Draw commands are executed before each file specified in DrawFile.

Example:

Draw=’reset,rotate 30,offset 20 20’

2.3.8.2 DrawAngle

This setting defines the initial rotation for drawing. This is also the angle set after each reset. The DrawAngle setting is a convenient equivalent to having a Draw command with an initial rotate command for the given angle. The angle is given in degrees.

Example:

DrawAngle=30

2.3.8.3 DrawFile

This setting specifies one or more Draw files. Each line in a draw file may contain a comment, one draw command or may be a blank.

Example:

DrawFile=hst_template.drw,chandra_template.drw

2.3.8.4 Draw commands

Each drawing command consists of one or more blank separated tokens. In the examples below we show the draw commands on separate lines, as they would be specified in a draw file, rather than the comma separated form in the Draw setting. Many of the drawing commands reference a coordinate system with an origin at the image center and angles which correspond to counterclockwise rotations. Any white space line or line whose first non-white space line is a # is a comment and will be ignored.

Color colorName

Draw subsequent lines and text in the specified color (see PlotColor for information on valid names)

Example: color red

Scale value

Specify the units for future drawing requests. The value should be a number which may optionally have any of the characters d,D,’, or ” appended. A d or D means that units are degrees, while ‘ implies arcminutes and “ arcseconds. If no character is appended the units are in pixels. An angular scale is converted to pixels using the scale of the output image. Typically this scale is only exact at the center of the image projection and not through the entire image. If an image has different scales in x and y, the geometric mean is used to get the scale for the image.

Examples:

scale 2.5

scale 1.7”

Offset x y

Indicate that in future requests actual pixel values are to be offset by an additional x and y value from the specified location. Offsets are cumulative. The unit of the offset is given by the current scale.

Examples:

offset 30 30

offset -30.3 21.98

Rotate angle

Indicate that in future requests after a rotation is to be applied to the positions after any offsets have been made. Rotations are cumulative. The unit is degrees. One common use for rotation is to rotate the template representing a telescope field of view as needed to accommodate the position angle of the observation.

Example:

rotate 30

Circle x y d

Draw a circle centered at x and y with the given diameter. The x and y values will have the current offsets and rotation applied.

Example

circle 0 0 40

Text x y angle label

Draw text on the image centered on x,y at a specified angle. The x and y values have the offset and rotation applied and add the angle to the current angle.

Examples:

text 14.3 12.9 0 Sirius (the Dog Star)

text 0 0 90 Center of the image

Thick n

Draw subsequent lines with the given thickness (which should be an integer).

Example: thick 3

Reset

The reset command is the only command that is a single token. It resets the color, thickness, offset, scale, and rotation to their default values (white, 1, (0,0), 1 and 0 respectively).

File filename

Run the commands in the referenced file.

Example: file rectangle.drw

x y

Users draw lines by entering sequences of commands which consist of just an x and y value. If the previous command was also an X Y command (or the sequence was interrupted only by a color or thickness command), then a line segment is drawn from the previous position to the current position.

We illustrate how some of these commands are used in the following file:

color green

scale 1"

text -140 140 0 Instrument template

thick 2

circle 0 0 4

thick 1

color white

-200 -200

200 -200

200 200

-200 200

-200 -200

offset 15 15

rotate 30

-30 -30

30 -30

30 30

-30 30

-30 -30

circle 0 0 30

text 0 0 special

Drawing on 3C273

2.3.9 Catalog query settings

Users can find objects and observations that are within the fields of generated images from thousands of catalogs at a variety of sites. The application uses the simple Virtual Observatory Cone Search protocol to query catalogs. All HEASARC and Vizier catalogs that can be queried by position are available. A number of other special catalogs (e.g., NED) are also available.

Catalogs are requested using the Catalog setting. Multiple catalog requests can be separated by commas. The catalog names are of several types. The strings 'NED' and 'SIMBAD' are recognized specially. All names that include a "/" are assumed to be Vizier tables specified using their table IDs, e.g., 'I/284'. All other simple strings are assumed to be HEASARC tables. You can query the Vizier system at http://vizier.u-strasbg.fr or the HEASARC at https://heasarc.gsfc.nasa.gov/cgi-bin/W3Browse/catindex.pl to get a complete list of catalogs available from these systems. The name used for HEASARC catalogs is the short single token name of the catalog not the longer descriptive name. You can also specify a full URL pointing to a VO Cone Service.

Catalog queries run in parallel with the generation of images with each query in a separate thread. With a bit of luck the catalog queries will be done before any image is ready.

The catalog queries are cached by the system, so that if the user asks for more than one image, the query need not be re-run for each image. However, if the second image uses larger pixels than the previous image, then the query will need to be re-run to ensure that the entire image is included (unless the CatalogRadius setting is specified). For maximum efficiency the surveys with the largest scale should be specified first. If the CatalogRadius is specified, then an object must be both within the field of the observation and within the specified radius of the center of the field to be included in the results.

The catalog options do not automatically turn on graphics display since a user may just be interested in the catalog output file. However if graphics is selected by some other option, then the positions of each catalog object will be overlaid. If the CatalogIDs field is specified, then in addition to displaying a symbol at the location of the object, an identifier string will also be displayed.

2.3.9.1 Catalog

Specify one or more catalogs to query for objects in field of the image.

The names used for catalogs are as described in the text or a full URL may be specified. This is assumed to return a VOTable matching the Cone Search protocol description (though it need not be a cone search query).

If a quicklook image is requested, then the positions of the catalog objects in the field will be overlaid on the image. The catalog option does not in itself imply graphics output.

Examples:

Catalog=rosmaster,ascamaster

Catalog=ned,I/246

Catalog=http://some.web.edu/aFile.xml

The HEAO1A X-ray sky overlaid with the 4U survey.

(survey=heao1a position=0,0 catalog=uhuru4 pixels=600,300 projection=Ait size=360,180 scaling=log quicklook=jpg)

after adding catalogIDs

after adding catalogfilter=count_rate>20

2.3.9.2 CatalogFile

This setting indicates that a file listing the catalog objects found in the field should be created. The file name may be given as the argument, or if no argument is specified a ".tab" suffix is appended to the stem used for the first file image. It is possible for users to request a series of images with different sizes (since the default pixel scale varies by survey). The catalog file will give the objects found in the region of the first image requested.

If the CatalogFile setting is specified a file is produced which contains a simple ASCII table with all of the returned catalog data. Each row gives the catalog from which the row was extracted, the name of the catalog object (using a column selected by the catalog provider), the J2000 RA and Dec of the object, and the X and Y pixel locations. These locations use the corner of the image as 0,0 (offset by 0.5 from the standard FITS convention). While the data for most columns in the input table are not included in the catalog file, all of the column names for the input column will be listed if CatalogFields is set.

Examples:

CatalogFile

CatalogFile=objects.list

Example output (adding catalogFile=out.cat to HEAO1A request)

N | Cat | ID/Name | RA/Lon | Dec/Lat | X | Y

1 | uhuru4 | 4U0042+32 | 11.1745| 33.0484| 283.7| 204.4

2 | uhuru4 | 4U2142+38 | 326.1659| 38.3175| 346.6| 213.3

3 | uhuru4 | 4U0336+01 | 54.6950| 1.1822| 209.7| 152.0

4 | uhuru4 | 4U2321+58 | 350.8689| 58.8326| 309.0| 243.9

5 | uhuru4 | 4U0316+41 | 49.9727| 41.5335| 234.1| 219.1

6 | uhuru4 | 4U2030+40 | 308.0896| 40.9559| 368.9| 218.3

....

2.3.9.3 CatalogRadius

Normally all catalog objects found in the image will be shown. If the catalog radius is specified, then only those objects that are also within the specified radius (in degrees) from the center of the image will be included.

Example:

CatalogRadius=0.2

2.3.9.4 CatalogFilter

A catalog filter filters the results according to the specified criteria. A filter string comprises a field name, operation, and value. Multiple filters may be specified as additional triplets separated by commas. If the returned data has no column which matches the field name, then no rows will be returned. CatalogFields may be set to show the fields returned by requested catalogs. E.g., if a user knows that a catalog has a column named vmag, then

CatalogFilter=vmag<10

will ensure that only the brightest objects are displayed. If a specific range were desired one could try

CatalogFilter=vmag<10,vmag>6

Suppose a user wished to know the location of archived Chandra observation, then they might try

Catalog=chanmaster CatalogFilter=status=Archived

Valid operators include =, >, <, >=, <=. Note that the > and < characters may need to be escaped if specified on the command line so that they are no interpreted as redirection operators.

Example:

CatalogFilter=vmag>12,vmag<15

2.3.9.5 CatalogFields

If a CatalogFile has been specified, then include a listing of all of the fields in the catalog. This can be useful when a user wishes to know the fields available for catalog filters.

Example catalog output generated by CatalogFields:

Table: uhuru4 Field:unique_id

type:char[*] UCD:ID_MAIN

Table: uhuru4 Field:name

type:char[*]

Table: uhuru4 Field:ra

type:double UCD:POS_EQ_RA_MAIN units:degree

Table: uhuru4 Field:dec

type:double UCD:POS_EQ_DEC_MAIN units:degree

Table: uhuru4 Field:count_rate

type:double units:ct/s

2.3.9.6 CatalogIDs

Indicates that both symbols and ID strings should be overlaid on images.

Example:

CatalogIDs

2.3.10 Processing settings

These settings control the operation of the system. Many of these will be defined in the system settings file or will be set specifically for given surveys.

2.3.10.1 NoExit

By default an invocation of the Imager's main class in the jar file ends with a call to the System.exit method which closes the Java Virtual machine. If the user does not wish this to happen (e.g., if the Imager.main method is being called from another class) then this setting may be specified. The ImageJ setting also precludes calling exit.

Example:

NoExit

2.3.10.2 SurveyFinder

SurveyFinder specifies the class used to find surveys that the user can generate images from. This class must implement the skyview.survey.SurveyFinder interface. By default this is the skyview.survey.XMLSurveyFinder but it may be overridden by knowledgeable users.

2.3.10.3 ImageFinder

An ImageFinder object determines which survey image to sample for a given output image pixel. This setting is used to set the class name to be used for this object. This class must inherit from the skyview.process.ImageFinder abstract class. The default image finder class is skyview.process.imagefinder.Border. When this setting is specified, the program first looks for a class in the skyview.process.imagefinder package. If this fails it then tries to see if the setting specifies the full class name. Supplied image finders are Border, ScaledBorder, Radius and MaxExposure. These differ in how they choose the best image for a given pixel.

The Border finder looks for the image where a given pixel lies furthest from any edge of an image. The ScaledBorder uses the same criterion, but with the distances scaled to the size of the given input image. Thus it will differ from Border only if the input images are of different sizes or if the tiles are not squares.

The Radius finder tries to minimize the distance between the output pixel and the center of the input tile. If the tiles are only exposed in a circular region this can work better than Border. E.g., ImageFinder=Radius is set as the default for the GALEX surveys.

The MaxExposure finder uses the input image on which the output pixel is found which has the longest exposure. If the quality of input image is roughly the same over their entire fields of view, then the longest exposure image may be the best observation. The exposure used is the value of EXPOSURE in the FITS header unless this is overridden using the ExposureKeyword setting.

The Bypass and Overlap image finders are used when the determination of which pixel to use for a given image is deferred to the mosaicking step. The Bypass finder simply returns the list of input images with no processing. The Overlap finder nulls out images which can be shown not to overlap in the input. Normally image finders generate an integer array matching the output pixels to the input images they are sampled from. These two finders return a 0 length array instead.

Image finders and mosaickers may need to be appropriately paired. The AddingMosaicker does not use the image array returned by the standard image finder and can use the Bypass or Overlap image finder.which use data from all of the input images that overlap a given output image. Such mosaickers will need to be paired with appropriately designed image finders.

ImageFinder=Border

ImageFinder=MaxExposure ExposureKeyword=ONTIME

ImageFinder=myclass.MyImageFinder

2.3.10.4 StrictGeometry

This flag can be set to indicate that the best pixel should be determined for each pixel individually rather than using any approximations. If an image appears to have missing segments due to resampling the wrong input, then using StrictGeometry may help. The StrictGeometry flag should be obsolescent with the new Border Image Finder class.

Example:

StrictGeometry

2.3.10.5 CheckNaNs

This flag, whose value is ignored, is used by the ImageFinder to see if the input images should be checked for NaNs. If an output pixel location lies on a NaN pixel for a given input image, that input image will not be used for sampling the given output pixel. Note that the checking for NaNs may not detect isolated regions of NaNs within valid pixels in the input image.

Since this keyword requires the actual image data in the earliest stages of the image processing, it can substantially slow down requests where the data needs to be downloaded from an external source. However if the data is local, the speed penalty is small.

Example:

CheckNaNs

2.3.10.6 FindRetry

The default ImageFinder routines use a recursive procedure looking at progressively smaller rectangles of the output image to find which input image should be used. When the borders of the rectangle all come from a giving input image the entire rectangle is sampled from that image. At each level of the recursion a test is applied to see if a given input image can contribute to pixels at the lower levels. In cases where the projection of the input images has singularities (Car, Ait, Csc) such that neighboring locations may project to distinct locations in the projection, it is possible that this pruning process will incorrectly filter out images. The FindRetry setting indicates that when the ImageFinder is unable to find an input image for a given pixel it should retry that pixel using all input images.

Example:

FindRetry

2.3.10.7 CornersOnly

The algorithm used in the supplied image finders uses a recursive technique looking for rectangles that belong to a given image. By default the Border image finder looks to see if the entire border of a rectangle in the output image is best satisfied from a given image and then colors the interior of the rectangle to be sampled from the same input image. This flag causes the algorithm to look only at the corners of the rectangle not the borders. This was the default (and only supplied) behavior before V2.02. Note that NaN checking occurs only in the border/corner checking, not when we are coloring the interior rectangle.

Example:

CornersOnly

2.3.10.8 ExposureKeyword

The MaxExposure image finder assumes that the input images are FITS images, reads the exposures from the headers and from there on prefers images with longer exposures to shorter. It uses this setting to find the FITS keyword to use for the exposure. If no setting is supplied the keyword “EXPOSURE” is assumed. This setting is also used in the FitsKeyword exposure finder.

Example:

ExposureKeyword=ONTIME

2.3.10.9 PreProcessor

One or more classes implementing the skyview.process.Processor interface that are to be used in processing before mosaicking takes place. If a user needs to communicate parameters to a pre (or post) processor, additional Settings can be defined which are used to transmit the information. A preprocessor is used when Catalog is set so that catalog retrieval can occur in parallel with image construction. If filtering of the input images were desired, a preprocessor could be used for this.

2.3.10.10 Mosaicker

A class implementing the Processor interface that fills in the pixel values in the output image. The default mosaicker is the class skyview.process.Mosaicker. The images used to generate the output image are included in history records in the FITS header produced.

Two other mosaickers are available in the standard jar. The IDMosaic mosaicker creates and output that lets a user find out which image a given output pixel was sampled from. Each pixel in the output image is just the index of the input pixel that would have been used to sample that image.

The AddingMosaicker is provided to allow SkyView to add together data from multiple overlapping images. The mosaicker processes each input candidate in turn. The overlap region between the input and output images is determined (using the Sutherland-Hodges algorithm used in the Clip sampler) and flux from each input is accumulated into the output images. Simultaneously a total ‘exposure’ for the output image is accumulated. After all input images have been processed the output is generated as the accumulated fluxes divided by the accumulated exposures. The method used to find the exposure is determined by the ExposureFinder setting.

2.3.10.11 ExposureFinder

The ExposureFinder is used to determine the exposure for a given pixel when using the AddingMosaicker. The value of this setting is the name of a class that implements the skyview.process.ExposureFinder interface. Just the class name can be given if the class is in the skyview.process.expfinder package, or the fully qualified class name can be specified. Three exposure finders are provided in the jar.

The Null exposure finder is the default. It assumes that every pixel in every input image has an equal exposure.

The FitsKeyword exposure finder looks for the value of the keyword specified in the ExposureKeyword setting (or EXPOSURE by default). This is used for all pixels in the specified image.

The ExposureFile finder uses an exposure map to find the appropriate exposure. The exposure map is assumed to be a scalar image in the primary HDU of a separate FITS file. The name of the exposure file uses two settings ExposureFileMatch and ExposureFileGen to do a transformation between the flux file and the corresponding exposure file. The transformation uses regular expressions. E.g., suppose the flux file is xxx/yyy.fits and the exposure file is xxx/yyy_exp.fits. The following settings might be used:

ExposureFinder=ExposureFile

ExposureFileMatch=(.*)(\.fits)

ExposureFileGen=$1_exp.fits

The exposure file name is generated by transforming the corresponding flux file name using the equivalent of the Java call:

exposureFile=fluxFile.replaceAll(fileMatch,,fileGen);

Describing regular expressions is beyond the scope of this guide but they are fully covered in both Java and Perl documentation and allow for quite powerful transformations.

2.3.10.12 ExposureFileMatch

A regular expression string which is used matched to a given flux file in the generation of the file name of the corresponding exposure file. See ExposureFinder.

2.3.10.13 ExposureFileGen

A replacement string, which may include regular expression back references, that is used in the generation of the file name of the exposure file which corresponds to a given flux file. See ExposureFinder.

2.3.10.14 Deedger

When survey images are mosaicked together there may be artifacts at the edges of the images where the different backgrounds of the images merge. The deedger attempts to minimize these artificats. Deedging is turned on by default for some surveys (e.g., the DSS). It can be turned off for those surveys by using deedger=null.

The de-edger is a kind of PostProcessor so in many cases a user could use the PostProcessor setting equivalently. However using the Deedger setting is preferred since it allows survey defaults to set de-edging on or off without confusion with other post-processors.

Supplied classes are:

skyview.process.Deedger which de-edges using the default algorithm (currently using the BoundaryMedian)

skyview.process.deedger.BoundaryMedian sets the median change across the boundary of two image to 0

skyview.process.deedger.BoundaryAverage sets the average change across boundaries to 0

skyview.process.deedger.ImageMedian sets the median pixel value for the regions derived from different input images to a common value.

Deedging generally works fairly well when there are only a few images that need to be matched but if many images are to be matched the simple adding of offsets may be inadequate. More complex algorithms which add a slope or more complex flat-fielding could be coded.

The offsets added to each input image are recorded in the FITS header.

DSS Image of the Horsehead nebula

survey=dss position='horsehead nebula' quicklook=jpg

Default (for DSS deedging on)

deedger=null turns off deedging

Examples:

Deedger=null Turn off de-edging in a survey that has it on by default.

Deedger=skyview.process.deedger.ImageMedian

2.3.10.15 PostProcessor

One or more classes defining the Processor interface which process the image after mosaicking. De-edgers (see above) and the graphics processor are included in the jar.

The class skyview.ij.IJProcessor handles the interface to ImageJ functionality. A call to this processor will normally be added whenever one of the graphic arguments is specified so that users do not need to specify this setting explicitly.

2.3.10.16 SettingsUpdaters

This argument is used to indicate classes that might wish to look over the arguments that have been specified before image processing begins. E.g., one could build a class that translated arguments from French to the English values expected in the program. The BatchCompatibility class does something very similar to this.

Three classes are specified in the system settings: skyview.executive.BatchCompatibility, skyview.vo.CatalogProcessor, and skyview.ij.IJProcessor. The first translates arguments from the old SkyView batch interface to comparable values for this program. The second ensures that the catalog pre- and post-processors are called if catalog arguments are found. The last fills in default values when the user specifies certain graphics keywords. Classes specified in this setting should implement the skyview.executive.SettingsUpdater interface.

Example:

SettingsUpdaters=skyview.executive.BatchCompatibility,skyview.ij.IJProcessor,skyview.vo.CatalogProcessor

2.3.10.17 ImageGenerator

An image generator class can be specified in lieu of a list of <Image> elements in the survey description file. It should return a set of strings that can be used by an image factory to generate candidate images. The

skyview.survey.SIAPImageGenerator can use the VO SIA protocol. The image generator is normally specified in the survey description file.

2.3.10.18 ImageFactory

An image factory must be specified in the <Images> area of the survey description file. It converts a string from an <Image> element or from an image generator into an image the can be used by the program. The two supplied image factories are the skyview.survey.FitsImageFactory which is given the name of a file and simply reads it in, and the skyview.survey.CachingImageFactory which is used to access remote data and supports caching. The image factory is normally specified in the survey description file.

2.3.11 HTML output settings

In Version 2.1 and later the SkyView jar can be used in CGI processing of SkyView requests. This is discussed in section 4. The settings that control CGI processing are described here briefly. Normally these settings would be set in the system settings file. System settings used in HTML templates are not included here.

2.3.11.1 HTMLWriter

The Java class for a post-processor that can write HTML describing the images generated. This class is used in all cases except when an RGB image is to be generated.

Example:

HTMLWriter=skyview.request.HTMLWriter

2.3.11.2 RGBWriter

The Java class for a post-processor that can write HTML describing the images generated when an RGB quicklook image has been generated.

Example:

RGBWriter=skyview.request.RGBWriter

2.3.11.3 HeaderTemplate

An HTML Template file used in creating the top of the HTML page.

Example:

HeaderTemplate=cgifiles/skyheader.html

2.3.11.4 SurveyTemplate

An HTML Template file used in creating the HTML text describing the processing of a given survey.

Example:

SurveyTemplate=cgifiles/skysurvey.html

2.3.11.5 FooterTemplate

An HTML Template file used in create HTML text at the end of the HTML page.

Example:

FooterTemplate=cgifiles/skyfooter.html

2.3.11.6 OutputRoot

The root of the name of output files generated in CGI processing. The stem of the name will be generated from the high-resolution timer. All files, FITS, quicklook and catalog, are currently created in the same output directory.

Example:

OutputRoot=../../tempdata/skyview

2.3.11.7 DescriptionXSLT

An XSLT file which will transform a SurveyDescription file into HTML which can be displayed to give information about the survey in a readable way. This is normally set cgifiles/survey.xslt in the system settings.

Example:

DescriptionXSLT=cgifiles/description.xsl

2.4 Batch compatibility keywords

For the convenience of users of the old SkyView batch interface, the SkyView-in-a-Jar application supports most of the arguments of that interface insofar as they related to the generation of FITS files. The following are supported as input settings:

SkyView Batch keyword	SkyView-in-a-Jar setting
VCOORD	Position
SCOORD	Coordinates
MAPROJ	Projection
PIXELX,PIXELY	If both specified, converted to Pixels
EQUINX	Equinox
SFACTR	Size
COLTAB	LUT
ISCALE	Scaling
file	Output

The values are also converted appropriately. E.g., MAPROJ=Gnomonic is translated to Projection=Tan.

Generally image results from the new interface should be very similar to the old SkyView interface. There is one major exception. The IDL code which the old interface used ran almost entirely in single precision arithmetic. The Java classes use double precision arithmetic exclusively with an option for converting the final result to single precision. Users must specify the Float setting to get single precision results. The difference in precision and other small differences in the algorithms mean that there can be small differences in the values returned. E.g., when using a nearest-neighbor resampling, positions near the edge of one pixel might move onto an adjacent pixel.

To prevent users from unexpectedly getting double precision values, the CGI interfaces provided in the jar will set the FLOAT keyword when the VCOORD keyword is found unless the user has explicitly set FLOAT=null.

The format of the FITS headers differs considerably between the two versions. Substantially more information about the processing is included in the new version including the files that were used in generating the output mosaic, all settings used in the command, and outputs from various processors.

3 Program internals

In this section we describe how the SkyView Java application works. This includes short descriptions of some of the algorithms used.

3.1 Order of processing

The basic goal of SkyView is relatively simple. Given a set of one or more existing images comprising a survey, SkyView generates a new image in a user-specified geometry. The output user image may overlap one or more of the survey images, and may overlap different images in different locations. This section discusses how the application accomplishes this task. It mentions some of the key classes that are used in various parts of the program. More information on these classes and the methods described here is available in the JavaDoc descriptions of these classes.

3.1.1.1 Program initiation

The main method of the Imager class is invoked to start the program. This method does no more than create an instance of the Imager class and then call a run method.

3.1.1.2 Handling settings

Settings are handled by the Settings class. When this class is loaded it immediately looks for the system settings file and loads any settings found there. The imager adds user arguments to the settings and has the Settings class process any user specified settings files.

One or more classes may wish to look at the settings before processing begins to fill in further defaults, to allow synonyms or for other reasons. These classes should be specified in the SettingsUpdaters setting. Currently the BatchCompability class allows syntax similar to the old Batch interface while the IJProcessor fills in missing settings when graphics have been requested. A user can add additional SettingsUpdaters if they build their own compatible classes.

3.1.1.3 Finding surveys

Once the user arguments have been parsed, the application looks for surveys using a SurveyFinder object. The class for this object is normally specified in the system settings but can be overridden by the user. Only the XMLSurveyFinder is supplied with the Jar. Using this default SurveyFinder there are four possible sources of surveys:

1. A survey manifest resource. This manifest gives the names of other resources or XML files where each entry defines one survey. The source manifest is where the default surveys are normally found when the executable jar file is used. The location of the survey manifest may be overridden using the appropriate setting.

2. The SourceXML setting. This may be set on the command line, or if the user sets the environment variable SKYVIEW_SOURCEXML then the value of that variable is used. When the SourceXML is set, that directory is searched and each file of type .xml is treated as a survey definition file. Users can use this method to add a set of surveys to their SkyView implementation.

3. The SurveyXML setting. Each field in the SurveyXML is assumed to be a survey definition file.

4. The ‘User’ survey created by the SurveyFile setting. Each field of the SurveyFile is treated as a survey image file. Users can generate an image from this survey by requesting an image from the survey User.

In the initial pass the XML is only parsed far enough to find the names of the surveys. Surveys can have several names. Only the ShortNames are extracted from the descriptions.

3.1.1.4 Looping over the surveys

Once the set of available surveys has been determined, the application loops over the surveys the user has requested. If a user requests a survey that is not found, an error is signaled and processing continues with the next survey. The imager asks the survey finder to create a Survey object matching the requested name. The corresponding survey definition file is parsed and a Survey object is created Part of the survey definition file is a set of survey default settings, e.g., the default scale for the image, or whether the image will be de-edged. These settings do not override settings already made, so that survey settings do not supersede anything the user explicitly specified.

3.1.1.5 Getting candidate survey images

The first step in processing a survey is determining a list of candidate survey images that may be used in generating the output image. The imager requests a set of candidate images from the survey object. The imager gives the position and size of the requested image.

If a survey uses the VO Simple Image Access Protocol (see http://us-vo.org), then the candidates are all images returned in the initial SIAP request. If the survey explicitly lists the images, then the application passes through these images and uses the ImageSize characteristic to find images that might overlap part of the user’s image. If this is a request for the User survey, then all of the images the user specified are candidates.

3.1.1.6 Creating a blank output image

At this point the imager knows enough to completely determine the geometry of the output image. The user will have specified the center position and there will be either explicit specification of or defaults of the projection, coordinate system, orientation, etc. The scale/size of the input image may not be known until the survey is loaded, since the default scale can vary from survey to survey.

A blank Image object is created for the output image. This image has the correct geometry for the output, but has all 0 pixel values.

3.1.1.7 Finding the best survey image for each output pixel

Once the set of candidate images is determined and the geometry of the output image is finalized the imager calls an ImageFinder to determine which input image (or images) to sample for each pixel in the output image. A number of image finder classes are available in the imagefinder package. The default is to use the Border image finder. The image finder can be specified using the ImageFinder setting.

The BorderFinder first looks at the corners of the output image and the positions of these four corners of the output image are transformed to the frame for each of the candidate input images. The best candidate image for each of the four pixels is then determined. The ‘best’ input image is where the output pixel location is located in the image but furthest from the edge of the input image.

E.g., consider a corner in the output image and assume there are three candidate images each of which is a 500x500 image. The corner position is transformed into the pixel coordinates of the three candidate images. If the pixel coordinates corresponding to the output pixel in three candidate inputs are (-80, 300), (40,40) and (250,35), then the second image is the best. The output pixel location is not within the first image, and is only 35 pixels from the edge of the third, but 40 pixels from the edge of the second. The other image finders (ScaledBorder, Radius and MaxExposure) use other methods for picking the 'best' candidate from among the candidate images where the image is in the field of view.

If all four corners match the same input image, then all of the border pixels are also checked. If all of the border pixels also have the same best image, then this class assumes that the interior of the rectangle can also be sampled from the same input image. Otherwise the input rectangle is split into subrectangles and these are checked recursively.

When the user specifies CornersOnly, only the corners are checked, not the borders. This was the default behavior in versions of SkyView prior to 2.02. The StrictGeometry setting was sometimes needed here to ensure that the correct image was chosen. It should now be obsolescent.

If CheckNaNs is set, then additional checking is done for the corner and border pixels. If for a given output pixel the nearest input image pixel is a NaN, then that input image will not be selected as the best image for the output. Since CheckNaNs requires the actual input data it requires that data for all candidate input images be downloaded.

Normally only the geometry of the input images is needed at this stage. If an image is not local rather than downloading it, a proxy image which has the same geometry (or a close approximation) is created. This proxy is only converted to a real image if and when the underlying data is required.

In the case where the output image is comparable to or larger than the input images, the initial checking will be done on rectangles no larger than half the size of the input images. As we recurse into smaller rectangles, only a subset of the input images are kept as candidates. When all four corners of the output rectangle project outside of the input image, and all project to one side (top or bottom, or left or right), then that input image is no longer a candidate for consideration. E.g., if the output image pixels project two to the top right of the input image and two top left of the input image, then all of the corners projected to the top and that input image no longer need be considered for the current rectangle (or its sub-rectangles).

The end-point of this process is an integer array with the same dimensions as the user output image but where the value at each pixel is the best input image. Special flag values are used to indicate that this output pixel is not matched by any survey image. An output pixel may also be outside of the standard projection coverage, e.g., outside the oval of an all-sky Aitoff projection, or the circle defined in the Orthographic (Sine) or Zea projections.

In many cases the user may have selected images from a set of surveys which have identical or near identical geometry (e.g., IRAS100 and IRAS25, or 2MASS-J and 2MASS-K). These are called ‘geometry twins’ and are identified in the survey descriptor files. If two geometry twins are processed in succession, then the calculation of the best image from the first twin processed is re-used for the later twin (or triplet, or …).

3.1.1.8 Creating the samplers

One or two more objects are needed to be able to process the image. A sampler object is created which encapsulates the algorithm that will be used to resample the input images. If the input images are three-dimensional a DepthSampler will be needed to do the resampling in the energy dimension. These are created according to the user specification or defaults.

3.1.1.9 Processing

At this point all of the pieces are ready for the actual processing of the image. A set of one or more processors will run on the image. Each processor will be given five objects:

· an array of candidate input images,

· the originally blank output image,

· the array of indices created by the image finder pointing to a given input image for each output pixel,

· the sampler, and

· the depth sampler (which may be null).

Processing is divided into three stages.

One or more preprocessors may be invoked. These work before the output image is filled. They may do some transformation of the input images or other preparatory tasks. The major current preprocessor handles catalog requests. Requests are initiated before image processing and run in threads parallel to the image processing. A catalog postprocessor collects the results of the queries initiated by the preprocessor. Since most catalog requests are of remote resources this reduces the total time needed for the request.

A single mosaicking processor is used to fill the output image. Only one mosaicker is provided in the Jar, but the user is free to use a customized mosaicker.

Postprocessors run after mosaicking. The may do additional processing of the output image (e.g., de-edging), or create additional output products.

3.1.1.10 Mosaicking and resampling

The default mosaicker loops over pixel index list created by the image finder to find a pixel that has not yet been resampled. It then begins to process all the pixels that are to be resampled from the same candidate image. For most resamplers the center of the output pixel is projected into the plane of the input image. For the clipping sampler, the corners of the pixel are projected. The output pixel is then populated with the resampled value according to the requested algorithm. If the output image has depth in the energy dimension, the sampling is performed at each output energy channel.

Higher order samplers use data from a sampling kernel, a few pixels around the point being sampled. If there is a NaN anywhere in the kernel, the result will also be a NaN. To limit the propogation of NaNs, the user may use a Combo resampler which normally uses a high-order, larger-kernel resampler, but falls back to a lower order resampler if the high order resampler detects a NaN. If the input images are not fully sampled and NaNs are used to indicate non-imaged regions, then using a Combo resampler may be needed to avoid NaNs where images overlap.

Currently the spline sampler cannot process 3-d images.

If the input data is three-dimensional the data is sampled in energy before being sampled in space using the depth sampler. Each of the energy planes is then resampled spatially as above.

After processing a given pixel the mosaicker marks it as processed and then moves onto the next pixel. After finishing all of the pixels from a given input image the mosaicker looks to see if there are any unprocessed pixels and if so begins processing pixels from another of the inputs.

3.1.1.11 Post-Processing

After the data have been resampled, post-processing may be performed. The interface for post-processing is exactly the same as for pre-processing and mosaicking. Examples of post-processor are de-edging and graphics processing. Users may add their own post-processors.

De-edging

Since survey data may have different background values in the different survey images, the edges of the image may show up as an unsightly artifact. If the user wishes to minimize the edges, then a de-edger may be run on the output image. .

The algorithm used by the default deedger attempts to minimize discontinuities along borders. The output image is divided into regions defined by the input image from which the pixels were sampled. These regions are placed into adjusted and unadjusted sets. The region with maximum number of pixels is placed in the adjusted set and all other images are initially unadjusted. The program then looks for the longest border between an adjusted and unadjusted region. Borders are defined by looking at each pixel and seeing if any of the four neighboring pixels is from another region (diagonals are not considered). The median of the shifts as we move across the border from the adjusted to the unadjusted regions is computed. An offset is applied to the unadjusted region to set the median shift across the border to 0. The unadjusted region is moved into the adjusted set, and the process iterates until all regions have been adjusted. Other classes use somewhat different algorithms to compute the offsets for images: using the average rather than the median shift at the border, or basing the medians on all pixels that come from an image, not just the boundary pixels.

The FITS headers include information on the adjustments made when de-edging is applied.

Graphics Processing

All graphics outputs are also produced in post-processing. Appropriate functions in the ImageJ library are called to produce the desired data. Graphics processing does not affect the FITS data. If Min or Max settings were given, then any values below or above the limits are replaced by the limit value. The data is then scaled using the appropriate scaling method. Logarithmic (Log) and Square-root (Sqrt) scaling scale negative values to 0 (or the minimum positive value for log). The result is an image with values ranging from 0 to 255. These data are then converted to the requested graphics output.

When a user requests an RGB image from three input surveys, each of these surveys is processed in turn and the scaled results are stored until the last survey is processed. Then the three images are combined to create a single RGB JPEG file.

HTML Processing

If an HTML postprocessor has been specified, then HTML output will be written to the standard output of the process. The metadata in the survey description file is fully parsed so that these metadata are available as settings to be included in the HTML stream. The HTML template files are read and any appropriate substitutions are made before they are written out to standard output.

3.1.1.12 Data conversion and writing the FITS file

If the user has not suppressed FITS output, the program now prepares the FITS file. All of the internal computations are done with the data as a one-dimensional double array of values. Before writing the data out, the application checks to see if the user wished to have only 4-byte reals (float’s in C or Java-speak) rather than the default 8-byte data (double’s). If so the data is converted. The program then creates a FITS header and calls all of the processing objects to add information to the header. The FITS header and data are then written. The nom.tam.fits is used for the FITS header, but the FITS data is written directly (starting in v2.1) since transforming the array to a two dimensional array requires an extra copy of the image array and limits the ability of Imager to handle large (>10 megapixel) images. Survey-dependent information to be included in the FITS header, is specified in the <FITS> element of the survey description. The various processors used in generating the image may also write history records into the header.

3.1.1.13 Cleanup

If a user requested data that was not present in local files, this data is first downloaded into the first cache directory (the current directory by default). By default downloaded survey files are left for possible use in subsequent requests, but if PurgeCache has been set, then these files are deleted as the processing for each survey is completed. However only the files actually downloaded during this request will be purged. Files already present in the cache will be left untouched.

During the processing of the survey many settings may have been altered or added. As the last stage in survey processing the settings revert to the state they had at the beginning of survey processing so that the imager is ready to handle the next survey.

3.2 Software organization

The SkyView jar uses Java packages to organize functionality. This section gives an overview of the functionality in the main SkyView packages and describes some of the main classes. Not all classes are mentioned especially if they are special cases of a more general class.

3.2.1 Package skyview.geometry

The geometry package contains all of the code which does coordinate transformations on amongst position representation within SkyView. Coordinates may represent points the sphere, in which case the coordinate is stored as a unit vector, or as a points on a projection plane, in which case the point is stored as (x,y) pair. A transformation is broken up into discrete elements of various types. The base class Transformer is specialized into Rotater, which rotates unit vectors; SphereDistorter, which does non-rotational transformations on the sphere; Projector, which projects coordinates from the sphere to a projection plane; Deprojector, which does the inverse; Scaler, which does linear transformations on the plane; and Distorter, which does non-linear transformations in the projection plane.

For example suppose we wish to resample a DSS image of 3C273 and make an image in a Tan projection in Galactic coordinates. To convert from one set of coordinates, we first use a Scaler to translate from the pixel coordinates of the DSS image to the nominal projection plane. A Distorter removes the distortions of the Schmidt plate geometry and transforms to a more standard Tan projection. A Tan Deprojecter transforms the coordinates onto the celestial sphere in the coordinate system of the DSS, J2000. Since we want Galactic coordinates we use a Rotater to convert the coordinates to Galactic. If Besselian coordinates were involved we would need a SphereDistorter to accommodate the peculiarities of that coordinate system. Next a Tan Projecter projects to a nominal Tangent plane projection. Another Scaler transforms from the nominal coordinate system to the pixel scale we are interested in.

Rather than requiring users to deal with all of these separately, two other Transformer classes provide a simpler view. The Converter class runs a series of transformations and lets the user build it up in pieces. The WCS (or WorldCoordinateSystem) combines all of the transformations involved in going from the standard coordinate system (J2000 coordinates) to a given image's pixels. CoordinateSystem and Projection classes are available as factories to provide needed transformers to add to a WCS.

The Sampler and DepthSampler classes do sampling in space and energy respectively and area also in the geometry package.

3.2.2 Package skyview.process

The process package includes most of the routines that do the bulk of the processing of requests and most of its classes implement the Processor interface. ImageFinder finds the best input image to resample at each pixel of the output image. Deedger tries to match backgrounds at the boundaries between input images. Mosaicker manages the mosaicking and resampling of pixels.

3.2.3 Package skyview.executive

The executive package has two key classes: Imager is the main class for the SkyView jar. It is the class that puts together all of the pieces to create the output data.

The Settings class manages SkyView's settings. Settings has only static methods.

BatchCompatability allows the user to use keywords from the old SkyView interface in the new system.

In Version 2.3 the Batch class is available. It provides a mechanism for running a series of image requests within the same Java session.

3.2.4 Package skyview.survey

The survey package includes the classes that deal with SkyView surveys and data. The SurveyFinder (implemented in XMLSurveyFinder) will find a survey given its name. A Survey will return a list of candidate images and also load survey specific settings and metadata. The Image class combines an array of pixel values with a WCS defining the geometry of the Image. An ImageFactory actually creates Images. The ImageGenerator classes will generate candidate names or URLs for images when they are to be generated programmatically rather than listed explicitly.

The XMLSurveyDescription class translates survey descriptions into HTML.

3.2.5 Package skyview.data

This package includes a BoxSmoother to smooth images. It also has a Gridder which creates the data for the coordinate grid overlays. The CoordinateFormatter formats coordinates in decimal and sexagesimal formats.

3.2.6 Package skyview.vo

The VO package includes the catalog query capabilities for SkyView which use the Virtual Observatory Cone Search protocol. The ConeQuerier class does the querying, which the CatalogProcessor and CatalogPostProcessor are invoked by Imager to display the results for the user.

3.2.7 Package skyview.sia

There are several classes in this package that support implementation of a VO Simple Image Access service. The SIA class uses special image finders and mosaickers.

3.2.8 Package skyview.ij

This package handles the interface between SkyView and the ImageJ package. The IJProcessor is invoked whenever the user has asked for quicklook data.

3.2.9 Package skyview.request

The request package handles the relationship between SkyView and CGI requests. It includes the SourceCoordinates class which will parse source coordinates and make name resolver queries to understand target names. The HTMLWriter and RGBWriter create HTML outputs, and the CGIInitiator class translates a CGI request into Settings before invoking an Imager.

3.2.10 Package skyview.test

The test package includes a regression test class BasicTester. Additional tests should be included in future releases.

3.2.11 Package skyview.util

The utility package has a number of convenience methods and classes used elsewhere.

3.2.12 External Software

Two major external packages are included in the SkyView jar. The nom.tam FITS and utility classes provide FITS I/O capabilities and general functionality for manipulating arrays. The ImageJ package is included for quick look functionality and to provide and interactive interface with the data. The single class net.ivoa.util.CGI is also included in release 2.1. It is expected that more Virtual Observatory developed classes will be included in future releases.

4 CGI Processing

The SkyView-in-a-Jar software is also designed to run SkyView's primary Web site and supports processing of standard Web CGI requests. Although a Servlet based approach might be somewhat faster, we have chosen to implement Web processing using CGI rather than servlets since it is much easier to set up an HTTP server for CGI. With Java 1.5 the initiation costs for Java requests is substantially reduced and is not too significant compared to the typical image request. All CGI methods can be invoked using either GET or POST HTTP requests.

The commands described here process the system settings file normally, but any arguments to the commands are also treated as settings files to set additional runtime settings. E.g., they might be invoked as

java -cp skyview.jar skyview.executive.CGIInitiator runtime.settings

Both the skyview.settings and runtime.settings file will be read for settings. There can be multiple runtime settings files specified on the command line.

4.1 CGI Image requests.

The skyview.request.CGIInitiator class's main method will convert CGI arguments into appropriate Settings and then invoke the skview.executive.Imager class that is invoked directly when using the jar file in a command line environment. This method translates repeated CGI arguments into a single setting, e.g., if a CGI GET request included the parameters survey=dss1r&survey=dss1b the survey setting would be dss1r,dss1b.

The CGIInitiator class also ensures that an HTMLWriter (or RGBWriter) postprocessor is invoked. This post-processor will write HTML which describes and links to the images generated. Thus the entire script to respond to a SkyView request might be as simple as:

#!/bin/sh

java –cp skyview.jar skyview.request.CGIInitiator

The HTML processors supplied by default use three template files. The header template includes whatever is to be presented at the top of the page before the first survey is processed. A survey template is invoked for each survey processed, and a footer template is written out after the last survey is processed. The header and footer templates may be static, but the survey template normally uses system settings to link to and describe the image being produced. A survey template file might look like the text in the box below. It consists of standard HTML but includes many strings that begin with $. As a template is processed any string which matches the regular expression \$[a-zA-Z0-9_]+ is replaced by the current setting corresponding to that string (with the leading $ omitted). This includes many settings that are set during survey and image processing which casual users would normally not see. If the setting does not exist, then text is unchanged. The HTML output can be annotated with the appropriate metadata about the surveys and the images created and appropriate links can be made to the files that were just created.

$Text Box: <h2>$_currentSurvey: $name</h2> <a href="$_output_ql"> <img alt="Quicklook $name image" src="$_output_ql"></a> <br> Download <a href=$_output.fits>FITS</a> or <a href=$_output_ql>quick look $quicklook </a> image. <br> <table> <tr><th align=right>Image color table:</td><td align=left><img src="ct$_ctnumb.gif" border="1alt="graphical"></td></tr> <tr><th align=right>Image scaling:</td> <td align=left>$scaling, values range from $_imageMin to $_imageMax</td></tr> <tr><th align=right>Image size(degrees):</td><td align=left> $_imageXsize x $_imageYsize</td></tr> <tr><th align=right>Image size(pixels):</td><td align=left> $_imageXpixel x $_imageYpixel</td></tr> <tr><th align=right>Requested Center:</td> <td> $position</td></tr> <tr><th align=right>Coordinate System:</td><td align=left> $_coordinateSystem</td> <tr><th align=right>Map projection:</td> <td align=left> $_projection</td></tr> <tr><th align=right>Sampler:</td> <td align=left> $_sampler</td></tr> <tr><th align=right>Provenance:</td> <td align=left> $_meta_provenance</td></tr> <tr><th align=right>Copyright:</td> <td align=left> $_meta_copyright</td></tr> <script language=JavaScript> if ( ! ('$catalogFile'.substring(1) == "catalogFile" ) ) { document.writeln("<tr><th align=right>Requested catalogs:</th>"+ "<td><a href='$catalogFile'>Data</a></td></tr>") } </script> <noscript> <tr><th align=right>Requested catalogs:</th><td><a href='$catalogFile'>$catalogFile</td></tr> </noscript> </table> <a href='surveyinfo.sh?survey=$_currentSurvey'>More information</a> </a> An example survey template file.$
A user can use JavaScript to conditionally write text in the HTML. In the example above, if the user has not specified a catalog request the catalogFile setting will not be available. The test in the first line of the JavaScript section will fail and the line in the table for describing the catalog outputs will not be included.

Special processing is invoked when an error is found. The ErrorMsg setting should have text describing the error.

4.2 Displaying survey descriptions

The class skyview.survey.XMLSurveyDescription converts the XML survey description file into an HTML document. This may be invoked from a CGI script as well. If a survey argument is present (in the CGI sense), only that survey will be displayed. If no survey is given, all surveys will be described. The class uses a straightforward XSL transformation. The XSLT file that describes the transformation is given in the DescriptionXSLT setting.

When no survey is specified, the descriptions of all of the surveys can be preceded by text in the file specified by SurveysHeader and suffixed by the text in SurveysTrailer.

4.3 Building a simple image access service

The class skyview.sia.SIA can be used to build a Virtual Observatory Simple Image access interface to surveys known to the local SkyView installation. Using the VO protocol, a user specifies a region in the sky and the class returns an XML file with URLs that link to the surveys with coverage in the region. The user can specify which surveys to look at and a number of other options. The SIA protocol specifies how a user makes CGI requests of the service and specifies an XML (VOTable) format in which the service returns information about images it may have that satisfy the users requirements.

The SIA service runs using a special image finder. The finder looks to see if there is any pixel in the user’s requested output region which can be resampled from any of the input images of the survey. If there is no overlap between a survey and the requested region, then no data is returned for that survey. If there is overlap, a URL that will invoke the regular SkyView query is returned along with appropriate metadata in the VOTable format required by the SIA protocol.

The setting DefaultSIASurveys is used to specify the surveys that will be searched if the user does not specify this explicitly. Also, settings can be used to create a group of surveys, e.g., 2MASS could mean all three 2MASS surveys. The program checks the name of the survey that a user has specified. If this name is itself a setting, then the value of the setting is used. So the system might be set up with a system settings file of

2mass=2mass-h,2mass-j,tmass-k

Then when a user makes an SIA request for the 2mass survey, all three surveys will be searched.

5 Survey configuration

Each survey (other than the User survey) used in SkyView is defined by a survey definition file. This is an XML file that pulls together all information needed to use the survey. This section describes the structure of the file. [Note: This assumes the default SurveyFinder object. A user can define SurveyFinder object with any behavior that they specify.]

There is no formal schema for the survey file format but the program assumes the following order.

Survey

ShortName

Name

Description

Settings

MetaTable

OnlineText

FITS

Images

5.1 Contents of the description file

5.1.1 <ShortName>

The short name element gives one or more short names for the survey. Short names are used as the values of the Survey keyword in the SkyView-in-a-Jar application and therefore it is recommended that they not contain embedded blanks. If multiple short names are to be specified they are separated by commas. All survey description files are read at program startup until the short name is found, so putting this first can speed up the program a little.

Examples:

<ShortName>EGREThard,EGRET100-10000</ShortName>

5.1.2 <Name>

The name element gives a longer name for the survey generally spelling out acronyms and such that may have been used in the short name.

Example:

<Name>Two Micron All-Sky Survey: K band </Name>

5.1.3 <Description>

This gives a text description of the survey. This may include HTML and if so should be coded as a CDATA element.

Example:

<![CDATA[

This LISA Galactic survey is a low-resolution image

of the gravitational background in

the Galactic plane as described in <a href=someurl>Lisa

Galactic Plane Handbook

</a>

]]>

</Description>

5.1.4 <Settings>

The settings element is used to specify survey specific settings. Within the settings element there may be 0 or more sub-elements of the form

<key>value</key>

When processing of a specific survey begins, the Settings element is parsed and the Settings hash is updated with any key/value pairs found. The case of the key is not distinguished but case may be important in the value. Note that XML parsers require that the opening and closing case of the keys be consistent within the file.

Common survey specific settings include the default image scale (Scale), other surveys that have the same geometry (GeometryTwin), the default energy binning for 3-d surveys (EBins), and post-processing options, notably the de-edger.

Survey settings will not override existing user-specified settings: they are inserted into the Settings using the suggest rather than the put method.

<GeometryTwin>SurveyA,SurveyB,SurveyC</GeometryTwin>

<Deedger> skyview.process.Deedger </Deedger>

</Settings>

Since the survey settings do not override user specified settings, the default de-edging of this survey will be turned off when the user specifies Deedger=null.

5.1.5 <MetaTable>

The MetaTable element includes a set of metadata elements that give an overall description of the survey. SkyView attempts to give some common information about all surveys, energy range, resolution, … and these are grouped in the MetaTable.

The MetaTable information is normally included in any FITS file produced and elements may be displayed in other interfaces. In CGI processing the values of the MetaTable elements are available as settings prefixed with "_meta_". E.g., the provenance of the data is stored in the Settings _meta_provenance. They may be included in the HTML output linked to the survey. If a MetaTable element will include HTML elements it should be enclosed as CDATA.

The elements expected in the MetaTable include

Provenance: The source of the data.

Copyright: Any copyright holder and restrictions on the user of the data

Regime: The spectral regime for the data: Radio, Infrared, Optical, UV, EUV, X-ray or gamma-ray.

NSurvey: The number of distinct surveys/bands described. E.g., the SDSS has 5 bands while 2MASS has 3. Each band will have its own survey description file, but the metatable information will typically be the same for all of them.

Frequency: The frequency of the data. This is always given in Hertz. Other units may also be provided.

Resolution: The typical resolution of the survey. This may not be the pixel size.

Scale: The size of the original pixels in the survey. This is normally the default scale for retrieval.

Coordinates: The original coordinate system of the survey data.

Equinox: The equinox of Equatorial or Ecliptic coordinates.

Projection: The projection of the survey data.

Epoch: The observational epoch of the survey data.

Reference: References to articles and web sites describing the survey in detail.

Example:

NASA IPAC/Jet Propulsion Laboratory

</Provenance>

<Copyright> Public Domain </Copyright>

<Regime> Infrared </Regime>

<Coordinates> Equatorial </Coordinates>

<Projection> Gnomonic(TAN) </Projection>

<![CDATA[

Wheelock, et al., 1991, IRAS Sky Survey Atlas Explanatory

Supplement.

]]>

</Reference>

</MetaTable>

5.1.6 <OnlineText>

The online text element is used to include text that is to be shown on Web pages associated with a generated image. Any string of the form $[a-zA-Z0-9_]* is replaced by the corresponding setting.

5.1.7 <FITS>

The FITS element includes information to be included in the FITS header generated with the image.

Example:

<FITS>

<![CDATA[

SURVEY = ‘IRAS 100 micron’

BUNIT = ‘MJY/SR ‘ / INTENSITY

COMMENT Note that the values are not adjusted for any change in pixel

COMMENT size from the original pixel size of 90 x 90 arcseconds

BLANK = -2000000000 / TAPE VALUE FOR EMPTY PIXEL

ORIGIN = ‘JPL-IPAC’ / INSTITUTION

TELESCOP= ‘IRAS ‘ /

INSTRUME= ‘ISSA-FLD’ / IRAS SKY SURVEY ATLAS

EDITED = T / SCANS EDITED

APPCAL = T / CALIBRATION CORRECTION 25 MICRON

DE-ZODY = T / DE-ZODIED IMAGE

GLBL-D = T / APPLIED GLOBAL PARAMETERS

LOCAL-D = T / LOCAL DESTRIPER

ASBLANK = T / ASTEROID BLANKING

]]>

</FITS>

5.1.8 < Images>

The main business of the survey file is in the Images element. There are two main configurations: an explicit list of the images in the survey, or a link to a class that will generate a list of images for a given user request. Most of the fields in the Images element (with the exception of Image elements) are parsed when survey processing begins and used to update or set entries in the Settings hash. However, unlike the fields in the Settings element, these settings override any existing settings.

5.1.8.1 Explicit Image Lists

In this case, the Images element will contain a set of Image elements. Each element has a text value with four blank delimited tokens: the filename or spell, a longitude and latitude, and the epoch of the image. The coordinate system for the longitude and latitude can be specified in the SurveyCoordinateSystem setting and defaults to J2000. In addition to the Image elements there should at a minimum be an ImageFactory element and an ImageSize element. The image size gives the size in degrees of the smaller dimension (if not square) of the images. This is used in the process of determining the best image for each output pixel.

The ImageFactory gives the class which given the appropriate spell or file name creates the image. The skyview.survey.FitsImageFactory takes a filename and simply reads the file to create the input image. If a <FileNamePrefix> element is found then this prefix is prepended to the file name in the Image element before being passed to the FitsImageFactory.

The skyview.survey.CachingImageFactory image factory assumes that it is being given a spell that tells it both how to retrieve the data as a URL as well as sufficient metadata to create a proxy image. The spell consists of 10 or 12 comma delimited fields. These are:

1. The URL to retrieve the data from

2. The file name to store the cached file as

3. The longitude of the center of the image/X-offset of the center of the image

4. The latitude of the center of the image/Y-offset of the center of the image

5. The projection used in the image

6. The coordinate system used in the image

7. The width of the image in pixels

8. The height of the image in pixels

9. The width of a pixel in degrees

10. The height of a pixel in degrees

..or..

9-12. The CD matrix elements for the image.

For projections (Aitoff, Cartesian and CSC) where the reference value of the projection is normally fixed, the third and fourth tokens are the pixel offsets for the image, while for other projections the reference pixel is assumed to be at the center of the image and these two values are the coordinates of the reference value.

The user familiar with FITS will note the similarity of fields 3-10 (or 12) to standard FITS WCS keywords. Note that the spell does not need to use the same coordinate system as the other fields in the Image elements.

If SpellPrefix or SpellSuffix values are specified in the Images element, then the Image spell string is appropriately extended. Usually much of a spell is constant for a given survey.

5.1.8.2 Image Generators

Rather than specifying each individual image, the survey file can describe an ImageGenerator class that will generate the images. An Image generator can generate either files or spells.

There are specialized image generators for the DSS and 2MASS surveys. Users may wish to examine these classes for extension to other special surveys, but the most useful generator is likely to be the SIAPGenerator. The SIAP generator uses the Virtual Observatory Simple Image Access protocol and can be adapted to use many of the existing SIAP services with appropriate entries in the Images element.

The settings keys used are:

SiapURL: defines the base URL for the Simple Image Access service.

SiapProjection: The projection used in images returned by the service

SiapCoordinates: The coordinate system used in images returned by the service

SiapNaxis: The size (in pixels) of image returned by the service

SiapScaling: The size (in degrees) of the pixels returned by the service

SiapMaxImages: The number of images returned to include as candidates.

Alert readers will note the correspondence of most of the fields to the spell parameters and to the FITS WCS fields. SIAP services can return WCS information for each image explicitly and to the extent that they do so (e.g., almost all return the size of the image in pixels), the user need not supply this information. However many (most) SIAP services do not supply all needed information. The fields above remedy any deficit.

Not all SIAP services are good candidates for immediate inclusion as a service. SkyView will use all images returned as candidates even if the images are quite heterogeneous. Only SIAP services that return relatively homogeneous images can be used without some filtering the SIAP results. However it is often easy to modify the SIAPGenerator to do such filtering.

The third example below shows the power of the SIAPGenerator. The entire SDSS survey is included as a survey with just a few lines of text.

5.1.8.3 <Images> Examples

Listing local files:

/surveydata/iras/iras100/

</FilePrefix>

skyview.survey.FitsImageFactory

</ImageFactory>

... 425 more Image elements ...

</Images>

Listing remote URLs:

<SpellPrefix> http://skyview.gsfc.nasa.gov/survey/iras100/images/

</SpellPrefix>

<ImageFactory> skyview.survey.CachingImageFactory </ImageFactory>

...425 more images ...

</Images>

Using an Image generator.

<![CDATA[

http://casjobs.sdss.org/vo/DR3SIAP/siap.asmx/getSiapInfo?FORMAT=image/fits&BANDPASS=I&

]]>

</SiapURL>

<ImageFactory> skyview.survey.CachingImageFactory </ImageFactory>

<ImageGenerator> skyview.survey.SIAPGenerator</ImageGenerator>

</Images>

5.2 A Simple Survey Definition File

While a survey XML definition file can be complex, most data is optional. A minimal survey definition need only include the short name of the survey, a default scaling, the image size and the names and locations of the included files.

<ShortName> MySimpleSurvey </ShortName>

</Settings>

<ImageFactory>skyview.survey.FitsImageFactory</ImageFactory>

</Image>

</Survey>

This describes a survey with three images along the equator (at RAs of 0, 10 and 20 degrees) which have a minimum dimension of 10 degrees and 0.1 x 0.1 degree pixels.

6 Organization of the jar file

The SkyView jar file contains files from a number of directories as well as individual files used by the program. This section discusses the content of the jar for users who may wish to create their own customized versions of the jar. You can view the contents of the jar file using the command jar –tf skyview.jar.

6.1.1.1 The Class Files

Class files are found in three directory trees:

skyview/... contains the class files for the class files developed in SkyView. This includes all the code relating to geometric transformations, image surveys and the main program for the jar file.
nom/... contains the methods for reading and writing FITS files and utility I/O functions.
ij/... contains the classes and a few data files) for ImageJ.

6.1.1.2 Survey data and metadata

The jar file contains metadata descriptions for all standard surveys and actual survey data for a few. Metadata descriptions in the format described above are found in surveys/xml. FITS data for a few surveys is found in surveys/data.

The survey manifest file gives a list of all of the surveys included in the jar and is found in surveys/survey.manifest.

6.1.1.3 Control files

A number of control and miscellaneous files in the jar.

The skyview.settings file contains the default system settings for the program.
IJProps.txt contains settings used by ImageJ.
The MANIFEST/MANIFEST.MF file is included in the jar using a command like jar fm skyview.jar manifest.fil (the jar command renames the file when it is inserted). It contains a single keyword value pair that gives the class which is to be used when the jar is executed (currently skyview.executive.Imager).
The onlineinfo.txt file contains help text which is displayed when the program is invoked without any arguments.

6.1.1.4 Source code

Source code is found in the source/... hierarchy for all Java classes defined in the jar file.

6.1.1.5 CGI processing

Files used in CGI processing are found in the cgifiles directory. This includes HTML template files, XSLT files for transforming the survey description file, and sample scripts for running the jar as a CGI application.