The usage of plot2plane
is
stilts <stilts-flags> plot2plane 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|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> xlog=true|false ylog=true|false xflip=true|false yflip=true|false xlabel=<text> ylabel=<text> aspect=<number> grid=true|false xcrowd=<number> ycrowd=<number> minor=true|false gridcolor=<rrggbb>|red|blue|... labelcolor=<rrggbb>|red|blue|... texttype=plain|antialias|latex fontsize=<int-value> fontstyle=standard|serif|mono fontweight=plain|bold|italic|bold_italic xmin=<number> xmax=<number> xsub=<lo>,<hi> ymin=<number> ymax=<number> ysub=<lo>,<hi> navaxes=xy|x|y xanchor=true|false yanchor=true|false zoomfactor=<number> leglabelN=<text> layerN=<layer-type> <layerN-specific-params>If you don't have the
stilts
script installed,
write "java -jar stilts.jar
" instead of
"stilts
" - see Section 3.
The available <stilts-flags>
are listed
in Section 2.1.
For programmatic invocation, the Task class for this
command is uk.ac.starlink.ttools.plot2.task.PlanePlot2Task
.
Parameter values are assigned on the command line as explained in Section 2.3. They are as follows:
acmd = <cmds>
(ProcessingStep[])
animate
,
before any other processing has taken place.
The value of this parameter is one or more of the filter
commands described in Section 6.1.
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.
afmt = <in-format>
(String)
animate
.
The known formats are listed in Section 5.2.1.
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.
[Default: (auto)
]
animate = <table>
(StarTable)
The location of the animation control table. This may take one of the following forms:
-
",
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.<
" 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.aspect = <number>
(Double)
astream = true|false
(Boolean)
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).
[Default: false
]
auxclip = <lo>,<hi>
(Subrange)
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.
auxcrowd = <factor>
(Double)
[Default: 1.0
]
auxflip = true|false
(Boolean)
[Default: false
]
auxfunc = log|linear|sqrt|square
(Scaling)
The available options are:
log
: Logarithmic scalinglinear
: Linear scalingsqrt
: Square root scalingsquare
: Square scaling[Default: linear
]
auxlabel = <text>
(String)
auxmap = <map-name>|<color>-<color>[-<color>...]
(Shader)
A mixed bag of colour ramps are available:
inferno
,
magma
,
plasma
,
viridis
,
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.
[Default: inferno
]
auxmax = <number>
(Double)
auxmin = <number>
(Double)
auxquant = <number>
(Double)
If left blank, the colour map is nominally continuous (though in practice it may be quantised to a medium-sized number like 256).
auxvisible = true|false
(Boolean)
If not supplied (the default), the aux axis will be visible when aux shading is used in any of the plotted layers.
auxwidth = <pixels>
(Integer)
[Default: 15
]
compositor = 0..1
(Compositor)
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.
[Default: 0.05
]
fontsize = <int-value>
(Integer)
[Default: 12
]
fontstyle = standard|serif|mono
(FontType)
The available options are:
standard
serif
mono
[Default: standard
]
fontweight = plain|bold|italic|bold_italic
(FontWeight)
The available options are:
plain
bold
italic
bold_italic
[Default: plain
]
forcebitmap = true|false
(Boolean)
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.
[Default: false
]
grid = true|false
(Boolean)
[Default: false
]
gridcolor = <rrggbb>|red|blue|...
(Color)
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.
[Default: light_grey
]
insets = <top>,<left>,<bottom>,<right>
(Padding)
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.
labelcolor = <rrggbb>|red|blue|...
(Color)
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.
[Default: black
]
layerN = <layer-type> <layerN-specific-params>
(LayerType)
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 Section 8.3:
mark
size
sizexy
xyvector
xyerror
xyellipse
xycorr
link2
mark2
line
linearfit
label
contour
grid
fill
quantile
histogram
kde
knn
densogram
gaussian
function
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:
inN
,
icmdN
)xN
,
yN
)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.
legborder = true|false
(Boolean)
[Default: true
]
legend = true|false
(Boolean)
leglabelN = <text>
(String)
If no value is supplied (the default), the suffix itself is used as the label.
legopaque = true|false
(Boolean)
[Default: true
]
legpos = <xfrac,yfrac>
(double[])
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.
legseq = <suffix>[,...]
(String[])
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
).
minor = true|false
(Boolean)
[Default: true
]
navaxes = xy|x|y
(boolean[])
xy
, which means that
the various mouse gestures will provide panning and zooming
in both X and Y directions.
However, if it is set to (for instance) x
then the mouse will only allow panning and
zooming in the horizontal direction,
with the vertical extent fixed.
[Default: xy
]
omode = swing|out|cgi|discard|auto
(PaintMode)
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[Default: auto
]
parallel = <int-value>
(Integer)
animate
parameter is supplied.
The default value is the number of processors apparently
available to the JVM.
[Default: 2
]
seq = <suffix>[,...]
(String[])
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.
storage = simple|cache|basic-cache
(DataStoreFactory)
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
.
[Default: simple
]
texttype = plain|antialias|latex
(TextSyntax)
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).
[Default: plain
]
title = <value>
(String)
xanchor = true|false
(Boolean)
[Default: false
]
xcrowd = <number>
(Double)
[Default: 1
]
xflip = true|false
(Boolean)
[Default: false
]
xlabel = <text>
(String)
[Default: X
]
xlog = true|false
(Boolean)
[Default: false
]
xmax = <number>
(Double)
xmin = <number>
(Double)
xpix = <int-value>
(Integer)
insets
.
[Default: 500
]
xsub = <lo>,<hi>
(Subrange)
The default value "0,1
" therefore has
no effect.
The range could be restricted to its lower half
with the value 0,0.5
.
[Default: 0,1
]
yanchor = true|false
(Boolean)
[Default: false
]
ycrowd = <number>
(Double)
[Default: 1
]
yflip = true|false
(Boolean)
[Default: false
]
ylabel = <text>
(String)
[Default: Y
]
ylog = true|false
(Boolean)
[Default: false
]
ymax = <number>
(Double)
ymin = <number>
(Double)
ypix = <int-value>
(Integer)
insets
.
[Default: 400
]
ysub = <lo>,<hi>
(Subrange)
The default value "0,1
" therefore has
no effect.
The range could be restricted to its lower half
with the value 0,0.5
.
[Default: 0,1
]
zoomfactor = <number>
(Double)
[Default: 1.2
]