Provided by: stilts_3.2-2_all 
NAME
stilts-plot2sky - Draws a sky plot
SYNOPSIS
stilts plot2sky [xpix=<int-value>] [ypix=<int-value>] [insets=<top>,<left>,<bottom>,<right>]
[omode=swing|out|cgi|discard|auto] [storage=simple|cache|basic-cache]
[seq=<suffix>[,...]] [legend=true|false] [legborder=true|false] [legopaque=true|false]
[legseq=<suffix>[,...]] [legpos=<xfrac,yfrac>] [title=<value>] [auxmap=<map-
name>|<color>-<color>[-<color>...]] [auxclip=<lo>,<hi>] [auxflip=true|false]
[auxquant=<number>] [auxfunc=log|linear|histogram|histolog|sqrt|square] [auxmin=<number>]
[auxmax=<number>] [auxlabel=<text>] [auxcrowd=<factor>] [auxwidth=<pixels>]
[auxvisible=true|false] [forcebitmap=true|false] [compositor=0..1] [animate=<table>]
[afmt=<in-format>] [astream=true|false] [acmd=<cmds>] [parallel=<int-value>]
[projection=sin|aitoff|car|car0] [viewsys=equatorial|galactic|supergalactic|ecliptic]
[reflectlon=true|false] [grid=true|false] [scalebar=true|false]
[labelpos=Auto|External|Internal|Basic|Hybrid|None] [sex=true|false] [crowd=<number>]
[gridcolor=<rrggbb>|red|blue|...] [labelcolor=<rrggbb>|red|blue|...] [gridaa=true|false]
[texttype=plain|antialias|latex] [fontsize=<int-value>] [fontstyle=standard|serif|mono]
[fontweight=plain|bold|italic|bold_italic] [clon=<degrees>] [clat=<degrees>]
[radius=<degrees>] [zoomfactor=<number>] [leglabelN=<text>] [layerN=<layer-type> <layerN-
specific-params>]
DESCRIPTION
plot2sky draws plots on the celestial sphere. This can be represented in a number of ways, controlled by
the projection parameter; by default the view is of a rotatable sphere seen from the outside (which
approximates to a tangent projection for small regions of the sky), but Aitoff and Plate Carée
projections are also available. A number of options are also provided for drawing and labelling the grid
showing celestial coordinates.
Positional coordinates are specified as lon, lat pairs giving longitude and latitude in decimal degrees.
By default these are represented in the output in the same, unlabelled, coordinate system. However the
command can can also transform between different coordinate systems if you specify the data and view
systems e.g.: plot2sky viewsys=galactic layer1=mark in1=cat.fits lon1=RA2000 lat1=DEC2000
datasys1=equatorial
Content is added to the plot by specifying one or more plot layers using the layerN parameter. The N part
is a suffix applied to all the parameters affecting a given layer; any suffix (including the empty
string) may be used. Available layers for this plot type are: mark, size, sizexy, skyvector, skyellipse,
skycorr, link2, mark2, poly4, mark4, polygon, label, contour, skydensity, healpix, skygrid.
OPTIONS
xpix=<int-value>
Size of the output image in the X direction in pixels. This includes space for any axis labels,
padding and other decoration outside the plot area itself. See also insets.
ypix=<int-value>
Size of the output image in the Y direction in pixels. This includes space for any axis labels,
padding and other decoration outside the plot area itself. See also insets.
insets=<top>,<left>,<bottom>,<right>
Defines the amount of space in pixels around the actual plotting area. This space is used for axis
labels, and other decorations and any left over forms an empty border.
The size and position of the actual plotting area is determined by this parameter along with xpix
and ypix.
The value of this parameter is 4 comma separated integers: <top>,<left>,<bottom>,<right>. Any or
all of these values may be left blank, in which case the corresponding margin will be calculated
automatically according to how much space is required.
omode=swing|out|cgi|discard|auto
Determines how the drawn plot will be output, see SUN/256.
* swing: Plot will be displayed in a window on the screen. This plot is "live"; it can be
resized and (except for old-style plots) navigated around with mouse actions in the same way
as plots in TOPCAT.
* out: Plot will be written to a file given by out using the graphics format given by ofmt.
* cgi: Plot will be written in a way suitable for CGI use direct from a web server. The output
is in the graphics format given by ofmt, preceded by a suitable "Content-type" declaration.
* discard: Plot is drawn, but discarded. There is no output.
* auto: Behaves as swing or out mode depending on presence of out parameter
storage=simple|cache|basic-cache
Determines the way that data is accessed when constructing the plot. There are two basic options,
cached or not.
If no caching is used (simple) then rows are read sequentially from the specified input table(s)
every time they are required. This generally requires a small memory footprint (though that can
depend on how the table is specified) and makes sense if the data only needs to be scanned once or
perhaps if the table is very large.
If caching is used (cache) then the required data is read once from the specified input table(s)
and cached before any plotting is performed, and plots are done using this cached data. This may
use a significant amount of memory for large tables but it's usually more sensible (faster) if the
data will need to be scanned multiple times.
The default value is cache if a live plot is being generated (omode=swing), since in that case the
plot needs to be redrawn every time the user performs plot navigation actions or resizes the
window, or if animations are being produced. Otherwise (e.g. output to a graphics file) the
default is simple.
seq=<suffix>[,...]
Contains a comma-separated list of layer suffixes to determine the order in which layers are drawn
on the plot. This can affect which symbol are plotted on top of, and so potentially obscure, which
other ones.
When specifying a plot, multiple layers may be specified, each introduced by a parameter layer<N>,
where <N> is a different (arbitrary) suffix labelling the layer, and is appended to all the
parameters specific to defining that layer.
By default the layers are drawn on the plot in the order in which the layer* parameters appear on
the command line. However if this parameter is specified, each comma-separated element is
interpreted as a layer suffix, giving the ordered list of layers to plot. Every element of the
list must be a suffix with a corresponding layer parameter, but missing or repeated elements are
allowed.
legend=true|false
Whether to draw a legend or not. If no value is supplied, the decision is made automatically: a
legend is drawn only if it would have more than one entry.
legborder=true|false
If true, a line border is drawn around the legend.
legopaque=true|false
If true, the background of the legend is opaque, and the legend obscures any plot components
behind it. Otherwise, it's transparent.
legseq=<suffix>[,...]
Determines which layers are represented in the legend (if present) and in which order they appear.
The legend has a line for each layer label (as determined by the leglabelN parameter). If multiple
layers have the same label, they will contribute to the same entry in the legend, with style icons
plotted over each other. The value of this parameter is a comma-separated sequence of layer
suffixes, which determines the order in which the legend entries appear. Layers with suffixes
missing from this list do not show up in the legend at all.
If no value is supplied (the default), the sequence is the same as the layer plotting sequence
(see seq).
legpos=<xfrac,yfrac>
Determines the internal position of the legend on the plot. The value is a comma-separated pair of
values giving the X and Y positions of the legend within the plotting bounds, so for instance
"0.5,0.5" will put the legend right in the middle of the plot. If no value is supplied, the legend
will appear outside the plot boundary.
title=<value>
Text of a title to be displayed at the top of the plot. If null, the default, no title is shown
and there's more space for the graphics.
auxmap=<map-name>|<color>-<color>[-<color>...]
Color map used for Aux axis shading.
A mixed bag of colour ramps are available: inferno, magma, plasma, viridis, cividis, cubehelix,
sron, rainbow, rainbow2, rainbow3, pastel, accent, gnuplot, gnuplot2, specxby, set1, paired,
hotcold, rdbu, piyg, brbg, cyan-magenta, red-blue, brg, heat, cold, light, greyscale, colour,
standard, bugn, bupu, orrd, pubu, purd, huecl, hue, intensity, rgb_red, rgb_green, rgb_blue,
hsv_h, hsv_s, hsv_v, yuv_y, yuv_u, yuv_v, scale_hsv_s, scale_hsv_v, scale_yuv_y, mask, blacker,
whiter, transparency. Note: many of these, including rainbow-like ones, are frowned upon by the
visualisation community.
You can also construct your own custom colour map by giving a sequence of colour names separated
by minus sign ("-") characters. In this case the ramp is a linear interpolation between each pair
of colours named, using the same syntax as when specifying a colour value. So for instance
"yellow-hotpink-#0000ff" would shade from yellow via hot pink to blue.
auxclip=<lo>,<hi>
Defines a subrange of the colour ramp to be used for Aux shading. The value is specified as a
(low,high) comma-separated pair of two numbers between 0 and 1.
If the full range 0,1 is used, the whole range of colours specified by the selected shader will be
used. But if for instance a value of 0,0.5 is given, only those colours at the left hand end of
the ramp will be seen.
If the null (default) value is chosen, a default clip will be used. This generally covers most or
all of the range 0-1 but for colour maps which fade to white, a small proportion of the lower end
may be excluded, to ensure that all the colours are visually distinguishable from a white
background. This default is usually a good idea if the colour map is being used with something
like a scatter plot, where markers are plotted against a white background. However, for something
like a density map when the whole plotting area is tiled with colours from the map, it may be
better to supply the whole range 0,1 explicitly.
auxflip=true|false
If true, the colour map on the Aux axis will be reversed.
auxquant=<number>
Allows the colour map used for the Aux axis to be quantised. If an integer value N is chosen then
the colour map will be viewed as N discrete evenly-spaced levels, so that only N different colours
will appear in the plot. This can be used to generate a contour-like effect, and may make it
easier to trace the boundaries of regions of interest by eye.
If left blank, the colour map is nominally continuous (though in practice it may be quantised to a
medium-sized number like 256).
auxfunc=log|linear|histogram|histolog|sqrt|square
Defines the way that values in the Aux range are mapped to the selected colour ramp.
The available options are:
* log: Logarithmic scaling
* linear: Linear scaling
* histogram: Scaling follows data distribution, with linear axis
* histolog: Scaling follows data distribution, with logarithmic axis
* sqrt: Square root scaling
* square: Square scaling
For all these options, the full range of data values is used, and displayed on the colour bar if
applicable. The Linear, Log, Square and Sqrt options just apply the named function to the full
data range. The histogram options on the other hand use a scaling function that corresponds to the
actual distribution of the data, so that there are about the same number of points (or pixels, or
whatever is being scaled) of each colour. The histogram options are somewhat more expensive, but
can be a good choice if you are exploring data whose distribution is unknown or not well-behaved
over its min-max range. The Histogram and HistoLog options both assign the colours in the same
way, but they display the colour ramp with linear or logarithmic annotation respectively; the
HistoLog option also ignores non-positive values.
auxmin=<number>
Minimum value of the data coordinate on the Aux axis. This sets the value before any subranging is
applied. If not supplied, the value is determined from the plotted data.
auxmax=<number>
Maximum value of the data coordinate on the Aux axis. This sets the value before any subranging is
applied. If not supplied, the value is determined from the plotted data.
auxlabel=<text>
Sets the label used to annotate the aux axis, if it is visible.
auxcrowd=<factor>
Determines how closely the tick marks are spaced on the Aux axis, if visible. The default value is
1, meaning normal crowding. Larger values result in more ticks, and smaller values fewer ticks.
Tick marks will not however be spaced so closely that the labels overlap each other, so to get
very closely spaced marks you may need to reduce the font size as well.
auxwidth=<pixels>
Determines the lateral size of the aux colour ramp, if visible, in pixels.
auxvisible=true|false
Determines whether the aux axis colour ramp is displayed alongside the plot.
If not supplied (the default), the aux axis will be visible when aux shading is used in any of the
plotted layers.
forcebitmap=true|false
Affects whether rendering of the data contents of a plot (though not axis labels etc) is always
done to an intermediate bitmap rather than, where possible, being painted using graphics
primitives. This is a rather arcane setting that may nevertheless have noticeable effects on the
appearance and size of an output graphics file, as well as plotting time. For some types of plot
(e.g. shadingN=auto or shadingN=density) it will have no effect, since this kind of rendering
happens in any case.
When writing to vector graphics formats (PDF and PostScript), setting it true will force the data
contents to be bitmapped. This may make the output less beautiful (round markers will no longer be
perfectly round), but it may result in a much smaller file if there are very many data points.
When writing to bitmapped output formats (PNG, GIF, JPEG, ...), it fixes shapes to be the same as
seen on the screen rather than be rendered at the mercy of the graphics system, which sometimes
introduces small distortions.
compositor=0..1
Defines how multiple overplotted partially transparent pixels are combined to form a resulting
colour. The way this is used depends on the details of the specified plot.
Currently, this parameter takes a "boost" value in the range 0..1. If the value is zero,
saturation semantics are used: RGB colours are added in proporition to their associated alpha
value until the total alpha is saturated (reaches 1), after which additional pixels have no
further effect. For larger boost values, the effect is similar, but any non-zero alpha in the
output is boosted to the given minimum value. The effect of this is that even very slightly
populated pixels can be visually distinguished from unpopulated ones which may not be the case for
saturation composition.
animate=<table>
If not null, this parameter causes the command to create a sequence of plots instead of just one.
The parameter value is a table with one row for each frame to be produced. Columns in the table
are interpreted as parameters which may take different values for each frame; the column name is
the parameter name, and the value for a given frame is its value from that row. Animating like
this is considerably more efficient than invoking the STILTS command in a loop.
The location of the animation control table. This may take one of the following forms:
* A filename.
* A URL.
* The special value "-", meaning standard input. In this case the input format must be given
explicitly using the afmt parameter. Note that not all formats can be streamed in this way.
* A system command line with either a "<" character at the start, or a "|" character at the end
("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output.
This will probably only work on unix-like systems.
In any case, compressed data in one of the supported compression formats (gzip, Unix compress or
bzip2) will be decompressed transparently.
afmt=<in-format>
Specifies the format of the animation control table as specified by parameter animate. The known
formats are listed in SUN/256. This flag can be used if you know what format your table is in. If
it has the special value (auto) (the default), then an attempt will be made to detect the format
of the table automatically. This cannot always be done correctly however, in which case the
program will exit with an error explaining which formats were attempted.
astream=true|false
If set true, the animation control table specified by the animate parameter will be read as a
stream. It is necessary to give the afmt parameter in this case. Depending on the required
operations and processing mode, this may cause the read to fail (sometimes it is necessary to read
the table more than once). It is not normally necessary to set this flag; in most cases the data
will be streamed automatically if that is the best thing to do. However it can sometimes result in
less resource usage when processing large files in certain formats (such as VOTable).
acmd=<cmds>
Specifies processing to be performed on the animation control table as specified by parameter
animate, before any other processing has taken place. The value of this parameter is one or more
of the filter commands described in SUN/256. If more than one is given, they must be separated by
semicolon characters (";"). This parameter can be repeated multiple times on the same command line
to build up a list of processing steps. The sequence of commands given in this way defines the
processing pipeline which is performed on the table.
Commands may alteratively be supplied in an external file, by using the indirection character '@'.
Thus a value of "@filename" causes the file filename to be read for a list of filter commands to
execute. The commands in the file may be separated by newline characters and/or semicolons, and
lines which are blank or which start with a '#' character are ignored.
parallel=<int-value>
Determines how many threads will run in parallel if animation output is being produced. Only used
if the animate parameter is supplied. The default value is the number of processors apparently
available to the JVM.
projection=sin|aitoff|car|car0
Sky projection used to display the plot.
The available options are:
* sin: rotatable sphere
* aitoff: Hammer-Aitoff projection
* car: Plate Carree projection (lon/lat on Cartesian axes) with lon=0 at center
* car0: Plate Carree Projection (lon/lat on Cartesian axes) with lon=180 at center
viewsys=equatorial|galactic|supergalactic|ecliptic
The sky coordinate system used for the generated plot.
Choice of this value goes along with the data coordinate system that may be specified for plot
layers. If unspecified, a generic longitude/latitude system is used, and all lon/lat coordinates
in the plotted data layers are assumed to be in the same system. If a value is supplied for this
parameter, then a sky system must (implicitly or explicitly) be supplied for each data layer, and
the coordinates are converted from data to view system before being plotted.
The available options are:
* equatorial: J2000 equatorial system
* galactic: IAU 1958 galactic system
* supergalactic: De Vaucouleurs supergalactic system
* ecliptic: ecliptic system based on conversion at 2000.0
reflectlon=true|false
Whether to invert the celestial sphere by displaying the longitude axis increasing right-to-left
rather than left-to-right. It is conventional to display the celestial sphere in this way because
that's what it looks like from the earth, so the default is true. Set it false to see the sphere
from the outside.
grid=true|false
If true, sky coordinate grid lines are drawn on the plot. If false, they are absent.
scalebar=true|false
If true, a small bar is drawn near the bottom left of the plot annotated with a distance in
degrees, arc minutes or arc seconds, to make it easier to determine the size of features on the
plot by eye.
labelpos=Auto|External|Internal|Basic|Hybrid|None
Controls whether and where the numeric annotations of the lon/lat axes are displayed. The default
option Auto usually does the sensible thing, but other options exist to force labelling internally
or externally to the plot region, or to remove numeric labels altogether.
The available options are:
* Auto: Uses External or Internal policy according to whether the sky fills the plot bounds or
not
* External: Labels are drawn outside the plot bounds
* Internal: Labels are drawn inside the plot bounds
* Basic: Labels are drawn somewhere near the grid line
* Hybrid: Grid lines are labelled outside the plot bounds where possible, but inside if they
would otherwise be invisible
* None: Axes are not labelled
sex=true|false
If true, grid line labels are written in sexagesimal notation, if false in decimal degrees.
crowd=<number>
Determines how closely sky grid lines are spaced. The default value is 1, meaning normal crowding.
Larger values result in more grid lines, and smaller values in fewer grid lines.
gridcolor=<rrggbb>|red|blue|...
The color of the plot grid, given by name or as a hexadecimal RGB value.
The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink,
yellow, black, light_grey, white. However, many other common colour names (too many to list here)
are also understood. The list currently contains those colour names understood by most web
browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the
CSS3 standard.
Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#"
or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for
magenta.
labelcolor=<rrggbb>|red|blue|...
The color of axis labels and other plot annotations, given by name or as a hexadecimal RGB value.
The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink,
yellow, black, light_grey, white. However, many other common colour names (too many to list here)
are also understood. The list currently contains those colour names understood by most web
browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the
CSS3 standard.
Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#"
or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for
magenta.
gridaa=true|false
If true, grid lines are drawn with antialiasing. Antialiased lines look smoother, but may take
perceptibly longer to draw. Only has any effect for bitmapped output formats.
texttype=plain|antialias|latex
Determines how to turn label text into characters on the plot. Plain and Antialias both take the
text at face value, but Antialias smooths the characters. LaTeX interprets the text as LaTeX
source code and typesets it accordingly.
When not using LaTeX, antialiased text usually looks nicer, but can be perceptibly slower to plot.
At time of writing, on MacOS antialiased text seems to be required to stop the writing coming out
upside-down for non-horizontal text (MacOS java bug).
fontsize=<int-value>
Size of the text font in points.
fontstyle=standard|serif|mono
Font style for text.
The available options are:
* standard
* serif
* mono
fontweight=plain|bold|italic|bold_italic
Font weight for text.
The available options are:
* plain
* bold
* italic
* bold_italic
clon=<degrees>
Longitude of the central position of the plot in decimal degrees. Use with clat and radius. If the
center is not specified, the field of view is determined from the data.
clat=<degrees>
Latitude of the central position of the plot in decimal degrees. Use with clon and radius. If the
center is not specified, the field of view is determined from the data.
radius=<degrees>
Approximate radius of the plot field of view in degrees. Only used if clon and clat are also
specified.
zoomfactor=<number>
Sets the amount by which the plot view zooms in or out for each unit of mouse wheel movement. A
value of 1 means that mouse wheel zooming has no effect. A higher value means that the mouse wheel
zooms faster and a value nearer 1 means it zooms slower. Values below 1 are not permitted.
leglabelN=<text>
Sets the presentation label for the layer with a given suffix. This is the text which is displayed
in the legend, if present. Multiple layers may use the same label, in which case they will be
combined to form a single legend entry.
If no value is supplied (the default), the suffix itself is used as the label.
layerN=<layer-type> <layerN-specific-params>
Selects one of the available plot types for layerN. A plot consists of a plotting surface, set up
using the various unsuffixed parameters of the plotting command, and zero or more plot layers.
Each layer is introduced by a parameter with the name layer<N> where the suffix "<N>" is a label
identifying the layer and is appended to all the parameter names which configure that layer.
Suffixes may be any string, including the empty string.
This parameter may take one of the following values, described in more detail in SUN/256:
* mark
* size
* sizexy
* skyvector
* skyellipse
* skycorr
* link2
* mark2
* poly4
* mark4
* polygon
* label
* contour
* skydensity
* healpix
* skygrid
Each of these layer types comes with a list of type-specific parameters to define the details of
that layer, including some or all of the following groups:
* input table parameters (e.g. inN, icmdN)
* coordinate params referring to input table columns (e.g. xN, yN)
* layer style parameters (e.g. shadingN, colorN)
Every parameter notionally carries the same suffix N. However, if the suffix is not present, the
application will try looking for a parameter with the same name with no suffix instead. In this
way, if several layers have the same value for a given parameter (for instance input table), you
can supply it using one unsuffixed parameter to save having to supply several parameters with the
same value but different suffixes.
SEE ALSO
stilts(1)
If the package stilts-doc is installed, the full documentation SUN/256 is available in HTML format:
file:///usr/share/doc/stilts-doc/sun256/index.html
VERSION
STILTS version 3.2-debian
This is the Debian version of Stilts, which lack the support of some file formats and network protocols.
For differences see
file:///usr/share/doc/stilts/README.Debian
AUTHOR
Mark Taylor (Bristol University)
Mar 2017 STILTS-PLOT2SKY(1)