sun253.xml

<?xml version='1.0'?>
<!DOCTYPE sun SYSTEM "docs.dtd" [

  <!-- Import entity definitions for icons used by the TOPCAT application. -->
  <!ENTITY % image-defs SYSTEM "image.defs">
  %image-defs;

  <!-- Define automatically generated text entities. -->
  <!ENTITY general.runtime.method.docs SYSTEM "general-javadocs.xml">
  <!ENTITY activation.runtime.method.docs SYSTEM "activation-javadocs.xml">
  <!ENTITY general.runtime.class.docs SYSTEM "general-classes-javadocs.xml">
  <!ENTITY activation.runtime.class.docs SYSTEM 
                                         "activation-classes-javadocs.xml">
  <!ENTITY topcat.usage SYSTEM "topcat.usage">

  <!-- Import entity definitions from other packages including customisation -->
  <!ENTITY gbin.stil.intro SYSTEM "gbin-stil-intro.xdoc">
  <!ENTITY gbin.stil.appexample SYSTEM "gbin-stil-appexample.xdoc">
  <!ENTITY gbin.stil.notes SYSTEM "gbin-stil-notes.xdoc">
  <!ENTITY gbin-package-name 'TOPCAT'>
  <!ENTITY gbin-package-cmdline 'topcat'>
  <!ENTITY gbin-package-classpath 'topcat-full.jar'>
  <!ENTITY gbin-package-mainclass 'uk.ac.starlink.topcat.Driver'>

  <!-- Define some character constants. -->
  <!ENTITY column.id.char '$'>
  <!ENTITY subset.id.char '_'>
  <!ENTITY ucd.prefix 'ucd$'>
  <!ENTITY utype.prefix 'utype$'>
  <!ENTITY param.prefix 'param$'>

  <!-- Define illustrations -->
  <!-- Note screenshots have mostly been taken using J2SE1.4, which uses
   !   a different visual theme from the 1.5 default.
   !   Use -Dswing.metalTheme=steel when taking screenshots for visual
   !   consistency. -->
  <!ENTITY figs '../figures/'>
  <!ENTITY FIG.ControlWindow '&figs;ControlWindow.gif'>
  <!ENTITY FIG.ColumnInfoWindow '&figs;ColumnInfoWindow.gif'>
  <!ENTITY FIG.JTable '&figs;JTable.gif'>
  <!ENTITY FIG.ParameterWindow '&figs;ParameterWindow.gif'>
  <!ENTITY FIG.TableViewerWindow '&figs;TableViewerWindow.gif'>
  <!ENTITY FIG.SubsetWindow '&figs;SubsetWindow.gif'>
  <!ENTITY FIG.StatsWindow '&figs;StatsWindow.gif'>
  <!ENTITY FIG.LoadWindow '&figs;LoadWindow.gif'>
  <!ENTITY FIG.FilestoreTableLoadDialog '&figs;FilestoreTableLoadDialog.gif'>
  <!ENTITY FIG.TreeTableLoadDialog '&figs;TreeTableLoadDialog.gif'>
  <!ENTITY FIG.SQLTableLoadDialog '&figs;SQLTableLoadDialog.gif'>
  <!ENTITY FIG.ConeSearchDialog '&figs;ConeSearchDialog.gif'>
  <!ENTITY FIG.GavoTableLoadDialog '&figs;GavoTableLoadDialog.gif'>
  <!ENTITY FIG.SaveQueryWindow '&figs;SaveQueryWindow.gif'>
  <!ENTITY FIG.FilestoreTableSaveDialog '&figs;FilestoreTableSaveDialog.gif'>
  <!ENTITY FIG.SQLWriteDialog '&figs;SQLWriteDialog.gif'>
  <!ENTITY FIG.ConcatWindow '&figs;ConcatWindow.gif'>
  <!ENTITY FIG.MatchWindow '&figs;MatchWindow.gif'>
  <!ENTITY FIG.MatchWindow1 '&figs;MatchWindow1.gif'>
  <!ENTITY FIG.MatchWindowN '&figs;MatchWindowN.gif'>
  <!ENTITY FIG.ActivationQueryWindow '&figs;ActivationQueryWindow.gif'>
  <!ENTITY FIG.SoG '&figs;SoG.gif'>
  <!ENTITY FIG.ImageWindow '&figs;ImageWindow.gif'>
  <!ENTITY FIG.Splat '&figs;Splat.gif'>
  <!ENTITY FIG.HelpWindow '&figs;HelpWindow.gif'>
  <!ENTITY FIG.ParameterQueryWindow '&figs;ParameterQueryWindow.gif'>
  <!ENTITY FIG.SyntheticColumnQueryWindow 
           '&figs;SyntheticColumnQueryWindow.gif'>
  <!ENTITY FIG.SkyColumnQueryWindow '&figs;SkyColumnQueryWindow.gif'>
  <!ENTITY FIG.SyntheticSubsetQueryWindow 
           '&figs;SyntheticSubsetQueryWindow.gif'>
  <!ENTITY FIG.MethodWindow '&figs;MethodWindow.gif'>
  <!ENTITY FIG.HtmlWindow '&figs;HtmlWindow.gif'>
  <!ENTITY FIG.LogWindow '&figs;LogWindow.gif'>
  <!ENTITY FIG.PointSelector '&figs;PointSelector.gif'>
  <!ENTITY FIG.AxisWindow '&figs;AxisWindow.gif'>
  <!ENTITY FIG.HistogramWindow '&figs;HistogramWindow.gif'>
  <!ENTITY FIG.PlotWindow '&figs;PlotWindow.gif'>
  <!ENTITY FIG.PlotWindow_blob '&figs;PlotWindow_blob.gif'>
  <!ENTITY FIG.Cartesian3DWindow '&figs;Cartesian3DWindow.gif'>
  <!ENTITY FIG.SphereWindow '&figs;SphereWindow.gif'>
  <!ENTITY FIG.DensityWindow '&figs;DensityWindow.gif'>
  <!ENTITY FIG.LinesWindow '&figs;LinesWindow.gif'>
  <!ENTITY FIG.MarkStyleEditor '&figs;MarkStyleEditor.gif'>
  <!ENTITY FIG.MarkStyleEditorNoLines '&figs;MarkStyleEditorNoLines.gif'>
  <!ENTITY FIG.BarStyleEditor '&figs;BarStyleEditor.gif'>
  <!ENTITY FIG.DensityStyleEditor '&figs;DensityStyleEditor.gif'>
  <!ENTITY FIG.LinesStyleEditor '&figs;LinesStyleEditor.gif'>
  <!ENTITY FIG.Cartesian3DWindow_aux '&figs;Cartesian3DWindow_aux.gif'>
  <!ENTITY FIG.PlotWindow_err '&figs;PlotWindow_err.gif'>
  <!ENTITY FIG.SphereWindow_labels '&figs;SphereWindow_labels.gif'>
  <!ENTITY FIG.sampPanel '&figs;sampPanel.gif'>
  <!ENTITY FIG.SampWindow_clients '&figs;SampWindow_clients.gif'>
  <!ENTITY FIG.SampWindow_msgs '&figs;SampWindow_msgs.gif'>
  <!ENTITY FIG.SiapTableLoadDialog '&figs;SiapTableLoadDialog.gif'>
  <!ENTITY FIG.SsapTableLoadDialog '&figs;SsapTableLoadDialog.gif'>
  <!ENTITY FIG.TapTableLoadDialog '&figs;TapTableLoadDialog.gif'>
  <!ENTITY FIG.TapTableLoadDialog_service
           '&figs;TapTableLoadDialog_service.gif'>
  <!ENTITY FIG.TapTableLoadDialog_query '&figs;TapTableLoadDialog_query.gif'>
  <!ENTITY FIG.TapTableLoadDialog_jobs '&figs;TapTableLoadDialog_jobs.gif'>
  <!ENTITY FIG.TapTableLoadDialog_resume '&figs;TapTableLoadDialog_resume.gif'>
  <!ENTITY FIG.columnSelector '&figs;columnSelector.gif'>
  <!ENTITY FIG.RegistryPanel '&figs;RegistryPanel.gif'>
  <!ENTITY FIG.DalTableLoadDialog '&figs;DalTableLoadDialog.gif'>
  <!ENTITY FIG.DalMultiPanel '&figs;DalMultiPanel.gif'>
  <!ENTITY FIG.ConeMultiWindow '&figs;ConeMultiWindow.gif'>
  <!ENTITY FIG.SiaMultiWindow '&figs;SiaMultiWindow.gif'>
  <!ENTITY FIG.SsaMultiWindow '&figs;SsaMultiWindow.gif'>
  <!ENTITY FIG.VizierTableLoadDialog '&figs;VizierTableLoadDialog.gif'>
  <!ENTITY FIG.MemoryMonitor '&figs;MemoryMonitor.gif'>
  <!ENTITY FIG.ParameterPanel '&figs;ParameterPanel.gif'>
  <!ENTITY FIG.TupleSelector '&figs;TupleSelector.gif'>
  <!ENTITY FIG.IntraMatchSpec '&figs;IntraMatchSpec.gif'>
  <!ENTITY FIG.PairMatchSpec '&figs;PairMatchSpec.gif'>
  <!ENTITY FIG.InterMatchSpec '&figs;InterMatchSpec.gif'>
  <!ENTITY FIG.BaSTITableLoadDialog '&figs;BaSTITableLoadDialog.gif'>
  <!ENTITY FIG.StackPlotWindow '&figs;StackPlotWindow.gif'>
  <!ENTITY FIG.StackPlotWindow_float '&figs;StackPlotWindow_float.gif'>
  <!ENTITY FIG.NavigationHelpPanel '&figs;NavigationHelpPanel.gif'>
  <!ENTITY FIG.StackPlotWindow_blob '&figs;StackPlotWindow_blob.gif'>
  <!ENTITY FIG.ControlStack_fixed '&figs;ControlStack_fixed.gif'>
  <!ENTITY FIG.form-style '&figs;form-style.gif'>
  <!ENTITY FIG.PlotExporter '&figs;PlotExporter.gif'>
  <!ENTITY FIG.LegendControl_style '&figs;LegendControl_style.gif'>
  <!ENTITY FIG.LegendControl_position '&figs;LegendControl_position.gif'>
  <!ENTITY FIG.ShaderControl_map '&figs;ShaderControl_map.gif'>
  <!ENTITY FIG.ShaderControl_ramp '&figs;ShaderControl_ramp.gif'>
  <!ENTITY FIG.ShaderControl_range '&figs;ShaderControl_range.gif'>
  <!ENTITY FIG.FunctionLayerControl '&figs;FunctionLayerControl.gif'>
  <!ENTITY FIG.FunctionLayerControl_function
           '&figs;FunctionLayerControl_function.gif'>
  <!ENTITY FIG.FunctionLayerControl_style
           '&figs;FunctionLayerControl_style.gif'>
  <!ENTITY FIG.FunctionLayerControl_label
           '&figs;FunctionLayerControl_label.gif'>
  <!ENTITY FIG.SpectrogramLayerControl '&figs;SpectrogramLayerControl.gif'>
  <!ENTITY FIG.SpectrogramLayerControl_data
           '&figs;SpectrogramLayerControl_data.gif'>
  <!ENTITY FIG.SpectrogramLayerControl_style
           '&figs;SpectrogramLayerControl_style.gif'>
  <!ENTITY FIG.GangLayerControl_position '&figs;GangLayerControl_position.gif'>
  <!ENTITY FIG.GangLayerControl_subsets '&figs;GangLayerControl_subsets.gif'>
  <!ENTITY FIG.GangLayerControl_form '&figs;GangLayerControl_form.gif'>
  <!ENTITY FIG.GangLayerControl_pair_position
           '&figs;GangLayerControl_pair_position.gif'>
  <!ENTITY FIG.GangLayerControl_pair_subsets
           '&figs;GangLayerControl_pair_subsets.gif'>
  <!ENTITY FIG.GangLayerControl_pair_form
           '&figs;GangLayerControl_pair_form.gif'>
  <!ENTITY FIG.HistogramLayerControl_position
           '&figs;HistogramLayerControl_position.gif'>
  <!ENTITY FIG.HistogramLayerControl_subsets
           '&figs;HistogramLayerControl_subsets.gif'>
  <!ENTITY FIG.HistogramLayerControl_form
           '&figs;HistogramLayerControl_form.gif'>
  <!ENTITY FIG.mode_flat '&figs;mode_flat.gif'>
  <!ENTITY FIG.mode_translucent '&figs;mode_translucent.gif'>
  <!ENTITY FIG.mode_transparent '&figs;mode_transparent.gif'>
  <!ENTITY FIG.mode_auto '&figs;mode_auto.gif'>
  <!ENTITY FIG.mode_density '&figs;mode_density.gif'>
  <!ENTITY FIG.mode_aux '&figs;mode_aux.gif'>
  <!ENTITY FIG.form_mark '&figs;form_mark.gif'>
  <!ENTITY FIG.form_size '&figs;form_size.gif'>
  <!ENTITY FIG.form_vector '&figs;form_vector.gif'>
  <!ENTITY FIG.form_error '&figs;form_error.gif'>
  <!ENTITY FIG.form_ellipse '&figs;form_ellipse.gif'>
  <!ENTITY FIG.form_line '&figs;form_line.gif'>
  <!ENTITY FIG.form_linearfit '&figs;form_linearfit.gif'>
  <!ENTITY FIG.form_label '&figs;form_label.gif'>
  <!ENTITY FIG.form_contour '&figs;form_contour.gif'>
  <!ENTITY FIG.form_marks2 '&figs;form_marks2.gif'>
  <!ENTITY FIG.form_link2 '&figs;form_link2.gif'>
  <!ENTITY FIG.font_tab '&figs;font_tab.gif'>
  <!ENTITY FIG.size_tab_insets '&figs;size_tab_insets.gif'>
  <!ENTITY FIG.size_tab_noinsets '&figs;size_tab_noinsets.gif'>
  <!ENTITY FIG.ConfigControl_histobars '&figs;ConfigControl_histobars.gif'>
  <!ENTITY FIG.PlaneAxisControl_coords '&figs;PlaneAxisControl_coords.gif'>
  <!ENTITY FIG.PlaneAxisControl_navigation
               '&figs;PlaneAxisControl_navigation.gif'>
  <!ENTITY FIG.PlaneAxisControl_range '&figs;PlaneAxisControl_range.gif'>
  <!ENTITY FIG.PlaneAxisControl_grid '&figs;PlaneAxisControl_grid.gif'>
  <!ENTITY FIG.PlaneAxisControl_labels '&figs;PlaneAxisControl_labels.gif'>
  <!ENTITY FIG.SkyAxisControl_projection '&figs;SkyAxisControl_projection.gif'>
  <!ENTITY FIG.SkyAxisControl_navigation '&figs;SkyAxisControl_navigation.gif'>
  <!ENTITY FIG.SkyAxisControl_fov '&figs;SkyAxisControl_fov.gif'>
  <!ENTITY FIG.SkyAxisControl_grid '&figs;SkyAxisControl_grid.gif'>
  <!ENTITY FIG.CubeAxisControl_coords '&figs;CubeAxisControl_coords.gif'>
  <!ENTITY FIG.CubeAxisControl_navigation
           '&figs;CubeAxisControl_navigation.gif'>
  <!ENTITY FIG.CubeAxisControl_range '&figs;CubeAxisControl_range.gif'>
  <!ENTITY FIG.CubeAxisControl_view '&figs;CubeAxisControl_view.gif'>
  <!ENTITY FIG.CubeAxisControl_grid '&figs;CubeAxisControl_grid.gif'>
  <!ENTITY FIG.CubeAxisControl_labels '&figs;CubeAxisControl_labels.gif'>
  <!ENTITY FIG.SphereAxisControl_navigation
           '&figs;SphereAxisControl_navigation.gif'>
  <!ENTITY FIG.SphereAxisControl_range '&figs;SphereAxisControl_range.gif'>
  <!ENTITY FIG.SphereAxisControl_view '&figs;SphereAxisControl_view.gif'>
  <!ENTITY FIG.SphereAxisControl_grid '&figs;SphereAxisControl_grid.gif'>
  <!ENTITY FIG.TimeAxisControl_coords '&figs;TimeAxisControl_coords.gif'>
  <!ENTITY FIG.TimeAxisControl_navigation
           '&figs;TimeAxisControl_navigation.gif'>
  <!ENTITY FIG.TimeAxisControl_range '&figs;TimeAxisControl_range.gif'>
  <!ENTITY FIG.TimeAxisControl_grid '&figs;TimeAxisControl_grid.gif'>
  <!ENTITY FIG.TimeAxisControl_labels '&figs;TimeAxisControl_labels.gif'>
  <!ENTITY FIG.HistogramPlotWindow '&figs;HistogramPlotWindow.gif'>
  <!ENTITY FIG.PlanePlotWindow '&figs;PlanePlotWindow.gif'>
  <!ENTITY FIG.SkyPlotWindow '&figs;SkyPlotWindow.gif'>
  <!ENTITY FIG.CubePlotWindow '&figs;CubePlotWindow.gif'>
  <!ENTITY FIG.SpherePlotWindow '&figs;SpherePlotWindow.gif'>
  <!ENTITY FIG.TimePlotWindow '&figs;TimePlotWindow.gif'>
  <!ENTITY FIG.plotmatch_dialog '&figs;plotmatch_dialog.gif'>
  <!ENTITY FIG.SkyPlotWindow_plotmatch '&figs;SkyPlotWindow_plotmatch.gif'>
  <!ENTITY FIG.CdsUploadMatchWindow '&figs;CdsUploadMatchWindow.gif'>

  <!-- Define external URLs. -->
  <!ENTITY URL.VOTABLE "http://www.ivoa.net/Documents/latest/VOT.html">
  <!ENTITY URL.J2SE_DOCS "http://java.sun.com/j2se/1.5.0/docs/">

  <!-- Plot2 control references. -->
  <!ENTITY CONTROL.single
           '&IMG.PLOT_DATA;
            <ref id="GangLayerControl_single">Position Layer Control</ref>'>
  <!ENTITY CONTROL.pair
           '&IMG.PLOT_PAIR;
            <ref id="GangLayerControl_pair">Pair Layer Control</ref>'>
  <!ENTITY CONTROL.function
           '&IMG.PLOT_FUNCTION;
            <ref id="FunctionLayerControl">Function Layer Control</ref>'>
  <!ENTITY CONTROL.histogram
           '&IMG.PLOT_HISTO;
            <ref id="HistogramLayerControl">Histogram Layer Control</ref>'>
  <!ENTITY CONTROL.spectrogram
           '&IMG.PLOT_SPECTRO;
            <ref id="SpectrogramLayerControl">Spectrogram Layer Control</ref>'>
  <!ENTITY FORM.mark '&IMG.FORM_MARK; <ref id="form-mark">Mark</ref>'>
  <!ENTITY FORM.size '&IMG.FORM_SIZE; <ref id="form-size">Size</ref>'>
  <!ENTITY FORM.vector '&IMG.FORM_VECTOR; <ref id="form-vector">Vector</ref>'>
  <!ENTITY FORM.error '&IMG.FORM_ERROR; <ref id="form-error">Error Bars</ref>'>
  <!ENTITY FORM.ellipse '&IMG.FORM_ELLIPSE;
                        <ref id="form-ellipse">Ellipse</ref>'>
  <!ENTITY FORM.line '&IMG.PLOT_LINE; <ref id="form-line">Line</ref>'>
  <!ENTITY FORM.linearfit '&IMG.FORM_LINEARFIT;
                          <ref id="form-linearfit">Linear Fit</ref>'>
  <!ENTITY FORM.label '&IMG.PLOT_LABEL; <ref id="form-label">Text Label</ref>'>
  <!ENTITY FORM.contour '&IMG.PLOT_CONTOUR;
                        <ref id="form-contour">Contour</ref>'>
  <!ENTITY FORM.marks2 '&IMG.FORM_MARKS2; <ref id="form-marks2">Marks</ref>'>
  <!ENTITY FORM.link2 '&IMG.FORM_LINK2; <ref id="form-link2">Link</ref>'>
  <!ENTITY GESTURE.DRAG1 '&IMG.DRAG1; Left drag'>
  <!ENTITY GESTURE.DRAG2 '&IMG.DRAG2; Center drag (SHIFT-drag)'>
  <!ENTITY GESTURE.DRAG3 '&IMG.DRAG3; Right drag (CTRL-drag)'>
  <!ENTITY GESTURE.CLICK1 '&IMG.CLICK1; Left click'>
  <!ENTITY GESTURE.CLICK2 '&IMG.CLICK2; Center click (SHIFT-click)'>
  <!ENTITY GESTURE.CLICK3 '&IMG.CLICK3; Right click (CTRL-click)'>
  <!ENTITY GESTURE.WHEEL '&IMG.MOUSE_WHEEL; Wheel'>
]>

<sun>

<docinfo>

<title>TOPCAT - Tool for OPerations on Catalogues And Tables</title>

<authorlist>
<author id="mbt" 
        email="m.b.taylor@bristol.ac.uk"
        webpage="http://www.star.bristol.ac.uk/~mbt/"
        affiliation="University of Bristol"
        >Mark Taylor</author>
</authorlist>

<docnumber>253</docnumber>

<docdate>13 November 2014</docdate>

<contactlist>
<contact>TOPCAT web page:
         <webref url="http://www.starlink.ac.uk/topcat/"/></contact>
<contact>Author email:
         <webref url="mailto:m.b.taylor@bristol.ac.uk"
                 >m.b.taylor@bristol.ac.uk</webref></contact>
<contact>Mailing list:
         <webref url="mailto:topcat-user@bristol.ac.uk"
                 >topcat-user@bristol.ac.uk</webref></contact>
</contactlist>

</docinfo>

<!-- ............................................................... -->
<docbody>

<abstract>
<px>TOPCAT is an interactive graphical viewer and editor for tabular data.
It has been designed for use with astronomical tables such as object 
catalogues, but is not restricted to astronomical applications.
It understands a number of different astronomically important formats,
and more formats can be added.
It is designed to cope well with large tables; 
a million rows by a hundred columns should not present a problem 
even with modest memory and CPU resources.
</px>

<px>It offers a variety of ways to view and analyse the data,
including a browser for the cell data themselves, 
viewers for information about table and column metadata,
tools for joining tables using flexible matching algorithms,
and extensive 2- and 3-d visualisation facilities.
Using a powerful and extensible Java-based expression language
new columns can be defined and row subsets selected for separate analysis.
Selecting a row can be configured to trigger an action, for instance
displaying an image of the catalogue object in an external viewer.
Table data and metadata can be edited and the resulting modified table
can be written out in a wide range of output formats.
</px>

<px>A number of options are provided for loading data from external
sources, including Virtual Observatory (VO) services, thus providing
a gateway to many remote archives of astronomical data.
It can also interoperate with other desktop tools using the SAMP protocol.
</px>

<px>TOPCAT is written in pure Java and is available under the 
GNU General Public Licence.  Its underlying table processing facilities
are provided by STIL, the Starlink Tables Infrastructure Library.
</px>

</abstract>

<sect id="intro">
<subhead><title>Introduction</title></subhead>

<p>TOPCAT is an interactive graphical program which can 
examine, analyse, combine, edit and
write out tables.  A table is, roughly, something with columns and rows;
each column contains objects of the same type
(for instance floating point numbers) and each row has an entry for
each of the columns (though some entries might be blank).
A common astronomical example of a table is an object catalogue.
</p>

<p>TOPCAT can read in tables in a number of formats from various sources, 
allow you to
inspect and manipulate them in various ways, and if you have
edited them optionally write them out in the modified state for later use,
again in a variety of formats.
Here is a summary of its main capabilities:
<ul>
<li>View/edit table data in a scrollable browser</li>
<li>View/edit table metadata (parameters)</li>
<li>View/edit column metadata (column names, units, UCDs...)</li>
<li>Re-order and hide/reveal columns</li>
<li>Insert 'synthetic' columns defined by algebraic expression</li>
<li>Sort rows on the values in a given column</li>
<li>Define row subsets in various ways, including algebraically 
    and graphically</li>
<li>Plot columns against each other in 1, 2 and 3 dimensions,
    distinguishing different subsets</li>
<li>Calculate statistics on each column for some or all rows</li>
<li>Trigger a configurable action (e.g. object image display) when a 
    column is selected</li>
<li>Perform flexible matching of rows in the same or different tables</li>
<li>Concatenate the rows of existing tables to create new ones</li>
<li>Acquire tables from web services, external filestores or other 
    customisable sources</li>
<li>Perform single and multiple queries to Virtual Observatory services</li>
<li>Interoperate with other desktop tools using SAMP</li>
<li>Write modified tables out in original or different format</li>
</ul>
</p>

<p>Considerable effort has gone into making it work with large tables;
a few million rows and hundreds of columns is usually quite manageable.
</p>

<p>The general idea of the program is quite straightforward.
At any time, it has a list of tables it knows about - these are 
displayed in the <ref id="ControlWindow">Control Window</ref> which 
is the first thing you see when you start up the program.
You can add to the list by <ref id="LoadWindow">loading tables in</ref>,
or by some actions which create new tables from the existing ones.
When you select a table in the list by clicking on it, 
you can see general information
about it in the control window, and you can also open more specialised 
<ref id="views">view windows</ref> which allow you to 
inspect it in more detail or edit it.
Some of the actions you can take, 
such as changing the current 
<ref id="order">Sort Order</ref>,
<ref id="subsets">Row Subset</ref> or
<ref id="columns">Column Set</ref>
change the <ref id="apparent" plaintextref="yes">Apparent Table</ref>, 
which is a view
of the table used for things such as saving it and performing row matches.
Changes that you make do not directly modify the tables on disk 
(or wherever they came from), 
but if you want to save the changes you have made,
you can <ref id="SaveQueryWindow">write</ref> 
the modified table(s) to a new location.
</p>

<p>The main body of this document explains these ideas and capabilities
in more detail, and 
<ref id="windows"/> gives a full description of all the windows which
form the application.
While the program is running, this document is available via the
online help system - clicking the <label>Help</label> (&IMG.HELP;)
toolbar button in any window will pop up a help browser open at
the page which describes that window.
This document is heavily hyperlinked, so you may find it easier to
read in its HTML form than on paper.
</p>

<p>Recent news about the program can be found on the
<webref url="http://www.starlink.ac.uk/topcat/" plaintextref="yes"
        >TOPCAT web page</webref>.
It was initially developed within the now-terminated
Starlink and then AstroGrid projects,
and has subsequently been supported by the UK's PPARC and STFC
research councils, various Euro-VO and FP7 projects,
GAVO and ESA.
The underlying table handling facilities are supplied by
the Starlink Tables Infrastructure Library
<webref url="http://www.starlink.ac.uk/stil/" plaintextref="yes">STIL</webref>,
which is documented more fully in 
<docxref doc="sun252" plaintextref="yes"/>.
The software is written in pure Java, and should run on any 
J2SE platform version 1.5 or later.
This makes it highly portable, since it can run on any machine which has
a suitable Java installation, which is available for MS Windows, Mac OS X and
most flavours of Unix amongst others.
Some of the external viewer applications it talks to rely on 
non-Java code however so one or two facilities, 
such as displaying spectra, may be absent in some cases.
TOPCAT is available under the terms of the 
GNU <webref url="http://www.gnu.org/copyleft/gpl.html"
            >General Public License</webref>.
</p>

</sect>

<sect id="quick">
<subhead><title>Quick Start Guide</title></subhead>

<p>This manual aims to give detailed tutorial and reference 
documentation on most aspects of TOPCAT's capabilities, and reading
it is an excellent way to learn about the program.
However, it's quite a fat document, and if you feel you've got better
things to do with your time than read it all, you should be able to
do most things by playing around with the software and dipping into
the manual (or equivalently the online help) 
when you can't see how to do something or the program isn't behaving 
as expected.
This section provides a short introduction for the impatient,
explaining how to get started.
</p>

<p>To start the program, you will probably type <code>topcat</code> or 
something like
<code>java -jar topcat-full.jar</code> (see <ref id="invoke"/> for
more detail).  To view a table that you have on disk, you can either
give its name on the command line or load it using the <label>Load</label>
button from the GUI.  FITS, VOTable, CDF and GBIN files
are recognised automatically;
if your data is in another format such as ASCII (see <ref id="inFormats"/>)
you need to tell the program (e.g. <code>-f ascii</code> on the command line).
If you just want to try the program out, <code>topcat -demo</code> will
start with a couple of small tables for demonstration purposes.
</p>

<p>The first thing that you see is the 
<ref id="ControlWindow" plaintextref="yes">Control Window</ref>.
This has a list of the loaded table(s) on the left.  If one of these
is highlighted by clicking on it, information about it will
be shown on the right; some of this (table name, sort order) you
can change here.
Along the top is a toolbar with a number of buttons, most of which
open up new windows.  These fall into a few groups:

<dl>
<dt>&IMG.LOAD; &IMG.SAVE; &IMG.BROADCAST;</dt>
<dd><p>Load/Save/Send Table(s).</p></dd>

<dt>&IMG.VIEWER; &IMG.PARAMS; &IMG.COLUMNS; &IMG.SUBSETS; &IMG.STATS;</dt>
<dd><p>Display various aspects of information about the table's data and
    metadata.</p></dd>

<dt>&IMG.PLOT2_HISTOGRAM;
    &IMG.PLOT2_PLANE;
    &IMG.PLOT2_CUBE;
    &IMG.PLOT2_SKY;
    &IMG.PLOT2_SPHERE;</dt>
<dd><p>Open plotting/visualisation windows of various kinds.</p></dd>

<dt>&IMG.MATCH2; &IMG.TAP_DIALOG; &IMG.CDSXMATCH;</dt>
<dd><p>Join tables in various ways including spatial crossmatching,
    and access remote databases.</p></dd>

<dt>&IMG.SAMP; &IMG.FUNCTION; &IMG.HELP;</dt>
<dd><p>Help and information</p></dd>
</dl>

The <label>Help</label> (&IMG.HELP;) button appears in most windows -
if you click it a help browser will be displayed showing an appropriate 
part of this manual.
As well as the tool bar there are a number of 
menus along the top - some of the options just repeat those appearing on the
toolbar, but several less common ones are available as well.
The <label>Help</label> menu gives you a few 
more options along the same lines, including displaying the help 
information in your usual web browser rather than in TOPCAT's (somewhat
scrappy) help viewer.
All the windows follow roughly this pattern.  For some of the toolbar
buttons you can probably guess what they do from their icons, 
for others probably not - to find out
you can hover with the mouse to see the tooltip, 
look in the menus, read the manual, or just push it and see.
</p>

<p>Some of the windows allow you to make changes of various sorts to the
tables, such as performing sorts, selecting rows, modifying data or
metadata.  None of these affect the table on disk (or database, or wherever),
but if you subsequently save the table the changes will be reflected
in the table that you save.
</p>

<p>A notable point to bear in mind concerns memory.
TOPCAT is fairly efficient in use of memory, but in some cases when 
dealing with large tables you might see an OutOfMemoryError.
It is usually possible to work round this by using the
<code>-Xmx</code><em>NNN</em><code>M</code>
flag on startup - see <ref id="jvmMemory"/>.
</p>

<p>Finally, if you have queries, comments or requests about the software,
and they don't appear to be addressed in the manual, consult the
<webref url="http://www.starlink.ac.uk/topcat/">TOPCAT web page</webref>,
use the
<webref url="http://www.star.bris.ac.uk/~mbt/topcat-lists.html"
        >topcat-user</webref> mailing list,
or contact the author - user feedback is always welcome.
</p>

</sect>


<sect id="apparent">
<subhead><title>Apparent Table</title></subhead>

<p>The <label>Apparent Table</label> 
is a particular view of a table which can be
influenced by some of the viewing controls.
</p>

<p>When you load a table into TOPCAT it has a number of characteristics
like the number of columns and rows it contains, the order of the rows
that make up the data, the data and metadata themselves, and so on.
While manipulating it you can modify the way that the table appears
to the program, by changing or adding data or metadata, 
or changing the order or selection of columns or rows that are visible.
For each table its "apparent table" is a table which corresponds to
the current state of the table according to the changes that you have made.
</p>

<p>In detail, the apparent table consists of the table as it was originally
imported into the program plus any of the following changes that you
have made:
<ul>
<li>Selection of rows changed by changing the current
    <ref id="subsets" plaintextref="yes">Row Subset</ref></li>
<li>Changes to the current 
    <ref id="order" plaintextref="yes">Row Order</ref> caused by 
    doing a sort</li>
<li>Changes to the current 
    <ref id="columns" plaintextref="yes">Column Set</ref> caused
    by adding, hiding or moving columns</li>
<li>Changes to cell data by editing cells in the 
    <ref id="TableViewerWindow">Data window</ref></li>
<li>Changes to table metadata by editing cells in the 
    <ref id="ParameterWindow">Parameter window</ref></li>
<li>Changes to column metadata by editing cells in the 
    <ref id="ColumnInfoWindow">Columns window</ref></li>
</ul>
</p>

<p>The apparent table is used in the following contexts:
<dl>

<dt>Data Window</dt>
<dd><p>The <ref id="TableViewerWindow">Data window</ref>
    always shows the rows and columns of the apparent table, 
    so if you are in doubt about what
    form a table will get exported in, you can see what it looks like there.
    </p></dd>

<dt>Exports</dt>
<dd><p>When you save a table, or export it by dragging it off the
    Table List panel in the <ref id="ControlWindow">Control Window</ref>,
    or create a duplicate table,
    it is the apparent table which is copied.
    So for instance if you define a subset containing only the first
    ten rows of a table
    and then save it to a new table, or create a duplicate within TOPCAT
    using the <label>Duplicate Table</label> (&IMG.COPY;) toolbar button,
    the resulting table will contain only those ten rows.
    </p></dd>

<dt>Joins</dt>
<dd><p>When you use the <ref id="MatchWindow">Match Window</ref> or
    <ref id="ConcatWindow">Concatenation Window</ref> to construct a
    new table on the basis of one or more existing ones,
    the new table will be built on the basis of the apparent versions
    of the tables being operated on.
    The same applies to the join-like functionality provided by 
    table uploads in the <ref id="TapTableLoadDialog">TAP window</ref>,
    <ref id="CdsUploadMatchWindow">CDS Upload X-Match window</ref>
    and the <ref id="DalMultiPanel">multiple positional search</ref>
    (Cone, SIA, SSA) windows.
    </p></dd>

</dl>
Some of the other table view windows are affected too, for instance
the <ref id="ColumnInfoWindow">Columns window</ref> 
displays its columns in the order that they appear in the Apparent Table.
</p>

<subsect id="subsets">
<subhead><title>Row Subsets</title></subhead>

<p>An important feature of TOPCAT is the ability to define and use 
<label>Row Subsets</label>.  A Row Subset is a selection of the 
rows within a whole table being viewed within the application, 
or equivalently a new table composed from some subset of its rows.
You can define these and use them in several different ways;
the usefulness comes from defining them in one context and using them
in another.
The <ref id="SubsetWindow">Subset Window</ref> displays the currently
defined Row Subsets and permits some operations on them.
</p>

<p>At any time each table has a <label>current</label> row subset,
and this affects the <ref id="apparent">Apparent Table</ref>.
You can always see what it is by looking at the "Row Subset" selector
in the <ref id="ControlWindow">Control Window</ref> when that table
is selected; by default it is one containing all the rows.
You can change it by choosing from this selector
or as a result of some other actions.
</p>

<p>Other contexts in which subsets can be used are picking a selection
of rows from which to calculate in the
<ref id="StatsWindow">Statistics Window</ref>
and marking groups of rows to plot using different markers in the
various <ref id="plot2">plotting</ref>
(and <ref id="GraphicsWindow">old-style plotting</ref>) windows.
</p>

<subsubsect id="subsetDef">
<subhead><title>Defining Subsets</title></subhead>

<p>You can define a Row Subset in one of the following ways:

<dl>
<dt>Selecting rows in the browser</dt>
<dd><p>You can select a single row in the 
    <ref id="TableViewerWindow">Data Window</ref> by
    clicking on it, or select a group of adjacent rows by dragging
    the mouse over them.  You can add more rows to the selection by
    keeping the &lt;Control&gt; button pressed while you do it.
    Once you have a set of rows selected you can use the
    <label>Subset From Selected Rows</label> (&IMG.INCLUDE_ROWS;) or
    <label>Subset From Unselected Rows</label> (&IMG.EXCLUDE_ROWS;)
    buttons to create a new subset based
    on the set of highlighted rows or their complement.
    </p>

    <p>Combining this with <ref id="order">sorting</ref> 
    the rows in the table can be useful; 
    if you do a Sort Up on a given column and then drag out the
    top few rows of the table you can easily create a subset consisting
    of the highest values of a given column.
    </p></dd>

<dt>Defining an algebraic expression</dt>
<dd><p>From the <ref id="SubsetWindow">Subset Window</ref> using the
    <label>Add New Subset</label> (&IMG.ADD;) button will pop up 
    the <ref id="SyntheticSubsetQueryWindow">Algebraic Subset Window</ref>
    which allows you to define a new subset using an algebraic expression
    based on the values of the cells in each row.
    The format of such expressions is described in <ref id="jel"/>.
    </p></dd>

<dt>Visible plotted points</dt>
<dd><p>In some of the <ref id="plot2">plotting</ref>
    (and <ref id="GraphicsWindow">old-style plotting</ref>)
    windows you can plot columns
    against each other, and subsequently zoom in and out using the
    mouse.  If you zoom to display only some of the plotted points and
    then use the <label>New Subset From Visible</label> 
    (&IMG.VISIBLE_SUBSET; or &IMG.RANGE_SUBSET;)
    button then a new subset will be
    created containing only rows represented by points in the field of
    view of the plot at the time.
    </p></dd>

<dt>Selected plotted points</dt>
<dd><p>For more control over which plotted points are to be included in
    a subset, you can use the <label>Draw Subset Region</label> 
    (&IMG.BLOB_SUBSET;) button in some of the plotting windows.
    This allows you 
    to trace out with the mouse a region or regions of any shape, 
    creating a new subset containing only those rows represented by 
    the points within those regions.
    </p></dd>

<dt>Boolean columns</dt>
<dd><p>Any column which has a boolean (true/false) type value can be used
    as a subset; rows in which it has a true value are in the subset
    and others are not.  Any boolean column in a table is made available
    as a row subset with the same name when the table is imported.
    </p></dd>

</dl>
</p>

<p>In all these cases you will be asked to assign a name for the subset.
As with column names, it is a good idea to follow a few rules for these
names so that they can be used in <ref id="jel">algebraic expressions</ref>.  
They should be:
<ul>
<li>Distinct from other subset and column names, 
    even apart from upper/lower case distinctions</li>
<li>In the form of a java identifier (starts with a letter, continues with
    alphanumerics including underscore, no spaces)</li>
<li>Not too long</li>
</ul>
When you choose a name, you can either type one in, or select one from
the drop-down list, which gives the names of all the existing subsets.
This allows you to redefine existing subsets.  Note if you do select 
or type in one of the existing names, 
any previous content of that subset will be lost.
</p>

<p>In the first subset definition method above, 
the <label>current</label> subset will be set immediately to the
newly created one.  In other cases the new subset may be highlighted
appropriately in other windows, for instance by being plotted in
scatter plot windows.
</p>

</subsubsect>

</subsect>

<subsect id="order">
<subhead><title>Row Order</title></subhead>

<p>You can sort the rows of each table according to the
values in a selected column.
Normally you will want to sort on
a numeric column, but other values may be sortable too, for instance
a String column will sort alphabetically.
Some kinds of columns (e.g. array ones) don't have any well-defined
order, and it is not possible to select these for sorting on.
</p>

<p>At any time, each table has a <label>current</label> row order,
and this affects the <ref id="apparent">Apparent Table</ref>.
You can always see what it is by looking under the "Sort Order" item
in the <ref id="ControlWindow">Control Window</ref> when that table
is selected; by default it is "(none)", which means the rows have the
same order as that of the table they were loaded in from.
The little arrow (&IMG.UP_TRIM;/&IMG.DOWN_TRIM;) indicates whether
the sense of the sort is up or down.  You can change the sort order
by selecting a column name from this control, and change the sense
by clicking on the arrow.  The sort order can also be changed
by using menu items in the 
<ref id="ColumnInfoWindow">Columns Window</ref> or right-clicking
popup menus in the <ref id="TableViewerWindow">Data Window</ref>.
</p>

<p>Selecting a column to sort by calculates the new row order 
by performing a sort on the cell values there and then.
If the table data change somehow (e.g. because you edit
cells in the table) then it is possible for the sort order 
to become out of date.
</p>

<p>The current row order affects the <ref id="apparent">Apparent Table</ref>,
and hence determines the order of rows in tables which are exported 
in any way (e.g. written out) from TOPCAT.  You can always see the
rows in their currently sorted order in the 
<ref id="TableViewerWindow">Data Window</ref>.
</p>

</subsect>

<subsect id="columns">
<subhead><title>Column Set</title></subhead>

<p>When each table is imported it has a list of columns.
Each column has header information which determines the kind of 
data which can fill the cells of that column as well as a name,
and maybe some additional information like units and 
<webref url="http://www.ivoa.net/Documents/latest/UCD.html"
         >Unified Content Descriptor</webref>.
All this information can be viewed, and in some cases modified,
in the <ref id="ColumnInfoWindow">Columns Window</ref>.
</p>

<p>During the lifetime of the table within TOPCAT, 
this list of columns can be
changed by adding new columns, hiding (and perhaps subsequently 
revealing) existing columns, and changing their order.  The 
current state of which columns are present and visible and what order 
they are in is collectively known as the <label>Column Set</label>,
and affects the <ref id="apparent">Apparent Table</ref>.
The current Column Set is always reflected in the order in which 
columns are displayed in the <ref id="TableViewerWindow">Data Window</ref>
and <ref id="StatsWindow">Statistics Window</ref>.
The <ref id="ColumnInfoWindow">Columns Window</ref> shows all the
known columns, including hidden ones, in Column Set order;
whether they are currently visible is indicated by the (leftmost)
"Visible" column.
</p>

<p>You can affect the current Column Set in the following ways:
<dl>

<dt>Hide/Reveal columns</dt>
<dd><p>In the Columns Window you can toggle columns between hidden and
    visible by clicking on their box in the <label>Visible</label> column.
    To make a group of columns hidden or visible at once,
    select the corresponding rows (drag the mouse over them to select
    a contiguous group; hold the Control button down to add
    more single rows or contiguous groups to the selection) and hit the 
    <label>Hide Selected</label> (&IMG.HIDE;) or
    <label>Reveal Selected</label> (&IMG.REVEAL;)
    button in the toolbar or menu.
    Note when selecting rows, don't drag the mouse over the Visible 
    column, do it somewhere in the middle of the table.
    The <label>Hide All</label> (&IMG.HIDE_ALL;) and
    <label>Reveal All (&IMG.REVEAL_ALL;)</label>
    buttons set all columns in the table invisible or visible - 
    a useful convenience if you've got a very wide table.
    </p>

    <p>You can also hide a column by right-clicking on it in the 
    <ref id="TableViewerWindow">Data Window</ref>, which brings up 
    a popup menu - select the <label>Hide</label> option.
    To make it visible again you have to go to the Columns Window as above.
    </p></dd>

<dt>Move Columns</dt>
<dd><p>In the Data Window you can move columns around by dragging the
    grey column header left or right to a new position (as usual in a 
    <ref id="JTable">JTable</ref>).
    Alternatively, you can drag the rows in the
    <ref id="ColumnInfoWindow">Columns Window</ref> by grabbing the
    grey row header (numbered cell at the left) and dragging it up or down.
    Either of these affects the Column Set, as you can see by looking
    at one window while moving columns in the other.
    </p></dd>

<dt>Add Columns</dt>
<dd><p>You can use the 
    <label>New Synthetic Column</label> (&IMG.ADD;)
    or <label>New Sky Coordinate Columns</label> (&IMG.ADDSKY;) buttons in the
    Columns Window or the (right-click) popup menu in the 
    Data Window to add new columns derived from exsiting ones.
    </p></dd>

<dt>Replace a Column</dt>
<dd><p>If a column is selected in the Columns Window or from the 
    Data Window popup menu you can use the 
    <label>Replace Column with Synthetic</label> (&IMG.MODIFY;) button.
    This is similar to the <label>Add a Synthetic Column</label> 
    described in the previous item, but it pops up a new column 
    dialogue with similar characteristics (name, units etc) 
    to those of the column that's being replaced, and when completed 
    it slots the new column in to the table hiding the old one.
    </p></dd>

<dt>Add a Subset Column</dt>
<dd><p>If you have defined a <ref id="subsets">Row Subset</ref> somehow
    and you want it to appear explicitly in the table 
    (for instance so that when you write the table out the selection is saved)
    you can select that subset in the 
    <ref id="SubsetWindow">Subsets Window</ref> and use the 
    <label>To Column</label> (&IMG.TO_COLUMN;) button, which will add
    a new boolean column to the table with the value <label>true</label> 
    for rows part of that subset and <label>false</label> for the other rows.
    </p></dd>

</dl>
</p>

</subsect>

</sect>

<sect>
<subhead><title>Table I/O</title></subhead>

<subsect>
<subhead><title>Table Formats</title></subhead>

<p>TOPCAT supports a wide variety of tabular data formats.
In most cases these are file formats for tables stored as single files
on a disk or at the end of a URL, but there are other possibilities,
for instance a table you have opened could 
be the result of an SQL query on a database.
</p>

<p>Since you can load a table from one format and save it in a different
one, TOPCAT can be used to convert a table from one format to another.
If this is all you want to do however, you may find it more 
convenient to use the <code>tcopy</code> command line utility in the 
<webref url="http://www.starlink.ac.uk/stilts/">STILTS</webref> package.
</p>

<p>The format handling is extensible, so new formats can
be added fairly easily.  All the table input/output is handled by 
STIL, the Starlink Tables Infrastructure Library;
more detailed descriptions of the I/O capabilities can be found in its
<webref plaintextref="yes" url="http://www.starlink.ac.uk/stil/"
        >documentation</webref>.
</p>

<p>The following subsections describe the available formats for reading
and writing tables.  The two operations are separate, so not all the
supported input formats have matching output formats and vice versa.
</p>

<subsubsect id="inFormats">
<subhead><title>Supported Input Formats</title></subhead>

<p>Loading tables into TOPCAT is done either from the command line
when you start the program up or
using the <ref id="LoadWindow">Load Table</ref> dialogue.
For FITS, VOTable, CDF and GBIN formats
the file format can be detected automatically
(note this is done by looking at the file content, it has nothing
to do with filename extensions).
For other formats though, for instance ASCII or Comma-Separated Values,
you will have to specify the format that the file is in.
In the Load Window, there is a selection box from which you can
choose the format, and from the command line you use the
<code>-f</code> flag - see <ref id="invoke"/> for details.
You can always specify the format rather than using automatic detection
if you prefer - this can be a good idea if a table appears to 
be failing to load in a surprising way, since it may give you 
a more detailed error message.
</p>

<p>In either case, table locations may be given as filenames or
as URLs, and any data compression (gzip, unix compress and bzip2)
will be automatically detected and dealt with - see <ref id="tableLocation"/>.
</p>

<p><strong>Note:</strong> in some earlier versions of TOPCAT, ASCII
format tables could be detected automatically, so you could load
them by typing something like "<code>topcat table.txt</code>".
In the current version, you have to signal that this is an 
ASCII table, for instance by typing "<code>topcat -f ascii table.txt</code>".
</p>

<p>The following sections describe the table formats which TOPCAT can read.</p>

<subsubsubsect id="inFits">
<subhead><title>FITS</title></subhead>

<p>FITS binary and ASCII table extensions can be read.
Normally, TOPCAT will load all TABLE or BINTABLE extensions in a given file.
</p>

<p>If only a single extension is required from a multi-extension FITS file,
this is indicated by giving an identifier after a '#' at the
end of the table location.
The identifier can be in one of two forms:
<ul>
<li>The numeric index of the HDU.  The first extension
    (first HDU after the primary HDU) is numbered 1.
    Thus in a compressed FITS table named "spec23.fits.gz"
    with one primary HDU and two BINTABLE extensions,
    you would view the first one using the name "spec23.fits.gz"
    or "spec23.fits.gz#1" and the second one using the name "spec23.fits.gz#2".
    The suffix "#0" is never used for a legal
    FITS file, since the primary HDU cannot contain a table.
    </li>
<li>The name of the extension.  This is the value of the EXTNAME header
    in the HDU, or alternatively the value of EXTNAME followed by "-"
    followed by the value of EXTVER.  This follows the recommendation in
    the FITS standard that EXTNAME and EXTVER headers can be used to
    identify an HDU.
    So in a multi-extension FITS file "cat.fits" where a table extension
    has EXTNAME='UV_DATA' and EXTVER=1, it could be referenced as
    "cat.fits#UV_DATA" or "cat.fits#UV_DATA-1".
    Matching of these names is case-insensitive.
    </li>
</ul>
</p>

<p>You can select which extension to use interactively
if you use the
<ref id="TreeTableLoadDialog">Hierarchy Browser</ref> to load the table.
</p>

<p>If the table has been written using TOPCAT's "<code>fits-plus</code>"
output format (see <ref id="outFits"/>) then the metadata will be
read in from the primary HDU as well.
</p>

<p>For normal FITS files, header cards in the table's HDU header will be
made available as table parameters (see <ref id="ParameterWindow"/>).
Only header cards which are not used to specify the table format itself
are visible as parameters (e.g. NAXIS, TTYPE* etc cards are not).
HISTORY and COMMENT cards are run together as one multi-line value.
</p>

<p>If the table is stored in a FITS binary table extension in a file
on local disk in uncompressed form, then the table is 'mapped' into
memory - this generally means fast loading and low memory use.
</p>

</subsubsubsect>

<subsubsubsect id="inColfits">
<subhead><title>Column-oriented FITS</title></subhead>

<p>As well as normal binary and ASCII FITS tables, STIL supports
FITS files which contain tabular data stored in column-oriented format.
This means that the table is stored in a BINTABLE extension HDU,
but that BINTABLE has a single row, with each cell of that row
holding a whole column's worth of data.  The final (slowest-varying)
dimension of each of these cells (declared via the TDIMn header cards)
is the same, namely, the number of rows in the table that is represented.
The point of this is that all the cells of a given column are stored
contiguously, which for very large, and especially very wide tables
means that certain access patterns (basically, ones which access
only a small proportion of the columns in a table) can be much more
efficient since they require less I/O overhead in reading data blocks.
</p>

<p>Such tables are perfectly legal FITS files, but most non-STIL software
will probably not recognise them as tables in the usual way.
This format is mostly intended for the case where you have a large
table in some other format (possibly the result of an SQL query)
and you wish to cache it in a way which can be read efficiently
by a STIL-based application.
</p>

<p>Like normal FITS, two variants are supported;
with (<code>colfits-plus</code>) and without (<code>colfits-basic</code>)
metadata stored as a VOTable byte array in the primary HDU.
</p>

<p>Colfits format is only available for data which stored as an
uncompressed file in the file system (not, for instance, from a URL).
</p>

</subsubsubsect>

<subsubsubsect id="inVotable">
<subhead><title>VOTable</title></subhead>

<p>VOTable is an XML-based format for tabular data endorsed by the
<webref url="http://www.ivoa.net/"
        >International Virtual Observatory Alliance</webref>;
while the tabular data which can be encoded is by design close to
what FITS allows, it provides for much richer encoding of structure 
and metadata.
TOPCAT is believed to read any table which conforms to the
VOTable 1.0, 1.1, 1.2 or 1.3
<webref plaintextref="yes" url="&URL.VOTABLE;">specifications</webref>.
This includes tables in which the cell data are
included in-line as XML elements (VOTable/TABLEDATA format),
or included/referenced as a FITS table (VOTable/FITS)
or included/referenced as a raw binary stream (VOTable/BINARY or
VOTable/BINARY2).
TOPCAT does not attempt to be fussy about input VOTable documents,
and it will have a good go at reading VOTables which 
violate the standards in various ways.
</p>

<p>VOTable documents can have a complicated hierarchical structure,
and may contain more than one actual table (TABLE element).
Normally, TOPCAT will load all tables it finds in the document.
If you just want to load a single table, indicate the
zero-based index of the TABLE element in a breadth-first search
after a '#' character at the end of the table specification.
Here is an example VOTable document:
<verbatim><![CDATA[
   <VOTABLE>
     <RESOURCE>
       <TABLE name="Star Catalogue"> ... </TABLE>
       <TABLE name="Galaxy Catalogue"> ... </TABLE>
     </RESOURCE>
   </VOTABLE>
]]></verbatim>
If this is available in a file named "cats.xml"
then loading the document in the usual way from the filestore browser
or command line will open two new tables in TOPCAT.
If you just want the Star Catalogue or the Galaxy Catalogue you can 
use the name "cats.xml#0" or "cats.xml#1" respectively.
</p>

</subsubsubsect>

<subsubsubsect id="inCdf">
<subhead><title>CDF</title></subhead>

<p>NASA's Common Data Format, described at
<webref url="http://cdf.gsfc.nasa.gov/"/>,
is a binary format for storing self-describing data.
It is typically used to store tabular data for subject areas like
space and solar physics.
Since v4.0-1 TOPCAT is capable of reading CDF files, though it can't
write them.
Currently, no attempt is made to represent values representing
times in a human-friendly fashion.  This may change in future releases.
</p>

</subsubsubsect>

<subsubsubsect id="inAscii">
<subhead><title>ASCII</title></subhead>

<p>In many cases tables are stored in some sort of unstructured plain
text format, with cells separated by spaces or some other delimiters.
There is a wide variety of such formats depending on what delimiters
are used, how columns are identified, whether blank values are permitted
and so on.  It is impossible to cope with them all, but TOPCAT
attempts to make a good guess about how to interpret a given ASCII file as
a table, which in many cases is successful.  In particular, if you just
have columns of numbers separated by something that looks like spaces,
you should be just fine.
</p>

<p>Here are the detailed rules for how the ASCII-format tables are 
interpreted:
<ul>
<li>Bytes in the file are interpreted as ASCII characters</li>
<li>Each table row is represented by a single line of text</li>
<li>Lines are terminated by one or more contiguous line termination
    characters: line feed (0x0A) or carriage return (0x0D)</li>
<li>Within a line, fields are separated by one or more whitespace
    characters: space (" ") or tab (0x09)</li>
<li>A field is either an unquoted sequence of non-whitespace characters,
    or a sequence of non-newline characters between matching
    single (') or double (") quote characters -
    spaces are therefore allowed in quoted fields</li>
<li>Within a quoted field, whitespace characters are permitted and are
    treated literally</li>
<li>Within a quoted field, any character preceded by a backslash character
    ("\") is treated literally.  This allows quote characters to appear
    within a quoted string.</li>
<li>An empty quoted string (two adjacent quotes) 
    or the string "<code>null</code>" (unquoted) represents
    the null value</li>
<li>All data lines must contain the same number of fields (this is the
    number of columns in the table)</li>
<li>The data type of a column is guessed according to the fields that
    appear in the table.  If all the fields in one column can be parsed
    as integers (or null values), then that column will turn into an 
    integer-type column.  The types that are tried, in order of 
    preference, are:
       <code>Boolean</code>,
       <code>Short</code>
       <code>Integer</code>,
       <code>Long</code>,
       <code>Float</code>,
       <code>Double</code>,
       <code>String</code>
    </li>
<li>Some special values are permitted for floating point columns:
    <code>NaN</code> for not-a-number, which is treated the same as a
    null value for most purposes, and <code>Infinity</code> or <code>inf</code>
    for infinity (with or without a preceding +/- sign).
    These values are matched case-insensitively.</li>
<li>Empty lines are ignored</li>
<li>Anything after a hash character "#" (except one in a quoted string)
    on a line is ignored as far as table data goes;
    any line which starts with a "!" is also ignored.
    However, lines which start with a "#" or "!" at the start of the table
    (before any data lines) will be interpreted as metadata as follows:
    <ul>
    <li>The last "#"/"!"-starting line before the first data line may
        contain
        the column names.  If it has the same number of fields as 
        there are columns in the table, each field will be taken to be 
        the title of the corresponding column.  Otherwise, it will be 
        taken as a normal comment line.</li>
    <li>Any comment lines before the first data line not covered by the
        above will be concatenated to form the "description" parameter
        of the table.</li>
    </ul>
    </li>
</ul>
</p>

<p>If the list of rules above looks frightening, don't worry,
in many cases it ought
to make sense of a table without you having to read the small print.
Here is an example of a suitable ASCII-format table:
<verbatim>
    #
    # Here is a list of some animals.
    #
    # RECNO  SPECIES         NAME         LEGS   HEIGHT/m
      1      pig             "Pigling Bland"  4  0.8
      2      cow             Daisy        4      2
      3      goldfish        Dobbin       ""     0.05
      4      ant             ""           6      0.001
      5      ant             ""           6      0.001
      6      ant             ''           6      0.001
      7      "queen ant"     'Ma\'am'     6      2e-3
      8      human           "Mark"       2      1.8
</verbatim>
In this case it will identify the following columns:
<verbatim>
    Name       Type
    ----       ----
    RECNO      Short
    SPECIES    String
    NAME       String
    LEGS       Short
    HEIGHT/m   Float
</verbatim>
It will also use the text "<code>Here is a list of some animals</code>"
as the Description parameter of the table.
Without any of the comment lines, it would still interpret the table,
but the columns would be given the names <code>col1</code>..<code>col5</code>.
</p>

<p>If you understand the format of your files but they don't exactly
match the criteria above, the best thing is probably to write a
simple free-standing program or script which will convert them
into the format described here.
You may find Perl or awk suitable languages for this sort of thing.
</p>

<p>This format is not detected automatically - you must specify that
you wish to load a table in <code>ascii</code> format.
</p>

</subsubsubsect>

<subsubsubsect id="inIpac">
<subhead><title>IPAC</title></subhead>

<p>CalTech's Infrared Processing and Analysis Center
use a text-based format for storage of tabular data,
defined at 
<webref 
   url="http://irsa.ipac.caltech.edu/applications/DDGEN/Doc/ipac_tbl.html"/>.
Tables can store column name, type, units and null values, as well
as table parameters.  They typically have a filename extension 
"<code>.tbl</code>" and are used for Spitzer data amongst other
things.  An example looks like this:
<verbatim>
   \title='Animals'
   \ This is a table with some animals in it.
   |   RECNO |    SPECIES |          NAME |    LEGS | HEIGHT   |
   |    char |       char |          char |     int | double   |
   |         |            |               |         | m        |
   |         |            |          null |         |          |
            1          pig   Pigling Bland         4        0.8
            2          cow           Daisy         4          2
            3     goldfish          Dobbin         0       0.05
            4          ant            null         6      0.001
</verbatim>
</p>

</subsubsubsect>

<subsubsubsect id="inCsv">
<subhead><title>Comma-Separated Values</title></subhead>

<p>Comma-separated value ("CSV") format is a common semi-standard 
text-based format in which fields are delimited by commas.
Spreadsheets and databases are often able to export data in some 
variant of it.  The intention is that TOPCAT can read tables in 
the version of the format spoken by MS Excel amongst other applications, 
though the documentation
on which it was based was not obtained directly from Microsoft.
</p>

<p>The rules for data which it understands are as follows:
<ul> 
<li>Each row must have the same number of comma-separated fields.
    </li>
<li>Whitespace (space or tab) adjacent to a comma is ignored.
    </li>
<li>Adjacent commas, or a comma at the start or end of a line
    (whitespace apart) indicates a null field.
    </li>
<li>Lines are terminated by any sequence of carriage-return or newline
    characters ('\r' or '\n')
    (a corollary of this is that blank lines are ignored).
    </li>
<li>Cells may be enclosed in double quotes; quoted values may contain
    linebreaks (or any other character); a double quote character within
    a quoted value is represented by two adjacent double quotes.
    </li>
<li>The first line <em>may</em> be a header line containing column names
    rather than a row of data.  Exactly the same syntactic rules are
    followed for such a row as for data rows.
    </li> 
</ul>
</p>

<p>This format is not detected automatically - you must specify that
you wish to load a table in <code>csv</code> format.
</p>

</subsubsubsect>

<subsubsubsect id="inGbin">
<subhead><title>GBIN</title></subhead>

&gbin.stil.intro;
&gbin.stil.appexample;
&gbin.stil.notes;

</subsubsubsect>

<subsubsubsect id="inTst">
<subhead><title>Tab-Separated Table</title></subhead>

<p>Tab-Separated Table, or TST, is a text-based table format used
by a number of astronomical tools including Starlink's 
<webref url="http://www.starlink.ac.uk/gaia/">GAIA</webref> and
ESO's <webref url="http://archive.eso.org/skycat/">SkyCat</webref>
on which it is based.
A definition of the format can be found in
<webref url="http://www.starlink.ac.uk/star/docs/ssn75.htx/node38.html"
        >Starlink Software Note 75</webref>.
The implementation here ignores all comment lines: special comments
such as the "<code>#column-units:</code>" are not processed.
</p>

<p>An example looks like this:
<verbatim><![CDATA[
    Simple TST example; stellar photometry catalogue.

    A.C. Davenhall (Edinburgh) 26/7/00.

    Catalogue of U,B,V colours.
    UBV photometry from Mount Pumpkin Observatory, 
    see Sage, Rosemary and Thyme (1988). 

    # Start of parameter definitions. 
    EQUINOX: J2000.0 
    EPOCH: J1996.35

    id_col: -1
    ra_col: 0
    dec_col: 1

    # End of parameter definitions.
    ra<tab>dec<tab>V<tab>B_V<tab>U_B
    --<tab>---<tab>-<tab>---<tab>---
    5:09:08.7<tab> -8:45:15<tab>  4.27<tab>  -0.19<tab>  -0.90
    5:07:50.9<tab> -5:05:11<tab>  2.79<tab>  +0.13<tab>  +0.10
    5:01:26.3<tab> -7:10:26<tab>  4.81<tab>  -0.19<tab>  -0.74
    5:17:36.3<tab> -6:50:40<tab>  3.60<tab>  -0.11<tab>  -0.47
    [EOD]
]]></verbatim>
</p>

</subsubsubsect>


<subsubsubsect id="inSql">
<subhead><title>SQL Database Queries</title></subhead>

<p>With appropriate configuration, TOPCAT can be used to examine the
results of queries on an SQL-compatible relational database.
</p>

<p>Database queries can be specified as a string in the form:
<verbatim>
   jdbc:<var>driver-specific-url</var>#<var>sql-query</var>
</verbatim>
The exact form is dependent on the driver.
Here is an example for MySQL:
<verbatim><![CDATA[
   jdbc:mysql://localhost/astro1?user=mbt#SELECT ra, dec FROM swaa WHERE vmag<18
]]></verbatim>
which would get a two-column table (the columns being "ra" and "dec"),
constructed from certain rows from the table "swaa" in the database
"astro1" on the local host, using the access privileges of user mbt.
</p>

<p>Fortunately you don't have to construct this by hand, there is
an <ref plaintextref="yes" id="SQLTableLoadDialog">SQL Query Dialogue</ref> 
to assist in putting it together.
</p>

<p>Note that TOPCAT does not view a table in the database directly,
but the result of an SQL query on that table.  If you want to view
the whole table you can use the query
<verbatim>
   SELECT * FROM table-name
</verbatim>
but be aware that such a query might be expensive on a large table.
</p>

<p>Use of SQL queries requires some additional configuration of TOPCAT;
see <ref id="jdbcConfig"/>.
</p>

</subsubsubsect>

<subsubsubsect>
<subhead><title>World Data Center</title></subhead>

<p>Some support is provided for files produced by the
<webref url="http://www.wdc.rl.ac.uk/">World Data Centre for
Solar Terrestrial Physics</webref>.
The format itself apparently has no name, but files in this format
look something like the following:
<verbatim><![CDATA[
  Column formats and units - (Fixed format columns which are single space seperated.)
  ------------------------
  Datetime (YYYY mm dd HHMMSS)            %4d %2d %2d %6d      -
                                          %1s
  aa index - 3-HOURLY (Provisional)       %3d                  nT

  2000 01 01 000000  67
  2000 01 01 030000  32
      ...
]]></verbatim>
Support for WDC tables is experimental <em>(does the format still exist?)</em>
- it may not be very robust.
</p>

<p>This format is not detected automatically - you must specify that
you wish to load a table in <code>wdc</code> format.
</p>

</subsubsubsect>

</subsubsect>


<subsubsect id="outFormats">
<subhead><title>Supported Output Formats</title></subhead>

<p>Writing out tables from TOPCAT is done 
using the <ref id="SaveQueryWindow">Save Table Window</ref>.
In general you have to specify the format in which you want the table
to be output by selecting from the Save Window's
<label>Table Output Format</label> selector; 
the following sections describe the possible choices.
In some cases there are variants within each format - these are
described as well.
</p>

<p>The program has no "native" file format, but if you have no particular
preference about which format to save tables to, 
<ref id="outFits">FITS</ref> is a good choice.
Uncompressed FITS tables do not in most cases have to be read all the
way through (they are 'mapped' into memory), which makes them very
fast to load up.
The FITS format which is written by default
(also known as "FITS-plus") also uses a trick to 
store extra metadata, such as table parameters and UCDs 
in a way TOPCAT can read in again later (see <ref id="outFits"/>). 
These files are quite usable as normal FITS tables by other applications, 
but they will only be able to see the limited metadata stored in the
FITS headers.
For very large files, in some circumstances column-oriented FITS
("<code>colfits</code>") format can be more efficient for some applications,
though this is unlikely to be understood except by STIL-based code
(TOPCAT and STILTS).
If you want to write to a format which retains all metadata in a portable
format, then one of the <ref id="outVotable"/> formats might be better.
</p>

<subsubsubsect id="outFits">
<subhead><title>FITS</title></subhead>

<p>When saving in FITS format a new file is written consisting of two HDUs
(Header+Data Units):
a primary one (required by the FITS standard), and a single extension of
type BINTABLE containing the table data.
</p>

<p>There are two variants of this format:
<dl>

<dt>fits-basic</dt>
<dd><p>The primary HDU contains only very minimal headers and no data.
    </p></dd>

<dt>fits-plus</dt>
<dd><p>The primary HDU contains an array of bytes
    which stores the full table metadata as the text of a VOTable document,
    along with headers that mark this has been done.
    Most FITS table readers will ignore this altogether and treat the
    file just as if it contained only the table.  
    When TOPCAT (or other 
    <webref url="http://www.starlink.ac.uk/stil/">STIL</webref>-based
    applications)
    read it however, they read out the metadata and make it available for use.
    In this way you can store your data in the efficient and widely portable
    FITS format without losing the additional metadata such as table parameters,
    column UCDs, lengthy column descriptions etc that may be attached
    to the table.  
    Other, more standard schemes exist for combining the benefits of FITS and
    VOTable, but suffer from some disadvantages: 
    <code>votable-fits-inline</code> is hard to process efficiently
    (in particular the data cannot easily be mapped into memory) and
    <code>votable-fits-href</code> requires that you keep your data in 
    two separate files, which can get separated from each other.
    If you want to ensure that the metadata are available to other VOTable-aware
    programs, you should use one of the normal
    <ref plaintextref="yes" id="outVotable">VOTable formats</ref>.
    </p></dd>

</dl>
In general, you can just let TOPCAT detect the format automatically
and not worry about which of these variants is being used - if 
<code>fits-plus</code> is being used you just get some hidden benefits.
</p>

</subsubsubsect>

<subsubsubsect id="outColfits">
<subhead><title>Column-oriented FITS</title></subhead>

<p>When saving in column-oriented FITS format a new file is written
consisting of two HDUs (Header+Data Units); a primary one (required
by the FITS standard) and a single extension of type BINTABLE
containing the table data.  Unlike normal FITS format however,
this table consists of a single row in which each cell holds the
data for an entire column.  This can be a more efficient format
to work with when dealing with very large, and especially very wide,
tables.  The benefits are greatest when the file size exceeds the
amount of available physical memory and operations are required
which scan through the table using only a few of the columns
(much of TOPCAT's operations, for instance plotting two columns
against each other, fit into this category).
The overhead for reading and writing this format is somewhat
higher than for normal FITS however, and other applications may not
be able to work with it (though it is a legal FITS file), so in most
cases normal FITS is a more suitable choice.
</p>

<p>Like normal (row-oriented) FITS (see <ref id="outFits"/>), 
there are two variants:
<dl>
<dt>colfits-plus</dt>
<dd><p>The primary HDU contains an array of bytes which stores the
    table metadata in VOTable format.
    </p></dd>
<dt>colfits-basic</dt>
<dd><p>The primary HDU contains no data.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="outVotable">
<subhead><title>VOTable</title></subhead>

<p>When a table is saved to VOTable format, a document conforming to the
VOTable specification containing a single TABLE element within
a single RESOURCE element is written.
The version of the VOTable specification according to which the output
is written can be controlled using the
<code>votable.version</code> <ref id="jvmProperties">system property</ref>.
</p>

<p>There are a number of variants which determine the form in which
the table data (DATA element) is written:
<dl>

<dt>votable-tabledata</dt>
<dd><p>TABLEDATA element (pure XML)
    </p></dd>

<dt>votable-binary-inline</dt>
<dd><p>BINARY element containing base64-encoded data within the document
    </p></dd>

<dt>votable-fits-href</dt>
<dd><p>FITS element containing a reference to an external newly-written FITS
    file (with a name derived from that of the VOTable document)
    </p></dd>

<dt>votable-binary-href</dt>
<dd><p>BINARY element containing a reference to an external newly-written
    binary file (with a name derived from that of the VOTable document)
    </p></dd>

<dt>votable-fits-inline</dt>
<dd><p>FITS element containing base64-encoded data within the document
    </p></dd>
</dl>
See the 
<webref url="&URL.VOTABLE;" plaintextref="yes">VOTable specification</webref> 
for more explanation of what these variants mean.
They can all be read by the 
<ref id="inVotable">VOTable input handler</ref>.
</p>

<p>If VOTable 1.3 output is in force, the <code>*-binary-*</code>
options will be replaced by <code>*-binary2-*</code>.
</p>

</subsubsubsect>

<subsubsubsect id="outAscii">
<subhead><title>ASCII</title></subhead>

<p>Tables can be written using a format which is compatible with
the <ref id="inAscii">ASCII input format</ref>.
It writes as plainly as possible, so should stand a good chance of
being comprehensible to other programs which require some sort of
plain text rendition of a table.  
</p>

<p>The first line is a comment (starting with a "<code>#</code>" character)
which names the columns, and
an attempt is made to line up data in columns using spaces.
Here is an example of a short table written in this format:
<verbatim>
   # index Species  Name   Legs Height Mammal
     1     pig      Bland  4    0.8    true  
     2     cow      Daisy  4    2.0    true  
     3     goldfish Dobbin 0    0.05   false 
     4     ant      ""     6    0.0010 false 
     5     ant      ""     6    0.0010 false 
     6     human    Mark   2    1.9    true  
</verbatim>
</p>

</subsubsubsect>


<subsubsubsect>
<subhead><title>Text</title></subhead>

<p>Tables can be written to a simple text-based format which is
designed to be read by humans.  No reader exists for this format.
</p>

<p>Here is an example of a short table written in this format:
<verbatim>
   +-------+----------+--------+------+--------+--------+
   | index | Species  | Name   | Legs | Height | Mammal |
   +-------+----------+--------+------+--------+--------+
   | 1     | pig      | Bland  | 4    | 0.8    | true   |
   | 2     | cow      | Daisy  | 4    | 2.0    | true   |
   | 3     | goldfish | Dobbin | 0    | 0.05   | false  |
   | 4     | ant      |        | 6    | 0.0010 | false  |
   | 5     | ant      |        | 6    | 0.0010 | false  |
   | 6     | human    | Mark   | 2    | 1.9    | true   |
   +-------+----------+--------+------+--------+--------+
</verbatim>
</p>

</subsubsubsect>

<subsubsubsect id="outCsv">
<subhead><title>Comma-Separated Values</title></subhead>

<p>Tables can be written to the semi-standard comma-separated value (CSV) 
format, described in more detail in <ref id="inCsv"/>.
This can be useful for importing into certain external applications,
such as some spreadsheets or databases.
</p>

<p>There are two variants:
<dl>

<dt>CSV</dt>
<dd><p>The first line is a header which contains the column names.
    </p></dd>

<dt>CSV-noheader</dt>
<dd><p>No header line is emitted, all lines represent data rows.
    </p></dd>

</dl>

</p>

</subsubsubsect>

<subsubsubsect id="outIpac">
<subhead><title>IPAC</title></subhead>

<p>Tables can be wrtten to the IPAC data format,
described in more detail in <ref id="inIpac"/>.
</p>

</subsubsubsect>

<subsubsubsect id="outTst">
<subhead><title>Tab-Separated Table</title></subhead>

<p>Tables can be written to TST format, which is described in more 
detail in <ref id="inTst"/>.  This can be useful for communicating 
with some other astronomical tools such as GAIA.
</p>

</subsubsubsect>

<subsubsubsect id="outSql">
<subhead><title>SQL Tables</title></subhead>

<p>With appropriate configuration, TOPCAT can write out tables as
new tables in an SQL-compatible relational database.
</p>

<p>For writing, the location is specified as the following URL:
<verbatim>
   jdbc:<var>driver-specific-url</var>#<var>new-table-name</var>
</verbatim>
The exact form is dependent on the driver.
Here is an example for MySQL:
<verbatim><![CDATA[
   jdbc:mysql://localhost/astro1?user=mbt#newtab
]]></verbatim>
which would write the current contents of the browser into a new table
named "newtab" in the database "astro1" on the local host with the
access privileges of user mbt.
</p>

<p>Fortunately you do not have to construct this URL by hand, there is
an <ref id="SQLWriteDialog">SQL dialogue box</ref> to assist
in putting it together.
</p>

<p>Use of SQL queries requires some additional configuration of TOPCAT;
see <ref id="jdbcConfig"/>.
</p>

</subsubsubsect>

<subsubsubsect>
<subhead><title>HTML</title></subhead>

<p>A table can be written out as an HTML 4.01
<webref url="http://www.w3.org/TR/html401/struct/tables.html">TABLE</webref>
element, suitable for use as a web page or insertion into one.
</p>

<p>There are two variants:
<dl>

<dt>HTML</dt>
<dd><p>A freestanding HTML document, complete with HTML, HEAD and BODY
    tags is output.
    </p></dd>

<dt>HTML-element</dt>
<dd><p>Only the TABLE element representing the table is output;
    this should normally be embedded in a larger HTML document before use.
    </p></dd>

</dl>
</p>

</subsubsubsect>

<subsubsubsect>
<subhead><title>LaTeX</title></subhead>

<p>A table can be written out as a LaTeX <code>tabular</code> environment,
suitable for insertion into a document intended for publication.
</p>

<p>There are two variants:
<dl>

<dt>LaTeX</dt>
<dd><p>The <code>tabular</code> element alone is output;
    this will have to be embedded in a larger LaTeX document before use.
    </p></dd>

<dt>LaTeX-document</dt>
<dd><p>A freestanding LaTeX document, consisting of the 
    <code>tabular</code> within a 
    <code>table</code> within a
    <code>document</code> is output.
    </p></dd>

</dl>
</p>

<p>Obviously, this isn't so suitable for very large tables.
</p>

</subsubsubsect>

<subsubsubsect id="mirage">
<subhead><title>Mirage Format</title></subhead>

<p><webref url="http://www.bell-labs.com/project/mirage/index.html"
           plaintextref="yes"
           >Mirage</webref>
is a powerful standalone java tool developed at Bell Labs for analysis of
multidimensional data.  It uses its own file format for input.
TOPCAT can write tables in the input format which Mirage uses,
so that you can prepare tables in TOPCAT and write them out for
subsequent use by Mirage.
</p>

<p>It is also possible in principle to launch Mirage directly
from within TOPCAT, using the 
<label>Export To Mirage</label> item on the 
<ref id="ControlWindow">Control Window</ref>'s <label>File</label> menu;
this will cause Mirage to start up viewing the currently selected
<ref id="apparent">Apparent Table</ref>.
In order for this to work the Mirage classes must
be on your classpath (see <ref id="jvmClasspath"/>) when TOPCAT is run.
</p>

<p>There appears to be 
a bug in Mirage which means this does not always work -
sometimes Mirage starts up with no data loaded into it.
In this case you will have to save the data to disk in Mirage format,
start up Mirage separately, and load the data in using the
<label>New Dataset</label> item in Mirage's <label>Console</label> menu.
</p>

<p>Note that when Mirage has been launched from TOPCAT, exiting Mirage
or closing its window will exit TOPCAT as well.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="customHandlers">
<subhead><title>Custom I/O Formats</title></subhead>

<p>It is in principle possible to configure TOPCAT to work with
table file formats other than the ones listed in this section.
It does not require any upgrade of TOPCAT itself, but you have
to write or otherwise acquire an input and/or output handler for the
table format in question.
</p>

<p>The steps that you need to take are:
<ol>
<li>Write java classes which constitute your input and/or output handler</li>
<li>Ensure that these classes are available on your classpath while
    TOPCAT is running (see <ref id="jvmClasspath"/>)</li>
<li>Set the <code>startable.readers</code> and/or 
    <code>startable.writers</code> system property to the name of the
    handler classes (see <ref id="jvmProperties"/>)</li>
</ol>
</p>

<p>Explaining how to write such handlers is beyond the scope of this
document - see the user document and javadocs for 
<webref url="http://www.starlink.ac.uk/stil/" plaintextref="yes">STIL</webref>.
</p>

</subsubsect>

</subsect>

<subsect id="tableLocation">
<subhead><title>Table Locations</title></subhead>

<p>In many cases loading and saving tables will be done using GUI
dialogues such as the filestore 
<ref id="FilestoreTableLoadDialog">load</ref> and 
<ref id="FilestoreTableSaveDialog">save</ref> windows, where you 
just need to click on a filename or directory to indicate the
load/save location.  However in some cases, for instance
specifying tables on the command line (<ref id="topcatArgs"/>) 
or typing pathnames directly into the 
<ref id="LoadWindow">load</ref>/<ref id="SaveQueryWindow">save</ref> 
dialogue windows,
you may want give the location of a table for input or output 
using only a single string.
</p>

<p>Most of the time you will just want to type in a filename; either
an absolute or relative pathname can be used.
However, TOPCAT also supports direct use of URLs, including ones
using some specialised protocols.  Here is the list of URL types
allowed:
<dl>
    <dt><code>http:</code></dt>
    <dd><p>Read from HTTP resources.</p></dd>
    <dt><code>ftp:</code></dt>
    <dd><p>Read from anonymous FTP resources.</p></dd>
    <dt><code>file:</code></dt>
    <dd><p>Read from local files; not particularly useful since you can
        do much the same using just the filename.</p></dd>
    <dt><code>jar:</code></dt>
    <dd><p>Specialised protocol for looking inside Java Archive files -
        see <webref url="&URL.J2SE_DOCS;api/java/net/JarURLConnection.html"
                    >JarURLConnection</webref> documentation.</p></dd>
    <dt><code>myspace:</code></dt>
    <dd><p>Accesses files in the AstroGrid "MySpace" virtual file store.
        These URLs look something like
        "<code>myspace:/survey/iras_psc.xml</code>",
        and can access files in the myspace are that the user is currently
        logged into.
        These URLs can be used for both input and output of tables.
        To use them you must have an AstroGrid account and the AstroGrid
        WorkBench or similar must be running; if you're not currently
        logged in a dialogue will pop up to ask you for name and
        password.</p></dd>
    <dt><code>ivo:</code></dt>
    <dd><p>Understands ivo-type URLs which signify files in the
        AstroGrid "MySpace" virtual file store.
        These URLs look something like
        "<code>ivo://uk.ac.le.star/filemanager#node-2583</code>".
        These URLs can be used for both input and output of tables.
        To use them you must have an AstroGrid account and the AstroGrid
        WorkBench or similar must be running; if you're not currently
        logged in a dialogue will pop up to ask you for name and
        password.</p></dd>
    <dt><code>jdbc:</code></dt>
    <dd><p>Used for communicating with SQL-compliant relational databases.
        These are a bit different to normal URLs - see
        <ref id="inSql"/> and <ref id="outSql"/>.</p></dd>
</dl>
</p>

<p>As with the GUI-based load dialogues, data compression in any of the
supported formats (gzip, bzip2, Unix compress) is detected and 
dealt with automatically for input locations.
</p>

</subsect>

</sect>

<sect id="join">
<subhead><title>Joins and Matches</title></subhead>

<p>TOPCAT allows you to join two or more tables together to 
produce a new one in a variety of ways, and also to identify
"similar" rows within a single table according to their cell contents.
This section describes the facilities for performing these related
operations.
</p>

<p>There are two basic ways to join tables together: top-to-bottom and
side-by-side.
A top-to-bottom join (which here I call <label>concatenation</label>)
is fairly straightforward in that it just requires you to decide
which columns in one table correspond to which columns in the other.
A side-by-side join is more complicated - it is rarely the case that
row <m>i</m> in the first table should correspond to row <m>i</m> in the
second one, so it is necessary to provide some criteria for 
deciding which (if any) row in the second table corresponds to a given
row in the first.  In other words, some sort of <label>matching</label>
between rows in different tables needs to take place.
This corresponds to what is called a <em>join</em> in database technology.
Matching rows within a single table is a useful operation
which involves many of the same issues, so that is described here too.
</p>

<subsect id="concat">
<subhead><title>Concatenating Tables</title></subhead>

<p>Two tables can be concatenated using the 
<ref id="ConcatWindow">Concatenation Window</ref>,
which just requires you to specify the two tables to be joined,
and for each column in the first ("Base") table,
which column in the second ("Appended") table (if any) corresponds to it.
The <ref plaintextref="yes" id="apparent">Apparent Table</ref> 
is used in each case.
The resulting table, which is added to the list of known tables in
the <ref id="ControlWindow">Control Window</ref>,
has the same columns as the Base table, and a number of rows 
equal to the sum of the number of rows in the Base and Appended tables.
</p>

<p>As a very simple example, concatenating these two tables:
<verbatim>
   Messier   RA       Dec      Name
   -------   --       ---      ----
   97        168.63   55.03    Owl Nebula
   101       210.75   54.375   Pinwheel Galaxy
   64        194.13   21.700   Black Eye Galaxy
</verbatim>
and
<verbatim>
   RA2000    DEC2000   ID
   ------    -------   --
   185.6     58.08     M40
   186.3     18.20     M85
</verbatim>
with the assignments RA->RA2000, Dec->DEC2000 and Messier->ID would give:
<verbatim>
   Messier   RA       Dec      Name
   -------   --       ---      ----
   97        168.63   55.03    Owl Nebula
   101       210.75   54.375   Pinwheel Galaxy
   64        194.13   21.700   Black Eye Galaxy
   M40       185.6    58.08
   M85       183.6    18.20
</verbatim>
Of course it is the user's responsibility to ensure that the 
correspondance of columns is sensible (that the two corresponding
columns mean the same thing).
</p>

<p>You can perform a concatenation using the 
<ref id="ConcatWindow">Concatenation Window</ref>;
obtain this using the <label>Concatenate Tables</label> (&IMG.CONCAT;) button
in the <ref id="ControlWindow">Control Window</ref>.
</p>

</subsect>

<subsect id="pairMatch">
<subhead><title>Matching Rows Between Tables</title></subhead>

<p>When joining two tables side-by-side you need to identify which
row(s) in one correspond to which row(s) in the other.
Conceptually, this is done by looking at each row in the first table,
somehow identifying in the second table which row
"refers to the same thing", and putting a new row in the joined table
which consists of all the fields of the row in the first table, 
followed by all the fields of its matched row in the second table.
The resulting table then has a number of columns equal to the 
sum of the number of columns in both input tables.
</p>

<p>In practice, there are a number of complications.  For one thing, each 
row in one table may be matched by zero, one or many rows in the 
the other.  
For another, defining what is meant by "referring to the same thing" 
may not be straightforward.  There is also the problem of 
actually identifying these matches
in a relatively efficient way (without explicitly comparing each
row in one table with each row in the other, which would be far too slow
for large tables).
</p>

<p>A common example is the case of matching two object catalogues -
suppose we have the following catalogues:
<verbatim>
    Xpos       Ypos        Vmag
    ----       ----        ----
   1134.822    599.247     13.8
    659.68    1046.874     17.2
    909.613    543.293      9.3
</verbatim>
and
<verbatim>
    x           y          Bmag
    -           -          ---- 
   909.523     543.800     10.1
   1832.114    409.567     12.3
   1135.201    600.100     14.6
    702.622   1004.972     19.0
</verbatim>
and we wish to combine them to create one new catalogue with a row
for each object which appears in both tables.
To do this, you have to specify what counts as a match - in this
case let's say that a row in one table matches (refers to the same
object as) a row in the other if the distance between the positions
indicated by their X and Y coordinates matches to within one unit
(sqrt((Xpos-x)<sup>2</sup> + (Ypos-y)<sup>2</sup>)&lt;=1)).
Then the catalogue we will end up with is:
<verbatim>
    Xpos       Ypos        Vmag    x           y          Bmag
    ----       ----        ----    -           -          ---- 
   1134.822    599.247     13.8   1135.201    600.100     14.6
    909.613    543.293      9.3    909.523    543.800     10.1
</verbatim>
There are a number of variations on this however - your match criteria
might involve sky coordinates instead of Cartesian ones (or not be
physical coordinates at all), you might want to match more than two
tables, you might want to identify groups of matching objects in
a single table, you might want the output to include rows which
don't match as well...
</p>

<p>The <ref id="MatchWindow">Match Window</ref> allows you to specify
<ul>
<li>Which tables are to be matched</li>
<li>What the criteria are for matching rows</li>
<li>What to do for rows that don't have exactly one match</li>
<li>What rows to include in the output table</li>
</ul>
and to start the matching operation.
Depending on the type of match chosen, some additional columns may be
appended to the resulting table giving additional details on 
how the match went.
Usually, the 'match score' is one of these;
The exact value and meaning of this column depends on the match,
but it typically gives the distance between
the matched points in some sensible units;
the smaller the value, the better the match.
You can find out exactly what this score means by examining 
the column's description
in the <ref id="ColumnInfoWindow">Columns Window</ref>.
Columns in the resulting table retain their original names
unless that would lead to ambiguity, in which case
a disambiguating suffix "_1" or "_2" is added to the column name.
</p>

<p>To match two tables, use the <label>Pair Match</label> (&IMG.MATCH2;) button
in the <ref id="ControlWindow">Control Window</ref>; 
to match more tables than two at once, use the other options on the
Control Window's <label>Join</label> menu.
</p>

</subsect>

<subsect id="internalMatch">
<subhead><title>Matching Rows Within a Table</title></subhead>

<p>Although the effect is rather different, searching through a 
single table for rows which match each other (refer to the same
object, as explained above) is a similar process and requires much
of the same information to be specified, mainly, what counts as
a match.
You can do this using the <ref id="MatchWindow1">Internal Match Window</ref>,
obtained by using the <label>Internal Match</label> (&IMG.MATCH1;) button
in the <ref id="ControlWindow">Control Window</ref>'s <label>Joins</label>
menu.
</p>

</subsect>

<subsect id="matchGroup">
<subhead><title>Multi-Object Matches</title></subhead>

<p>The matching in TOPCAT is determined by specified
match criteria, as described in <ref id="matchCriteria"/>.
These criteria give conditions for whether two items (table rows)
count as matched with each other.  In the case of a pair match,
it is clear how this is to be interpreted.
</p>

<p>However, some of the matching operations such as the
<ref id="MatchWindow1">Internal Match</ref>
search for match groups which may have more than two members.
This section explains how TOPCAT applies the pair-wise
matching criteria it is given to identifying multi-object groups.
</p>

<p>In a multi-object match context, the matcher identifies a matched
group as the largest possible group of objects in which each is
linked by a pair match to <em>any</em> other object in the group -
it is a group of "friends of friends".
Formally, the set of matched groups is a set of disjoint graphs whose nodes
are input table rows and whose edges are successful pair matches,
where no successful pair match exists between nodes in
different elements of that set.
Thus the set has a minimal number of elements, and each of its elements
is a matched group of maximal size.
The important point to note
is that for any particular pair in a matched group,
there is no guarantee that the two objects match each other,
only that you can hop from one to the other via pairs which do match.
</p>

<p>So in the case of a multi-object sky match
on a field which is very crowded compared to the specified error radius,
it is quite possible for <em>all</em> the objects in the input table(s)
to end up as part of the same large matching group.
Results at or near this percolation threshold are
(a) probably not useful and
(b) likely to take a long time to run.
Some care should therefore be exercised when specifying match criteria
in multi-object match contexts.
</p>

</subsect>

<subsect id="matchPlot">
<subhead><title>Plotting Match Results</title></subhead>

<p>Having performed a crossmatch, it is very often a good idea
to look at the results graphically.
If you can plot the input catalogues, and the output catalogue,
with an indication of which rows in the inputs have been joined
together, you can rapidly get a good idea of the result of the
match, and whether it did what you expected.
This is especially true in the presence of crowded fields,
tentative match criteria, or other circumstances under which the
match might not go as expected.
</p>

<p>Since TOPCAT version 4.1, for most pair matches, you can do this
automatically.
When a suitable match completes, you may see a confirmation dialogue
like this:
</p>
<figure>
<caption><px>Pair plot completion confirmation dialogue</px></caption>
<figureimage src="&FIG.plotmatch_dialog;"/>
</figure>

<p>If you click the <label>OK</label> button, it will simply dismiss
the dialogue.
However, if you click the <label>Plot Result</label> button, a new
plot window will appear with all the points from the input catalogues
and pair links (lines between the joined positions) for the joined rows.
The result is something like this:
</p>
<figure>
<caption><px>Output from crossmatch Plot Result</px></caption>
<figureimage src="&FIG.SkyPlotWindow_plotmatch;"/>
</figure>

<p>It shows clearly which points have been joined.
You can fiddle with the plot controls in the usual way
to adjust the output (see <ref id="plot2"/>).
It is also possible to set up such plots by hand.
</p>

</subsect>

<subsect id="matchAlgorithm">
<subhead><title>Notes on Matching</title></subhead>

<p>This section provides a bit more detail on the how the row matching
of local tables 
(sections <ref id="pairMatch"/> and <ref id="internalMatch"/>)
is done.
It is designed to give a rough idea to interested parties;
it is <em>not</em> a tutorial description from 
first principles of how it all works.
</p>

<p>The basic algorithm for matching is based on dividing up the space
of possibly-matching rows into an (indeterminate) number of bins.  
These bins will typically correspond to disjoint cells of a physical
or notional coordinate space, but need not do so.  In the first step, each
row of each table is assessed to determine which bins might contain
matches to it - this will generally be the bin that it falls into and
any "adjacent" bins within a distance corresponding to the matching
tolerance.  A reference to the row is associated with each such bin.
In the second step, each bin is examined, and if two or more 
rows are associated with it every possible pair of rows in the associated set
is assessed to see whether it does in fact constitute a matched pair.
This will identify all and only those row pairs which 
are related according to the selected match criteria.
During this process a number of optimisations may be applied depending
on the details of the data and the requested match.
</p>

<p>The matching algorithm described above is 
roughly an <m>O(N log(N))</m> process, 
where <m>N</m> is the total number of rows in all the tables participating
in a match.  This is good news, since the naive interpretation 
would be <m>O(N<sup>2</sup>)</m>.  
This can break down however if the matching
tolerance is such that the number of rows associated with some or most bins
gets large, in which case an <m>O(M<sup>2</sup>)</m> component can come to
dominate, where <m>M</m> is the number of rows per bin.
The average number of rows per bin is reported in the logging while a
match is proceeding, so you can keep an eye on this.
</p>

<p>For more detail on the matching algorithms, see the 
javadocs for the <code>uk.ac.starlink.table.join</code> package,
or contact the author.
</p>

</subsect>

<subsect>
<subhead><title>Matching against a Remote Table</title></subhead>

<p>TOPCAT provides a number of facilities for positional crossmatches
against tables which are exposed via Virtual Observatory web services
(Cone Search, Simple Image Access and Simple Spectral Access)
and general SQL-like matching (TAP).
These work rather differently from the other functions described
in this section, which operate on local tables, though conceptually
the result is similar.
See <ref id="vo"/> for more details.
</p>

<p>It also provides access to the X-Match service provided by the CDS,
as described in <ref id="CdsUploadMatchWindow"/>, which allows fast matching
against any VizieR table or SIMBAD.
</p>

<p>In many cases the CDS Upload X-Match window is the easiest, fastest and
best way to match against remote tables.  TAP is more flexible, but
has a somewhat steeper learning curve, and may not be as fast or
scalable for large local tables.  The multi-SIA and multi-SSA
windows may be useful for performing per-row searches of modest size
against remote image or spectral archives.
The multi-cone window is (since version 4.2)
present mostly for historical reasons, and is not usually a good choice,
since it is much less efficient than TAP or CDS X-Match.
</p>

</subsect>

</sect>

<sect id="vo">
<subhead><title>Virtual Observatory Access</title></subhead>

<p>Several of the windows in TOPCAT allow you to interface with
so-called <em>Data Access Layer</em> services provided within the
Virtual Observatory (VO).
The buzzwords are not important, but the basic idea is that this
allows you to locate a service providing data which may be
of interest to you, and then query that service to obtain the data.
The VO is not a single monolithic entity, but a set of protocols
which allow a general purpose tool such as TOPCAT to talk to 
services made available by many different participating data
providers in a uniform way, without having to have prior knowledge
of what services are out there or the details of how their data
is arranged.
</p>

<p>The basic operation is similar for all of TOPCAT's access to 
these services:
<ol>
<li>Select the <em>registry</em> to query for services
    (or use the default one)</li>
<li>Query that registry for services of interest</li>
<li>From the returned list of services,
    select one that you wish to query for data</li>
<li>Specify the query to send to the data service</li>
<li>Start the query and wait for the result</li>
</ol>
</p>

<p>These ideas are explained in more detail in the following subsections.
The windows from which this is done are documented in <ref id="vo-windows"/>.
</p>

<p><strong>Note:</strong>
For information on SAMP or PLASTIC, which are protocols developed
within the Virtual Observatory context, but are not necessarily 
concerned with remote data access, see <ref id="interop"/>.
</p>

<subsect id="registry">
<subhead><title>The Registry</title></subhead>

<p>The <label>Registry</label> is fundamental to the way that the VO works.
A registry is a list of
all the services made available by different data providers.
Each entry records some information about the type of service,
who provided it, what kind of data it contains, and so on
(registries may contain other types of entry as well, but we will
not discuss these further here).
Any data provider can add an entry to the registry
to advertise that it has certain datasets available for access.
</p>

<p>Several registries exist; they tend to be maintained by different
regional VO organisations.  At the time of writing, there are 
registries maintained for public access by GAVO, ESA, STScI
and (remnants of) the UK's AstroGrid, amongst others.
Particular projects may also maintain their own registries with
limited holdings for internal use.
The main public access registries talk to each other to synchronize 
their contents,
so to a first approximation, they contain similar lists of entries
to each other, and it shouldn't matter too much which one you use.
In practice, there are some differences of format and content
between them, so one may work better than another for you or may
contain a record that you need.
In most cases though, using the default registry (currently the GAVO one)
will probably do what you want it to.
</p>

</subsect>

<subsect>
<subhead><title>Data Access Services</title></subhead>

<p>A number of different service types are defined and listed
in the registry; the ones that
TOPCAT currently knows how to access are the following:
<dl>
<dt>Cone Search:</dt>
<dd><p>retrieve entries in a certain region of the sky 
    from a remote catalogue
    </p></dd>
<dt>Simple Image Access (SIA):</dt>
<dd><p>find image data (often in FITS format) in a certain region of the sky
    from a remote image archive
    </p></dd>
<dt>Simple Spectral Access (SSA):</dt>
<dd><p>find spectral data, usually in a certain region of the sky,
    from a remote archive of spectral observations or theoretical models
    </p></dd>
<dt>Table Access Protocol (TAP):</dt>
<dd><p>make free-form queries to a remote database using an SQL-like
    query language
    </p></dd>
</dl>
Detailed technical information about these protocols can be found
at the IVOA web site (<webref url="http://www.ivoa.net/"/>) in the
<webref url="http://www.ivoa.net/Documents/latest/ConeSearch.html"
        >Cone Search</webref>,
<webref url="http://www.ivoa.net/Documents/latest/SIA.html">SIA</webref>,
<webref url="http://www.ivoa.net/Documents/latest/SSA.html">SSA</webref>
and
<webref url="http://www.ivoa.net/Documents/latest/TAP.html">TAP</webref>
documents, but these are by no means required reading for users of the
services.
These protocols (apart from Cone Search) are quite complex
and have many specialised and optional features.
The options offered for Cone Search and TAP are
reasonably complete, but for SIA and SSA
TOPCAT only provides a fairly basic level of interaction,
and many features (for instance SSA queries by wavelength, 
or non-positional queries for theoretical data) are not accessible from it.
</p>

<p>Cone Search, SIA and SSA are <em>positional</em> protocols meaning
that they query a single region of the sky.
TOPCAT provides access to these service types in two main ways:
<dl>
<dt>Single positional query</dt>
<dd><p>If you enter by hand a sky position (RA, Dec) and radius,
    you can download a table containing the results of a search for a
    single (usually, small) region on the sky.
    See the sections on
    <ref id="ConeSearchDialog">Cone</ref>,
    <ref id="SiapTableLoadDialog">SIA</ref>,
    <ref id="SsapTableLoadDialog">SSA</ref>
    load dialogues in <ref id="vo-windows"/>.
    </p></dd>
<dt>Multiple positional query</dt>
<dd><p>You can define how each row of an input table selects a region on
    the sky.  This will usually correspond to selecting a column for RA
    and a column for Dec, and either a fixed radius or a column giving
    the radius.  Then a positional query can be made for each row of
    the input table.
    The result is effectively a join between the input
    <ref id="apparent">Apparent Table</ref> and the
    remote table of object data, images or spectra.
    See the sections on
    <ref id="ConeMultiWindow">Cone</ref>,
    <ref id="SiaMultiWindow">SIA</ref>,
    <ref id="SsaMultiWindow">SSA</ref>
    multiple query windows in <ref id="vo-windows"/>.
    </p></dd>
</dl>
</p>

<p>TAP is a much more powerful protocol
not restricted to positional queries, and has its own interface.
See the <ref id="TapTableLoadDialog">TAP</ref> load dialogue section
in <ref id="vo-windows"/>.
</p>

</subsect>


</sect>

<sect id="jel">
<subhead><title>Algebraic Expression Syntax</title></subhead>

<p>TOPCAT allows you to enter algebraic expressions in a number of contexts:
<ol>
<li>To define a new column in terms of existing columns in the
    <ref id="SyntheticColumnQueryWindow">Synthetic Column</ref> dialogue</li>
<li>To define a new <ref id="subsets" plaintextref="yes">Row Subset</ref>
    on the basis of table data in the 
    <ref id="SyntheticSubsetQueryWindow">Algebraic Subset</ref> dialogue</li>
<li>To define a custom
    <ref id="activation" plaintextref="yes">Activation Action</ref>
    in the <ref id="ActivationQueryWindow">Activation</ref> dialogue.</li>
<li>When faced with a <ref id="columnSelector">column selector</ref>
    for plotting or other purposes,
    in some cases you can type in an expression rather than selecting
    or typing a simple column name.</li>
</ol>
This is a powerful feature which permits you to manipulate and select
table data in very flexible ways - you can think of it like a 
sort of column-oriented spreadsheet.
The syntax for entering these expressions is explained in this section.
</p>

<p>What you write are actually expressions in
the Java language, which are compiled into Java bytecode before
evaluation.  However, this does not mean that you need to be a
Java programmer to write them.  The syntax is pretty similar to C,
but even if you've never programmed in C most simple things, 
and some complicated ones, are quite intuitive.
</p>

<p>The following explanation gives
some guidance and <ref id="jelExamples">examples</ref>
for writing these expressions.
Unfortunately a complete tutorial on writing Java is beyond
the scope of this document, but it should provide enough information
for even a novice to write useful expressions.
</p>

<p>The expressions that you can write are basically any function
of all the column values and subset inclusion flags which apply
to a given row; the function result can then define 
the per-row value of a new column, 
or the inclusion flag for a new subset,
or the action to be performed when a row is activated by clicking on it.
If the built-in operators and functions are not sufficient,
or it's unwieldy to express your function in one line of code,
you can add new functions by writing your own classes -
see <ref id="jelExtend"/>.
</p>

<p><strong>Note:</strong> if Java is running in an environment with
certain security restrictions (a security manager which
does not permit creation of custom class loaders) then algebraic
expressions won't work at all, and the buttons which allow you to
enter them will be disabled.
</p>

<subsect id="jelCols">
<subhead><title>Referencing Cell Values</title></subhead>

<p>To create a useful expression for a cell in a column, you will
have to refer to other cells in different columns of the same table row.
You can do this in three ways:
<dl>
<dt>By Name</dt>
<dd><p>The Name of the column may be used if it is unique (no other column in
    the table has the same name) and if it has a suitable form.
    This means that it must have the form of a Java variable - basically
    starting with a letter and continuing with
    letters or numbers.  In particular it cannot have any spaces in it.
    The underscore and currency symbols count as
    letters for this purpose.
    Column names are treated case-insensitively.
    </p></dd>

<dt>By &column.id.char;ID</dt>
<dd><p>The "&column.id.char;ID" 
    identifier of the column may always be used to refer to it;
    this is a useful fallback if the column name isn't suitable for
    some reason (for instance it contains spaces or is not unique).
    This is just a "&column.id.char;" sign
    followed by a unique integer assigned by the
    program to each column when it is first encountered.
    You can find out the &column.id.char;ID identifier by looking in the
    <ref id="ColumnInfoWindow">Columns Window</ref>.
    </p></dd>

<dt>By &ucd.prefix; specifier</dt>
<dd><p>If the column has a
    <webref url="http://www.ivoa.net/Documents/latest/UCD.html"
            >Unified Content Descriptor</webref>
    (this will usually only be the case for VOTable or possibly FITS format
    tables) you can refer to it using an identifier of the form
    "<code>ucd$&lt;ucd-spec&gt;</code>".  Depending on the version of
    UCD scheme used, UCDs can contain various punctuation marks such
    as underscores, semicolons and dots; for the purpose of this syntax
    these should all be represented as underscores ("<code>_</code>").
    So to identify a column which has the UCD "<code>phot.mag;em.opt.R</code>",
    you should use the identifier "<code>ucd$phot_mag_em_opt_r</code>".
    Matching is not case-sensitive.  Futhermore, a trailing underscore
    acts as a wildcard, so that the above column could also be referenced
    using the identifier "<code>ucd$phot_mag_</code>".  If multiple
    columns have UCDs which match the given identifer, the first one
    will be used.
    </p>
    <p>Note that the same syntax can be used for referencing table
    parameters (see <ref id="jelParams"/>);
    columns take preference so if a column and a parameter both match
    the requested UCD, the column value will be used.
    </p></dd>

<dt>By &utype.prefix; specifier</dt>
<dd><p>If the column has a <label>Utype</label>
    (this will usually only be the case for VOTable or possibly FITS format
    tables) you can refer to it using an identifier of the form
    "<code>&utype.prefix;&lt;utype-spec&gt;</code>".
    Utypes can contain various punctuation marks such as colons and dots;
    for the purpose of this syntax
    these should all be represented as underscores ("<code>_</code>").
    So to identify a column which has the Utype
    "<code>ssa:Access.Format</code>",
    you should use the identifier
    "<code>&utype.prefix;ssa_Access_Format</code>".
    Matching is not case-sensitive.
    If multiple columns have Utypes which match the given identifier,
    the first one will be used.
    </p>
    <p>Note that the same syntax can be used for referencing table
    parameters (see <ref id="jelParams"/>);
    columns take preference so if a column and a parameter both match
    the requested Utype, the column value will be used.
    </p></dd>

</dl>
</p>

<p>There is also a special column:
<dl>
<dt><code>$index</code></dt>
<dd><p>The value of this is the current row number in the unsorted
    table (the first row is 1).
    This is the value seen in the grey numbers at the left of the grid in the 
    <ref id="TableViewerWindow">Data Window</ref>).
    You can alternatively use the form
    <strong><code>&column.id.char;0</code></strong>.
    (The form <strong><code>index</code></strong> is also permitted,
    but deprecated).
    Note that this value is a <code>long</code> (8-byte integer);
    when using it in certain expressions you may find it necessary to convert
    it to an <code>int</code> (4-byte integer) using the
    <code>toInteger()</code> function.
    </p></dd>
</dl>
</p>

<p>The value of the variables so referenced will be a primitive
(boolean, byte, short, char, int, long, float, double) if the
column contains one of the corresponding types.  Otherwise it will
be an Object of the type held by the column, for instance a String.
In practice this means: you can write the name of a column, and it will
evaluate to the numeric (or string) value that that column contains
in each row.  You can then use this in normal algebraic expressions
such as "<code>B_MAG-U_MAG</code>" as you'd expect.
</p>

</subsect>

<subsect>
<subhead><title>Referencing Row Subset Flags</title></subhead>

<p>If you have any <ref id="subsets">Row Subsets</ref> defined
you can also access the value
of the boolean (true/false) flag indicating whether the current row
is in each subset.  Again there are two ways of doing this:
<dl>
<dt>By Name</dt>
<dd><p>The name assigned to the subset when it was created can be used
    if it is unique and if it has a suitable form.  The same comments
    apply as to column names above.
    </p></dd>

<dt>By &subset.id.char;ID</dt>
<dd><p>The "&subset.id.char;ID" identifier of the subset
    may always be used to refer to it.
    Like the "&column.id.char;ID" identifier for columns above,
    this is a unique
    integer preceded by a special symbol, this time the underscore, 
    "&subset.id.char;".
    </p>

    <p><strong>Note:</strong> in early versions of TOPCAT the hash
    sign ("#") was used instead of the underscore for this purpose;
    the hash sign no longer has this meaning.
    </p></dd>
</dl>
In either case, the value will be a boolean value; these can be useful
in conjunction with the conditional "<code>? :</code>" operator or
when combining existing subsets using logical operators to create
a new subset.
</p>
</subsect>

<subsect id="jelParams">
<subhead><title>Referencing Table Parameters</title></subhead>

<p>Some tables have constant values associated with them; these may
represent such things as the epoch at which observations were taken,
the name of the catalogue, an angular resolution associated with
all observations, or any number of other things.
Such constants are known as <em>table parameters</em> and
can be viewed and modified in the 
<ref id="ParameterWindow">Parameter Window</ref>.
The values of such parameters can be referenced in algebraic expressions
as follows:
<dl>
<dt>&param.prefix;<em>name</em></dt>
<dd><p>If the parameter name has a suitable form (starting with a letter
    and continuing with letters or numbers) it can be referenced by
    prefixing that name with the string <code>&param.prefix;</code>.
    </p></dd>

<dt>&ucd.prefix;<em>ucd-spec</em></dt>
<dd><p>If the parameter has a
    <webref url="http://www.ivoa.net/Documents/latest/UCD.html"
            >Unified Content Descriptor</webref>
    it can be referenced by prefixing the UCD specifier with the
    string <code>&ucd.prefix;</code>.  Any punctuation marks in the
    UCD should be replaced by underscores, and a trailing underscore
    is interpreted as a wildcard.  See <ref id="jelCols"/> for 
    more discussion.
    </p></dd>

<dt>&utype.prefix;<em>utype-spec</em></dt>
<dd><p>If the parameter has a Utype,
    it can be referenced by prefixing the Utype specifier with the
    string <code>&utype.prefix;</code>.  Any punctuation marks in the
    Utype should be replaced by underscores.  See <ref id="jelCols"/> for
    more discussion.
    </p></dd>

</dl>
Note that if a parameter has a name in an unsuitable form (e.g. containing
spaces) and has no UCD then it cannot be referenced in an expression.
</p>

<p>There are also a couple of special values:
<dl>
<dt>$ncol</dt>
<dd><p>The number of columns in the table.
    This figure refers to the underlying table, not the apparent table,
    so it is not affected by hiding columns.
    </p></dd>
<dt>$nrow</dt>
<dd><p>The number of rows in the table.
    This figure refers to the underlying table, not the apparent table,
    so it is not affected by the value of the current subset.
    Note that this value is a <code>long</code> (8-byte integer);
    when using it in certain expressions you may find it necessary to convert
    it to an <code>int</code> (4-byte integer) using the
    <code>toInteger()</code> function.
    </p></dd>
</dl>
</p>


</subsect>

<subsect>
<subhead><title>Null Values</title></subhead>

<p>When no special steps are taken, if a null value (blank cell)
is encountered
in evaluating an expression (usually because one of the columns
it relies on has a null value in the row in question) then the
result of the expression is also null.
</p>

<p>It is possible to exercise more control than this, but it
requires a little bit of care,
because the expressions work in terms of primitive values
(numeric or boolean ones) which don't in general have a defined null
value.  The name "null" in expressions gives you the java <code>null</code>
reference, but this cannot be matched against a primitive value
or used as the return value of a primitive expression.
</p>

<p>For most purposes, the following two tips should enable you to
work with null values:

<dl>
<dt>Testing for null</dt>
<dd><p>To test whether a column contains a null value, prepend the
    string "<code>NULL_</code>"
    (use upper case) to the column name or &column.id.char;ID.  This
    will yield a boolean value which is true if the column contains
    a blank or a floating point NaN (not-a-number) value,
    and false otherwise.
    </p></dd>

<dt>Returning null</dt>
<dd><p>To return a null value from a numeric expression, use the name
    "<code>NULL</code>"
    (upper case).  To return a null value from a non-numeric expression
    (e.g. a String column) use the name "<code>null</code>" (lower case).
    </p></dd>
</dl>
</p>

<p>Null values are often used in conjunction with the conditional
operator, "<code>? :</code>"; the expression
<verbatim>
   test ? tval : fval
</verbatim>
returns the value <code>tval</code> if the boolean expression <code>test</code>
evaluates true, or <code>fval</code> if <code>test</code> evaluates false.
So for instance the following expression:
<verbatim>
   Vmag == -99 ? NULL : Vmag
</verbatim>
can be used to define a new column which has the same value as the Vmag
column for most values, but if Vmag has the "magic" value -99 the new
column will contain a blank.
The opposite trick (substituting a blank value with a magic one) can
be done like this:
<verbatim>
   NULL_Vmag ? -99 : Vmag
</verbatim>
Some more examples are given in <ref id="jelExamples"/>.
</p>

</subsect>

<subsect>
<subhead><title>Operators</title></subhead>

<p>The operators are pretty much the same as in the C language.
The common ones are:
<dl>
<dt>Arithmetic</dt>
<dd><p>
  <dl>
  <dt><code>+</code> (add)</dt>
  <dt><code>-</code> (subtract)</dt>
  <dt><code>*</code> (multiply)</dt>
  <dt><code>/</code> (divide)</dt>
  <dt><code>%</code> (modulus)</dt>
  </dl>
</p></dd>

<dt>Logical</dt>
<dd><p>
  <dl>
  <dt><code>!</code> (not)</dt>
  <dt><code>&amp;&amp;</code> (and)</dt>
  <dt><code>||</code> (or)</dt>
  <dt><code>^</code> (exclusive-or)</dt>
  <dt><code>==</code> (numeric identity)</dt>
  <dt><code>!=</code> (numeric non-identity)</dt>
  <dt><code>&lt;</code> (less than)</dt>
  <dt><code>&gt;</code> (greater than)</dt>
  <dt><code>&lt;=</code> (less than or equal)</dt>
  <dt><code>&gt;=</code> (greater than or equal)</dt>
  </dl>
</p></dd>

<dt>Bitwise</dt>
<dd><p>
   <dl>
   <dt><code>&amp;</code> (and)</dt>
   <dt><code>|</code> (or)</dt>
   <dt><code>^</code> (exclusive-or)</dt>
   <dt><code>&lt;&lt;</code> (left shift)</dt>
   <dt><code>&gt;&gt;</code> (right shift)</dt>
   <dt><code>&gt;&gt;&gt;</code> (logical right shift)</dt>
   </dl>
</p></dd>

<dt>Numeric Typecasts</dt>
<dd><p>
  <dl>
  <dt><code>(byte)</code>   (numeric -> signed byte)</dt>
  <dt><code>(short)</code>  (numeric -> 2-byte integer)</dt>
  <dt><code>(int)</code>    (numeric -> 4-byte integer)</dt>
  <dt><code>(long)</code>   (numeric -> 8-byte integer)</dt>
  <dt><code>(float)</code>  (numeric -> 4-byte floating point)</dt>
  <dt><code>(double)</code> (numeric -> 8-byte floating point)</dt>
  </dl>
  Note you may find the numeric conversion functions in the 
  <strong>Maths</strong> class described in <ref id="generalJel"/> below
  more convenient for numeric conversions than these.
</p></dd>

<dt>Other</dt>
<dd><p>
  <dl>
  <dt><code>+</code>  (string concatenation)</dt>
  <dt><code>[]</code> (array dereferencing - first element is zero)</dt>
  <dt><code>?:</code> (conditional switch)</dt>
  <dt><code>instanceof</code> (class membership)</dt>
  </dl>
</p></dd>
</dl>
</p>

</subsect>

<subsect id="staticMethods">
<subhead><title>Functions</title></subhead>

<p>Many functions are available for use within your expressions,
covering standard mathematical and trigonometric functions,
arithmetic utility functions, type conversions, and some more 
specialised astronomical ones.
You can use them in just the way you'd expect,
by using the function name 
(unlike column names, this is case-sensitive) followed by 
comma-separated arguments in brackets, so
<verbatim>
    max(IMAG,JMAG)
</verbatim>
will give you the larger of the values in the columns IMAG and JMAG,
and so on.
</p>

<p>The functions are grouped into the following classes:
 
&general.runtime.class.docs;

</p>

<p>A listing of the functions in these classes is given in 
<ref id="generalJel"/>, and complete documentation on them is
available within TOPCAT from the 
<ref id="MethodWindow">Available Functions Window</ref>.
</p>

<subsubsect>
<subhead><title>Technical Note</title></subhead>

<p>This note provides a bit more detail for Java programmers on what
is going on here; only read on if you want to understand how the use
of functions in TOPCAT algebraic expressions relates to normal Java
code.
</p>

<p>The expressions which you write are compiled to Java bytecode
when you enter them (if there is a 'compilation error' it will be
reported straight away).  The functions listed in the previous subsections
are all the <code>public static</code> methods of the classes which
are made available by default.  The classes listed are all in the
packages <code>uk.ac.starlink.ttools.func</code> and
<code>uk.ac.starlink.topcat.func</code>
(<code>uk.ac.starlink.topcat.func.Strings</code> etc).
However, the public static methods are all imported into an anonymous
namespace for bytecode compilation, so that you write
(<code>sqrt(x)</code> and not <code>Maths.sqrt(x)</code>.
The same happens to other classes that are imported (which can be
in any package or none) - their public
static methods all go into the anonymous namespace.  Thus, method
name clashes are a possibility.
</p>

<p>This cleverness is all made possible by the rather wonderful
<webref url="http://www.gnu.org/software/jel/" plaintextref="yes">JEL</webref>.
</p>

</subsubsect>

</subsect>

<subsect>
<subhead><title>Instance Methods</title></subhead>

<p>There is another category of functions which can be used apart from
those listed in the <ref id="staticMethods">previous section</ref>.
These are called, in Java/object-oriented parlance, "instance methods"
and represent functions that can be executed on an object.
</p>

<p>It is possible to invoke any of its public 
instance methods on any object 
(though not on primitive values - numeric and boolean ones).
The syntax is that you place a "." followed by the method invocation
after the object you want to invoke the method on, 
hence <code>NAME.substring(3)</code> instead of <code>substring(NAME,3)</code>.
If you know what you're doing, feel free to go ahead and do this.
However, most of the instance methods you're likely to want to use 
have equivalents in the normal functions listed in the previous section,
so unless you're a Java programmer or feeling adventurous, you are
probably best off ignoring this feature.
</p>

</subsect>

<subsect id="jelExamples">
<subhead><title>Examples</title></subhead>

<p>Here are some general examples.
They could be used to define synthetic columns or (where numeric) to 
define values for one of the axes in a plot.
<dl>

<dt>Average</dt>
<dd><p><verbatim>
    (first + second) * 0.5
</verbatim></p></dd>

<dt>Square root</dt>
<dd><p><verbatim>
    sqrt(variance)
</verbatim></p></dd>

<dt>Angle conversion</dt>
<dd><p><verbatim>
    radiansToDegrees(DEC_radians)
    degreesToRadians(RA_degrees)
</verbatim></p></dd>

<dt>Conversion from string to number</dt>
<dd><p><verbatim>
    parseInt(&column.id.char;12)
    parseDouble(ident)
</verbatim></p></dd>

<dt>Conversion from number to string</dt>
<dd><p><verbatim>
    toString(index)
</verbatim></p></dd>

<dt>Conversion between numeric types</dt>
<dd><p><verbatim>
     toShort(obs_type)
     toDouble(range)
</verbatim><em>or</em><verbatim>
    (short) obs_type
    (double) range
</verbatim></p></dd>

<dt>Conversion from sexagesimal to degrees</dt>
<dd><p><verbatim>
    hmsToDegrees(RA1950)
    dmsToDegrees(decDeg,decMin,decSec)
</verbatim></p></dd>

<dt>Conversion from degrees to sexagesimal</dt>
<dd><p><verbatim>
    degreesToDms(&column.id.char;3)
    degreesToHms(RA,2)
</verbatim></p></dd>

<dt>Outlier clipping</dt>
<dd><p><verbatim>
    min(1000, max(value, 0))
</verbatim></p></dd>

<dt>Converting a magic value to null</dt>
<dd><p><verbatim>
    jmag == 9999 ? NULL : jmag
</verbatim></p></dd>

<dt>Converting a null value to a magic one</dt>
<dd><p><verbatim>
    NULL_jmag ? 9999 : jmag
</verbatim></p></dd>

<dt>Taking the third scalar element from an array-valued column</dt>
<dd><p><verbatim>
    psfCounts[2]
</verbatim></p></dd>

</dl>

and here are some examples of boolean expressions that could be used
to define <ref id="subsets">row subsets</ref>
(or to create boolean synthetic columns):

<dl>
<dt>Within a numeric range</dt>
<dd><p><verbatim>
    <![CDATA[RA > 100 && RA < 120 && Dec > 75 && Dec < 85]]>
</verbatim></p></dd>

<dt>Within a circle</dt>
<dd><p><verbatim>
    &column.id.char;2*&column.id.char;2 + &column.id.char;3*&column.id.char;3 &lt; 1
    skyDistanceDegrees(ra0,dec0,hmsToDegrees(RA),dmsToDegrees(DEC))&lt;15./3600.
</verbatim></p></dd>

<dt>First 100 rows</dt>
<dd><p><verbatim>
    index &lt;= 100
</verbatim></p></dd>

<dt>Every tenth row</dt>
<dd><p><verbatim>
    index % 10 == 0
</verbatim></p></dd>

<dt>String equality/matching</dt>
<dd><p><verbatim>
    equals(SECTOR, "ZZ9 Plural Z Alpha")
    equalsIgnoreCase(SECTOR, "zz9 plural z alpha")
    startsWith(SECTOR, "ZZ")
    contains(ph_qual, "U")
</verbatim></p></dd>

<dt>String regular expression matching</dt>
<dd><p><verbatim>
    matches(SECTOR, "[XYZ] Alpha")
</verbatim></p></dd>

<dt>Combining subsets</dt>
<dd><p><verbatim>
    (&subset.id.char;1 &amp;&amp; &subset.id.char;2) &amp;&amp; ! &subset.id.char;3
</verbatim></p></dd>

<dt>Test for non-blank value</dt>
<dd><p><verbatim>
    ! NULL_ellipticity
</verbatim></p></dd>
</dl>
</p>

</subsect>

<subsect id="jelExtend">
<subhead><title>Adding User-Defined Functions</title></subhead>

<p>The functions provided by default for use with algebraic expressions,
while powerful, may not provide all the operations you need.
For this reason, it is possible to write your own extensions to the
expression language.  In this way you can specify arbitrarily complicated
functions.
Note however that this will only allow you to define new columns or subsets
where each cell is a function only of the other cells in the same row - 
there is no way to define a value in one row as a function of
values in other rows.
</p>

<p>In order to do this, you have to write and compile a 
(probably short) program
in the Java language.  A full discussion of how to go about this
is beyond the scope of this document, so if you are new 
to Java and/or programming you may need to find a friendly local 
programmer to assist (or mail the author).
The following explanation is aimed at Java programmers, but may not
be incomprehensible to non-specialists.
</p>

<p>The steps you need to follow are:
<ol>
<li>Write and compile a class containing one or more static public 
    methods representing the function(s) required</li>
<li>Make this class available on the application's classpath at runtime
    as described in <ref id="jvmClasspath"/></li>
<li>Specify the class's name to the application,
    <em>either</em> as the value of the
    <code>jel.classes</code> or <code>jel.classes.activation</code> 
    system properties (colon-separated if there are several) 
    as described in <ref id="jvmProperties"/>
    <em>or</em> during a run using the 
    <ref id="MethodWindow">Available Function Window</ref>'s
    <label>Add Class</label> (&IMG.ADD;) button</li>
</ol>
</p>

<p>Any public static methods defined in the classes thus specified
will be available for use in the 
<ref id="SyntheticColumnQueryWindow">Synthetic Column</ref>, 
<ref id="SyntheticSubsetQueryWindow">Algebraic Subset</ref> or
(in the case of activation functions only)
<ref id="ActivationQueryWindow">Activation Window</ref> windows.
They should be defined to take and return the relevant primitive or
Object types for the function required
(in the case of activation functions the return value should normally
be a short log string).
</p>

<p>For example, a class written as follows would define a three-value average:
<verbatim>
    public class AuxFuncs {
        public static double average3( double x, double y, double z ) {
            return ( x + y + z ) / 3.0;
        }
    }
</verbatim>
and the expression 
"<code>average3(&column.id.char;1,&column.id.char;2,&column.id.char;3)</code>"
could then be used to define a new synthetic column, giving the average of
the first three existing columns.
Exactly how you would build this is dependent on your system, 
but it might involve doing something like the following:
<ol>
<li>Writing a file named "AuxFuncs.java" containing the above code</li>
<li>Compiling it using a command like "<code>javac AuxFuncs.java</code>"</li>
<li>Starting up TOPCAT with the flags: 
    "<code>topcat -Djel.classes=AuxFuncs -classpath .</code>"</li>
</ol>
</p>

</subsect>

</sect>

<sect id="activation">
<subhead><title>Activation Actions</title></subhead>

<p>As well as seeing the overview of table data provided by a plot
or statistics summary, it is often necessary to focus on a particular row
of the table, which according to the nature of the table may represent
an astronomical object, an event or some other entity.  
In the <ref id="TableViewerWindow">Data Window</ref> a table row is
simply a row of the displayed JTable, and in a plot it corresponds to
one plotted point.
</p>

<p>If you click on plotted point in one of the graphics windows,
or on a row in the 
Data Window, the corresponding table row will be <em>activated</em>.
When a row is activated, three things happen:
<ol>
<li>If that row is represented by a point in any open 2- or 3-dimensional
    scatter plot windows, a visible cursor marker will be drawn
    centred on that point.</li>
<li>If the Data Window is visible, the table will be scrolled to show the
    row and it will be highlighted</li>
<li>If an <em>activation action</em> has been defined, it will be invoked</li>
</ol>
The first two of these mean that you can easily see which point in a
plot corresponds to which row in the table and vice versa - just click
on one and the other will be highlighted.
</p>

<p>The third one can be more complicated.  By default, no activation
action is set, so nothing else happens, and this may very well be
what you want.  
However, by clicking on the <label>Activation Action</label> selector in the 
<ref id="ControlWindow">Control Window</ref> 
you can bring up the <ref id="ActivationQueryWindow">Activation Window</ref>
which enables you to choose an additional action to take place.
There are various options here and various ways to achieve them
(see <ref id="ActivationQueryWindow"/> for more details)
but the kinds of actions which are envisaged are to display one or
more images or spectra relating to the row you have identified.
One of the options available for instance retrieves a postage-stamp image
of a few arcminutes around the sky position defined by the row
from a SuperCOSMOS all-sky image survey and pops it up in a viewer
window.  So for instance having spotted an interesting point in a 
plot of a galaxy catalogue you can click on it, and immediately see 
a picture to identify its morphological type.
</p>

<p>The exact actions you want to perform may be closely tailored to the 
data you have, for instance you may have a set of spectra on disk
named by object ID.  It's impossible to cater for such possibilities
with a set of pre-packaged options, so you are able to define your own 
custom actions here.  This is done by writing a expression
using the syntax described in <ref id="jel"/>.
A number of special functions 
(described in the <ref id="activationJel">following subsection</ref>)
are provided to do things like display an image or a spectrum in a browser
(given its filename or URL), or access data from certain data servers 
on the web, but there is nothing to stop the adventurous plugging in their
own external programs so in principle you can configure pretty much 
anything to happen on the basis of the values in the row that you
have activated.
</p>

<subsect>
<subhead><title>Activation Functions</title></subhead>

<p>When defining custom activation actions in the
<ref id="ActivationQueryWindow">Activation Window</ref>,
you enter an expression to be invoked on a row when it is activated.
This expression uses the syntax defined in <ref id="jel"/> and
can make use of the functions listed in <ref id="generalJel"/>.
However in this case there is an additional list of functions you can use 
which cause something to happen (for instance displaying an image) rather
than just returning a value.  The following classes of functions
are available:

&activation.runtime.class.docs;

</p>

<p>A listing of the functions in these classes is given in
<ref id="activationJel"/>, and complete documentation on them is
available within TOPCAT from the
<ref id="MethodWindow">Available Functions Window</ref>.
</p>

</subsect>

</sect>

<sect id="interop">
<subhead><title>Tool Interoperability</title></subhead>

<p>TOPCAT is able to communicate with other tools using one or other of two
messaging protocols:
<ul>
<li><webref url="http://www.ivoa.net/samp/">SAMP</webref>
    (Simple Applications Messaging Protocol)</li>
<li><webref url="http://plastic.sourceforge.net/">PLASTIC</webref>
    (PLatform for AStronomical InterConnection</li>
</ul>
An example of the kind of thing which can be done might be:
<ol>
<li>TOPCAT sends a catalogue to an image display tool</li>
<li>The image display tool shows the catalogue entries as markers
    placed appropriately on a displayed image</li>
<li>User actions which highlight one of the points in one tool can then
    automatically highlight the same point in the other</li>
</ol>
Examples of the kind of tool which TOPCAT can interoperate with in this
way are 
image analysis tools
(<webref url="http://aladin.u-strasbg.fr/">Aladin</webref>,
 <webref url="http://www.starlink.ac.uk/gaia/">GAIA</webref>,
 <webref url="http://hea-www.harvard.edu/RD/ds9/">ds9</webref>)
table analysis tools
(<webref url="http://visivo.cineca.it/">VisIVO</webref>,
 <webref url="http://www.starlink.ac.uk/stilts/">STILTS</webref>,
 other instances of TOPCAT itself),
spectrum analysis tools
(<webref url="http://www.starlink.ac.uk/splat/">SPLAT</webref>,
 <webref url="http://esavo.esa.int/vospec/">VOSpec</webref>),
sky visualisation tools
(<webref url="http://www.worldwidetelescope.org/">World Wide Telescope</webref>,
 <webref url="http://archive.eso.org/cms/virgo/">VirGO</webref>),
scripting languages
(<webref url="http://pypi.python.org/pypi/sampy/">SAMPy</webref>),
and others.
</p>

<p>SAMP and PLASTIC do much the same job as each other, and work in much
the same way.  SAMP is an evolution of PLASTIC with a number of
technical improvements, and so PLASTIC is now deprecated in favour
of SAMP.
It is not necessary for users to understand the differences between the two, 
but in general a tool using SAMP can communicate with other tools using SAMP,
and the same with PLASTIC, but in most cases interoperation between
PLASTIC and SAMP tools will not work.
</p>

<p>The communication architecture of the two protocols is basically the same:
all tools communicate with a central "Hub" process,
so a hub must be running in order for the messaging to operate.
If a hub is running when TOPCAT starts,
or if one starts up while TOPCAT is in operation,
it will connect to it automatically.
A hub can be started from within TOPCAT if required - details of how to
do this are given in the <ref id="sampControl">SAMP</ref> and 
<ref id="plasticControl">PLASTIC</ref> sections below.
Other tools will have their own policies for connecting to the hub,
but in general it is a good idea to start a hub first
before starting up the tools which you want to talk to it.
</p>

<p>TOPCAT can work in either SAMP or PLASTIC mode, but not both at once.
It determines which mode to use at startup:
if the <code>-samp</code> or <code>-plastic</code> flag is supplied
on the command line the corresponding mode will be used;
otherwise if a running SAMP or PLASTIC hub can be found,
the corresponding mode is used, otherwise it defaults to SAMP.
It is easy to tell which mode is being used by looking at the 
<ref id="ControlWindow">Control Window</ref>;
in SAMP mode the <ref id="sampPanel">SAMP panel</ref> displaying connection
and message status is visible at the bottom of the right hand panel
(there are a few other changes to the GUI as well).
Facilities for communications monitoring are considerably better in
SAMP than in PLASTIC mode.
</p>

<p>This communication has two aspects to it: on the one hand
TOPCAT can send messages to other applications which causes them
to do things, and on the other hand TOPCAT can receive and act on
such messages sent by other applications.
The 
<ref id="interopSend">sent</ref> and 
<ref id="interopReceive">received</ref> 
messages are described separately in the subsections below.
There are also sections on the, somewhat different, 
ways to control and monitor messaging operatiion
for the cases of SAMP and PLASTIC.
</p>

<subsect id="sampControl">
<subhead><title>SAMP control</title></subhead>

<p>When running in SAMP mode, the <ref id="ControlWindow">Control Window</ref>
features several ways to view and control SAMP status.
<dl>

<dt>SAMP Status button (&IMG.SAMP;)</dt>
<dd><p>Pops up the <ref id="SampWindow">SAMP Window</ref> which shows a 
    detailed view of the status of SAMP communications,
    and allows you to register or unregister with the hub,
    and to start a hub if required.
    </p></dd>

<dt>SAMP Status panel</dt>
<dd><p>The bottom part of the right hand panel has an 
    area labelled <label>SAMP</label>.
    This gives a summary view of registration status,
    other connected applications, and messages recently sent and received.
    It is described in more detail in <ref id="sampPanel"/>.
    </p></dd>

<dt>Table Broadcast (&IMG.BROADCAST;) and Table Send (&IMG.SEND;)
    menu options</dt>
<dd><p>The <label>Interop</label> menu provides these options which allow
    you to send the currently selected table to one or all connected clients.
    Note they will only be enabled if the hub is running, and there is at 
    least one connected client which knows how to receive a table.
    The <label>Broadcast</label> option is also available on the toolbar.
    </p></dd>

<dt>Stop Internal Hub (&IMG.NO_HUB;) menu option</dt>
<dd><p>By default, when TOPCAT starts up, it will look for a SAMP hub,
    and if none appears to be running it will start one internally,
    which will normally run until TOPCAT exits.
    This is usually not problematic, but if you would prefer to run a
    hub external to TOPCAT, then you may need to shut down TOPCAT's before 
    starting a new one.  Using this option shuts down TOPCAT's internal hub.
    </p></dd>

</dl>
</p>

<p>A number of other windows feature an <label>Interop</label> menu with
<label>Broadcast</label> (&IMG.BROADCAST;) and
<label>Send</label> (&IMG.SEND;)
operations for data types appropriate to that window.
Sometimes Broadcast appears in the toolbar as well.
In some cases there are also <label>Accept</label> (&IMG.LISTEN;)
toggle options in the Interop menu.
These control whether TOPCAT will respond to appropriate messages sent
by other SAMP applications.
</p>

</subsect>


<subsect id="plasticControl">
<subhead><title>PLASTIC control</title></subhead>

<p>You can view and control operations relating to the PLASTIC hub
from the <label>Interop</label> menu in the 
<ref id="ControlWindow">Control Window</ref>.
It contains the following options:
<dl>
<dt>Register with PLASTIC</dt>
<dd><p>Attempts to locate a running PLASTIC hub and register with it.
    </p></dd>

<dt>Unregister with PLASTIC</dt>
<dd><p>If currently registered with a PLASTIC hub, unregisters with it.
    </p></dd>

<dt>Show registered applications</dt>
<dd><p>Pops up a small window which displays what applications are currently
    registered with any PLASTIC hub with which TOPCAT is registered.
    This will be kept up to date as applications register and unregister.
    </p></dd>

<dt>Start internal PLASTIC hub</dt>
<dd><p>Starts a PLASTIC hub as part of the process within which TOPCAT is
    running.  This will only work if a hub is not already running.
    The hub will terminate when TOPCAT exits.
    </p></dd>

<dt>Start external PLASTIC hub</dt>
<dd><p>Starts a PLASTIC hub as a separate process.  This will only work if
    a hub is not already running.
    The hub will continue running until it is explicitly terminated
    (e.g. using a <code>kill</code> command).
    Because this has some system-dependent features, it's not guaranteed to
    work, especially in non-Unix environments.
    </p></dd>

<dt>&IMG.HELP; Help on interoperability</dt>
<dd><p>Opens an appropriate help section in the help browser.
    </p></dd>

<dt>&IMG.BROADCAST; Broadcast Table</dt>
<dd><p>Broadcasts the currently selected table to all listening applications
    using PLASTIC.</p></dd>

<dt>&IMG.SEND; Send Table to ...</dt>
<dd><p>Sends the currently selected table to a selected listening application
    using PLASTIC.  Select the desired recipient application from the
    submenu.</p></dd>

</dl>
</p>

</subsect>

<subsect id="interopSend">
<subhead><title>Messages Transmitted</title></subhead>

<p>This section describes the messages which TOPCAT can transmit to other 
tools which understand the SAMP or PLASTIC protocol, and how to cause them
to be sent.  Approximately the same behaviour results for either
SAMP or PLASTIC, except as noted.
</p>

<p>In most cases you can choose two ways to transmit a message
from TOPCAT:
<dl>
<dt>&IMG.BROADCAST; Broadcast</dt>
<dd><p>Broadcasts the message to all other applications currently registered
    with the hub which understand that message.
    </p></dd>
<dt>&IMG.SEND; Send</dt>
<dd><p>Sends the message to a single application which you select.
    The suitable applications (ones which are registered with the hub 
    and claim to understand that message) are listed and you can choose one.
    </p></dd>
</dl>
Examining the list of applications in the <label>Send</label> 
menu gives you an indication of which ones a <label>Broadcast</label> 
would broadcast to.  
Note however that just because an application appears in this 
list doesn't necessarily mean it will do
something substantial with the message, for instance some applications
register with the hub just to monitor traffic.
In general the <label>Broadcast</label> and <label>Send</label> 
actions will be disabled (greyed-out) if TOPCAT is
not registered with a hub, or if there are no applications listening
which claim to support the relevant message.
</p>

<p>Below is a list of places you can cause TOPCAT to transmit messages.
The SAMP <em>MTypes</em> and PLASTIC <em>message IDs</em> 
are listed along with the descriptions;
unless you are a tool developer you can probably ignore these.

<dl>
<dt>Transmit Table</dt>
<dd><p>The <ref id="ControlWindow">Control Window</ref>'s 
    <label>Interop</label> menu provides
    <label>Broadcast Table</label> and <label>Send Table</label>
    options which cause the currently selected table to be transmitted
    to other listening applications.  
    They are invited to load the table in its current 
    ("<ref id="apparent">apparent</ref>") form.
    The <label>Broadcast</label> action is also available in the toolbar.
    </p>
    <p>SAMP MTypes:
          <code>table.load.votable</code> or
          <code>table.load.fits</code>
    </p>
    <p>PLASTIC Message IDs:
          <code>ivo://votech.org/votable/load</code> or
          <code>ivo://votech.org/votable/loadFromURL</code>
    </p></dd>

<dt>Transmit Subset</dt>
<dd><p>The <ref id="SubsetWindow" plaintextref="yes">Subset Window</ref>'s
    <label>Interop</label> menu
    contains <label>Broadcast Subset</label> and <label>Send Subset</label>
    options.
    These cause the selected subset to be sent to other listening applications
    (these actions are only available when one of the subsets is currently
    selected).
    Applications are invited to highlight the rows corresponding to that subset.
    Note this will only have an effect if the other application(s) are
    displaying the table that this subset relates to.  This will be
    the case in one of two situations:
    (1) the table has been loaded from the same URL/filename by the 
    other tool(s) or
    (2) the other tool(s) have acquired the table because it has 
    already been broadcast using SAMP/PLASTIC.
    </p>
    <p>Also, whenever a new subset is created, for instance by entering an
    algebraic expression or tracing out a region on a plot
    (see <ref id="subsetDef"/>),
    you have the option of transmitting the subset directly to one or all 
    listening applications as an alternative to adding the new subset to
    the table's subset list.
    </p>
    <p>SAMP MType: <code>table.select.rowList</code>
    </p>
    <p>PLASTIC Message ID: <code>ivo://votech.org/votable/showObjects</code>
    </p></dd>

<dt>Transmit Row</dt>
<dd><p>The <ref id="ControlWindow">ControlWindow</ref> has a
    <label>Broadcast Row</label> checkbox by the 
    <label>Activation Action</label> selector.
    If this is selected, then any time you activate a row
    (e.g. by clicking on the corresponding point in a plot)
    other applications who are looking at the same table are invited
    to highlight that row in their copy of the table.
    As for <label>Transmit Subset</label> above, this will only have an
    effect if the other application(s) are displaying the same table.
    </p>
    <p>A similar facility is available as the <label>Transmit Row</label>
    option in the 
    <ref id="activation" plaintextref="yes">Activation Actions</ref>
    window itself - the checkbox is just a convenience for a commonly-used
    option.
    </p>
    <p>SAMP MType: <code>table.highlight.row</code>
    </p>
    <p>PLASTIC Message ID: <code>ivo://votech.org/votable/highlightObject</code>
    </p></dd>

<dt>Transmit Coordinates</dt>
<dd><p>Another 
    <ref id="activation" plaintextref="yes">Activation Action</ref>
    is <label>Transmit Coordinates</label>.
    In this case when you activate a row (e.g. by clicking on the 
    corresponding point in a plot) 
    other applications are invited to point out the
    sky position corresponding to the row which is activated,
    for instance by placing a cursor over it.
    The table columns which correspond to Right Ascension and Declination
    must be selected for this to work.
    </p>
    <p>SAMP MType: <code>coord.pointAt.sky</code>
    </p>
    <p>PLASTIC Message ID: <code>ivo://votech.org/sky/pointAtCoords</code>
    </p></dd>

<dt>Transmit Image</dt>
<dd><p>The <ref id="DensityWindow" plaintextref="yes">Density Plot</ref> 
    produces a 2-d histogram which is actually an image.
    Its <label>Interop</label> menu provides
    <label>Broadcast Image</label> and <label>Send Image</label> options
    which will send this (as a FITS image) to other applications 
    which can display it in some way.
    This is a useful supplement to the facilities of the Density Plot
    window, since it doesn't have very sophisticated image display
    features (variable colour maps, contour plots etc).
    </p>
    <p>Also, the <label>View URL as Image</label>
    <ref id="activation">Activation Action</ref>
    option allows you to identify a column which contains an image URL
    and to send it to a suitable image viewer or viewers.
    </p>
    <p>SAMP MType: <code>image.load.fits</code>
    </p>
    <p>PLASTIC Message ID: <code>ivo://votech.org/fits/image/loadFromURL</code>
    </p></dd>

<dt>Transmit Spectrum</dt>
<dd><p>The <label>View URL as Spectrum</label>
    <ref id="activation">Activation Action</ref>
    option allows you to identify a column which contains a spectrum URL
    and to send it to a suitable spectrum viewer or viewers.
    </p>
    <p>SAMP MType: <code>spectrum.load.ssa-generic</code>
    </p>
    <p>PLASTIC Message ID: <code>ivo://votech.org/spectrum/loadFromURL</code>
    </p></dd>

<dt>Transmit Resource List</dt>
<dd><p>The <ref id="RegistryPanel">Registry Query Panel</ref>
    present in most of the Virtual Observatory windows allows
    you to send lists of VO registry resource identifiers to other
    applications which can make use of them.
    Note this only works in SAMP mode, not for PLASTIC.
    </p>
    <p>SAMP MTypes: <code>voresource.loadlist.cone</code>,
                    <code>voresource.loadlist.siap</code>,
                    <code>voresource.loadlist.ssap</code>
    </p></dd>
</dl>
</p>

</subsect>

<subsect id="interopReceive">
<subhead><title>Messages Received</title></subhead>

<p>This section describes the messages which TOPCAT will respond to 
when it receives them from other applications via the SAMP/PLASTIC hub.
The SAMP MTypes and PLASTIC message IDs are listed along with the descriptions;
unless you are a tool developer you can probably ignore these.

<dl>
<dt>Load Table</dt>
<dd><p>Loads a table sent by another application.
    It is added to the list of tables in the
    <ref id="ControlWindow">Control Window</ref>.
    </p>
    <p>SAMP MType:
       <code>table.load.votable</code>,
       <code>table.load.fits</code>,
       <code>table.load.cdf</code> or
       <code>table.load.stil</code>
    </p>
    <p>PLASTIC Message ID:
       <code>ivo://votech.org/votable/load</code> or
       <code>ivo://votech.org/votable/loadFromURL</code>
    </p>
    <p>Note the non-standard MType <code>table.load.stil</code> is
    supported for loading tables with SAMP.  This is like the other
    <code>table.load.*</code> MTypes, but any table format supported
    by the application is permitted.  This MType has an additional
    parameter "<code>format</code>", which must contain the table format
    name (not case sensitive).
    </p></dd>

<dt>New Subset</dt>
<dd><p>Loads a row selection sent from another application.
    If an external application is looking at the same table as one that
    TOPCAT has loaded, it can send a row selection.
    In this case, TOPCAT will add that selection as a new 
    <ref id="subsets">Row Subset</ref> for the table.
    The name of the received subset will be that of the sending application,
    for instance "Aladin". 
    If a subset of that name already exists (which is probably because 
    the same application has sent a row selection previously) 
    then its content will be overwritten by the new selection.
    In either case, receiving the message causes plots displaying 
    data from the table in question to show the points from the 
    new subset.
    </p>
    <p>Note: this behaviour differs from the behaviour in TOPCAT versions
    prior to v3.0.
    Different options for handling exactly how a received row selection is
    treated may be made available in future versions.
    </p>
    <p>SAMP MType: <code>table.select.rowList</code>
    </p>
    <p>PLASTIC Message ID: <code>ivo://votech.org/votable/showObjects</code>
    </p></dd>

<dt>Highlight Row</dt>
<dd><p>If TOPCAT already has loaded the table identified by the request,
    it will <ref id="activation" plaintextref="yes">activate</ref>
    the requested row.  This will result in the row being marked in any
    currently visible plots and in the 
    <ref id="TableViewerWindow">Data Window</ref> if it is visible, 
    as well as performing any additional actions you have configured
    in the <ref id="ActivationQueryWindow">Activation Window</ref>.
    </p>
    <p>SAMP MType: <code>table.highlight.row</code>
    </p>
    <p>PLASTIC Message ID: <code>ivo://votech.org/votable/highlightObject</code>
    </p></dd>

<dt>Load Resource Identifiers</dt>
<dd><p>Receives a list of VO registry resource identifiers from another
    application.
    Several of TOPCAT's
    <ref id="vo-windows">Virtual Observatory access windows</ref>
    display a list of resources in their
    <ref id="RegistryPanel">Registry Query Panel</ref>.
    Normally, the displayed resources are a default set or are those
    you have selected by entering keywords.
    However, another application can send a list of resources, and if they
    are of an appropriate type for the window in question, and if the window
    is currently visible, its currently displayed list will
    be replaced with the ones which have been sent.
    </p>
    <p>SAMP MTypes: <code>voresource.loadlist</code>,
                    <code>voresource.loadlist.cone</code>,
                    <code>voresource.loadlist.siap</code>,
                    <code>voresource.loadlist.ssap</code>
    </p></dd>

<dt>Get Table</dt>
<dd><p>Allows clients to retrieve tables currently loaded into TOPCAT.
    This MType has a mandatory parameter <code>format</code>
    giving the (case-insensitive) table format name required for
    the output table.
    It also takes an optional integer-like parameter <code>id</code>,
    giving the ID number (as shown in the Control Window table list)
    of the table required.  If <code>id</code> is missing or non-positive,
    the current table is used.
    The returned response has an output parameter <code>url</code>
    giving the URL of the <ref id="apparent">apparent</ref> table in question.
    This MType is experimental and may be modified or withdrawn in
    the future.
    </p>
    <p>SAMP MType: <code>table.get.stil</code>.
    </p></dd>
</dl>
</p>

<p>System-level messages are also responded to.
For SAMP these are:
<ul>
<li><code>samp.hub.disconnect</code></li>
<li><code>samp.hub.event.shutdown</code></li>
<li><code>samp.hub.event.register</code></li>
<li><code>samp.hub.event.unregister</code></li>
<li><code>samp.hub.event.metadata</code></li>
<li><code>samp.hub.event.subscriptions</code></li>
<li><code>samp.app.ping</code></li>
</ul>
and for PLASTIC:
<ul>
<li><code>ivo://votech.org/test/echo</code></li>
<li><code>ivo://votech.org/info/getName</code></li>
<li><code>ivo://votech.org/info/getIconURL</code></li>
<li><code>ivo://votech.org/hub/event/ApplicationRegistered</code></li>
<li><code>ivo://votech.org/hub/event/ApplicationUnregistered</code></li>
<li><code>ivo://votech.org/hub/event/HubStopping</code></li>
</ul>
</p>

</subsect>

</sect>

<sect id="invoke">
<subhead><title>Invoking TOPCAT</title></subhead>

<p>Starting up TOPCAT may just be a case of typing "<code>topcat</code>" or
clicking on an appropriate icon and watching the
<ref id="ControlWindow">Control Window</ref> pop up.
If that is the case, and it's running happily for you, 
you can probably ignore this section.
What follows is a description of how to start the program up, 
and various command line arguments and configuration options which can't be 
changed from within the program.
Some examples are given in <ref id="invokeExamples"/>.
Actually obtaining the program is not covered here; please see
the TOPCAT web page 
<webref url="http://www.starlink.ac.uk/topcat/"/>.
</p>

<p>There are various ways of starting up TOPCAT depending on how (and whether)
it has been installed on your system; some of these are described below.
</p>

<p>There may be some sort of short-cut icon on your desktop which
starts up the program - in this case just clicking on it will probably work.
Failing that you may be able to locate the
jar file (probably named <code>topcat.jar</code>, 
<code>topcat-full.jar</code> or <code>topcat-lite.jar</code>)
and click on that.  These files would be located in the
<code>java/lib/topcat/</code> directory in a standard Starjava installation.
Note that when you start by clicking on something
you may not have the option of entering
any of the command line options described below -
to use these options, which you may need to do for serious use of 
the program, you will have to run the program from the command line.
</p>

<p>Alternatively you will have to invoke the program from the command line.
On Unix-like operating systems, you can use the <code>topcat</code> script.
If you have the full starjava installation, this is probably in 
the <em>starjava</em>/java/bin directory.  If you have one of the
standalone jar files (topcat-full.jar or topcat-lite.jar), it should
be in the same directory as it/them.  If it's not there,
you can unpack it from the jar file itself, using a command like
<code>unzip topcat-lite.jar topcat</code>.
If that directory (and java) is on your path then you can write:
<verbatim>
   topcat [java-args] [topcat-args]
</verbatim>
In this case any arguments which start <code>-D</code> or <code>-X</code>
are assumed to be arguments to the java command,
any arguments which start <code>-J</code> are stripped of the <code>-J</code>
and then passed as arguments to the java command,
a <code>-classpath</code> <var>path</var> defines a class path to
be used in addition to the TOPCAT classes,
and any remaining arguments are used by TOPCAT.
</p>

<p>If you're not running Unix then to start from the
command line you will have to use the <code>java</code> command itself.
The most straightforward way of doing this will look like:
<verbatim>
   java [java-args] -jar path/to/topcat.jar [topcat-args]
</verbatim>
(or the same for <code>topcat-full.jar</code> etc).
However <strong>NOTE</strong>: using java's <code>-jar</code> flag ignores
any other class path information, such as the CLASSPATH environment
variable or java's <code>-classpath</code> flag - see <ref id="jvmClasspath"/>.
</p>

<p>Note that Java
<webref url="http://java.sun.com/products/javawebstart/">Web Start</webref>
can also be used to invoke the program
without requiring any prior download/installation - sorry, this isn't
documented properly here yet.
</p>

<p>The meaning of the optional 
<code>[topcat-args]</code> 
and 
<code>[java-args]</code>
sequences are described in 
<ref id="topcatArgs"/> and 
<ref id="jvmOpt"/> below respectively.
</p>

<subsect id="topcatArgs">
<subhead><title>TOPCAT Command-line Arguments</title></subhead>

<p>You can start TOPCAT from the command line with no arguments -
in this case it will just pop up the command window from which you
can load in tables.  However you may specify flags and/or table locations
and formats.
</p>

<p>If you invoke the program with the "<code>-help</code>" flag you
will see the following usage message:
<verbatim>&topcat.usage;</verbatim>
The meaning of the flags is as follows:
<dl>

<dt>-f &lt;format&gt;</dt>
<dd><p>Signifies that the file(s) named after it on the command line
    are in a particular file format.
    Some file formats (VOTable, FITS) can be detected automatically by
    TOPCAT, but others (including Comma-Separated Values) cannot -
    see <ref id="inFormats"/>.  In this case you have to specify with 
    the <code>-f</code> flag what format the named files are in.
    Any table file on the command line following a 
    <code>-f &lt;format&gt;</code>
    sequence must be in the named format until the next <code>-f</code> flag.
    The names of both the auto-detected formats (ones which don't need
    a <code>-f</code>) and the non-auto-detected formats (ones which do)
    are given in the usage message you can see by giving the 
    <code>-help</code> flag (this message is shown above).
    You may also use the classname of a class on the classpath which
    implements the <code>TableBuilder</code> interface - 
    see <docxref doc="sun252"/>.
    </p></dd>

<dt>-help</dt>
<dd><p>If the <code>-help</code> (or <code>-h</code>) 
    flag is given, TOPCAT will write a usage
    message and exit straight away.
    </p></dd>

<dt>-version</dt>
<dd><p>If the <code>-version</code> flag is given, TOPCAT will print
    a summary of its version and the versions and availability of some 
    its components, and exit straight away.
    </p></dd>

<dt>-verbose</dt>
<dd><p>The <code>-verbose</code> (or <code>-v</code>) flag increases 
    the level of verbosity of messages which TOPCAT writes to standard
    output (the console).
    It may be repeated to increase the verbosity further.
    The messages it controls are currently those written through
    java's standard logging system - see the description of the 
    <ref id="LogWindow" plaintextref="yes">Log Window</ref> for more
    information about this.
    </p></dd>

<dt>-debug</dt>
<dd><p>The <code>-debug</code> flag affects how logging messages appear
    (whether they appear is affected by the <code>-verbose</code> flag).
    If present, these messages will provide more detail about where
    each message was generated from.
    </p></dd>

<dt>-demo</dt>
<dd><p>The <code>-demo</code> flag causes the program to start up with
    a few demonstration tables loaded in.  You can use these to play
    around with its facilities.  Note these demo tables are quite small
    to avoid taking up a lot of space in the installation, and don't 
    contain particularly sensible data, they are just to give an idea.
    </p></dd>

<dt>-running</dt>
<dd><p>The <code>-running</code> flag can be used when specifying tables
    on the command line.  If an existing instance of TOPCAT is already
    running, the tables are loaded into it.  If no instance of TOPCAT
    is running (or at least one cannot be discovered), then the
    <code>-running</code> flag has no effect and a new instance is
    started up as usual.
    </p></dd>

<dt>-memory</dt>
<dd><p>If the <code>-memory</code> flag is given then the program will
    store table data in memory,
    rather than the default which is to store small tables in memory,
    and larger ones in temporary disk files.
    </p></dd>

<dt>-disk</dt>
<dd><p>If the <code>-disk</code> flag is given then the program will
    store table data in temporary disk files,
    rather than the default which is to store small tables in memory,
    and larger ones on disk.
    If you get out of memory messages, running with the <code>-disk</code>
    flag might help, though the default policy should work fairly well.
    The temporary data files are written in the default temporary 
    directory (defined by the <code>java.io.tmpdir</code> system property -
    often <code>/tmp</code> - and deleted when the program exits, unless
    it exits in an unusual way.
    </p></dd>

<dt>-samp</dt>
<dd><p>Forces TOPCAT to use SAMP for tool interoperability
    (see <ref id="interop"/>).  This is the default, but PLASTIC mode 
    instead of SAMP will otherwise be chosen if a PLASTIC hub but no SAMP
    hub is running on startup.
    </p></dd>

<dt>-plastic</dt>
<dd><p>Forces TOPCAT to use PLASTIC instead of SAMP for tool
    interoperability (see <ref id="interop"/>).
    </p></dd>

<dt>-[no]hub</dt>
<dd><p>The <code>-hub</code> flag causes TOPCAT to run an internal
    SAMP or PLASTIC hub (SAMP by default), if no hub is already
    running, and the <code>-nohub</code> flag prevents this from happening.
    The default behaviour, when neither of these flags is given,
    is currently (since v3.8) to start a hub automatically for
    SAMP but not for PLASTIC.  The hub will terminate when TOPCAT does,
    or can be shut down manually with the 
    <label>Interop|Stop Internal Hub</label> (&IMG.NO_HUB;) menu item.
    See <ref id="interop"/>.
    </p></dd>

<dt>-exthub</dt>
<dd><p>Causes TOPCAT to attempt to run an external SAMP or PLASTIC hub,
    if no hub
    is already running.  The hub will show up in its own window, and can
    be stopped by closing the window.  The hub will continue to run 
    after TOPCAT terminates.
    Invoking external processes from Java is inherently 
    unreliable, so this is done on a best-efforts basis.
    See <ref id="interop"/>.
    </p></dd>

<dt>-noserv</dt>
<dd><p>Prevents TOPCAT from running any services.  Currently the services
    which it may run are SAMP or PLASTIC (see above).
    </p></dd>

<dt>-checkvers</dt>
<dd><p>Prevents TOPCAT from checking an external URL so it can determine
    whether the latest version is being run.
    </p></dd>

<dt>-stilts &lt;stilts-args&gt;</dt>
<dd><p>This flag is a convenience which allows you to run the
    <webref url="http://www.starlink.ac.uk/stilts/">STILTS</webref>
    command-line tool instead of TOPCAT.  This is possible
    because TOPCAT is built on top of STILTS and contains a superset
    of its code. 
    See the STILTS
    <webref url="http://www.starlink.ac.uk/stilts/sun256/invoke.html"
            >manual</webref>
    (or <code>topcat -stilts -help</code>)
    for the form of the <code>&lt;stilts-args&gt;</code>.
    </p></dd>

<dt>-jsamp &lt;jsamp-args&gt;</dt>
<dd><p>This flag is a convenience which allows you to run the 
    <webref url="http://software.astrogrid.org/doc/jsamp/commands.html"
            >jsamp</webref> command-line tool, from the
    <webref url="http://software.astrogrid.org/doc/jsamp/">JSAMP</webref> 
    package, instead of TOPCAT.  This is possible because TOPCAT contains
    the JSAMP library.  
    JSAMP provides various 
    <webref url="http://www.ivoa.net/samp/">SAMP</webref>-related utilities,
    such as a freestanding hub and diagnostic tools.
    See the JSAMP documentation, or do <code>topcat -jsamp -help</code>
    for more information.
    </p></dd>

</dl>
</p>

<p>Other arguments on the command line are taken to be the locations
of tables.  Any tables so specified will be loaded into TOPCAT at startup.
These locations are typically filenames, but could also
be URLs or SQL queries, or perhaps something else.  In addition
they may contain "fragment identifiers" (with a "#") to locate a table within
a given resource, so that for instance the location
<verbatim>
   /my/data/cat1.fits#2
</verbatim>
means the second extension in the multi-extension FITS file
<code>/my/data/cat1.fits</code>.
<ref id="tableLocation"/> describes in more detail the
kinds of URLs which can be used here.
</p>

<p>Note that options to Java itself may also be specified on the command-line,
as described in <ref id="jvmOpt">the next section</ref>.
</p>

</subsect>

<subsect id="jvmOpt">
<subhead><title>Java Options</title></subhead>

<p>As described above, depending on how you
invoke TOPCAT you may be able to specify arguments to Java itself
(the "Java Virtual Machine") which affect how it runs.
These may be defined on the command line or in some other way.
The following subsections describe how to control Java in ways 
which may be relevant to TOPCAT;
they are however somewhat dependent on
the environment you are running in, so you may experience 
OS-dependent variations.
</p>

<subsubsect id="jvmClasspath">
<subhead><title>Class Path</title></subhead>

<p>The classpath is the list of places that Java looks to find 
the bits of compiled code that it uses to run an application.
When running TOPCAT this always has to include the TOPCAT classes
themselves - this is part of the usual invocation 
and is described in <ref id="invoke"/>.  
However, for certain things Java might need to find some other classes, 
in particular for:
<ul>
<li>JDBC drivers (see <ref id="jdbcConfig"/>)</li>
<li>Providing extended algebraic functions (see <ref id="jelExtend"/>)</li>
<li>Launching Mirage (see <ref id="mirage"/>)</li>
<li>Installing I/O handlers for new table formats
    (see <ref id="customHandlers"/>)</li>
</ul>
</p>

<p>If you are going to use these facilities you will need to start the
program with additional class path elements that point to the location
of the classes required.  How you do this depends on how you 
are invoking TOPCAT.
If you are using tht <code>topcat</code> startup script, you can write:
<verbatim>
    topcat -classpath <var>other-paths</var> ...
</verbatim>
(this adds the given paths to the standard ones required for TOPCAT itself).
If you are invoking java directly, then you can either write on the
command line:
<verbatim>
    java -classpath path/to/topcat.jar:<var>other-paths</var>
         uk.ac.starlink.topcat.Driver ...
</verbatim>
or set the CLASSPATH environment variable something like this:
<verbatim>
    setenv CLASSPATH path/to/topcat.jar:<var>other-paths</var>
</verbatim>
In any case, multiple (extra) paths should be separated by colons
in the <var>other-paths</var> string.
</p>

<p><strong>Note</strong> that if you are running TOPCAT 
using java's <code>-jar</code> flag,
any attempt you make to specify the classpath will be ignored!
This is to do with Java's security model.
If you need to specify a classpath which includes more than the
TOPCAT classes themselves, you can't use <code>java -jar</code>
(use 
<code>java -classpath topcat-lite.jar:... uk.ac.starlink.topcat.Driver</code>
instead).
</p>

</subsubsect>

<subsubsect id="jvmMemory">
<subhead><title>Memory Size</title></subhead>

<p>If TOPCAT fails during operation with a message that says something
about a <code>java.lang.OutOfMemoryError</code>, then your heap
size is too small for what you are trying to do.  You will have to
run java with a bigger heap size using the <code>-Xmx</code> flag.
Invoking TOPCAT from the <code>topcat</code> script you would write
something like:
<verbatim>
    topcat -Xmx256M ...
</verbatim>
or using java directly:
<verbatim>
    java -Xmx256M ...
</verbatim>
which means use up to 256 megabytes of memory (don't forget the "M"
for megabyte).  JVMs often default to a heap size of 64M.
You probably don't want to specify a heap size larger than the
physical memory of the machine that you are running on.
</p>

<p>There are other types of memory and tuning options controlled 
using options of the form <code>-X&lt;something-or-other&gt;</code>;
if you're feeling adventurous you may be able to find out about these
by typing "<code>java -X</code>".
</p>

<p><strong>Note</strong> however: using the <code>-disk</code> flag
described in <ref id="topcatArgs"/> may be a better solution; this
makes the program store data from large tables on disk rather than in memory.
</p>

</subsubsect>

<subsubsect id="jvmProperties">
<subhead><title>System properties</title></subhead>

<p>System properties are a way of getting information into Java
(they are the Java equivalent of environment variables).
The following ones have special significance within TOPCAT:
<dl>

<dt><code>apple.laf.useScreenMenuBar</code></dt>
<dd><p>On the Apple Macintosh platform only, this property controls whether
    menus appear at the top of the screen as usual for Mac, or at the
    top of individual windows as usual for Java.  By default
    it is set to <code>true</code> for TOPCAT, 
    so menus mostly appear at the top of the screen (though it's not 
    true to say that TOPCAT obeys the Mac look and feel completely); 
    if you prefer the more Java-like look and feel, set it to 
    <code>false</code>.
    </p></dd>

<dt><code>http.proxyHost</code></dt>
<dd><p>If you are operating inside a firewall which prohibits direct
    HTTP connections, you can set this to the name of an HTTP proxy server
    in order to access remote servers as required for VO functionality etc.
    There are a number of related system properties which you may or may
    not need to use in this case:
    <code>http.proxyPort</code>,
    <code>https.proxyHost</code> etc.
    See the appropriate java documentation
    (e.g. by googling for "http.proxyHost") for details.
    </p></dd>

<dt><code>java.io.tmpdir</code></dt>
<dd><p>The directory in which TOPCAT will write any temporary files it needs.
    This is usually only done if the <code>-disk</code> flag has been
    specified (see <ref id="topcatArgs"/>).
    </p></dd>

<dt><code>jdbc.drivers</code></dt>
<dd><p>Can be set to a (colon-separated) list of JDBC driver classes 
    using which SQL databases can be accessed
    (see <ref id="jdbcConfig"/>).
    </p></dd>

<dt><code>jel.classes</code></dt>
<dd><p>Can be set to a (colon-separated) list of classes containing 
    static methods which define user-provided
    functions for synthetic columns or subsets.
    (see <ref id="jelExtend"/>).
    </p></dd>

<dt><code>jel.classes.activation</code></dt>
<dd><p>Can be set to a (colon-separated) list of classes containing 
    static methods which define user-provided
    functions for use in custom activation expressions.
    (see <ref id="jelExtend"/>).
    </p></dd>

<dt><code>jsamp.hub.profiles</code></dt>
<dd><p>This property determines what profiles a SAMP hub will use
    if you run an internal or external hub from TOPCAT
    (either with the <code>-hub</code>/<code>-exthub</code> flag or
    from the GUI).
    The value is a comma-separated list of profile specifiers;
    options are
    "<code>std</code>" for Standard Profile, 
    "<code>web</code>" for Web Profile or
    the name of a class implementing the 
    <code>org.astrogrid.samp.hub.HubProfile</code> interface.
    The default setting runs just a Standard Profile hub,
    but, for instance, setting it to "<code>std,web</code>" would run a
    Web Profile as well.   Note you should include <code>std</code> in
    the list, otherwise TOPCAT will not be able to talk to the hub.
    See the JSAMP documentation for more detail.
    </p></dd>

<dt><code>jsamp.localhost</code></dt>
<dd><p>Sets the hostname by which the local host is to be identified in
    URLs, for instance server endpoints.
    If unset, the default is currently the loopback address 
    "<code>127.0.0.1</code>".
    However, if this property is set (presumably to the local host's
    fully- or partly-qualified domain name) its value will be used instead.
    Two special values may also be set:
    "<code>[hostname]</code>" for the host's fully qualified domain name, and
    "<code>[hostnumber]</code>" for the IP number.
    </p></dd>

<dt><code>jsamp.server.port</code></dt>
<dd><p>Gives a preferred port number on which to open TOPCAT's internal
    HTTP server, used for SAMP communications amongst other things.
    If this port is unavailable, some other port will be used instead.
    </p></dd>

<dt><code>jsamp.xmlrpc.impl</code></dt>
<dd><p>Indicates which pluggable XML-RPC implementation should be used
    for SAMP communications.
    By default an internal implementation is used.
    If it is set to "<code>xml-log</code>" or "<code>rpc-log</code>"
    then all XML-RPC communications will be logged in very or fairly 
    verbose terms respectively to standard output.
    The classname of an <code>org.astrogrid.samp.xmlrpc.XmlRpcKit</code>
    implementation may be given instead to use a custom implementation.
    </p></dd>

<dt><code>lut.files</code></dt>
<dd><p>Can be set to a (colon-separated on *nix, semicolon-separated on Windows)
    list of files giving custom lookup tables for auxiliary axis and
    density map colour maps.  Each file should be a text file containing
    a number of space-separated lines, each containing red, green, blue 
    samples in the range 0-1.  For instance the file
    <verbatim>
       1.0  1.0  0.0
       1.0  0.0  1.0
    </verbatim>
    would give a colour map that fades from yellow to magenta.  Any number of
    samples may be given; the scale is interpolated.
    </p></dd>

<dt><code>mark.workaround</code></dt>
<dd><p>If set to "true", this will work around a bug in the 
    <code>mark()</code>/<code>reset()</code> methods of some java 
    <code>InputStream</code> classes.  These are rather common, 
    including in Sun's J2SE system libraries.
    Use this if you are seeing errors that say something like
    "<code>Resetting to invalid mark</code>".
    Currently defaults to "false".</p></dd>

<dt><code>myspace.cache</code></dt>
<dd><p>If set to "true", this will prevent directories in the MySpace file
    browser from being read more than once.  This is a workaround for
    MySpace performance problems at time of writing (April 2006);
    setting it true may lead to out of date file listings in MySpace,
    but it may be much faster.  This behaviour may be withdrawn in
    future versions if MySpace performance improves. 
    Currently defaults to "false".
    </p></dd>

<dt><code>service.maxparallel</code></dt>
<dd><p>Raises the maximum number of concurrent queries that may be made
    during a multi-cone operation.
    You should only increase this value <strong>with great care</strong>
    since you risk overloading servers and becoming unpopular with
    data centres.
    As a rule, you should only increase this value if you have
    obtained permission from the data centres whose services
    on which you will be using the increased parallelism.
    </p></dd>

<dt><code>star.basicauth.user</code></dt>
<dt><code>star.basicauth.password</code></dt>
<dd><p>If set, these will provide username and password for HTTP Basic
    Authentication.  Any time the application attempts to access an
    HTTP URL and is met by a 401 Unauthorized response, it will try again
    supplying these user credentials.  This is a rather blunt instrument,
    since the same identity is supplied regardless of which URL is being
    accessed, but it may be of some use in accessing basic-authentication
    protected services.
    </p>
    <p>If these properties are not set, then on encountering a 401 in
    the application will pop up a dialogue window asking for username
    and password.
    </p></dd>

<dt><code>star.connectors</code></dt>
<dd><p>Can be set to a (colon-separated) list of classes which provide
    access to remote filespace implementations.
    Thus-named classes should implement the
    <code>uk.ac.starlink.connect.Connector</code> interface which 
    specifies how you can log on to such a service and provides a
    hierarchical view of the filespace it contains.
    </p></dd>

<dt><code>startable.load.dialogs</code></dt>
<dd><p>Can be set to a (colon-separated) list of custom table load dialogue
    classes.  Briefly, you can install your own table import dialogues at
    runtime by providing classes which implement the 
    <code>uk.ac.starlink.table.gui.TableLoadDialog</code> interface and
    naming them in this property.  
    See <webref url="http://www.starlink.ac.uk/stil/">STIL</webref> 
    documentation for more detail.
    </p></dd>

<dt><code>startable.readers</code></dt>
<dd><p>Can be set to a (colon-separated) list of custom table format input
    handler classes (see <ref id="customHandlers"/>).
    </p></dd>

<dt><code>startable.storage</code></dt>
<dd><p>Can be set to determine the default storage policy.
    Setting it to "<code>disk</code>" has basically the same effect as
    supplying the "<code>-disk</code>" argument on the TOPCAT command line
    (see <ref id="topcatArgs"/>).
    Other possible values are "<code>adaptive</code>", "<code>memory</code>", 
    "<code>sideways</code>" and "<code>discard</code>";
    see <docxref doc="sun252" loc="storagePolicy"/>.
    The default is "<code>adaptive</code>", which means storing smaller
    tables in memory, and larger ones on disk.
    </p></dd>

<dt><code>startable.writers</code></dt>
<dd><p>Can be set to a (colon-separated) list of custom table format output
    handler classes (see <ref id="customHandlers"/>).
    </p></dd>

<dt><code>topcat.exttools</code></dt>
<dd><p>Defines extension tools to be used by TOPCAT.
    The value is a colon-separated list of class names,
    each of which must implement the
    <code>uk.ac.starlink.topcat.TopcatToolAction</code> interface and have a
    no-arg constructor.
    The actions corresponding to any such classes will be added to toolbar.
    This is an experimental extensibility feature, which may be modified or
    withdrawn in a future release.
    </p></dd>

<dt><code>user.dir</code></dt>
<dd><p>Sets the current working directory.
    This determines the default from which the file browsers will start.
    </p></dd>

<dt><code>votable.namespacing</code></dt>
<dd><p>Determines how namespacing is handled in input VOTable documents.
    Known values are
    "<code>none</code>" (no namespacing, xmlns declarations
    in VOTable document will probably confuse parser),
    "<code>lax</code>" (anything that looks like it is probably a VOTable
    element will be treated as a VOTable element) and
    "<code>strict</code>" (VOTable elements must be properly declared in one
    of the correct VOTable namespaces).
    May also be set to the classname of a
    <code>uk.ac.starlink.votable.Namespacing</code> implementation.
    The default is "<code>lax</code>".
    </p></dd>

<dt><code>votable.strict</code></dt>
<dd><p>Set <code>true</code> for strict enforcement of the VOTable standard
    when parsing VOTables.  This prevents the parser from working round
    certain common errors, such as missing <code>arraysize</code>
    attributes on FIELD/PARAM elements with <code>datatype="char"</code>.
    False by default.
    </p></dd>

<dt><code>votable.version</code></dt>
<dd><p>Selects the version of the VOTable standard which output VOTables
    will conform to by default.
    May take the values "<code>1.0</code>", "<code>1.1</code>", 
    "<code>1.2</code>" or "<code>1.3</code>".
    By default, version 1.2 VOTables are written.
    </p></dd>

</dl>
</p>

<p>To define these properties on the command line
you use the <code>-D</code> flag, which has the form
<verbatim>
    -D&lt;property-name&gt;=&lt;value&gt;
</verbatim>
If you're using the TOPCAT startup script, you can write something like:
<verbatim>
    topcat -Djdbc.drivers=org.postgresql.Driver ...
</verbatim>
or if you're using the <code>java</code> command directly:
<verbatim>
    java -Djdbc.drivers=org.postgresql.Driver ...
</verbatim>
</p>

<p>Alternatively you may find it more convenient to 
write these definitions in a file named
<code>.starjava.properties</code> in your home directory; the above
command-line flag would be equivalent to inserting the line:
<verbatim>
    jdbc.drivers=org.postgresql.Driver
</verbatim>
in your <code>.starjava.properties</code> file.
</p>

</subsubsect>

</subsect>

<subsect id="jdbcConfig">
<subhead><title>JDBC Configuration</title></subhead>

<p>This section describes additional configuration which must be
done to allow TOPCAT to access SQL-compatible relational databases
for reading (see <ref id="inSql"/>) or
writing (see <ref id="outSql"/>) tables.
If you don't need to talk to SQL-type databases, 
you can ignore the rest of this section.
The steps described here are the standard ones
for configuring JDBC (which sort-of stands for Java Database Connectivity),
described in more detail on 
<webref url="&URL.J2SE_DOCS;guide/jdbc/">Sun's JDBC web page</webref>.
</p>

<p>To use TOPCAT with SQL-compatible databases you must:
<ul>
<li>Have access to an SQL-compatible database locally or over the network</li>
<li>Have a JDBC driver appropriate for that database</li>
<li>Install this driver for use with TOPCAT</li>
<li>Know the format the driver uses for URLs to access database tables</li>
<li>Have appropriate privileges on the database to perform the
    desired operations</li>
</ul>
Installing the driver consists of two steps:
<ol>
<li>Set the <code>jdbc.drivers</code> system property to the name of the
    driver class as described in <ref id="jvmProperties"/></li>
<li>Ensure that the classpath you are using includes this driver class
    as described in <ref id="jvmClasspath"/></li>
</ol>
</p>

<p>These steps are all standard for use of the
<webref url="&URL.J2SE_DOCS;guide/jdbc/">JDBC</webref>
system.
</p>

<p>To the author's knowledge, TOPCAT has so far successfully been used
with the following RDBMSs and corresponding JDBC drivers:
<dl>

<dt><webref url="http://www.mysql.com/">MySQL</webref></dt>
<dd><p>MySQL has been tested on Linux with the
    <webref url="http://www.mysql.com/products/connector/j/"
            >Connector/J</webref> driver and seems to work;
    tested versions are server 3.23.55 with driver 3.0.8 and
    server 4.1.20 with driver 5.0.4.
    Sometimes tables with very many (hundreds of) columns cannot be 
    written owing to SQL statement length restrictions.
    Note there is known to be a column metadata bug in version 3.0.6 of the
    driver which can cause a ClassCastException error when tables are written.
    Check the driver's documentation for additional parameters, for instance
    "<code>useUnicode=true&amp;characterEncoding=UTF8</code>" may be required
    to handle some non-ASCII characters.
    </p></dd>

<dt><webref url="http://www.postgresql.org/">PostgreSQL</webref></dt>
<dd><p>PostgreSQL 7.4.1 apparently works with 
    <webref url="http://jdbc.postgresql.org/">its own driver</webref>.
    Note the performance of this driver appears to be rather poor,
    at least for writing tables.
    </p></dd>

<dt><webref url="http://www.oracle.com/">Oracle</webref></dt>
<dd><p>You can use Oracle with the JDBC driver that comes as part of its
    <webref url="http://www.oracle.com/technology/tech/oci/instantclient/instantclient.html"
            >Basic Instant Client Package</webref>.
    However, you <em>can't</em> currently use the
    <ref id="SQLTableLoadDialog">SQL load</ref
         >/<ref id="SQLWriteDialog">SQL save</ref>
    dialogue boxes to do it.  You have to specify a JDBC URL specifying
    the query to read/table to write as a string in the 
    <label>Location</label> field of the normal table 
    <ref id="LoadWindow">load</ref>/<ref id="SaveQueryWindow">save</ref> 
    dialogue boxes.  The URL will look something like
    <verbatim>
    jdbc:oracle:thin:@//hostname:1521/database#SELECT ...
    </verbatim>
    for querying an existing database (loading) and
    <verbatim>
    jdbc:oracle:thin:@//hostname:1521/database#new-table-name
    </verbatim>
    for writing a new table (saving).
    </p></dd>

<dt><webref url="http://www.microsoft.com/SQL">SQL Server</webref></dt>
<dd><p>There is more than one JDBC driver known to work with
    SQL Server, including 
    <webref url="http://jtds.sourceforge.net/">jTDS</webref> 
    and the
    <webref url="http://www.microsoft.com/sql/technologies/jdbc/default.mspx"
            >Microsoft JDBC driver</webref>.
    Some evidence suggests that jTDS may be the better choice, 
    but your mileage may vary.
    </p></dd>

<dt><webref url="http://www.sybase.com/products/databasemanagement/adaptiveserverenterprise"
            >Sybase ASE</webref></dt>
<dd><p>There has been a successful use of Sybase 12.5.2 and jConnect 
    (jconn3.jar) using a JDBC URL like
    "<code>jdbc:sybase:Tds:hostname:port/dbname?user=XXX&amp;password=XXX#SELECT...</code>".
    An earlier attempt using Sybase ASE 11.9.2 failed.
    </p></dd>

</dl>
Other RDBMSs and drivers may or may not work - please let us know the
results of any experiments you carry out.
Sun maintain a list of JDBC drivers for various databases; it can be found at
<webref url="http://servlet.java.sun.com/products/jdbc/drivers"/>.
</p>

<p>Here are example command lines to start up TOPCAT using 
databases known to work.
<dl>

<dt>PostgreSQL</dt>
<dd><p><verbatim>
   java -classpath topcat-full.jar:pg73jdbc3.jar \
        -Djdbc.drivers=org.postgresql.Driver \
        uk.ac.starlink.topcat.Driver
</verbatim></p></dd>

<dt>MySQL</dt>
<dd><p><verbatim>
   java -classpath topcat-full.jar:mysql-connector-java-3.0.8-bin.jar \
        -Djdbc.drivers=com.mysql.jdbc.Driver \
        uk.ac.starlink.topcat.Driver
</verbatim></p></dd>

<dt>Oracle</dt>
<dd><p><verbatim>
   java -classpath topcat-full.jar:ojdbc14.jar \
        -Djdbc.drivers=oracle.jdbc.driver.OracleDriver \
        uk.ac.starlink.topcat.Driver
</verbatim></p></dd>

<dt>SQL Server with jTDS</dt>
<dd><p><verbatim>
   java -classpath topcat-full.jar:jtds-1.1.jar \
        -Djdbc.drivers=net.sourceforge.jtds.jdbc.Driver \
        uk.ac.starlink.topcat.Driver
</verbatim></p></dd>

</dl>
</p>

</subsect>

<subsect id="largeTables">
<subhead><title>Tips for Large Tables</title></subhead>

<p>Considerable effort has gone into making TOPCAT capable of
dealing with large datasets.  In particular it does not in general
have to read entire files into memory in order to do its work, 
so it's not restricted to using files which fit into the java virtual
machine's 'heap memory' or into the physical memory of the machine.
As a rule of thumb, the program will work at reasonable speed
with tables up to about 1-10 million rows, depending on the machine
it's running on.
The number of columns is less of an issue,
though see below concerning performance.
</p>

<p>However, the way you invoke the program affects how well it can cope 
with large tables; you may in some circumstances get a message that 
TOPCAT has run out of memory (either a popup or a terse "OutOfMemoryError" 
report on the console), and there are some things you can do about this:
</p>

<p>
<dl>

<dt>Increase Java's heap memory</dt>
<dd><p>When a Java program runs, it has a fixed maximum amount of memory
    that it will use; Java does not really make use of virtual memory.
    The default maximum is typically 64Mb, though that depends on your
    java setup.  You can increase this by
    using the <code>-Xmx</code> flag, followed by the maximum heap memory,
    for instance "<code>topcat -Xmx256M</code>" or 
    "<code>java -Xmx256M -jar topcat-full.jar</code>".
    Don't forget the "<code>M</code>" to indicate megabytes.
    It's generally reasonable to increase this value up to nearly the
    amount of free physical memory in your machine if you need to
    (taking account of the needs of other processes running at the same time)
    but attempting any more will usually result in abysmal performance.
    See <ref id="jvmMemory"/>.
    </p></dd>

<dt>Use FITS files</dt>
<dd><p>Because of the way that FITS files are organised, TOPCAT is able to 
    load tables which are stored as uncompressed FITS binary tables
    on disk almost instantly regardless of their size 
    (in this case loading just reads the metadata, and any data elements
    are only read if and when they are required).
    So if you have a large file stored in VOTable or ASCII-based form
    which you use often and takes a long time to load, it's a good idea
    to convert it to FITS format once for subsequent use.
    You can do this either by loading it into TOPCAT once and saving it
    as FITS, or using the separate command-line package 
    <webref url="http://www.starlink.ac.uk/stilts/sun256/tcopy.html"
            >STILTS</webref>.
    Note that the "fits-plus" variant which TOPCAT uses by default retains
    all the metadata that would be stored in a corresponding VOTable,
    so you won't normally lose information by doing this 
    (see <ref id="outFits"/>).
    As well as speeding things up, using FITS files will 
    also reduce the need to use <code>-Xmx</code> flags as above.
    </p></dd>

<dt>Run in 64-bit mode</dt>
<dd><p>If you are working with a file or files whose total size approaches
    or exceeds about 2 Gbyte, you should use a 64-bit version of java.
    This means that you will need a 64-bit operating system, and also
    a 64-bit version of the Java Virtual Machine.
    Executing "<code>java -version</code>" (or "<code>topcat -version</code>")
    will probably say something about 64-bit-ness if it is 64-bit.
    </p></dd>

<dt>Use column-oriented storage</dt>
<dd><p>For really large tables storing them in 
    the <ref id="outColfits">colfits</ref> output format 
    can significantly improve performance.
    This stores all the elements of a single column contiguously on disk,
    which means that scanning through all the values in one or a few
    columns can proceed with much less unnecessary I/O than in normal
    (row-oriented) FITS format.  It will make most difference when
    the table is larger than the amount of physical memory available,
    and the table has many columns.  Be aware however that operations
    which require all the cells in all the rows
    (for instance, calculating <ref id="StatsWindow">row statistics</ref>) 
    may be somewhat slower using this format.
    </p>
    <p>It is also possible to use column-oriented storage for non-FITS
    files by specifying the flag <code>-Dstartable.storage=sideways</code>.
    This is like using the <code>-disk</code> flag but uses column-oriented
    rather than row-oriented temporary files.  However, using it for
    such large files means that the conversion is likely to be rather
    slow, so you may be better off converting the original file to
    <code>colfits</code> format in a separate step and using that.
    </p></dd>

<dt>Use the -disk flag</dt>
<dd><p>The way TOPCAT stores table data is configurable, and 
    the details can be controlled by setting its <em>Storage Policy</em>.
    The default storage policy (since version 3.5),
    "<code>adaptive</code>", means that the data for relatively small
    tables are stored in memory, and for larger ones in temporary disk files.
    This usually works fairly well and you're not likely to need to change it.
    However, you can experiment if you like, and a small amount of
    memory may be saved if you encourage it to store all table data on disk,
    by specifying the <code>-disk</code> flag on the command line.
    You can achieve the same effect by adding the line 
    <code>startable.storage=disk</code> in the 
    <code>.starjava.properties</code> in your home directory.
    See <ref id="topcatArgs"/>, <ref id="jvmProperties"/>.
    </p></dd>
</dl>
</p>

<p>As far as performance goes, the memory size of the machine you're
using does make a difference.  If the size of the dataset you're dealing
with (this is the size of the FITS HDU if it's in FITS format but may 
be greater or less than the file size for other formats) will
fit into unused physical memory then general everything will run very quickly
because the operating system can cache the data in memory; if it's
larger than physical memory then the data has to keep being re-read
from disk and most operations will be much slower, though use of
column-oriented storage can help a lot in that case.
</p>

</subsect>
    

<subsect id="invokeExamples">
<subhead><title>Examples</title></subhead>

<p>Here are some examples of invoking TOPCAT from the command line.
In each case two forms are shown: one using the <code>topcat</code>
script, and one using the jar file directly.  In the latter case,
the <code>java</code> command is assumed to be on the your path, and
the jar file itself, assumed in directory <code>my/tcdir</code>, 
might be named <code>topcat.jar</code>, 
<code>topcat-full.jar</code>, or something else, but the form 
of the command is the same.

<dl>

<dt>No arguments</dt>
<dd><p><verbatim>
    topcat
    java -jar topcat.jar
</verbatim></p></dd>

<dt>Output usage message</dt>
<dd><p><verbatim>
    topcat -h
    java -jar topcat.jar -h
</verbatim></p></dd>

<dt>Load a FITS file</dt>
<dd><p><verbatim>
    topcat testcat.fits
    java -jar my/tcdir/topcat.jar testcat.fits
</verbatim></p></dd>

<dt>Loading files of various formats</dt>
<dd><p><verbatim>
    topcat t1.fits -f ascii t2.txt t3.txt -f votable t4.xml
    java -jar my/tcdir/topcat.jar t1.fits -f ascii t2.txt t3.txt -f votable t4.xml
</verbatim></p></dd>

<dt>Use disk storage format and boosted heap memory</dt>
<dd><p><verbatim>
    topcat -Xmx256M -disk 
    java -Xmx256M -jar my/tcdir/topcat.jar -disk
</verbatim></p></dd>

<dt>Make custom functions available</dt>
<dd><p><verbatim>
    topcat -classpath my/funcdir/funcs.jar -Djel.classes=my.ExtraFuncs t1.fits
    java -classpath my/tcdir/topcat.jar:my/funcdir/funcs.jar \
         -Djel.classes=func.ExtraFuncs \
         uk.ac.starlink.topcat.Driver t1.fits
</verbatim></p></dd>

<dt>Make PostgreSQL database connectivity available</dt>
<dd><p><verbatim>
    topcat -classpath my/jdbcdir/pg73jdbc3.jar -Djdbc.drivers=org.postgresql.Driver
    java -classpath my/tcdir/topcat.jar:my/jdbcdir/pg73jdbc3.jar \
         -Djdbc.drivers=org.postgresql.Driver uk.ac.starlink.topcat.Driver
</verbatim></p></dd>

<dt>Use custom I/O handlers</dt>
<dd><p><verbatim>
    topcat -classpath my/driverdir/drivers.jar \
           -Dstartable.readers=my.MyTableBuilder \
           -Dstartable.writers=my.MyTableWriter \
    java -classpath my/tcdir/topcat.jar:my/driverdir/drivers.jar \
         -Dstartable.readers=my.MyTableBuilder \
         -Dstartable.writers=my.MyTableWriter \
         uk.ac.starlink.topcat.Driver
</verbatim></p></dd>

</dl>
The <code>-Dx=y</code> definitions can be avoided by putting equivalent
<code>x=y</code> lines into the <code>.starjava.properties</code> in your
home directory.
</p>


</subsect>

</sect>

<appendices>

<sect id="windows">
<subhead><title>TOPCAT Windows</title></subhead>

<p>This appendix gives a tour of all the windows that form the
TOPCAT application, explaining the anatomy of the windows and
the various tools, menus and other controls.
Attributes common to many or all windows are described in
<ref id="commonFeatures"/>, and the subsequent sections describe
each of the windows individually.
</p>

<p>When the application is running, the <label>Help For Window</label>
(&IMG.HELP;) toolbar button will display the appropriate description 
for the window on which it is invoked.
</p>


<subsect id="commonFeatures">
<subhead><title>Common Window Features</title></subhead>

<p>This section describes some features which are common to many or
all of the windows used in the TOPCAT program.
</p>

<subsubsect>
<subhead><title>Toolbar</title></subhead> 

<p>Each window has a toolbar at the top containing various buttons
representing actions that can be invoked from the window.
Most of them contain the following buttons:
<dl>

<dt>&IMG.CLOSE; Close</dt> 
<dd><p>Closes the window.  This convenience button 
    has the same effect as closing the window
    in whatever way your graphics platform normally allows.
    In most cases, closing the window does not lose state associated with
    it (such as fields filled in); if you recover the window later it
    will look the same as when you closed it.
    </p></dd>

<dt>&IMG.HELP; Help</dt>
<dd><p>Pops up a <ref id="HelpWindow">Help browser</ref> window, or makes
    sure it is visible if it has already been opened.
    The window will display help information relevant to the window in
    which you pushed this button.
    </p></dd> 

</dl>
</p>

<p>Buttons in the toolbar often appear in menus of the same window as well;
you can identify them because they have the same icon.
This is a convenience; invoking the action from the toolbar or from
the menu will have the same effect.
</p>

<p>Often an action will only be possible in certain circumstances, 
for instance if some rows in the associated <ref id="JTable">JTable</ref> 
have been selected.
If the action is not possible (i.e. it would make no sense to invoke it)
then the button in the toolbar and the menu option will be greyed out,
indicating that it cannot be invoked in the current state.
</p>

</subsubsect>

<subsubsect id="commonMenus">
<subhead><title>Menus</title></subhead>

<p>Most windows have a menu bar at the top containing one or more menus.
These menus will usually provide the actions available from the 
toolbar (identifiable because they have the same icons), and
may provide some other less-commonly-required actions too.
</p>

<p>Here are some of the menus common to several windows:
<dl>

<dt>Window menu</dt>
<dd><p>Nearly all windows have this menu.
    At least the following options are available:
    <dl>

    <dt>&IMG.CONTROL; Control Window</dt>
    <dd><p>Ensures that the Control Window is visible on the screen,
        deiconifying and raising it if necessary.  This can be useful if
        you 'lose' the window behind a proliferation of other ones.
        </p></dd>

    <dt>&IMG.SCROLLER; Scrollable</dt>
    <dd><p>If selected, this causes the entire content of the window to be
        wrapped in scrollbars.  It is not generally recommended to use this
        option, since in general the windows are arranged so that resizing
        them will resize sensible parts of them, but it may be useful
        if using some of the larger windows on an unusually small screen.
        </p></dd>

    <dt>&IMG.CLOSE; Close</dt>
    <dd><p>Closes the window.  This convenience button 
        has the same effect as closing the window
        in whatever way your graphics platform normally allows.
        In most cases, closing the window does not lose state associated with
        it (such as fields filled in); if you recover the window later it
        will look the same as when you closed it.
        </p></dd>

    <dt>&IMG.EXIT; Exit</dt>
    <dd><p>Exits TOPCAT.  You will be prompted to confirm this action
        if tables are loaded, since it might result in loss of data.
        </p></dd>

    </dl>
    </p></dd>

<dt>Help menu</dt>
<dd><p>Nearly all windows have this menu.
    The following options are available:
    <dl>

    <dt>&IMG.MANUAL; Help</dt>
    <dd><p>Pops up the <ref id="HelpWindow">Help Window</ref>.
        </p></dd>

    <dt>&IMG.HELP; Help for Window</dt>
    <dd><p>Pops up the <ref id="HelpWindow">Help Window</ref>;
        the window will display help information relevant to the window in
        which the menu appears.
        </p></dd>

    <dt>&IMG.MANUAL_BROWSER; Help in Browser</dt>
    <dd><p>Attempts to show the application help in a web browser.
        This is somewhat system dependent and is not guaranteed to work.
        </p></dd>

    <dt>&IMG.MANUAL1_BROWSER; Help in Browser (single page)</dt>
    <dd><p>Attempts to show the application help in a web browser as a single
        (long page).  This can be useful if you want to search for a given
        word or string in the text.
        This is somewhat system dependent and is not guaranteed to work.
        </p></dd>

    <dt>&IMG.HELP_BROWSER; Help for Window in Browser</dt>
    <dd><p>Attempts to show the help page relevant to the window in which
        the menu appears in a web browser.
        This is somewhat system dependent and is not guaranteed to work.
        </p></dd>

    <dt>&IMG.TOPCAT_LOGO_SMALL; About TOPCAT</dt>
    <dd><p>Pops up a little window giving information on the version and
        authorship of the program.
        It also reports on availability of some optional components.
        </p></dd>

    </dl>
    </p></dd>

<dt>Display menu</dt>
<dd><p>This menu is available for most windows which display their data
    using a <ref id="JTable">JTable</ref> component.
    If present, it contains a list of the columns in the JTable with 
    tickboxes next to them - clicking on a column name in this menu
    toggles whether the column is visible in the window.
    </p></dd>

</dl>
</p>

</subsubsect>

<subsubsect id="JTable">
<subhead><title>JTables</title></subhead>

<figure>
<caption><px>An example JTable</px></caption>
<figureimage src="&FIG.JTable;"/>
</figure>

<p>Many of the windows, including the 
<ref id="TableViewerWindow">Data Window</ref>,
display their data in a visual component called a <label>JTable</label>.
This displays a grid of values, with headings for each column, in
a window which you can scroll around.  Although JTables are used for
a number of different things (for instance, showing the table data themselves
in the <ref id="TableViewerWindow">Data Window</ref>
and showing the column metadata in the 
<ref id="ColumnInfoWindow">Columns Window</ref>), 
the fact that the same widget is
used provides a common look and feel.
</p>

<p>Here are some of the things you can do with a JTable:
<dl>
<dt>Scroll around</dt>
<dd><p>Using the scrollbars which may appear to the right and below the
    table you can scroll around it to see parts which are not initially
    visible.  
    You can grab the sliders and drag them around by holding the mouse
    button down while you move it, or click in the slider "trough" one side
    or other of the current slider position to move a screenful.
    Under some circumstances the cursor arrow keys and PageUp/PageDown
    keys may move the table too.
    If the JTable is small enough to fit within the window the scrollbars
    may not appear.
    </p></dd>

<dt>Move columns</dt>
<dd><p>By clicking on the header (grey title bit at the top) of a column
    and dragging it left or right, you can change the order of columns
    as displayed.  In some cases 
    (the <ref id="TableViewerWindow">Data Window</ref>)
    this actually has the effect of changing the order of the columns
    in the table; in other cases it is just cosmetic.
    </p></dd>

<dt>Resize columns</dt>
<dd><p>By dragging on the line between row headers you can change the width
    of the columns in the table.
    </p></dd>

<dt>Edit cells</dt>
<dd><p>In some cases, cells are editable.  If they are, then double-clicking
    in the cell will begin an edit session for that cell, and pressing
    Return will confirm that the edit has been made.
    </p></dd>

<dt>Select rows</dt>
<dd><p>Sometimes rows can be highlighted; you can select one row by clicking
    on it or a number of contiguous rows by clicking and dragging from the
    first to the last.
    To add further rows to a set already selected without deselecting
    the first lot, hold the "Control" key down while you do it.
    </p></dd>

<dt>Sort rows</dt>
<dd><p>In some, but not all cases, you may see a little up or down arrow
    in one of the column headers.  This indicates that the rows of the
    table have been sorted according to the values in that column.
    If you click on another column header, the rows will be re-sorted
    according to the values in that column.  Clicking again on the same
    column reverses the sort order.
    This feature is only available for certain displayed JTables.
    </p></dd>
</dl>
</p>

<p>In some cases where a JTable is displayed, there will be a menu
on the menu bar named <label>Display</label>.
This permits you to select which columns are visible and which are hidden.
Clicking on the menu will give you a list of all the available columns
in the table, each with a checkbox by it; click the box to toggle
whether the column is displayed or not.
</p>

</subsubsect>

<subsubsect id="columnSelector">
<subhead><title>Column Selector</title></subhead>

<figure>
<caption><px>Editable Column Selector</px></caption>
<figureimage src="&FIG.columnSelector;"/>
</figure>

<p>Several windows in TOPCAT invite you to select a column value from
one of the loaded tables by presenting a selection box like the one in 
the figure.
Examples are the
<ref id="PointSelector">Plot</ref> and
<ref id="MatchWindow">Match</ref> windows.
</p>

<p>In the simplest case you can simply select the value from the list
of columns by clicking on the down-arrow at the right and then selecting
one from the drop-down list of columns which is offered.
Note that only appropriate columns will be offered - for instance if
a numeric value is required, string-valued columns will not be included.
</p>

<p>Another possibility is to use the little left/right arrows on the far
right to cycle through all the known columns.  This can be useful in
plots, for instance to see a sequence of all the available plots 
against a given abcissa using only one click at a time.
</p>

<p>Finally, you can type in an expression giving the required value.
This can either be the name of a column just as if you had selected
it from the drop-down list, or an expression based on column names, 
or even a constant value.  The syntax of the expression language is
explained in <ref id="jel"/>.
Typing the column name rather than selecting it may be more convenient
if the selection list is very long; typing an expression obviously gives
you a lot more possibilities.
</p>

<p>Note that depending on your platform the selection box may not look
exactly like the figure above.  However, if you can type into it
(probably by clicking on it) then you should be able to use expressions
as described above.  Some selectors however only take column names;
if you can't type a value into it, you have to choose one of the 
options given.
</p>

</subsubsect>

</subsect>

<subsect id="ControlWindow">
<subhead><title>Control Window</title></subhead>

<figure>
<caption><px>The Control Window</px></caption>
<figureimage src="&FIG.ControlWindow;"/>
</figure>

<p>The Control Window is the main window from which all of TOPCAT's
activities are controlled.  It lists the known tables, summarises
their characteristics, and allows you to open other windows for
more specialised tasks.
When TOPCAT starts up you will see this window - it may or may not have
some tables loaded into it according to how you invoked the program.
</p>

<p>The window consists of two main parts:
the <label>Table List</label> panel on the left, and
the <label>Current Table Properties</label> panel on the right.
Tables loaded into TOPCAT are shown in the Table List,
each identified by an index number which never changes for a given table,
and a label which is initially set from its location, but can be changed
for convenience.
</p>

<p>One of the tables in the list is highlighted, 
which means it is the currently selected table;
you can change the selection by clicking on an item in the list.
Information about the selected table is shown
in the properties panel on the right.  This shows such things as the
number of rows and columns, current sort order, current row subset
selection and so on.  It contains some controls which allow you to
change these properties.
Additionally, many of the buttons in the toolbar relate to the
currently selected table.
</p>

<p>Additionally there is a toolbar and some menus at the top which
display windows and perform other actions, there is a memory monitor
at the bottom left, and there may, depending on
how TOPCAT was invoked, be a panel labelled <label>SAMP</label> 
at the bottom of the right hand panel.
</p>

<p>The Table List, Current Table Properties panel, memory monitor, 
SAMP panel, and
actions available from the Control Window's toolbar and menus 
are described in the following subsections.
</p>

<subsubsect>
<subhead><title>Table List</title></subhead>

<p>The Table List panel on the left of the Control Window is 
pretty straightforward - it lists all the tables currently known
to TOPCAT.  If a new table is introduced by loading it from the 
<ref id="LoadWindow">Load Window</ref> or as a result of 
some action such as <ref id="join">table joining</ref> then its
name and number will appear in this list.
The currently selected table is highlighted - clicking on a different
table name (or using the arrow keys if the list has keyboard focus) 
will change the selection.  The properties of the
selected table are displayed in the Current Table Properties panel
to its right, and a number of the toolbar buttons and menu items
refer to it.
</p>

<p>If you double-click on a table in the list, or press Return
while it is selected, that table's 
<ref id="TableViewerWindow">Data Window</ref> will appear.
</p>

<p>Certain other applications
(<webref url="http://www.starlink.ac.uk/treeview/">Treeview</webref>
 or even another instance of TOPCAT)
can interoperate with TOPCAT using drag-and-drop, and for these the
table list is a good place to drag/drop tables.
For instance you can drag a table node off of the main panel of 
Treeview and drop it onto the table list of TOPCAT, and you will
be able to use that table as if it had been loaded from disk.
You can also paste the filename or URL of a table onto the table list,
and it will be loaded.
</p>

<p>Sometimes while a table is being loaded 
a greyed-out entry will appear in
this list with text like "<em>Loading SAMP table</em>" or similar.
Such entries cannot be selected, but they let you know that something
is happening.
</p>

</subsubsect>

<subsubsect>
<subhead><title>Current Table Properties panel</title></subhead>

<p>The <label>Current Table Properties</label> panel on the right hand
side of the Control Window contains a number of
controls which relate to the currently selected table and its 
<ref id="apparent" plaintextref="yes">Apparent properties</ref>;
they will be blank if no table is selected.
Here is what the individual items mean:
<dl>
<dt>Label</dt>
<dd><p>The short name associated with the selected table.
    It is used in the
    Table List panel and in labelling view windows so you can see which
    table they refer to.  It usually set initially according to where
    the table came from, but you can change it by typing into the text field.
    </p></dd>

<dt>Location</dt>
<dd><p>The original source of the selected table.
    This is typically a filename or URL (perhaps abbreviated), 
    but may be something else depending
    on where the table came from.
    </p></dd>

<dt>Name</dt>
<dd><p>A name associated with the selected table.
    This may be derived from the table's filename if it had one or from
    some naming string stored within the table metadata.
    </p></dd>

<dt>Rows</dt>
<dd><p>The number of rows in the selected table.
    If the current <ref id="subsets">Row Subset</ref> does not include all the
    rows, then an indication of how many are visible within that subset
    will be given too.
    </p></dd>

<dt>Columns</dt>
<dd><p>The number of columns in the selected table.
    If some are currently hidden 
    (not included in the current <ref id="columns">Column Set</ref>),
    an indication of how many are visible will be given too.
    </p></dd>

<dt>Sort Order</dt>
<dd><p>The column (if any) which determines the current
    <ref id="order">Row Order</ref>.
    A selector shows the column (if any) on which the rows of the 
    Apparent Table are sorted
    and allows you to choose a different one.  
    The little arrow beside it
    indicates whether the sort is ascending or descending.
    </p></dd>

<dt>Row Subset</dt>
<dd><p>The name of the current <ref id="subsets">Row Subset</ref>.
    A selector shows the name of the subset which determines which 
    rows are part of the Apparent Table
    and allows you to choose another one.  "All" indicates that all
    rows are included.
    If you select a new value using this selector, then other windows
    which display subset-sensitive information for the current table
    will change their displayed subset to the newly-selected one.
    However the reverse does not happen - you can change the visible
    subset in the statistics window for instance or one of the graphics
    windows and it will not affect the value displayed here.
    </p></dd>

<dt>Activation Action</dt>
<dd><p>The currently selected
    <ref plaintextref="yes" id="activation">Activation Action</ref>.
    The action can be changed by clicking on this button to display
    the <ref id="ActivationQueryWindow">Activation Window</ref>.
    </p>
    <p>The <label>Broadcast Row</label> checkbox to the right is a shortcut
    for one useful activation action; it corresponds to the
    Activation Window's option <label>Transmit Row</label> to All Listeners - 
    that is it means that any other tools talking to TOPCAT using SAMP 
    or PLASTIC will be informed about a row activation any time it happens.
    This checkbox will be greyed out if no suitable 
    messaging protocol is in use (see <ref id="interop"/>).
    </p></dd>

</dl>
</p>

</subsubsect>

<subsubsect id="MemoryMonitor">
<subhead><title>Memory Monitor</title></subhead>

<figure>
<caption><px>Control Window Memory Monitor</px></caption>
<figureimage src="&FIG.MemoryMonitor;"/>
</figure>

<p>The memory monitor is a small widget at the bottom left of the 
Control Window which gives an indication of TOPCAT's memory usage.
The numbers indicate the currently used and maximum heap size that 
Java will use (e.g. "64 M" for 64 megabytes), 
and the two darker colours filled in
from the left indicate the current total and used proportions of this.
It's not necessary to understand in detail what these mean, but if
the darkest (used) colour comes to fill up the whole area, the 
application will slow down and then signal an Out Of Memory Error.
See <ref id="largeTables"/> for some tips on what to do if this
happens.
</p>

<p>If you click on the memory monitor, you will request that the
Java Virtual Machine performs a garbage collection round, 
which may have the effect of reclaiming some memory and 
modifying the current usage.
This is not really useful (Java will garbage collect at sensible times
without prompting), but you can do it if you're bored.
</p>

</subsubsect>

<subsubsect id="sampPanel">
<subhead><title>SAMP Panel</title></subhead>

<figure>
<caption><px>Control Window SAMP Panel</px></caption>
<figureimage src="&FIG.sampPanel;"/>
</figure>

<p>If TOPCAT is running in SAMP mode,
the SAMP panel at the bottom of the Control Window gives a quick view
of the current status of SAMP communications.
For a discussion of the whats and whys of SAMP, see
<ref id="interop"/>.
<strong>Note</strong> that if not running in SAMP mode
(e.g. if in PLASTIC or no-server mode) this panel will not appear.
SAMP mode is the default under normal circumstances.
</p>

<p>The panel is made up of the following main parts:
<dl>
<dt>Message View</dt>
<dd><p>This shows a graphical representation of any messages which have
    been recently sent to or received from other applications by TOPCAT.
    Triangles to the left of the central circle represent incoming messages
    and triangles to the right represent outgoing ones. 
    A filled triangle represents a message which is still waiting for an
    answer, and an open one represents a message which either is not 
    expecting an answer or has already received one.  Colour coding is
    used to indicate success or failure.
    The triangles disappear from the display shortly after they are no longer
    waiting for a reply.
    </p></dd>

<dt>Client View</dt>
<dd><p>An icon is shown in this panel for each application currently registered
    with the SAMP hub, including TOPCAT itself.  If no icon is available
    for a registered application, a generic grey square is used.
    </p></dd>

<dt>Connection Indicator</dt>
<dd><p>An icon at the right may be visible to indicate whether or not 
    TOPCAT is currently registered with the hub.
    </p></dd>
</dl>
When TOPCAT is not connected to a SAMP hub (most likely because none
is running) these panels will be greyed out.
</p>

<p>More detail and control for the information presented in this panel
is available in the <ref id="SampWindow">SAMP Window</ref>.
</p>


</subsubsect>


<subsubsect id="controlTools">
<subhead><title>Toolbar Buttons</title></subhead>

<p>There are a number of buttons on the Control Window's toolbar;
these are the most convenient way of invoking most of TOPCAT's
functions.  They are grouped as follows:

<dl>
<dt>Import and export</dt>
<dd><p>
    <dl>

    <dt>&IMG.LOAD; Load Table</dt>
    <dd><p>Pops up the <ref id="LoadWindow">Load Table</ref> dialogue
        which allows you to load a table into TOPCAT.
        If a table is loaded it becomes the new current table.
        </p></dd>

    <dt>&IMG.SAVE; Save Table(s)/Session</dt>
    <dd><p>Pops up the <ref id="SaveQueryWindow">Save Table</ref> dialogue
        which allows you to write out tables in various ways.
        You can either write out the current
        <ref id="apparent">Apparent Table</ref>, or multiple tables,
        or save (much of) the current session state.
        </p></dd>

    <dt>&IMG.BROADCAST; Broadcast Table</dt>
    <dd><p>Broadcasts the current <label>Apparent Table</label> to any
        applications registered using the SAMP or PLASTIC protocol.
        See <ref id="interop"/>.
        </p></dd>

    </dl>
    </p></dd>

<dt>Table views (see <ref id="views"/>)</dt>
<dd><p>
    <dl>

    <dt>&IMG.VIEWER; <ref id="TableViewerWindow">Data Window</ref></dt>
    <dd><p>Displays the table rows and columns in a scrollable viewer so you
        can see the cell contents themselves.
        </p></dd>

    <dt>&IMG.PARAMS; <ref id="ParameterWindow">Parameters Window</ref></dt>
    <dd><p>Displays table "parameters", that is metadata which applies to the
        whole table.
        </p></dd>

    <dt>&IMG.COLUMNS; <ref id="ColumnInfoWindow">Columns Window</ref></dt>
    <dd><p>Displays metadata about each column such as data type, units,
        description, UCDs etc.
        </p></dd>

    <dt>&IMG.SUBSETS; <ref id="SubsetWindow">Subsets Window</ref></dt>
    <dd><p>Displays the currently defined 
        <ref id="subsets" plaintextref="yes">row subsets</ref>
        and enables new ones to be defined.
        </p></dd>

    <dt>&IMG.STATS; <ref id="StatsWindow">Statistics Window</ref></dt>
    <dd><p>Displays a window for calculating 
        statistical quantities for the values in each
        column of the table.
        </p></dd>

    </dl>
    </p></dd>

<dt>Graphics windows</dt>
<dd><p>
    <dl>

    <dt>&IMG.PLOT2_HISTOGRAM;
        <ref id="HistogramPlotWindow">Histogram Plot</ref></dt>
    <dd><p>Displays a window for plotting 1D histograms.
        </p></dd>

    <dt>&IMG.PLOT2_PLANE; <ref id="PlanePlotWindow">Plane Plot</ref></dt>
    <dd><p>Displays a window for making various types of plot
        on 2D Cartesian axes.
        </p></dd>

    <dt>&IMG.PLOT2_SKY; <ref id="SkyPlotWindow">Sky Plot</ref></dt>
    <dd><p>Displays a window for making various types of plot
        on the celestial sphere.</p></dd>

    <dt>&IMG.PLOT2_CUBE; <ref id="CubePlotWindow">Cube Plot</ref></dt>
    <dd><p>Displays a window for making various types of plot
        on 3D Cartesian axes.
        </p></dd>

    <dt>&IMG.PLOT2_SPHERE; <ref id="SpherePlotWindow">Sphere Plot</ref></dt>
    <dd><p>Displays a window for making various types of plot
        on 3D axes using spherical polar coordinates.
        </p></dd>

    </dl>
    </p></dd>

<dt>Matching etc (see <ref id="join"/>)</dt>
<dd><p>
    <dl>

    <dt>&IMG.MATCH2; <ref id="MatchWindow">Pair Match Window</ref></dt>
    <dd><p>Displays a dialog for joining tables side-by-side by locating
        rows which match between them.
        </p></dd>

    <dt>&IMG.TAP_DIALOG;
        <ref id="TapTableLoadDialog">TAP Query</ref></dt>
    <dd><p>Displays a dialogue window for querying remote databases using
        the Table Access Protocol (TAP).
        This is a very powerful way to access remote data by writing
        SQL-like queries, and can be used to do joins with remote tables
        as well as simply downloading data.
        </p></dd>

    <dt>&IMG.CDSXMATCH;
        <ref id="CdsUploadMatchWindow">CDS Upload X-Match</ref></dt>
    <dd><p>Displays a dialog window which uses the X-Match
        provided by the Centre de Donn&#x00e9;es astronomiques de Strasbourg
        to allow fast matching local tables with any tables in the remote
        VizieR or SIMBAD databases.
        </p></dd>

    </dl>
    Note that other options for joining tables,
    including matches involving a single table or more than two tables,
    and joining tables top-to-bottom, are available
    from the <label>Joins</label> menu.
    </p></dd>

<dt>Miscellaneous</dt>
<dd><p>
    <dl>

    <dt>&IMG.SAMP; <ref id="SampWindow">SAMP Window</ref></dt>
    <dd><p>Displays a window which displays detail about the current
        status, and allows configuration, of SAMP messaging
        (see <ref id="interop"/>).  Note this button will not be
        visible if TOPCAT is running in PLASTIC mode.
        </p></dd>

    <dt>&IMG.FUNCTION; <ref id="MethodWindow">Available Functions</ref></dt>
    <dd><p>Displays a window containing all the functions which can be used 
        for writing algebraic expressions (see <ref id="jel"/>).
        </p></dd>

    <dt>&IMG.HELP; <ref id="HelpWindow">Help</ref></dt>
    <dd><p>Displays the help browser, open at the entry on the
        Control Window.
        </p></dd>

    <dt>&IMG.EXIT; Exit</dt>
    <dd><p>Queries for confirmation, then exits the application.
        </p></dd>

    </dl>
    </p></dd>

</dl>
</p>

</subsubsect>

<subsubsect id="controlMenus">
<subhead><title>Menu Items</title></subhead>

<p>This section describes actions available from the Control Window
menus additional to those also available from the toolbar
(described in <ref id="controlTools">the previous section</ref>) 
and those common to other windows (described in <ref id="commonMenus"/>).
</p>

<p>The <label>File</label> menu contains the following additional actions:
<dl>

<dt>&IMG.COPY; Duplicate Table</dt>
<dd><p>Adds a new copy of the current
    <ref id="apparent">Apparent Table</ref> to the list of known tables.
    This is like loading in the current table again, except that
    its apparent characteristics become the basic characteristics
    of the copied one, so for instance whatever is the current
    row order becomes the natural order of the new one.
    </p></dd>

<dt>&IMG.DELETE; Discard Table(s)</dt>
<dd><p>Removes the current table from the list and closes and forgets any 
    view windows associated with it.  A discarded table cannot be reinstated.
    You will be prompted to confirm this action.
    Discarding a table in this way <em>may</em> free up memory, for other 
    operations, but often will not; 
    whether it does or not depends on the details of
    where the table comes from.
    This action can also be triggered by hitting the <label>Delete</label>
    key on the keyboard when the table list has keyboard focus.
    If multiple tables are selected at the same time, you will be
    prompted to remove them all.
    </p></dd>

<dt>&IMG.UP; Move Table Up</dt>
<dd><p>Moves the currently selected table up one slot in the tables list.
    This can be convenient for viewing, and it also influences the order
    in which tables are saved when doing a Multiple Table or Session save. 
    This action can also be triggered by hitting <label>ALT-up-arrow</label>
    key on the keyboard when the table list has keyboard focus.
    </p></dd>

<dt>&IMG.DOWN; Move Table Down</dt>
<dd><p>Moves the currently selected table down one slot in the tables list.
    This can be convenient for viewing, and it also influences the order
    in which tables are saved when doing a Multiple Table or Session save.
    This action can also be triggered by hitting <label>ALT-down-arrow</label>
    key on the keyboard when the table list has keyboard focus.
    </p></dd>

<dt>&IMG.SEND; Send Table to ...</dt>
<dd><p>Sends the currently selected table to a selected listening application
    using SAMP or PLASTIC.  Select the desired recipient application from the
    submenu.</p></dd>

<dt>&IMG.LOG; View Log</dt>
<dd><p>Pops up the <ref id="LogWindow">Log Window</ref> to display 
    logging messages generated by the application.
    Intended mainly for debugging.
    </p></dd>

</dl>
</p>

<p>The <label>Views</label> menu contains actions for launching the
windows which give certain views of the table metadata.
These are all provided as toolbar buttons as well.
</p>

<p>The <label>Graphics</label> menu contains actions for launching the
windows which give various plotting and visualisation options.
The most important ones are provided as toolbar buttons as well,
but this menu contains some actions not available elsewhere.
The ones marked "(old)" are the plotting windows that were available 
before TOPCAT version 4; they have a different user interface, are
generally less powerful, and are somewhat deprecated, but still work.
The other non-toolbar options are somewhat experimental.
Items available from this menu and not the toolbar are:
<dl>

<dt>&IMG.PLOT2_TIME; Time Plot</dt>
<dd><p>Displays the <ref id="TimePlotWindow">Time Plot window</ref>
    for plotting time series data.
    This is currently experimental and lacks some useful features.
    </p></dd>

<dt>&IMG.HISTOGRAM; Histogram Plot (old)</dt>
<dd><p>Displays the <ref id="HistogramWindow">old-style Histogram window</ref>
    for plotting 1-d histograms.
    </p></dd>

<dt>&IMG.PLOT; 2D Plot (old)</dt>
<dd><p>Displays the <ref id="PlotWindow">old-style 2D plot window</ref>
    for plotting 2-d scatter plots.
    </p></dd>

<dt>&IMG.PLOT3D; 3D Plot (old)</dt>
<dd><p>Displays the <ref id="Cartesian3DWindow">old-style 3D plot window</ref>
    for plotting 3-d scatter plots on Cartesian axes.
    </p></dd>

<dt>&IMG.SPHERE; Sphere Plot (old)</dt>
<dd><p>Displays the <ref id="SphereWindow">old-style sphere window</ref>
    for plotting 3-d scatter plots on spherical polar axes,
    with or without a radial coordinate.
    </p></dd>

<dt>&IMG.STACK; Stacked Line Plot (old)</dt>
<dd><p>Displays the
    <ref id="LinesWindow">old-style Stacked Line Plot window</ref>
    for plotting multiple vertically stacked line plots
    against a single X coordinate (this functionality is not currently
    duplicated in one of the new-style windows).
    </p></dd>

<dt>&IMG.DENSITY; Density Map (old)</dt>
<dd><p>Displays the <ref id="DensityWindow">old-style Density Map window</ref>
    for plotting 2-d density maps (image-like histograms on a 2-d grid of bins).
    </p></dd>

</dl>
</p>

<p>The <label>Joins</label> menu contains actions for various types of
table join.  The items provided additional to those on the toolbar are:
<dl>

<dt>&IMG.CONCAT; Concatenation Window</dt>
<dd><p>Displays the
    <ref id="ConcatWindow">Contatenate Tables window</ref>,
    which allows you to join two tables top-to-bottom.
    </p></dd>

<dt>&IMG.MULTICONE; Multiple Cone Search</dt>
<dd><p>Displays the
    <ref id="ConeMultiWindow">Multiple Cone Search Window</ref>
    which allows you to crossmatch a local table
    with a remote catalogue exposed via the Cone Search protocol.
    Note this is somewhat deprecated in favour of TAP or CDS X-Match Upload.
    </p></dd>

<dt>&IMG.MULTISIA; Multiple SIA</dt>
<dd><p>Displays the <ref id="SiaMultiWindow">Multiple SIA Window</ref>
    which allows you to crossmatch with a remote image service.
    </p></dd>

<dt>&IMG.MULTISSA; Multiple SSA</dt>
<dd><p>Displays the <ref id="SsaMultiWindow">Multiple SSA Window</ref>
    which allows you to crossmatch with a remote spectrum service.
    </p></dd>

<dt>&IMG.MATCH1; Internal Match</dt>
<dd><p>Displays the <ref id="MatchWindow1">Internal Match Window</ref>
    for finding internal matches between rows in the same table.
    </p></dd>

<dt>&IMG.MATCHN; N-Table Match</dt>
<dd><p>Displays a dialog for matching more than two tables together.
    </p></dd>

</dl>
</p>

<p>The <label>Windows</label> menu contains actions for controlling which
<ref id="views" plaintextref="yes">table view windows</ref>
are currently visible on the screen.
If you have lots of tables and are using various different views of 
several of them, the number of windows on the screen can get out of
hand and it's easy to lose track of what window is where.
The actions on this menu do some combination of 
either hiding or revealing all the various view windows associated
with either the selected table or all the other ones.
Windows hidden are removed from the screen but if reactivated
(e.g. by using the appropriate toolbar button) will come back in the same
place and the same state.  Revealing all the windows associated with
a given table means showing all the view windows which have been opened
before (it won't display windows which have never explicitly been opened).
<dl>

<dt>Show Selected Views Only</dt>
<dd><p>Reveal all view windows associated with the currently selected 
    table and hide all others.
    </p></dd>

<dt>Show Selected Views</dt>
<dd><p>Reveal all view windows which are associated with the currently
    selected table.
    </p></dd>

<dt>Show All Views</dt>
<dd><p>Reveal all view windows associated with all tables.
    </p></dd>

<dt>Hide Unselected Views</dt>
<dd><p>Hide all view windows associated with tables other than the 
    currently selected one.
    </p></dd>

<dt>Hide Selected Views</dt>
<dd><p>Hide all view windows associated with the currently selected table.
    </p></dd>

<dt>Hide All Views</dt>
<dd><p>Hide all the view windows.
    If you get really confused, this is a good one to select to clear up 
    your screen prior to reinstating the ones that you actually want to
    look at.
    </p></dd>

</dl>
Note that the <label>Control Window</label> item (&IMG.CONTROL;) 
on menus on all other windows is also useful for window management -
it brings back the control window if it's been hidden.
</p>

<p>The <label>VO</label> menu groups together those actions which access
remote data sources.  All of these options can also be found in
either the <ref id="LoadWindow">Load Window</ref> toolbar or
the <label>Joins</label> menu.
</p>

<p>The <label>Interop</label> menu contains options relevant to 
tool interoperability (SAMP or PLASTIC).  These items are available
elsewhere on the toolbar or <label>File</label> menu.
</p>

</subsubsect>

</subsect>

<subsect id="views">
<subhead><title>Table View Windows</title></subhead>

<p>Many of the windows you will see within TOPCAT display information
about a single table. 
There are several of these, each displaying a different aspect of
the table data - cell contents, statistics, column metadata etc.
There is one of each type for each of the tables currently loaded,
though they won't necessarily all be displayed at once.
The title bar of these windows will say something like
<label>TOPCAT(3): Table Columns</label>,
which indicates that it is displaying information about the column 
metadata for the table labelled "3:" in the
<ref id="ControlWindow">Control Window</ref>.
</p>

<p>To open any of these windows, select the table of interest in
the Control Window and click the appropriate toolbar button
(or the equivalent item in the <label>Table Views</label> menu).
This will either open up a new window of the sort you have requested,
or if you have opened it before, will make sure it's visible.
</p>

<p>If you have lots of tables and are using various different views of 
several of them, the number of windows on the screen can get out of
hand and it's easy to lose track of what window is where.
In this case the Control Window's <label>Windows</label> menu
(described in <ref id="controlMenus"/>), or the
<label>Window|Control Window</label> menu item in any of the view windows
can be handy to keep them under control.
</p>

<p>The following sections describe each of these table view windows in turn.
</p>

<subsubsect id="TableViewerWindow">
<subhead><title>Data Window</title></subhead>

<figure>
<caption><px>Data Window</px></caption>
<figureimage src="&FIG.TableViewerWindow;"/>
</figure>

<p>The Data Window presents a <ref id="JTable">JTable</ref>
containing the actual cells of the 
<ref id="apparent" plaintextref="yes">Apparent Table</ref>.
You can display it using the <label>Table Data</label> (&IMG.TABLE;) 
button when the chosen table is selected in the
<ref id="ControlWindow">Control Window</ref>'s Table List.
</p>

<p>You can scroll around the table in the usual way. 
In most cases you can edit cells by double-clicking in them, though
some cells (e.g. ones containing arrays rather than scalars) cannot
currently be edited.  If it looks like an edit has taken place, it has.
</p>

<p>There is a grey column of numbers on the left of the JTable 
which gives the row index of each row.  This is the value of the
special Index column, which numbers each row of the original 
(not apparent) table starting at 1.
If the table has been <ref id="order">sorted</ref> these numbers 
may not be in order.
</p>

<p>Note that reordering the columns by dragging their headings around
will change the order of columns in the table's 
<ref id="columns">Column Set</ref> and hence the Apparent Table.
</p>

<p>If you have table with very many columns it can be difficult to
scroll the display sideways so that a column you are interested in
is in view.  In this case, you can go to the 
<ref id="ColumnInfoWindow">Columns Window</ref> and click on the
description of the column you are after in the display there.
This will have the effect of scrolling the Data Window sideways
so that your selected column is visible in the centre of the display
here.
</p>

<p>The following buttons are available in the toolbar:
<dl> 
<dt>&IMG.INCLUDE_ROWS; Subset From Selected Rows</dt>
<dd><p>Defines a new <ref id="subsets">Row Subset</ref> consisting of those
    rows which are currently highlighted.  You can highlight a  
    contiguous group of rows by dragging the mouse over them; 
    further contiguous groups can be added by holding the  
    Control key down while dragging. 
    This action is only available when some rows have been selected.
    </p></dd>

<dt>&IMG.EXCLUDE_ROWS; Subset From Unselected Rows</dt>
<dd><p>Defines a new Row Subset consisting of those rows which are visible
    but currently not highlighted.  You can highlight a
    contiguous group of rows by dragging the mouse over them;
    further contiguous groups can be added by holding the
    Control key down while dragging.
    This action is only available when some rows have been selected.
    </p></dd>
</dl>
</p>

<p>The <label>Subsets</label> menu additionally contains the following item:
<dl>
<dt>&IMG.HIGHLIGHT; Highlight Subset</dt>
<dd><p>This is a submenu in which all the currently defined row subsets
    are listed.  Selecting one of them marks the rows corresponding to that
    subset as if they have been selected.
    </p></dd>
</dl>
</p>

<p>As well as the normal menu, right-clicking over one of the columns
in the displayed table will present a
<label>Column Popup Menu</label>, which provides a convenient
way to do some things with the column in question:
<dl>

<dt>&IMG.MODIFY; Replace Column</dt>
<dd><p>Pops up a
    <ref id="SyntheticColumnQueryWindow">Synthetic Column dialogue</ref>
    to replace this column with a new synthetic one.
    The dialogue is initialised with the same name, units etc as the
    selected column, and with an expression that evaluates to its value.
    You can alter any of these, and the new column will replace the
    old one, which will be hidden and renamed by appending a suffix
    like "_old" to its name.
    </p></dd>

<dt>&IMG.ADD; New Synthetic Column</dt>
<dd><p>Pops up a 
    <ref id="SyntheticColumnQueryWindow">Synthetic Column dialogue</ref> 
    to insert a new synthetic column just after this one.
    </p></dd>

<dt>&IMG.UP; Sort up</dt>
<dd><p>Sorts the table rows according to ascending value of the contents of
    the column.  Only available if some kind of order (e.g. numeric or
    alphabetic) can sensibly be applied to the column.
    </p></dd>

<dt>&IMG.DOWN; Sort down</dt>
<dd><p>Sorts the table rows according to descending value of the contents of
    the column.  Only available if some kind of order (e.g. numeric or
    alphabetic) can sensibly be applied to the column.
    </p></dd>

<dt>&IMG.HIDE; Hide</dt>
<dd><p>Hides the column.  It can be reinstated from the
    <ref id="ColumnInfoWindow">Columns window</ref>.
    </p></dd>

<dt>&IMG.SEARCH; Search Column</dt>
<dd><p>For string-valued columns, this option allows you to search 
    for values in a column.  If you select it you will be asked to enter
    a regular expression, and then any row which matches that expression
    in this column will be selected (highlighted).  If there's just one
    matching column it will be <ref id="activation">activated</ref> as well.
    The expression obeys normal 
    <webref url="http://en.wikipedia.org/wiki/Regular_expression"
            >regular expression</webref> syntax, so for instance
    you'd enter "<code>.*XYZ.*</code>" to find all rows which contain 
    the string "XYZ".
    </p></dd>

<dt>&IMG.EXPLODE; Explode Array Column</dt>
<dd><p>For columns which have an array value with a fixed number of elements,
    selecting this option will hide the original column and replace it
    by a set of scalar columns, one for each of its elements.
    For instance if a column PMAG contains a 5-element vector of type
    <code>float[]</code> representing magnitudes in 5 different bands,
    selecting this option will hide PMAG and insert 5 new
    <code>Float</code>-type columns PMAG_1...PMAG_5 in its place, 
    each containing one of the magnitudes.
    </p></dd>

</dl>
</p>

</subsubsect>


<subsubsect id="ParameterWindow">
<subhead><title>Parameters Window</title></subhead>

<figure>
<caption><px>Parameters Window</px></caption>
<figureimage src="&FIG.ParameterWindow;"/>
</figure>

<p>The Parameters Window displays metadata which applies to the whole table
(rather than that for each column).  
You can display it using the <label>Table Parameters</label> (&IMG.PARAMS;)
button when the chosen table is selected in the
<ref id="ControlWindow">Control Window</ref>'s Table List.
</p>

<p>In table/database parlance, an item of
per-table metadata is often known as a "parameter" of the table.
At least the number of rows and columns will be listed.
Some table file formats (for instance VOTable and FITS) have provision
for storing other table parameters, while others (for instance CSV)
do not.  In the latter case there may not much much of interest displayed
in this window.
</p>

<p>The top part of the display is a <ref id="JTable">JTable</ref> 
with one row for each
parameter.  It indicates the parameter's name, its value, the type of
item it is (integer, string etc) and other items of interest such as
units, dimensionality or UCD if they are defined.
If a column of the table has no entries
(for instance, the Units column might be empty because none of the
parameters has had units defined for it) then that column may be absent
from the display - in this case the <label>Display</label> menu can be
used to reveal it.
</p>

<p>You can edit some parameter values and descriptions by double-clicking
on them as usual.  
</p>

<p>The bottom part of the display gives an expanded view of a
selected parameter (click on a row in the top part to select one).
This is especially useful if the parameter value is too long to show
fully in the table display.  In most cases you can edit the fields here
to change the value and other characteristics of a parameter.
</p>

<p>The following items are available in the toolbar:
<dl>

<dt>&IMG.ADD; Add Parameter</dt>
<dd><p>Pops up a <ref id="ParameterQueryWindow">New Parameter Window</ref>
    to allow you to add a new parameter to the table.
    </p></dd>

<dt>&IMG.DELETE; Remove Parameter</dt>
<dd><p>If one or more of the parameters displayed in the JTable in this window
    have been selected by clicking on the relevant rows,
    then clicking this button will remove them. 
    Some parameters such as Row Count cannot be removed.
    </p></dd>
</dl>
</p>

</subsubsect>


<subsubsect id="ColumnInfoWindow">
<subhead><title>Columns Window</title></subhead>

<figure>
<caption><px>Columns Window</px></caption>
<figureimage src="&FIG.ColumnInfoWindow;"/>
</figure>

<p>The Columns Window displays a <ref id="JTable">JTable</ref>
giving all the information (metadata)
known about each column in the table.  
You can display it using the <label>Column Info</label> (&IMG.COLUMNS;)
button when the chosen table is selected in the 
<ref id="ControlWindow">Control Window</ref>'s Table List.
</p>

<p>The display may take a little bit
of getting used to, since each <var>column</var> in the main data table
is represented by a <var>row</var> in the JTable displayed here.
The order and widths of the columns of JTable widget can be
changed in the same way as those for the
<ref id="TableViewerWindow">Data Window</ref> JTable,
but this has no effect on the data.
</p>

<p>The leftmost column, labelled "Visible", contains a checkbox in
each row (one for each column of the data table).
Initially, these are all ticked.
By clicking on those boxes, you can toggle them between ticked and
unticked.  When unticked, the column in question will become hidden.
The row can still be seen in this window, but the corresponding data
column is no longer a part of
the <ref id="apparent">Apparent Table</ref>, so will not be seen
in the <ref id="TableViewerWindow">Data Window</ref> or appear in
exported versions of the table.
You can tick/untick multiple columns at once by highlighting a set of
rows by dragging the mouse over them and then using the
<label>Hide Selected</label> (&IMG.HIDE;) or 
<label>Reveal Selected</label> (&IMG.REVEAL;) 
toolbar buttons or menu items.
If you want to hide or reveal all the columns in the table, use the
<label>Hide All</label> (&IMG.HIDE_ALL;) or 
<label>Reveal All</label> (&IMG.REVEAL_ALL;) buttons.
</p>

<p>Each column in the displayed JTable corresponds to one piece of
information for each of the columns in the data table -
column name, description, UCD etc.
Tables of different types (e.g. ones read from different input formats)
can have different categories of metadata.  By default a metadata
category is displayed in this JTable if at least one
table column has a non-blank
value for that metadata category, so for instance if no table columns
have a defined UCD then the UCD column will not appear.
Categories can be made to appear and disappear however by using the
<label>Display</label> menu.
The metadata items are as follows:
<dl>

<dt>Visible</dt>
<dd><p>Indicates whether the column is part of the Apparent Table.
    If this box is not filled in,
    then for most purposes the column will be hidden from display.
    You can toggle visibility by clicking on this column.
    </p></dd>

<dt>Name</dt>
<dd><p>The name of the column.
    </p></dd>

<dt>&column.id.char;ID</dt>
<dd><p>A unique and unchanging ID value for each column.   These are useful
    in defining algebraic expressions (see <ref id="jel"/>) since they are
    guaranteed unique for each column.  Although the column Name can
    be used as well, the Name may not be unique and may not have the
    correct form for use in an algebraic expression.
    </p></dd>

<dt>Class</dt>
<dd><p>The Java class of the items in that column.  You don't have to know
    very much Java to understand these; they are Float or Double for
    floating point numbers; Byte, Short, Integer or Long for integer
    numbers, Boolean for a logical (true/false) flag,
    or String for a string of ASCII or Unicode characters.
    There are other possibilities, but these will cover most.
    The characters '[]' after the name of the class indicates that each
    cell in the column holds an array of the indicated type.
    </p></dd>

<dt>Shape</dt>
<dd><p>Cells of a table can contain arrays as well as scalars.
    If the column contains an array type, this indicates the shape that
    it should be interpreted as.  It gives the dimensions in column-major
    order.  The last element may be a '*' to indicate that the size
    of the array may be variable.  For scalar columns, this item will be blank.
    </p></dd>

<dt>Units</dt>
<dd><p>The units in which quantities in this column are expressed.
    </p></dd>

<dt>Expression</dt>
<dd><p>The algebraic expression defining the values in this column.
    This will only be filled in if the column in question is a
    <ref id="SyntheticColumnQueryWindow">synthetic column</ref> 
    which you have added, rather than one present in
    the data in their original loaded form.
    </p></dd>

<dt>Description</dt>
<dd><p>A textual description of the function of this column.
    </p></dd>

<dt>UCD</dt>
<dd><p>The UCD associated with this column, if one is specified.
    UCDs are <webref url="http://vizier.u-strasbg.fr/doc/UCD.htx">Uniform
    Content Descriptors</webref>, and indicate the semantics
    of the values in this column.
    </p></dd>

<dt>UCD Description</dt>
<dd><p>If the string in the UCD column is the identifier of a known UCD,
    the standard description associated with that UCD is shown here.
    </p></dd>

</dl>
There may be other items in the list specific to the table in question.
</p>

<p>You can edit column names and some other entries in this JTable by 
double-clicking on them as usual.
</p>

<p>The order in which the rows are presented is determined
by the table's current <ref id="columns" plaintextref="yes">Column Set</ref>.
You can change the position of a column in the order by dragging the 
grey number cell at the left of the corresponding row up or down;
note this is only possible for currently visible columns
(ones with the Visible checkbox ticked).
Another way to change this order is to drag the column headers left or right
in the <ref id="TableViewerWindow">Data Window</ref>.
</p>

<p>The following buttons are available in the toolbar:
<dl>

<dt>&IMG.ADD; New Synthetic Column</dt>
<dd><p>This pops up a 
    <ref id="SyntheticColumnQueryWindow">Synthetic Column Window</ref>
    which allows you to define a new column in terms of the existing ones
    by writing an algebraic expression.
    The new column will be added by default after the last selected
    column, or at the end if none is selected.
    </p></dd>

<dt>&IMG.ADDSKY; Add Sky Coordinate Columns</dt>
<dd><p>This pops up a 
    <ref id="SkyColumnQueryWindow" plaintextref="yes"
         >Sky Coordinates Window</ref>
    which allows you to define a pair of new sky coordinate columns based on 
    an existing pair of sky coordinate columns.
    </p></dd>

<dt>&IMG.MODIFY; Replace Column With Synthetic</dt>
<dd><p>If a single column is selected, then clicking this button will
    pop up a 
    <ref id="SyntheticColumnQueryWindow" plaintextref="yes"
         >Synthetic Column dialogue</ref>
    to replace the selected column with a new synthetic one.
    The dialogue is initialised with the same name, units etc as the
    selected column, and with an expression that evaluates to its value.
    You can alter any of these, and the new column will replace the
    old one, which will be hidden and renamed by appending a suffix
    like "_old" to its name.
    </p></dd>

<dt>&IMG.HIDE; Hide Selected Column(s)</dt>
<dd><p>If any of the columns are selected, then clicking this button
    will hide them, that is, remove them from the
    current <ref id="columns">Column Set</ref>.
    This has the same effect as deselecting all the checkboxes corresponding
    to these columns in the <label>Visible</label> column.
    </p></dd>

<dt>&IMG.REVEAL; Reveal Selected Column(s)</dt>
<dd><p>If any of the columns are selected, then clicking this button
    will make sure they are visible, that is, that they appear in
    the current <ref id="columns">Column Set</ref>.
    This has the same effect as selecting all the checkboxes corresponding
    to these columns in the <label>Visible</label> column.
    </p></dd>

<dt>&IMG.HIDE_ALL; Hide All Columns</dt>
<dd><p>Clicking this button will hide all the columns in the table;
    the table will have no columns visible in it following this.
    If you just want to see a few columns, it may be convenient to use this
    button and then select a few visible ones individually to reveal.
    </p></dd>

<dt>&IMG.REVEAL_ALL; Reveal All Columns</dt>
<dd><p>Clicking this button will ensure that all the table's columns
    are visible (none are hidden).
    </p></dd>

<dt>&IMG.EXPLODE; Explode Array Column</dt>
<dd><p>If a column is selected which has an array type, clicking this button
    will replace it with scalar-valued columns containing each of its elements.
    For instance if a column PMAG contains a 5-element vector of type
    <code>float[]</code> representing magnitudes in 5 different bands,
    then selecting it and hitting this button will hide PMAG and
    insert 5 new <code>Float</code>-type columns PMAG_1...PMAG_5 
    in its place each containing one of the magnitudes.
    </p></dd>

<dt>&IMG.UP; Sort Selected Up</dt>
<dd><p>If a single column is selected then the table's current 
    <ref id="order">Sort Order</ref> will be set to sort ascending on 
    that column.  Otherwise this action is not available.
    </p></dd>

<dt>&IMG.DOWN; Sort Selected Down</dt>
<dd><p>If a single column is selected then the table's current
    <ref id="order">Sort Order</ref> will be set to sort descending on
    that column.  Otherwise this action is not available.
    </p></dd>

</dl>
</p>

<p>Several of these actions operate on the currently selected column
or columns.  You can select columns by clicking on the corresponding
row in the displayed JTable as usual.  A side effect of selecting a
single column is that the table view in the 
<ref id="TableViewerWindow">Data Window</ref> will be scrolled sideways
so that the selected column is visible in (approximately) the middle of
the screen.  This can be a boon if you are dealing with a table that
contains a large number of columns.
</p>

</subsubsect>

<subsubsect id="SubsetWindow">
<subhead><title>Subsets Window</title></subhead>

<figure>
<caption><px>Subsets Window</px></caption>
<figureimage src="&FIG.SubsetWindow;"/>
</figure>

<p>The Subsets Window displays the 
<ref id="subsets" plaintextref="yes">Row Subsets</ref>
which have been defined.
You can display it using the <label>Row Subsets</label> (&IMG.SUBSETS;)
button when the chosen table is selected in the
<ref id="ControlWindow">Control Window</ref>'s Table List.
</p>

<p>The subsets are displayed in a <ref id="JTable">JTable</ref>
widget with a row for each subset.  The columns of the JTable
are as follows:
<dl>
<dt>&subset.id.char;ID</dt>
<dd><p>A unique and unchanging identifier for the subset, which consists of
    a "&subset.id.char;" character (underscore) followed by an integer.  
    This can be used to refer
    to it in <ref id="jel" plaintextref="yes">expressions</ref>
    for synthetic columns or other subsets.
    </p>

    <p><strong>Note:</strong> in previous versions of TOPCAT the hash
    sign ("#") was used instead of the underscore for this purpose;
    the hash sign no longer has this meaning.
    </p></dd>

<dt>Name</dt>
<dd><p>A name used to identify the subset.  It is ideally, but not necessarily,
    unique.
    It can be edited (double-click on the cell) to change the name.
    </p></dd>

<dt>Size</dt>
<dd><p>The number of rows in this subset.  This column is usually 
    filled in when the subset is defined, but it is
    not guaranteed to remain correct if the table data change,
    since counting may be an expensive
    process so it is not automatically done with every change.
    If values in this column are blank or suspected incorrect, 
    a recount can be forced by using the
    <label>Count Subsets</label> (&IMG.COUNT;) button described below.
    </p></dd>

<dt>Fraction</dt>
<dd><p>Shows the same information as the preceding <label>Size</label> column,
    but as a percentage of the total number of rows in the table.
    </p></dd>

<dt>Expression</dt>
<dd><p>If the subset has been defined by an algebraic expression, this will be
    here.  It can be edited (double-click on the cell) 
    to change the expression.
    </p></dd>

<dt>Column &column.id.char;ID</dt>
<dd><p>If the subset has been defined by equivalence with a boolean-valued
    column, this will show the &column.id.char;ID of
    the column that it came from (see <ref id="ColumnInfoWindow"/>).
    </p></dd>
</dl>
</p>

<p>Entries in the <label>Name</label> and <label>Expression</label> columns
can be edited by double-clicking on them in the normal way.
</p>

<p>The following toolbar buttons are available in this window:
<dl>

<dt>&IMG.ADD; New Subset</dt>
<dd><p>Pops up the 
    <ref id="SyntheticSubsetQueryWindow">Algebraic Subset Window</ref>
    to allow you to define a new subset algebraically.
    </p></dd>

<dt>&IMG.SAMPLE; Add Sample Subset</dt>
<dd><p>Pops up a dialogue window to allow you to define a new subset
    consisting of every <m>N</m>'th row of the table.
    </p></dd>

<dt>&IMG.HEAD; Add Head Subset</dt>
<dd><p>Pops up a dialogue window to allow you to define a new subset
    consisting of the first <m>N</m> rows of the table.
    </p></dd>

<dt>&IMG.TAIL; Add Tail Subset</dt>
<dd><p>Pops up a dialogue window to allow you to define a new subset
    consisting of the last <m>N</m> rows of the table.
    </p></dd>

<dt>&IMG.DELETE; Remove Subset</dt>
<dd><p>Deletes one of the subsets in the list.
    Once deleted, a subset cannot be recovered.
    Note that attempts to use its name or _ID in algebraic expressions
    which you add or modify in the future will fail, though its use in 
    existing expressions will continue to work.
    </p></dd>

<dt>&IMG.INVERT; Invert Subset</dt>
<dd><p>Creates a new subset which is the complement of the selected one.
    The new one will include all the rows which are excluded by the
    selected one (and vice versa).
    To use this action, first select a subset by clicking on its row
    in the JTable.
    </p></dd>

<dt>&IMG.TO_COLUMN; To Column</dt>
<dd><p>If one of the rows in the JTable is selected, this will turn that
    subset into a new column.  It will pop up the
    <ref id="SyntheticColumnQueryWindow">Synthetic Column Window</ref>, 
    filled in
    appropriately to add a new boolean column to the table based on
    the selected subset.  You can either accept it as is, or
    modify some of the fields.
    To use this action, first select a subset by clicking on its row
    in the JTable.
    </p></dd>

<dt>&IMG.HIGHLIGHT; Highlight Subset</dt>
<dd><p>Highlights the contents of this subset by marking the rows visibly
    in the <ref id="TableViewerWindow">data window</ref> and also ensuring
    that the rows are visible in any plot windows.  This replicates what
    happens when the subset is first created.
    </p></dd>

<dt>&IMG.COUNT; Count Rows</dt>
<dd><p>Counts how many rows are in each subset and displays this in the
    <label>Size</label> column.  
    This forces a count or recount to fill in or update these values.
    </p></dd>

<dt>&IMG.BROADCAST; Broadcast Subset</dt>
<dd><p>Causes the selected subset to be broadcast using SAMP or PLASTIC to other
    listening applications.  Any other listening application which is
    displaying the same table is then invited to highlight the selection
    of rows corresonding to the selected subset.
    This option and the corresponding <label>Send Subset to ...</label>
    option are also available from the <label>Interop</label> menu.
    See <ref id="interop"/> for more information about tool
    interoperability.
    </p></dd>

</dl>
</p>

<p>The following additional menu items are available:
<dl>
<dt>&IMG.SEND; Send subset to ...</dt>
<dd><p>As for the <label>Broadcast Subset</label> item above, but sends
    the subset to only a single selected application.  A submenu will
    give a list of all the currently registered applications which can
    make sense of a subset.  If there are none, this item will be disabled.
    </p></dd>

<dt>&IMG.RECOUNT; Autocount rows</dt>
<dd><p>Normally, the <label>Size</label> and <label>Fraction</label>
    columns of the displayed table (see above) are filled in as soon 
    as a new subset is defined.  However for very large tables this could
    be slow - if you want to prevent this autocounting
    you can deselect this menu item.  In this case the Size and Fraction
    columns will only be filled in when the <label>Count</label> (&IMG.COUNT;)
    button is hit or if TOPCAT finds out the size as the result of some
    other operation (such as plotting).
    </p></dd>
</dl>
</p>

</subsubsect>

<subsubsect id="StatsWindow">
<subhead><title>Statistics Window</title></subhead>

<figure>
<caption><px>Statistics Window</px></caption>
<figureimage src="&FIG.StatsWindow;"/>
</figure>

<p>The Statistics Window shows statistics for the values in each
of the table's columns.  
You can display it using the <label>Column Statistics</label> (&IMG.STATS;)
button when the chosen table is selected in the 
<ref id="ControlWindow">Control Window</ref>'s Table List.
</p>

<p>The calculated values are displayed in a
<ref id="JTable">JTable</ref>  widget with a row for each
column in the main table, and a column for each of a number of
statistical quantities calculated on <ref id="subsets">some or all</ref> of
the values in the data table column corresponding to that grid row.
The following columns are shown by default:
<dl>
<dt>Name</dt>
<dd><p>The name of the column in the main table represented by this grid row.
    </p></dd>

<dt>Mean</dt>
<dd><p>The mean value of the good cells.  For boolean columns, this is
    the proportion of good cells which are True.
    </p></dd>

<dt>SD</dt>
<dd><p>The population standard deviation of the good cells.
    </p></dd>

<dt>Minimum</dt>
<dd><p>The minimum value.  For numeric columns the meaning of this is quite
    obvious.  For other columns, if an ordering can be reasonably defined
    on them, the 'smallest' value may be shown.  For instance string
    values will show the entry which would be first alphabetically.
    </p></dd>

<dt>Maximum</dt>
<dd><p>As minimum, but shows the largest values.
    </p></dd>

<dt>nGood</dt>
<dd><p>The number of non-blank cells.
    </p></dd>

</dl>
Several additional items of statistical information are also calculated,
but the columns displaying these are hidden by default to avoid clutter.
You can reveal these by using the <label>Display</label> menu:
<dl>

<dt>Index</dt>
<dd><p>The index of the column in the table, i.e. the order in which
    it is displayed.
    </p></dd>

<dt>&column.id.char;ID</dt>
<dd><p>The unique identifier label for the column in the main table.
    </p></dd>

<dt>Sum</dt>
<dd><p>The sum of all the values in the column.  For boolean columns this
    is a count of the number of True values in the column.
    </p></dd>

<dt>Variance</dt>
<dd><p>The population variance of the good cells.
    </p></dd>

<dt>Sample SD</dt>
<dd><p>The sample standard deviation of the good cells.
    </p></dd>

<dt>Sample Variance</dt>
<dd><p>The sample variance of the good cells.
    </p></dd>

<dt>Median Absolute Deviation</dt>
<dd><p>The median of absolute deviations from the median:
    <code>median(abs(x-median(x))</code>.
    This is a robust measure of statistical dispersion.
    </p></dd>

<dt>Scaled Median Absolute Deviation</dt>
<dd><p>The <label>Median Absolute Deviation</label> (see above) multiplied
    by 1.4826.
    This is supposed to be a consistent estimator for the standard deviation,
    on the assumption of a normal distribution.
    </p></dd>

<dt>Skew</dt>
<dd><p>Gamma 1 measure of skewness of the value distribution.
    </p></dd>

<dt>Kurtosis</dt>
<dd><p>Gamma 2 measure of peakedness of the value distribution.
    </p></dd>

<dt>Row of min</dt>
<dd><p>The index of the row in the main table at which the minimum value
    occurred.
    </p></dd>

<dt>Row of max</dt>
<dd><p>The index of the row in the main table at which the maximum value
    occurred.
    </p></dd>

<dt>nBad</dt>
<dd><p>The number of blank cells; the sum of
    this value and the Good cells value will be the same for each
    column.
    </p></dd>

<dt>Cardinality</dt>
<dd><p>If the column contains a small number of distinct values
    then that number, the column's <em>cardinality</em> will be shown here.
    Cardinality is the number of distinct values which appear in that column.
    If the number of values represented is large (currently &gt;50) or
    a large proportion of the non-bad values (currently &gt;75%) then
    no value is shown.
    </p></dd>

</dl>
</p>

<p>In addition, some <label>quantile</label> values can calculated on demand 
(by selecting their values in the <label>Display</label> menu, as for
the previous list).  The available values are:
<dl>
<dt>Q001:</dt>
<dd><p>value below which 0.1% of rows fall</p></dd>
<dt>Q01:</dt>
<dd><p>value below which 1% of rows fall (1st percentile)</p></dd>
<dt>Quartile1:</dt> 
<dd><p>value below which 25% of rows fall (first quartile)</p></dd>
<dt>Median:</dt>
<dd><p>value below which 50% of rows fall (median)</p></dd>
<dt>Quartile3:</dt>
<dd><p>value below which 75% of rows fall (third quartile)</p></dd>
<dt>Q99:</dt>
<dd><p>value below which 99% of rows fall (99th percentile)</p></dd>
<dt>Q999:</dt>
<dd><p>value below which 99.9% of rows fall</p></dd>
</dl>
These are considerably more expensive to calculate than the other 
statistical quantities, and so they are not provided by default.
If you attempt to calculate them for large tables, 
you may get a message saying that there is insufficient memory.
</p>

<p>The quantities displayed in this window are not necessarily those for
the entire table; they are those for a particular
<ref id="subsets" plaintextref="yes">Row Subset</ref>.
At the bottom of the window is the <label>Subset For Calculations</label>
selector, which allows you
to choose which subset you want the calculations to be done for.
By clicking on this you can calculate the statistics for different
subsets.
When the window is first opened, or when it is invoked from a menu
or the toolbar in the <ref id="ControlWindow">Control Window</ref>,
the subset will correspond to the current row subset.
</p>

<p>The toolbar contains the following extra buttons:
<dl>

<dt>&IMG.SAVE; Save as Table</dt>
<dd><p>Clicking this button will save the quantities displayed in this
    window to a table on disk.  It can be saved in any of the tabular
    formats which TOPCAT understands.
    </p></dd>

<dt>&IMG.IMPORT; Import as Table</dt>
<dd><p>The table of statistical quantities displayed by this window 
    (rows corresponding to input table columns and columns corresponding
    to statistical quantities) is itself a table.  By clicking this 
    button it can be loaded into TOPCAT as a new table and manipulated
    in all the usual ways.  This has the same effect as saving the
    statistics to file (see previous button) and then reloading that file.
    </p></dd>

<dt>&IMG.REDO; Recalculate</dt>
<dd><p>Once statistics have been calculated for a given subset they are
    cached and not normally recalculated again.
    Use this button if you want to force a recalculation because the
    data may have changed.
    </p></dd>

</dl>
</p>

<p>For a large table the calculations may take a little while.  While they are
being performed you can interact with the window as normal,
but a progress bar is shown at the bottom of the window.
If you initiate a new calculation (by pushing the Recalculate button or
selecting a new subset) or close the window during a calculation,
the superceded calculation will be stopped.
</p>

</subsubsect>

</subsect>

<subsect id="plot2">
<subhead><title>Plot Windows</title></subhead>

<p><em>This section describes the plotting windows introduced at TOPCAT
version 4.
These provide most of the same functionality as the 
<ref id="GraphicsWindow" plaintextref="yes">old-style plot windows</ref>,
but additionally much more flexibility, configurability, extensibility
and better performance and capabilities for making visual sense
of very large data sets.
</em></p>

<p>TOPCAT has a number of windows for performing data visualisation of
various kinds.  These share various characteristics which are described
in the first subsection below; the specific windows themselves 
are described in the later subsections.
</p>

<p>Six plot windows are currently available (one is experimental):
<ul>
<li>&IMG.PLOT2_HISTOGRAM;
    <ref id="HistogramPlotWindow">Histogram Plot</ref></li>
<li>&IMG.PLOT2_PLANE; <ref id="PlanePlotWindow">Plane Plot</ref></li>
<li>&IMG.PLOT2_SKY; <ref id="SkyPlotWindow">Sky Plot</ref></li>
<li>&IMG.PLOT2_CUBE; <ref id="CubePlotWindow">Cube Plot</ref></li>
<li>&IMG.PLOT2_SPHERE; <ref id="SpherePlotWindow">Sphere Plot</ref></li>
<li>&IMG.PLOT2_TIME; <ref id="TimePlotWindow">Time Plot</ref>
                     (experimental)</li>
</ul>
More may be introduced in future releases.
</p>

<p>The rest of this section describes the plotting functions in detail.
</p>

<subsubsect>
<subhead><title>Differences From Old-Style Plot Windows</title></subhead>

<p>A brief summary of improvements these windows offer over the 
<ref id="GraphicsWindow">old-style</ref> plot windows is:
<dl>

<dt>New Sky Coordinate Plot</dt>
<dd><p>
    <ul>
    <li>Choice of projection: Sin (rotatable), Aitoff, Plate Carr&#x00e9;e</li>
    <li>Data and view sky coordinate systems selected separately:
        options are equatorial, galactic, supergalactic, ecliptic</li>
    <li>Sky coordinate grid labelled, configurable and visible at all zooms</li>
    </ul>
    </p></dd>

<dt>New data plot options</dt>
<dd><p>
    <ul>
    <li>Vectors</li>
    <li>Ellipses (with position angle)</li>
    <li>Pair data point links</li>
    <li>Contours</li>
    <li>Variable size markers</li>
    </ul>
    </p></dd>

<dt>Improved interactive response</dt>
<dd><p>
    <ul>
    <li>Various mouse wheel and drag actions
        pan and zoom the plot instantly</li>
    <li>In 3d plots right mouse button recentres cube on selected point</li>
    <li>In 3d plots zooming zooms data in the cube rather than enlarging the
        cube wireframe itself</li>
    <li>Many controls are sliders which update the plot as you slide</li>
    </ul>
    </p></dd>

<dt>Better support for large datasets</dt>
<dd><p>Several features have been introduced to provide more meaningful
    visualisation of large datasets.  Improved density-like plots
    and contours give you better ways to understand plots containing
    many more points than there are pixels to plot them on.
    There is separately some improvement in scalability:
    you can typically get reasonable interactive performance
    up to about 10 million points depending on available memory etc and what
    you're doing (though there are reports of it working with several
    10<sup>8</sup> points).
    The intention is to improve this limit further in future.
    </p></dd>

<dt>New plot shading modes</dt>
<dd><p>Density colour coding for all plot types,
    with colour map either absolute or modifying dataset base colour.
    The result is something that looks like a scatter plot at low
    densities and a density plot for high densities, and
    generally means that you can easily make quantitative sense of
    overcrowded regions of a scatter plot.
    Flat, transparent and aux colour coding still available as before.
    </p></dd>

<dt>Improved axis labelling</dt>
<dd><p>
    <ul>
    <li>Choice of font size and style</li>
    <li>Option of LaTeX input for non-ASCII characters etc</li>
    <li>Log axes labelled better</li>
    <li>Minor tick option</li>
    </ul>
    </p></dd>

<dt>Analytic function plotting in 2D</dt>
<dd><p>Plot functions of X or Y coordinate using algebraic expression language.
    </p></dd>

<dt>Configurability</dt>
<dd><p>Many more configuration options including legend placement,
    grid display and colour, antialiasing, text label crowding limits etc etc.
    </p></dd>

</dl>
</p>

<p>The new windows allow you to assemble a stack of layers representing
different plot types of different data sets on the same axes.
The user interface for controlling this is quite a bit different than
for the old-style plot windows, and is described in the subsequent sections.
However, making a simple plot is still simple: select a table, select
the columns, and you're off.
</p>

<p>Some features from the old-style plots that are <em>not</em>
currently (v4.1) available in the new-style plots are:
<ul>
<li>the stacked line plot</li>
<li>true RGB density maps (though density shading modes will often do as good
    or a better job)</li>
<li>fogging in 3D plots</li>
<li>plot titles</li>
</ul>
The intention is to introduce some of all of these in a future release,
possibly informed by user demand.
</p>

</subsubsect>

<subsubsect id="StackPlotWindow">
<subhead><title>Window Overview</title></subhead>

<figure>
<caption><px>Plot window</px></caption>
<figureimage src="&FIG.StackPlotWindow;"/>
</figure>

<p>Plot windows consist of two main parts:
the <label>Plot Panel</label> containing the actual plotted graphics
(by default, at the top),
and the <label>Control Panel</label> (by default, at the bottom).
The Control Panel is where you configure what will be plotted.
For a simple scatter plot it may just be a case of selecting what
columns to plot against each other, but it can get quite detailed.
If you want more screen space to play with, it can be helpful
to float the control panel into a separate window using the
<label>Float Controls</label> (&IMG.FLOAT;) toolbar button;
you can find this button in both the main and the control panel toolbars.
To unfloat the control panel, either just close the control panel window,
or click the Float Controls toolbar button again.
With floating controls, the window looks like the following figure.
</p>

<figure>
<caption><px>Plot window with floated control panel</px></caption>
<figureimage src="&FIG.StackPlotWindow_float;"/>
</figure>

<p>The <label>control panel</label>
itself has two main parts: a <label>control stack</label> on the left
containing currently active controls (represented by names and icons),
and a <label>detail panel</label>
on the right which shows information about the currently selected control.
Click on one of the control entries on the left to see its details
on the right.
Different controls have different detail panels, but in general each
one will have multiple tabs for configuring different things.
You can select these by clicking on the tab names.
A good way to learn about the options is to click on
the different controls and their tabs to see what's available
and experiment with the various options to see what happens to the plot,
but all the panels and tabs are also explained in this manual.
The control panel also has a toolbar at the top, used for
adding and removing controls from the stack.
</p>

<p>The <label>control list</label> has two types of entry:
<dl>
<dt>Fixed controls:</dt>
<dd><p>These control the overall plot appearance.
    In the above figure, the fixed controls
    <label>Axes</label> (&IMG.AXIS_EDIT;) and
    <label>Legend</label> (&IMG.LEGEND;) are visible.
    </p>
    <p>The different fixed controls are described in
    <ref id="plot2FixedControls"/>.
    </p></dd>
<dt>Layer controls:</dt>
<dd><p>These determine the actual data that will be plotted and what
    graphical form it takes; each control contributes a layer or
    layers to the plot.
    To add a layer control, use the toolbar just above; each button
    with a little green "+" adds a control of the corresponding type.
    To remove a layer control, select it and use the
    <label>Remove Current Layer</label> (&IMG.DELETE;) button in the
    toolbar.  You can also use the <label>Layers</label> menu at the top
    of the main window to add and remove layers.
    </p>
    <p>The checkbox beside each control determines whether it is currently
    active; if unchecked, any plotting instructions is contains will be
    ignored.
    You can set them active or inactive by clicking on the checkboxes.
    </p>
    <p>You can also drag each control up or down by dragging with the
    grab handle (&IMG.UP_DOWN;).  Layers lower down the list are plotted
    later (perhaps obscuring earlier one), so you can drag them up and
    down until you have the layers you want on top.
    </p>
    <p>The different layer controls are described in
    <ref id="plot2LayerControls"/>.
    </p></dd>
</dl>
</p>

<p>In the foot of the window, there are also four other small panels:
<dl>
<dt>Position Panel</dt>
<dd><p>When the cursor is positioned over the plot itself, this reports
    its position in data coordinates.  In some cases, such as 
    3-d plots, this may not be possible, in which case it's blank.
    </p></dd>
<dt>Count Panel</dt>
<dd><p>Displays the number of points currently plotted
    and the total number of points represented by the plot.
    The total (the second figure) is the number of positions in all
    the plotted data sets, and the current number (the first figure)
    excludes those in subsets not currently plotted and those outside
    the bounds of the visible plot.
    </p></dd>
<dt>Navigation Help</dt>
<dd><p>Shows some reminders for what different mouse gestures do.
    Little icons are supposed to represent clicking and dragging different
    mouse buttons and the mouse wheel.  Note the content changes according
    to where the mouse is on the plot, since that affects navigation
    behaviour.  For more information see <ref id="plot2Navigation"/>.
    Clicking on the &IMG.SMALL_CLOSE; button
    will make this panel go away.
    </p></dd>
<dt>Progress Bar</dt>
<dd><p>If something slow is happening
    you may see a progress bar at the bottom of the screen while you wait.
    Unless you are plotting several million points, you may not see this
    at all.
    For slow data loads, this will always be displayed.
    For actions like actually drawing the plot and turning a blob into
    a subset selection you can choose whether progress is shown using
    the <label>Show Plot Progress</label> (&IMG.PROGRESS;)
    button in the toolbar.  It's nice to know that something's going on,
    but it can be distracting; displaying progress also slows the plot down
    a bit.
    </p></dd>
</dl>
</p>

<p>The <label>main toolbar</label> at the top of the window
contains the following actions (repeated in the menus):
<dl>

<dt>&IMG.FLOAT; Float Controls</dt>
<dd><p>Puts the Control Panel into a floating window rather than at
    the bottom of the plot window, as described above.
    Once floating, the control panel can be joined back to the main window
    by clicking this button again.
    </p></dd>

<dt>&IMG.BLOB_SUBSET; Draw Subset Region</dt>
<dd><p>Allows you to draw a region on the screen defining a new 
    <ref id="subsets">Row Subset</ref>.  When you have finished 
    drawing it, click this button again to indicate you're done.
    See <ref id="plot2-subsets"/> for more details.
    </p></dd>

<dt>&IMG.VISIBLE_SUBSET; Subset From Visible</dt>
<dd><p>Defines a new <label>Row Subset</label>
    consisting of only the points which
    are currently visible on the plotting surface.
    See <ref id="plot2-subsets"/> for more explanation.
    </p></dd>

<dt>&IMG.REDO; Replot</dt>
<dd><p>Redraws the current plot.  It is usually not necessary to
    use this button, since if you change any of the plot characteristics
    with the controls in this window the plot will be redrawn
    automatically.  However if you have changed the data, e.g. by
    editing cells in the <ref id="TableViewerWindow">Data Window</ref>,
    or by redefining a subset, the plot is not automatically redrawn.
    Clicking this button redraws the plot taking account of any changes
    to the table data.
    </p></dd>

<dt>&IMG.RESIZE; Rescale</dt>
<dd><p>Rescales the axes of the current plot so that it contains all
    the data points in the currently selected subsets.
    By default the plot will be initially scaled like this,
    but it it may have changed
    because of changes in the subset selection or from zooming in or out.
    </p></dd>

<dt>&IMG.AXIS_LOCK; Lock Axes</dt>
<dd><p>Usually, when the data plotted has changed significantly,
    the axes are automatically rescaled so that all the points are visible.
    The application makes a guess about when it's a good idea to do this
    automatic rescaling.  If you don't want it to auto-rescale, set this
    toggle button, and it won't rescale unless it really has to.
    This is not available for the <label>Sky Plot</label>.
    </p></dd>

<dt>&IMG.SKETCH; Sketch Frames</dt>
<dd><p>If selected causes intermediate "sketch" frames to be drawn when
    navigating around very large plots.
    For plots that take a long time (at least a non-negligable fraction
    of a second) to draw, if this option is selected then when
    navigating around it will paint intermediate frames based on a subsample
    of the data rather than painting the whole plot at every step.
    This can result in a somewhat flickering appearance, but it means
    that frame updates happen more frequently, so it's a bit more responsive.
    </p></dd>

<dt>&IMG.PROGRESS; Show Plot Progress</dt>
<dd><p>If selected a progress bar at the bottom of the window is active
    when large (slow) plots are in progress.  This can be useful if you
    are navigating round a very large plot so that you can see something
    is happening rather than the application apparently just doing nothing.
    On the other hand a flickering progress bar can be distracting.
    Updating the progress bar may also slow the plot down a little.
    </p></dd>

<dt>&IMG.IMAGE; Export Plot</dt>
<dd><p>Allows you to save the plot in a variety of graphics formats
    using the <ref id="plot2-export">Plot Export</ref> window.
    </p></dd>
</dl>
</p>

<p>The following subsections explain some other features common to
all the plotting windows.
</p>

<subsubsubsect id="plot2Navigation">
<subhead><title>Navigation</title></subhead>

<p>All the plot windows are interactive, and you can navigate around
them using the mouse buttons.  For most plot types the left and right
buttons and the mouse wheel do something;
in 3d plots the middle button is used as well.
</p>

<p>The details of what mouse actions do what depend on which plot
window you are using, and they can also be configured to some extent
using the <label>Navigation</label> tab in the <label>Axes</label>
fixed control in the control stack.
However, as a rule, the actions when used on the body of the plot are these:
<dl>
<dt>&IMG.DRAG1; Left drag</dt>
<dd><p>Drags the plot around.  Where possible, the same plot position
    stays under the cursor as you drag.  In 2d this pans the plot
    left/right/up/down, and in 3d it rotates it.
    </p></dd>
<dt>&IMG.DRAG3; Right drag</dt>
<dd><p>Stretch zoom.
    Dragging up/down stretches/squashes the plot vertically, and
    dragging left/right stretches/squashes it horizontally.
    The zoom is centered on the position where you start the drag from,
    so that data position stays in the same place on the screen.
    In 3d, the zoom is along the two plot directions most closely
    aligned with the plane of the screen.
    </p></dd>
<dt>&IMG.DRAG2; Middle drag</dt>
<dd><p>Frame zoom.
    Dragging right-and-down or right-and-up drags out a frame;
    when the button is released, the plot will be zoomed in
    to cover area enclosed by the frame.
    Dragging left (and up or down) does something like the opposite,
    you can zoom out using a similar (though not quite the same) mechanism.
    </p></dd>
<dt>&IMG.MOUSE_WHEEL; Mouse wheel</dt>
<dd><p>Spinning the mouse wheel forwards/backwards will zoom in/out.
    In 2d the zoom is around the current position of the mouse,
    and in 3d it is (usually) around the center of the view cube.
    </p></dd>
<dt>&IMG.CLICK1; Left click</dt>
<dd><p>Identifies a point.  If there is a plotted point near the cursor,
    it will plot a marker on it and
    <ref id="activation" plaintextref="yes">activate</ref> it.
    If you click on an empty bit of the plot, any existing activated point
    will be removed, otherwise nothing will happen.
    </p></dd>
</dl>
In the 2d plot types, you can pan or zoom in just one direction
by using the same actions outside of the plot itself.
If you do a pan/zoom action to the left of the Y axis, it will pan/zoom
only vertically, and if you do it below the X axis, it will do it only
horizontally.
</p>

<p>Most of these actions give you some visual feedback on the screen,
showing a rectangle or some arrows to give you a clue what you're doing.
If you find that distracting, you can turn it off using the
<label>Plot|Show Navigation Graphics</label> (&IMG.NAV_DEC;) menu item.
</p>

<figure>
<caption><px>Navigation help panel at the bottom of plot windows</px></caption>
<figureimage src="&FIG.NavigationHelpPanel;"/>
</figure>

<p>In each plot window there is a row at the bottom of the window
giving hints on the currently available navigation actions.
The little icons are each supposed to represent either a 
<em>click</em> (&IMG.CLICK1;) or a <em>drag</em> (&IMG.DRAG1;)
with one of the three buttons pressed,
or a wheel spin (&IMG.MOUSE_WHEEL;),
and are followed by a short description of what it will achieve.
Note these hints change according to where the mouse is currently
positioned on the screen.
Moving the button over this panel will give you some help on the help.
Clicking the &IMG.SMALL_CLOSE; button will make the line disappear,
and you can bring it back with the <label>Window|Show Navigation Help</label>
(&IMG.NAV_HELP;) menu item.
The &IMG.SMALL_HELP; button will bring up a help window specific to
the navigation in this window.
</p>

<p>If you are using a mouse with fewer than three buttons or no wheel,
the following <strong>subsitute gestures</strong> can usually be used:
<dl>
<dt>&IMG.CLICK1; Left button</dt>
<dd><p>If you only have one button, this is it.
    </p></dd>
<dt>&IMG.CLICK3; Right button</dt>
<dd><p>If you only have one button, you can use it with the CTRL key.
    </p></dd>
<dt>&IMG.CLICK2; Middle button</dt>
<dd><p>If you only have one button, you can use it with the SHIFT key.
    If you have two buttons, sometimes pressing them both at once will work.
    </p></dd>
<dt>&IMG.MOUSE_WHEEL; Wheel</dt>
<dd><p>Often a wheel action can be simulated on a trackpad by moving
    two fingers together up or down.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="tableDataControl">
<subhead><title>Table Data Layer Controls</title></subhead>

<p>Most, but not all, of the available 
<ref id="plot2LayerControls" plaintextref="yes">layer controls</ref>
are concerned with plotting table data in some way or other.
In general, these allow you to set up a way to generate a plot layer 
(some generated graphics)
from some selected columns of a given table with a chosen style.
</p>

<p>However, if you have more than one <ref id="subsets">Row Subset</ref>
for a given table, a single control can be used to generate several
layers, one for each subset.
In most cases it makes sense to have the graphics generated by
the different subsets configured similarly, but still visually
distinguishable.
</p>

<p>These table layer controls generally have three tabs:
<label>Position</label>, <label>Subsets</label> and <label>Form</label>.
The Position tab is for specifying coordinates, and depends on the
specific type of the plot and the layer control.
The <label>Subsets</label> and <label>Form</label> control which
row subsets are plotted and how they are displayed,
and a description of how they are arranged follows below.
</p>

<figure>
<caption><px>Subsets tab of a table data layer control</px></caption>
<figureimage src="&FIG.GangLayerControl_subsets;"/>
</figure>

<p>The <label>Subsets</label> tab lists the defined Row Subsets for
the table you have selected in the <label>Position</label> tab.
The subset <label>All</label> is always present;
others may or may not be depending on whether any have been defined.
Note that actions you take in the plot (for instance selecting
a new subset <ref id="plotSubsets">by region</ref>)
can result in new entries being added to this list.
</p>

<p>The list on the left names the subsets with an activation checkbox
and a grab handle; the panel on the right gives the detail for the
currently selected subset.  Select a subset to see/change its detail
by clicking on it.
</p>

<p>For each subset you can select:
<ul>
<li>Whether it is plotted (using the activation checkbox)</li>
<li>The plotting sequence (by dragging it up and down using
    its grab handle)</li>
<li>The default plotting colour</li>
<li>The label with which it is annotated in the legend (if visible)</li>
<li>Whether it appears in the legend at all</li>
</ul>
Although you can select plotting colours in the <label>Form</label> tab as well,
it's generally better to do it here since this changes the colour of
all the forms plotted for a given subset, rather than one form at a time.
</p>

<figure>
<caption><px>Style configuration in Form tab
             of a table data layer control</px></caption>
<figureimage src="&FIG.form-style;"/>
</figure>

<p>The <label>Form</label> tab allows you to select style information
to determine the details of how the plot will look for each layer.
The details differ greatly between layer control types, but they
generally contain two sub-panels for defining the style details,
<label>Global Style</label> and <label>Subset Styles</label>:
<dl>
<dt>Global Style</dt>
<dd><p>Controls the style details for the chosen form, for instance
    marker shape and size.  Options here affect all subsets,
    though by default the colour is taken from the <label>Subsets</label> tab.
    If you want to set the colour the same for all subsets, uncheck the
    <label>By Subset</label> checkbox which will activate the
    <label>Colour</label> selector.
    </p></dd>
<dt>Subset Styles</dt>
<dd><p>If you want to have different subsets represented with different
    styles, for instance different shapes for different subsets,
    you can select a subset here and alter style details for
    that subset only, overriding the Global settings above.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="plot2-subsets">
<subhead><title>Defining Subsets by Region</title></subhead>
<!-- see section plotSubsets -->

<p>The plot windows can be used to make new Row Subset selections.
</p>

<p>If you have panned, zoomed, set the axes manually or 
otherwise navigated the plot so that only the points currently
visible in the plot are the ones you are interested in,
you can click the
<label>New Subset From Visible</label> (&IMG.VISIBLE_SUBSET;) toolbar button.
This defines a subset consisting of all the
points that are visible on the current plot.
This is only useful if the group you are interested in
corresponds to a rectangular region in the plotting space.
</p>

<p>A more flexible way is to draw a region or regions
on the plot which identify the points you are interested in.
To do this, hit the
<label>Draw Subset Region</label> (&IMG.BLOB_SUBSET;)
toolbar button.  Having done this, you can drag the mouse around
on the plot (keep the left mouse button down while you move)
to encircle the points that you're interested in.
As you do so, a translucent grey blob will be left behind -
anything inside the
blob will end up in the subset.  You can draw one or many blobs,
which may be overlapping or not.  If you make a mistake while
drawing a sequence of blobs, you can click the right mouse button,
and the most recently added blob will disappear.
When you're in this region-drawing mode,
you can't zoom or resize the window or change the characteristics
of the plot, and the <label>Draw Subset Region</label> button
appears with a tick over it (&IMG.BLOB_SUBSET_END;) to remind you
you're in it.  Here's what the plot looks like while you're drawing:
</p>

<figure>
<caption><px>Region-Drawing Mode</px></caption>
<figureimage src="&FIG.StackPlotWindow_blob;"/>
</figure>

<p>When you're happy with the region you've defined, click the
&IMG.BLOB_SUBSET_END; toolbar button again.
</p>

<p>In either case, when you have indicated that you want to define a
new row subset, a dialogue box will pop up to ask you its name.
As described in <ref id="subsetDef"/>, it's a good idea to use a
name which is just composed of letters, numbers and underscores.
You can optionally select a subset name which has been used before
from the list, which will overwrite the former contents of that subset.
When you enter a name and hit the <label>OK</label> button,
the new subset will be created and the points in it will be
shown straight away on the plot using a new symbol.
As usual, you can toggle whether the points in this subset are displayed
using the <label>Subsets</label> tab in the
<ref id="GangLayerControl_single">table layer control</ref>.
</p>

</subsubsubsect>

<subsubsubsect id="plot2-export">
<subhead><title>Plot Export Window</title></subhead>

<figure>
<caption><px>Plot export window</px></caption>
<figureimage src="&FIG.PlotExporter;"/>
</figure>

<p>The <label>Plot Export Window</label> can be reached with the
<label>Export plot to file</label> (&IMG.IMAGE;)
toolbar button in any of the plot windows.
</p>

<p>You can select a file in the usual way, and save the plot
in one of the following graphics formats:
<dl>
<dt>png</dt>
<dd><p>
    PNG bitmap.  The background is opaque.
    </p></dd>
<dt>png-transp</dt>
<dd><p>
    PNG bitmap with a transparent background.
    Background pixels that fall outside the plot surface itself
    (for instance outside the axes for a Plane plot or outside the
    celestial sphere for a Sky plot) are transparent.
    </p></dd>
<dt>gif</dt>
<dd><p>GIF bitmap; note the number of colours is limited to 256.
    </p></dd>
<dt>jpeg</dt>
<dd><p>JPEG bitmap; note that this is a lossy format, better suited to
    photographs than plots, and colours will be blurred.
    </p></dd>
<dt>pdf</dt>
<dd><p>Portable Document Format; in most cases this vector format
    gives pretty good output, in particular text will be rendered properly.
    </p></dd>
<dt>eps</dt>
<dd><p>Encapsulated PostScript; PostScript cannot handle transparency,
    which means that in some cases the output will come out wrong.
    PostScript files can also be very large if there are many data points.
    </p></dd>
<dt>eps-gzip</dt>
<dd><p>Just like <label>eps</label>, but the output is gzipped before output.
    </p></dd>
</dl>
</p>

<p>There are two additional controls on the right hand side of this window:
<dl>
<dt>File Format</dt>
<dd><p>Selects the output file format as above.
    The default setting is <label>(auto)</label>, which guesses what
    format you want to use from the filename, and which usually does the
    right thing.
    </p></dd>
<dt>Force Bitmap</dt>
<dd><p>This option only has an effect for vector graphics formats
    (PDF and PostScript).  If selected, it draws the data contents of the
    plot as a pixel map and embeds that into the output file rather than
    plotting each point in the output.  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.  Plot annotations such as axis labels will not be
    affected - they are still drawn as vector text.
    Note that in some cases (e.g. use of the 
    <ref id="mode-auto">auto</ref> or <ref id="mode-density">density</ref>
    shading modes) this kind of pixellisation will happen in any case.
    </p></dd>
</dl>
</p>

<p>Exporting to the pixel-based formats (GIF, JPEG, PNG) is fairly
straightforward: each pixel on the screen appears as one pixel 
in the output file.  PNG is generally recommended.
GIF works well in most cases, but if there are
more than 255 colours some of the colour resolution will be lost.
JPEG can preserve a wide range of colours, but does not support
transparency and is lossy, so close inspection of image features
will reveal blurring.
</p>

<p>When exporting to Portable Document Format (PDF) or
Encapsulated PostScript (EPS), which are vector graphics formats,
there are a few things to consider:
<dl>
<dt>Positional Quantisation</dt>
<dd><p>Some of the shading modes
    (<ref id="mode-density">Density</ref>,
     <ref id="mode-auto">Auto</ref>) are inherently pixellated,
    and others
    (<ref id="mode-flat">Flat</ref>,
     <ref id="mode-aux">Aux</ref>) are not.
    In the former case you will see
    pixel boundaries for the plotted points rather than nice rounded
    edges at high magnifications (though text and axes will always be
    plotted nicely).
    In both cases, at present the <em>positional</em>
    resolution is the same as it would be on the screen, so if you
    have a 400-pixel high plot for instance, there are only 400 possible
    Y coordinates at which a marker can be plotted, which in general
    is not obvious by looking at the output plot.
    In future versions the positional resolution of non-pixellated modes
    may be improved.
    In either case, increasing the size of the plot on the screen
    by resizing the window before performing an export to PDF or EPS
    will reduce the effect of the positional quantisation.
    Note it will also have the effect of making the text labels
    proportionally smaller to the graphics, so you may want to
    increase the font size too.
    </p></dd>

<dt>Transparency</dt>
<dd><p>For technical reasons transparent markers cannot easily
    be rendered when a plot is exported to PostScript.  In some cases
    the plot is done using a bitmap in the PostScript output to permit
    transparency and in some cases the points are just plotted opaque.
    PDF does a bit better, but the compositing of transparent shapes is
    sometimes a bit different on the screen and rendered to a PDF.
    It's a good idea to check the output of screen exports by looking
    at the produced file - if it doesn't look like it should do,
    setting the <label>Force Bitmap</label> option will probably
    make sure it does, though this will also pixellate the plotted symbols.
    There is more discussion of this point in the subsections for
    the various <ref id="ShapeMode">shading modes</ref>.
    </p></dd>

<dt>File Size</dt>
<dd><p>In some cases (2D and 3D scatter plots with many thousands of points
    or more)
    output EPS files can get extremely large; the size scales
    with the number of points drawn, currently with a factor of a few
    hundred bytes per point.  In some cases you can work round this by
    plotting some points as transparent so that the plot is rendered
    as a bitmap (see the discussion of transparency above) which
    scales as the number of pixels rather than the number of points.
    The Gzipped EPS format helps somewhat (though can be slow);
    PDF output is better still.  Even PDF files may be unmanageably large
    for very many points however.
    </p></dd>
</dl>
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="plot2FixedControls">
<subhead><title>Fixed Controls</title></subhead>

<figure>
<caption><px>Fixed controls in control panel stack</px></caption>
<figureimage src="&FIG.ControlStack_fixed;"/>
</figure>

<p>Fixed controls are those controls that appear at the top of
the stack in the control panel, and do not have a checkbox or
a drag handle.
They are used to configure the overall appearance of the plot,
independent of any particular plot layer or data set.
Those common to all plot types are described in the following subsections,
though some plot types may also have their own.
</p>

<subsubsubsect id="AxesControl">
<subhead><title>Axes</title></subhead>

<p>The <label>Axes</label> control (&IMG.AXIS_EDIT;)
has a number of tabs specific to the particular plot type.
These tabs allow you to configure things like the axis ranges,
linear/log axis scaling, axis labelling, grid drawing,
details of the navigation controls and so on.
The different plot types have axis controls that differ significantly
from each other; the specific axis controls are described separately
along with each plot type.
</p>
</subsubsubsect>

<subsubsubsect id="LegendControl">
<subhead><title>Legend</title></subhead>

<p>The <label>Legend</label> control (&IMG.LEGEND;)
is always visible in the plot Control Panel.
It allows you to configure whether and how the plot legend appears.
</p>

<p>This control has two tabs.
</p>

<figure>
<caption><px>Legend control Style tab</px></caption>
<figureimage src="&FIG.LegendControl_style;"/>
</figure>

<p>The <label>Style</label> tab configures the appearance of the legend
panel, and has the folowing options:
<dl>
<dt>Show Legend</dt>
<dd><p>Whether the legend appears in the plot.
    This is set automatically: if only one data set is present
    no legend is shown, but once multiple datasets are present
    the legend is visible.
    But the option can be overridden manually using this control.
    </p></dd>
<dt>Opaque</dt>
<dd><p>If true, the legend has an opaque white background.
    If false, it is transparent, and any plot data underneath it
    is visible.
    </p></dd>
<dt>Border</dt>
<dd><p>If true, a black line border is shown around the legend.
    If false, there is no border.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Legend control Location tab</px></caption>
<figureimage src="&FIG.LegendControl_position;"/>
</figure>

<p>The <label>Location</label> tab configures where on the plot
the legend is drawn (if present).
There are two options, <label>External</label> and <label>Internal</label>.
If Internal is chosen, then a control is activated showing a small box
inside a large box.  Drag the small box around with the mouse to
change the position of the legend inside the plot bounds.
</p>

<p>Note the font used in the legend is currently controlled by the font from
the <label>Axes</label> selector.
</p>

</subsubsubsect>

<subsubsubsect id="ShaderControl">
<subhead><title>Aux Axis</title></subhead>

<p>The <label>Aux Axis</label> control (&IMG.COLORS;) is only
visible when the <ref id="mode-aux" plaintextref="yes">Aux colour mode</ref>
has been selected for one of the data layers;
if no layer is using Aux shading, the control will not appear in the stack.
It controls a single colour scale for points which
are coloured by data value to represent an additional dimension in the data.
</p>

<p>When present, this control has three following tabs.
</p>

<figure>
<caption><px>Aux axis control Map tab</px></caption>
<figureimage src="&FIG.ShaderControl_map;"/>
</figure>

<p>The <label>Map</label> tab controls the aux axis colour map.
It has the following options:
<dl>
<dt>Shader</dt>
<dd><p>Select the colour map from a list of options.
    </p></dd>
<dt>Shade Clip</dt>
<dd><p>Select a sub-range of the full colour map above.
    By default the whole colour map is used, but if you want the range
    of colours in the plot to be formed from only a part of the colour
    band shown in the <label>Shader</label> control,
    you can move the handles in from the end of this slider.
    </p></dd>
<dt>Shade Log</dt>
<dd><p>Whether the aux scale should map linearly or logarithmically
    into the colour map.
    </p></dd>
<dt>Shade Flip</dt>
<dd><p>Whether the aux scale should map forwards or backwards
    into the colour map.
    </p></dd>
<dt>Null Colour</dt>
<dd><p>What colour should be used to represent points with a null value
    for the aux data coordinate. 
    If the associated <label>Hide</label> option is selected,
    then those points will not appear in the plot at all.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Aux axis control Ramp tab</px></caption>
<figureimage src="&FIG.ShaderControl_ramp;"/>
</figure>

<p>The <label>Ramp</label> tab controls the display and annotation of
the colour ramp that displays the colour map on the plot.
It has the following options:
<dl>
<dt>Show Scale</dt>
<dd><p>Whether the aux scale ramp is visible;
    if so an appropriately labelled colour ramp
    appears at the right of the plot.
    The associated <label>Auto</label> option makes this decision
    automatically: if any aux data is plotted, the scale will appear,
    otherwise it won't.
    Deselect Auto if you want to determine visibility by hand.
    </p></dd>
<dt>Aux Axis Label</dt>
<dd><p>Selects the axis label to be displayed near the aux colour ramp
    if it is visible.
    The associated <label>Auto</label> option, if selected, uses the
    name of one of the coordinates supplying aux data;
    deselect Auto if you want to enter a label by hand.
</p></dd>
</dl>
</p>

<figure>
<caption><px>Aux axis control Range tab</px></caption>
<figureimage src="&FIG.ShaderControl_range;"/>
</figure>

<p>The <label>Range</label> tab lets you enter lower and upper values
for the aux data range by hand,
and provides a double slider to restrict the range within these limits.
If either the lower or upper range is left blank,
it will be determined from the data.
</p>

<p>Note the font used for labelling the aux axis is currently controlled by 
the font from the <label>Axes</label> selector.
</p>

</subsubsubsect>


</subsubsect>

<subsubsect id="plot2LayerControls">
<subhead><title>Layer Controls</title></subhead>

<p>The layer controls are controls in the Control Stack
that can be added, removed and
moved around to determine what layers go to make up the contents of a plot.
You can have zero, one or several of each.
Which ones are available is dependent on which plot type you are using
(for instance the Spectrogram control is only available for the Time plot).
Add instances of each control to the control stack by using the
appropriate button from the control panel toolbar (the one in the lower
half of the window) or the corresponding item in the <label>Layers</label>
menu.
</p>

<p>The available layer controls are described in the following subsections.
More may be added in future releases.
</p>

<subsubsubsect id="GangLayerControl_single">
<subhead><title>Position Layer Control</title></subhead>

<p>The <label>Position</label> layer control (&IMG.PLOT_DATA;)
is available for all the plot types.
Most plots start off with one of these in the stack by default,
and you can add a new instance by using the
<label>Add Position Control</label> (&IMG.ADD_PLOT_DATA;) button
in the control panel toolbar,
or the corresponding item in the <label>Layers</label> menu.
</p>

<p>This is the control which is used for most of the data plotting in
the plotting windows.
Each instance of this control in the stack does plotting for a
particular set of positions from a single table.
The set of positions is defined in the <label>Positions</label> tab
as a column name or expression for each
plot coordinate (e.g. for X and Y in a plane plot).
However, the control can generate multiple layers from these positions;
the <label>Subsets</label> tab controls which subsets are plotted
and how each one is identified,
and the <label>Form</label> tab provides many options for what graphics
will be plotted based on the positions.
</p>

<p>This control is a Table Data control as described in
<ref id="tableDataControl"/>.  That section explains the
<label>Subsets</label> tab;
the <label>Position</label> and <label>Form</label> tabs
are described in more detail below.
</p>

<figure>
<caption><px>Position tab of Position layer control,
             for Plane plot</px></caption>
<figureimage src="&FIG.GangLayerControl_position;"/>
</figure>

<p>In the <label>Position</label> tab you enter the base position
coordinates for each plotted point.
This generally means selecting a table and
providing a value (table column or expression) for each
positional coordinate.
When you first open a plot window, TOPCAT gives you a table layer control
by default, and attempts to fill in the positional coordinates with
some reasonable values from the table (for instance the first few
numeric columns).
</p>

<p>Note the details of the <label>Position</label> tab will be
different for different plot types, for instance the Cube plot
has a Z coordinate field alongside X and Y.
</p>

<figure>
<caption><px>Form tab of Position layer control</px></caption>
<figureimage src="&FIG.GangLayerControl_form;"/>
</figure>

<p>The <label>Form</label> tab lets you define how the specified
data set is plotted.
The stack on the left gives a list of forms currently being plotted,
and the panel on the right shows the detailed configuration for the
currently selected form.
</p>

<p>When first added, the stack contains a single entry, <label>Mark</label>,
which plots a marker of a given fixed shape and size.
The colour is by default determined by the setting in the Subsets tab.
For a simple scatter plot, this is all that you need.
However, there are a number of other forms that you can plot as well
or instead of the simple markers - vectors, error bars, ellipses,
contours, text labels etc.  You add a new form to the stack by
clicking on one of the buttons in the toolbar in the tab.
You can remove a form with the <label>Remove</label> (&IMG.DELETE;)
button in the same toolbar.  You can also activate/deactivate them
with the checkbox and move them up and down with the drag handle as usual.
The list of forms that are avaiable depends on the plot type;
the full list is in <ref id="ShapeForm"/>.
</p>

<p>The detail panel of each form depends on the form itself.
It is divided into the following panels, though not all
forms have all the panels.
<dl>
<dt>Shading</dt>
<dd><p>The shading mode controls how points are shaded based on their
    chosen colour.  The various options are described in <ref id="ShapeMode"/>.
    Depending on the mode there may be more settings to fill in here.
    </p></dd>
<dt>Coordinates</dt>
<dd><p>If additional coordinates are required for this form,
    for instance the size of error bars, you need to enter the
    column or expression here.  Each coordinate effectively adds
    another dimension to the plot.
    Many forms, like Mark, do not require any additional coordinates.
    </p></dd>
<dt>Global/Subset Styles</dt>
<dd><p>Controls the style details for the chosen form;
    see <ref id="tableDataControl"/>.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="GangLayerControl_pair">
<subhead><title>Pair Position Layer Control</title></subhead>

<p>The <label>Pair Position</label> layer control (&IMG.PLOT_PAIR;)
allows you to plot symbols linking two positions in the plot space
from the same table.
You can add one of these controls to the stack by using the
<label>Add Pair Control</label> (&IMG.ADD_PLOT_PAIR;) button
in the control panel toolbar,
or the corresponding item in the <label>Layers</label> menu.
</p>

<p>This control is particularly useful for visualising the results
of a crossmatch, and it is used automatically by the
<label>Plot Result</label> (&IMG.MATCHPLOT;) option offered by
some of the <ref id="MatchWindow">Match Window</ref> results.
If you want to plot pairs of points from different input tables,
you first have to create a joined table by using one of the
crossmatch functions.
</p>

<p>It works in a similar way to the
<ref id="GangLayerControl_single">Single Position Layer Control</ref>,
but the <label>Position</label> tab has fields for not one but two sets of
coordinates to fill in.
</p>

<p>This control is a Table Data control as described in
<ref id="tableDataControl"/>.  That section explains the
<label>Subsets</label> tab;
the <label>Position</label> and <label>Form</label> tabs
are described in more detail below.
</p>

<figure>
<caption><px>Position tab of Pair Position layer control,
             for Sky plot</px></caption>
<figureimage src="&FIG.GangLayerControl_pair_position;"/>
</figure>

<p>In the <label>Position</label> tab you enter the pair of position
coordinates for each plotted pair.
This generally means selecting a table and
providing a value (table column or expression) for the first and
second sets of positional coordinates.
</p>

<p>Note the details of the <label>Position</label> tab will be
different for different plot types, for instance the Sky plot has
<label>Lon1</label>, <label>Lat1</label>,
<label>Lon2</label> and <label>Lat2</label>
fields for the first and second longitude/latitude pairs,
while a Plane plot has
<label>X1</label>, <label>Y1</label>, <label>X2</label> and <label>Y2</label>.
</p>

<figure>
<caption><px>Form tab of Pair Position layer control</px></caption>
<figureimage src="&FIG.GangLayerControl_pair_form;"/>
</figure>

<p>The <label>Form</label> tab lets you define how the specified
data set is plotted.
The list on the left gives a list of forms currently being plotted,
and the panel on the right shows the detailed configuration for the
currently selected form.
</p>

<p>The available forms for a pair plot are currently
<ref id="form-marks2">Marks</ref> (&IMG.FORM_MARKS2;)
which draws the points at both ends of the pair, and
<ref id="form-link2">Link</ref> (&IMG.FORM_LINK2;)
which draws a line linking them.
You can configure these, and select them on or off, separately.
The detail panel for these forms are dependent on the form itself
and are described in more detail in <ref id="ShapeForm"/>,
but the detail panels are divided into these parts:
<dl>
<dt>Shading</dt>
<dd><p>The shading mode controls how points are shaded based on their
    chosen colour.  The various options are described in <ref id="ShapeMode"/>.
    Depending on the mode there may be more settings to fill in here.
    </p></dd>
<dt>Global/Subset Styles</dt>
<dd><p>Controls the style details for the chosen form;
    see <ref id="tableDataControl"/>.
    </p></dd>
</dl>
</p>


</subsubsubsect>

<subsubsubsect id="HistogramLayerControl">
<subhead><title>Histogram Layer Control</title></subhead>

<p>The <label>Histogram</label> layer control (&IMG.PLOT_HISTO;),
allows you to plot a 1-dimensional histogram.
It is the main control in the
<ref id="HistogramPlotWindow">Histogram</ref> plot window,
but is also available  in the <ref id="PlanePlotWindow">Plane</ref>
plot window, so you can overplot a histogram on a scatter plot,
if you can think of some reason to do that.
The Histogram window starts off with one of these controls in the stack by
default, but as usual you can add more by using the
<label>Add Histogram Control</label> (&IMG.ADD_PLOT_HISTO;) button
in the control panel toolbar,
or the corresponding item in the <label>Layers</label> menu.
</p>

<p>Each instance of this control in the stack can plot a histogram
of a particular quantity from a particular table.
The value to be histogrammed, and optionally an associated weighting term,
are defined in the <label>Positions</label> tab using column names
or expressions.
However, the control can generate multiple layers from these coordinates;
the <label>Subsets</label> tab controls which subsets are plotted
and how each one is identified,
and the <label>Form</label> tab provides many options for what graphics
will be plotted based on the positions.
</p>

<p>This control is a Table Data control as described in
<ref id="tableDataControl"/>.  That section explains the
<label>Subsets</label> tab;
the <label>Position</label> and <label>Form</label> tabs
are described in more detail below.
</p>

<figure>
<caption><px>Position tab of Histogram layer control</px></caption>
<figureimage src="&FIG.HistogramLayerControl_position;"/>
</figure>

<p>In the <label>Position</label> tab you enter the value of the
<label>X</label> value, the one which is to be binned to generate
the histogram.  This may be a table column name or an expression.
You may also optionally fill in a column name or expression in
the <label>Weight</label> field.  This weights the values as they
are counted; each table row contributes a height value of the 
weighting coordinate to the bin into which its X coordinate falls.
If Weight is not filled in, a value of 1 is assumed.
</p>

<figure>
<caption><px>Form tab of Histogram layer control</px></caption>
<figureimage src="&FIG.HistogramLayerControl_form;"/>
</figure>

<p>The <label>Form</label> tab lets you define how the specified
data set is plotted.  The <label>Global Style</label> and
<label>Subset Style</label> sub-panels control shared and per-subset
configration as described in <ref id="tableDataControl"/>.
The specific configuration options are:
<dl>
<dt>Transparency</dt>
<dd><p>How transparent the bars are.
    </p></dd>
<dt>Bar Form</dt>
<dd><p>Type of histogram bars: filled, open, steps, spikes etc.
    </p></dd>
<dt>Thickness</dt>
<dd><p>Controls line thickness where applicable.
    This is only relevant for bar styles that draw a finite thickness
    line, so has no effect for Filled bars.
    </p></dd>
<dt>Dash</dt>
<dd><p>Controls the dash pattern of the line (solid, dots, dashes etc).
    This is only relevant for bar styles that draw a finite thickness
    line, so has no effect for Filled bars.
    </p></dd>
</dl>
</p>

<p>Histograms have some additional configuration items,
as described in the <ref id="ConfigControl_histobars">Bars</ref>
fixed control.
When a histogram layer control is used in the
<ref id="HistogramPlotWindow">Histogram window</ref>,
those configuration items are found in the 
<label>Bars</label> fixed control, where they control the settings
for all the histogram layers in the plot.
However, if you use a histogram layer in a
<ref id="PlanePlotWindow">Plane</ref> plot,
those items will appear as additional items in the <label>Form</label> tab
and can be controlled separately for each histogram.
</p>


</subsubsubsect>

<subsubsubsect id="SpectrogramLayerControl">
<subhead><title>Spectrogram Layer Control</title></subhead>

<p><em>This control is experimental.
As currently implemented it lacks some important features.
It may be improved or withdrawn in a future version.
</em></p>

<p>The <label>Spectrogram Layer Control</label> (&IMG.PLOT_SPECTRO;)
plots a spectrum at successive (usually, but not necessarily,
regularly-spaced) points in a time series.
It is only available for the <em>experimental</em>
<ref id="TimePlotWindow">Time Plot Window</ref>.
</p>

<figure>
<caption><px>Time Plot window with a Spectrogram layer</px></caption>
<figureimage src="&FIG.SpectrogramLayerControl;"/>
</figure>

<p>This control has two tabs, <label>Data</label> and <label>Style</label>,
described below.
</p>

<figure>
<caption><px>Spectrogram control Data tab</px></caption>
<figureimage src="&FIG.SpectrogramLayerControl_data;"/>
</figure>

<p>The <label>Data</label> tab allows you to specify which values from
a table will generate a spectrogram.
It has the following fields:
<dl>
<dt>Table</dt>
<dd><p>The table supplying the data.
    </p></dd>
<dt>Time</dt>
<dd><p>A table column or expression giving the epoch coordinate at which
    spectra are located.
    This should normally be a time-typed column;
    if it is simply of numeric type it will be interpreted as seconds
    since 1 Jan 1970.
    </p></dd>
<dt>Spectrum</dt>
<dd><p>An array-valued table column giving the spectral data.
    </p></dd>
<dt>TimeWidth</dt>
<dd><p>A table column or expression (variable or constant) giving the
    temporal coverage of a plotted spectrum.
    If not filled in, it is assumed to be the most common
    (median) difference between time points.
    </p></dd>
<dt>Row Subset</dt>
<dd><p>The <ref id="subsets">subset</ref> for which the spectrum should
    be plotted.  To plot multiple subsets (not usually useful with this
    kind of plot) you would need multiple spectrogram layer controls
    in the stack.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Spectrogram control Style tab</px></caption>
<figureimage src="&FIG.SpectrogramLayerControl_style;"/>
</figure>

<p>The <label>Style</label> allows you to configure the way the spectrogram
is plotted.  It has the following fields:
<dl>
<dt>Shader</dt>
<dd><p>Select the colour map from a list of options.
    </p></dd>
<dt>Shade Log</dt>
<dd><p>Whether the aux scale should map linearly or logarithmically
    into the colour map.
    </p></dd>
<dt>Shade Flip</dt>
<dd><p>Whether the aux scale should map forwards or backwards
    into the colour map.
    </p></dd>
<dt>Null Colour</dt>
<dd><p>What colour should be used to represent spectral samples with a null
    value.
    If the associated <label>Hide</label> option is selected,
    then those points will not appear in the plot at all (they will be
    transparent).
    </p></dd>
</dl>
</p>


</subsubsubsect>

<subsubsubsect id="FunctionLayerControl">
<subhead><title>Function Layer Control</title></subhead>

<p>The <label>Function</label> layer control (&IMG.PLOT_FUNCTION;)
is only available for the 
<ref id="PlanePlotWindow">Plane</ref> and
<ref id="HistogramPlotWindow">Histogram</ref> plots.
Use the <label>Layers</label> menu item or corresponding toolbar button to
add an instance to the control stack.
</p>

<figure>
<caption><px>Plane plot with two function layers plotted,
             one as a function of Horizontal axis value, and
             one as a function of Vertical axis value</px></caption>
<figureimage src="&FIG.FunctionLayerControl;"/>
</figure>

<p>This control has three tabs,
<label>Function</label>, <label>Style</label> and <label>Label</label>,
described below.
</p>

<figure>
<caption><px>Function control Function tab</px></caption>
<figureimage src="&FIG.FunctionLayerControl_function;"/>
</figure>

<p>The <label>Function</label> tab defines the function to be plotted
and has the following fields:
<dl>
<dt>Independent Axis</dt>
<dd><p>Which axis the independent variable varies along;
    options are currently
    <label>Horizontal</label> and <label>Vertical</label>.
    </p></dd>
<dt>Independent Variable Name</dt>
<dd><p>Name of the independent variable.
    This is typically <code>x</code> for a horizontal independent variable
    and <code>y</code> for a vertical independent variable,
    but any string that is a legal expression language identifier
    (starts with a letter, continues with letters, numbers, underscores)
    can be used.
    </p></dd>
<dt>Function Expression</dt>
<dd><p>An expression using TOPCAT's <ref id="jel">expression language</ref>
    in terms of the independent variable that defines the function.
    This expression must be standalone - it cannot reference any tables.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Function control Style tab</px></caption>
<figureimage src="&FIG.FunctionLayerControl_style;"/>
</figure>

<p>The <label>Style</label> tab configures the plotting style.
Options are:
<dl>
<dt>Colour</dt>
<dd><p>Colour of the line.
    </p></dd>
<dt>Thickness</dt>
<dd><p>Thickness of the line in pixels.
    </p></dd>
<dt>Dash</dt>
<dd><p>Dash pattern of the line - solid is the default, but various
    options are available.
    </p></dd>
<dt>Antialiasing</dt>
<dd><p>If true, lines are antialiased, which makes them look smoother
    on the screen or bitmapped export images.
    Has no effect on vector export images (PDF, EPS).
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Function control Label tab</px></caption>
<figureimage src="&FIG.FunctionLayerControl_label;"/>
</figure>

<p>The <label>Label</label> tab allows you to choose the text
that appears in the legend.  Options are:
<dl>
<dt>Label</dt>
<dd><p>Gives the label that will appear in the legend.
    By default the function expression is used, but if you want to
    override this you can deselect the associated <label>Auto</label>
    checkbox and enter your own value.
    </p></dd>
<dt>In Legend</dt>
<dd><p>If true, an entry for this function appears in the legend,
    if false it does not.
    Note the setting of this value does not affect whether the legend
    itself appears, which is controlled by the
    <ref id="LegendControl">Legend</ref> control.
    </p></dd>
</dl>
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="ShapeForm">
<subhead><title>Plot Forms</title></subhead>

<p>Plot "forms" are the instructions for what shapes to actually paint
on the plotting surface given some positional data from a table.
The most obvious (<ref id="form-mark">Mark</ref>)
is simply to plot a marker with a fixed size and shape
at each data position.
However, there is a range of other things you might want to do,
including error bars, vectors, contours, text labels, ...
</p>

<p>The options provided are described, with the additional configuration
information required, in the following sections.
Not all are available for every plot type.
</p>

<subsubsubsect id="form-mark">
<subhead><title>Mark Form</title></subhead>

<figure>
<caption><px>Mark form configuration panel</px></caption>
<figureimage src="&FIG.form_mark;"/>
</figure>

<p>The <label>Mark</label> form (&IMG.FORM_MARK;)
simply plots markers with a fixed shape and size.
</p>

<p>Configuration options are:
<dl>
<dt>Shading Mode</dt>
<dd><p>See <ref id="ShapeMode"/>.
    </p></dd>
<dt>Shape</dt>
<dd><p>Marker shape from a list of options.
    </p></dd>
<dt>Size</dt>
<dd><p>Marker size in pixels.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-size">
<subhead><title>Size Form</title></subhead>

<figure>
<caption><px>Size form configuration panel</px></caption>
<figureimage src="&FIG.form_size;"/>
</figure>

<p>The <label>Size</label> form (&IMG.FORM_SIZE;)
plots markers of a fixed shape
whose size varies according to a supplied data coordinate.
The marker size thus represents an additional dimension of the plot.
</p>

<p>The marker size is scaled according to the values of the data.
The data range in the visible part of the plot is determined,
the maximum value is assigned to the maximum marker size,
and the size of each marker is determined as (data value)/(max data value).
Currently data values of zero always correspond to marker size of zero,
negative data values are not represented, and the mapping is linear.
Other options may be introduced in future.
</p>

<p>Note the scaling to size is in terms of screen dimensions (pixels).
For sizes that correspond to actual data values,
the <ref id="form-error">Error</ref> form may be more appropriate.
</p>

<p>The configuration options are:
<dl>
<dt>Shading Mode</dt>
<dd><p>See <ref id="ShapeMode"/>.
    </p></dd>
<dt>Size</dt>
<dd><p>The size coordinate data values.
    Fill this in with a column name or expression from the table
    just like for the positional coordinates.
    </p></dd>
<dt>Shape</dt>
<dd><p>Marker shape from a list of options.
    </p></dd>
<dt>Max Marker Size</dt>
<dd><p>Scales the maximum marker size in pixels.
    Slide this along to scale the sizes of all the markers up or down.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-vector">
<subhead><title>Vector Form</title></subhead>

<figure>
<caption><px>Vector form configuration panel</px></caption>
<figureimage src="&FIG.form_vector;"/>
</figure>

<p>The <label>Vector</label> form (&IMG.FORM_VECTOR;)
plots directed lines from the
data position given delta values for the coordinates.
The plotted markers are typically little arrows, but there are
other options.
</p>

<p>In some cases such delta values may be the actual magnitude required
for the plot, but more often the vector data represents a value which
has a different magnitude or is in different units to the positional data.
As a convenience for this case, the plotter can optionally
(and does by default) scale the magnitudes of all the vectors to make
them a sensible size (so the largest ones are a few tens of pixels long).
This scaling can be adjusted or turned off using the
<label>Scale</label> and <label>Auto Scale</label> options below.
</p>

<p>The configuration options are:
<dl>
<dt>Shading Mode</dt>
<dd><p>See <ref id="ShapeMode"/>.
    </p></dd>
<dt>DeltaX, DeltaY, ...</dt>
<dd><p>The coordinates of the changes in each coordinate which gives the
    vector.  The coordinates here match the coordinates of the plot.
    For sky coordinates, the supplied longitude delta values are
    in degrees and <em>are</em>
    considered to have been already multiplied by cos(latitude).
    </p></dd>
<dt>Arrow</dt>
<dd><p>Arrow shape selected from a range of options.
    </p></dd>
<dt>Scale</dt>
<dd><p>Changes the factor by which all vector sizes are scaled.
    If the arrows are too small, slide it right, if they are too big,
    slide it left.  The scale is logarithmic.
    </p></dd>
<dt>Auto Scale</dt>
<dd><p>If selected, this option will determine the default arrow scale size
    from the data - it will fix it so that the largest arrows are a
    few tens of pixels long by default.
    That scaling can then be adjusted using the <label>Scale</label> slider.
    If unselected, then the default position of the Scale slider corresponds
    to the actual positions given by the submitted delta coordinates.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-error">
<subhead><title>Error Bars Form</title></subhead>

<figure>
<caption><px>Error Bars form configuration panel</px></caption>
<figureimage src="&FIG.form_error;"/>
</figure>

<p>The <label>Error Bars</label> form (&IMG.FORM_ERROR;)
draws symmetric or asymmetric
error bars in some or all of the dimensions of a 1-, 2- or 3-dimensional
Cartesian plot.
The shape of the error "bars" is quite configurable, including
(for 2- and 3-d errors) ellipses, rectangles etc, aligned with the axes
(for rotated ellipses and rectangles,
see the <ref id="form-ellipse">Ellipse</ref> form).
</p>

<p>The configuration options are:
<dl>
<dt>Shading Mode</dt>
<dd><p>See <ref id="ShapeMode"/>.
    </p></dd>
<dt>X Positive Error, X Negative Error, ...</dt>
<dd><p>For each dimension of the plot, you can enter positive and/or
    negative error values as columns or expressions from the table.
    All of these values must be positive; any negative values will
    be ignored.
    If both positive and negative values are filled in for an axis,
    the errors will be asymmetric.
    If the negative value is blank (either because the coordinate is not
    filled in, or because its value is blank for that row),
    the error bars will be symmetric,
    i.e. the negative error bar will be the same size as the positive one.
    If you want to ensure only a positive error bar is plotted,
    enter "<code>0</code>" for the corresponding negative error.
    </p></dd>
<dt>Error Bar</dt>
<dd><p>Error bar shape from a list of options.
    Exact appearance will also depend on the dimensionality of the supplied
    errors.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-ellipse">
<subhead><title>Ellipse Form</title></subhead>

<figure>
<caption><px>Ellipse form configuration panel</px></caption>
<figureimage src="&FIG.form_ellipse;"/>
</figure>

<p>The <label>Ellipse</label> form (&IMG.FORM_ELLIPSE;)
draws an ellipse (or rectangle, or other similar figure) defined by 
major and minor radii and an optional rotation angle.
</p>

<p>The configuration options are:
<dl>
<dt>Shading Mode</dt>
<dd><p>See <ref id="ShapeMode"/>.
    </p></dd>
<dt>Major Radius, Minor Radius</dt>
<dd><p>Two radii for the ellipse, in the same units as the
    position coordinates (which is degrees for the sky plot).
    It doesn't matter whether the major one is larger than the minor one.
    </p></dd>
<dt>Orientation</dt>
<dd><p>Position angle in degrees.
    For the plane plot it is the angle anticlockwise from the X axis
    to the major radius.
    For the sky plot it is the angle from the North pole to the major axis
    in the direction of positive RA.
    If the value is missing (either this field not filled in or blank in
    the data) it is considered to be zero.
    </p></dd>
<dt>Ellipse</dt>
<dd><p>Ellipse shape, selected from a range of options
    (includes also rectangles, crosses etc).
    </p></dd>
<dt>Scale</dt>
<dd><p>Changes the factor by which all ellipse sizes are scaled.
    If the ellipses are too small, slide it right, if they are too big,
    slide it left.  The scale is logarithmic.
    </p></dd>
<dt>Auto Scale</dt>
<dd><p>If selected, this option will determine the default ellipse scale size
    from the data - it will fix it so that the largest ellipses are a few
    tens of pixels long by default.
    That scaling can then be adjusted using the <label>Scale</label> slider.
    If unselected, then the default position of the Scale slider corresponds
    to the actual positions given by the submitted ellipse radii coordinates.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-line">
<subhead><title>Line Form</title></subhead>

<figure>
<caption><px>Line form configuration panel</px></caption>
<figureimage src="&FIG.form_line;"/>
</figure>

<p>The <label>Line</label> form (&IMG.PLOT_LINE;)
draws a point-to-point line joining
up the points making up the data set.
Note that for a large and unordered data set this can lead to a big
scribble on the screen.
</p>

<p>The configuration options are:
<dl>
<dt>Thickness</dt>
<dd><p>Line thickness in pixels.
    </p></dd>
<dt>Dash</dt>
<dd><p>Dash pattern.  The line is solid by default.
    </p></dd>
<dt>Antialiasing</dt>
<dd><p>If true, pixels are blurred to give the line a smoother appearance.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-linearfit">
<subhead><title>Linear Fit Form</title></subhead>

<figure>
<caption><px>Linear Fit configuration panel</px></caption>
<figureimage src="&FIG.form_linearfit;"/>
<!-- Data from VizieR J/A+A/320/79/table4 -->
</figure>

<p>The <label>Linear Fit</label> form (&IMG.FORM_LINEARFIT;)
determines a least-squares best fit of a line to the data points,
optionally weighted by a given value, and plots the corresponding line.
</p>

<p>The configuration options are:
<dl>
<dt>Weight</dt>
<dd><p>Weighting to apply to each point.
    If left blank, no weighting (equivalent to unit weighting) is applied.
    If independent sampling errors <code>E</code> are available for each point,
    a suitable value for this may be <code>1./(E*E)</code>
    (equivalently <code>pow(E,-2)</code>).
    </p></dd>
<dt>Thickness</dt>
<dd><p>Line thickness in pixels.
    </p></dd>
<dt>Dash</dt>
<dd><p>Dash pattern.  The line is solid by default.
    </p></dd>
<dt>Antialiasing</dt>
<dd><p>If true, pixels are blurred to give the line a smoother appearance.
    </p></dd>
</dl>
</p>

<p>As well as drawing the line onto the plot,
the calculated fitting coefficients are
displayed at the bottom of the form configuration panel,
under the heading <label>Report</label>.
Note the coefficients are calculated by subset, and
are only displayed for one subset at a time.
To see the calculated values, select the subset of interest in
the <label>Subset</label> selector.
The reported items are:
<dl>
<dt>Equation</dt>
<dd><p>The equation of the line.
    The basic linear equation is <code>y=m*x+c</code>,
    but if one or both of the axes are plotted logarithmically,
    the fit is performed to take account of this, and the equation
    is displayed accordingly.
    </p></dd>
<dt>c</dt>
<dd><p>The constant intercept of the line on the Y axis.
    </p></dd>
<dt>m</dt>
<dd><p>The line gradient.
    </p></dd>
<dt>Correlation</dt>
<dd><p>Pearson's product moment correlation coefficient.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-label">
<subhead><title>Text Label Form</title></subhead>

<figure>
<caption><px>Text Label form configuration panel</px></caption>
<figureimage src="&FIG.form_label;"/>
</figure>

<p>The <label>Text Label</label> form (&IMG.PLOT_LABEL;)
draws a text label by each point position.
</p>

<p>The configuration options are:
<dl>
<dt>Text</dt>
<dd><p>A column or expression from the table supplying the text to
    write on the plot.  Any data type (string or numeric) is permitted.
    </p></dd>
<dt>Text Syntax</dt>
<dd><p>How to turn the text into characters on the screen.
    <label>Plain</label> and <label>Antialias</label> both take the
    text at face value, but Antialias smooths the characters.
    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.
    <label>LaTeX</label> interprets the text as LaTeX source code
    and typesets it accordingly.
    </p></dd>
<dt>Font Size</dt>
<dd><p>Size of the font in points.
    </p></dd>
<dt>Font Style</dt>
<dd><p>Style of the font - standard, serif or monospaced.
    </p></dd>
<dt>Font Weight</dt>
<dd><p>Whether the font is plain, bold or italic.
    </p></dd>
<dt>Anchor</dt>
<dd><p>The position of the text relative to the data position.
    </p></dd>
<dt>Spacing Threshold</dt>
<dt>Crowding Limit</dt>
<dd><p>These two options control how closely spaced labels can be.
    Labels which are too closely crowded together will simply not be shown,
    since overplotting many labels together ends up with them being illegible.
    The <label>Spacing Threshold</label> slider controls the smallest
    area that a group of labels can have to themselves - if there are too
    many in the same area, none will be drawn.  Sliding it left allows more
    crowding and right allows less.  The <label>Crowding Limit</label>
    controls the largest number of labels that can be in a group.
    Setting it to 2 for instance is useful if you want to see pairs of
    labels, even if the pair is close.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-contour">
<subhead><title>Contour Form</title></subhead>

<figure>
<caption><px>Contour form configuration panel</px></caption>
<figureimage src="&FIG.form_contour;"/>
</figure>

<p>The <label>Contour</label> form (&IMG.PLOT_CONTOUR;)
plots position density contours.
These provide another way
(alongside the <ref id="mode-auto">Auto</ref> and
<ref id="mode-density">Density</ref> shading modes)
to visualise the characteristics of overdense regions in a crowded plot.
</p>

<p>The contours are currently drawn as pixels rather than lines,
so they don't look very beautiful in exported vector output formats
(PDF, PostScript).
</p>

<p>The configuration options are:
<dl>
<dt>Level Count</dt>
<dd><p>The number of contours drawn.
    In fact this is an upper limit; if there is not enough variation
    in the plot's density, then fewer contour lines will be drawn.
    </p></dd>
<dt>Smoothing</dt>
<dd><p>The size of the smoothing kernel applied to the density before
    performing the contour determination.  If set too low the contours
    will be too crinkly, and if too high they will lose definition.
    </p></dd>
<dt>Scaling</dt>
<dd><p>How the smoothed density is treated before the contours levels
    are determined.  Options are linear, logarithmic and equal area.
    </p></dd>
<dt>Zero Point</dt>
<dd><p>Determines the level at which the first contour (and hence all the
    others, which are separated from it by a fixed amount) are drawn.
    By sliding this from side to side you can sweep the contours over
    the density range and get a good idea of where interesting features lie.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-marks2">
<subhead><title>Pair Marks Form</title></subhead>

<figure>
<caption><px>Pair Mark form configuration panel</px></caption>
<figureimage src="&FIG.form_marks2;"/>
</figure>

<p>The <label>Pair Mark</label> form (&IMG.FORM_MARKS2;)
is available from the
<ref id="GangLayerControl_pair">pair position layer control</ref>,
and plots a marker of configurable
shape and size at both points in a position pair.
The same marker is used for both ends; if you want different points
you can use two single <ref id="form-mark">Mark</ref> forms.
</p>

<p>Configuration options are:
<dl>
<dt>Shading Mode</dt>
<dd><p>See <ref id="ShapeMode"/>.
    </p></dd>
<dt>Shape</dt>
<dd><p>Marker shape from a list of options.
    </p></dd>
<dt>Size</dt>
<dd><p>Marker size in pixels.
    </p></dd>
</dl>
</p>

</subsubsubsect>

<subsubsubsect id="form-link2">
<subhead><title>Pair Link Form</title></subhead>

<figure>
<caption><px>Pair Link form configuration panel</px></caption>
<figureimage src="&FIG.form_link2;"/>
</figure>

<p>The <label>Pair Link</label> form (&IMG.FORM_LINK2;)
is available from the
<ref id="GangLayerControl_pair">pair position layer control</ref>,
and plots a line linking the two points in a position pair.
</p>

<p>Configuration options are:
<dl>
<dt>Shading Mode</dt>
<dt>Shading Mode</dt>
<dd><p>See <ref id="ShapeMode"/>.
    </p></dd>
</dl>
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="ShapeMode">
<subhead><title>Shading Modes</title></subhead>

<p>Most of the <ref id="ShapeForm" plaintextref="yes">Plot Forms</ref>
have a style colour associated with them for each data set.
This defines the basic colour used to plot the shape at each data point.
However, many of the forms also ask you to select a
<label>Shading Mode</label>,
which determines the actual colour displayed in the plot for the
plotted points.
The shaded colour is based on the selected style colour, but may also be
influenced by the number of points plotted there, some extra
data coordinate, or other configuration information.
</p>

<p>When exporting plots to an external vector graphics format 
(EPS or PDF), some of the shading modes may not behave the same
as in a bitmap (on the screen, or to a bitmapped format such as 
GIF or PNG).
Any such anomalies are noted in the in the mode descriptions below.
</p>

<p>The different mode shading mode options are described in the following
subsections.
</p>

<subsubsubsect id="mode-flat">
<subhead><title>Flat Mode</title></subhead>

<figure>
<caption><px>Flat shading mode selection</px></caption>
<figureimage src="&FIG.mode_flat;"/>
</figure>

<p>The <label>Flat</label> shading mode (&IMG.MODE_FLAT;)
simply colours points in the colour selected by their style.
It has no additional parameters or coordinates.
</p>

<p><strong>Exporting:</strong>
This mode works without problem for both bitmapped and vector output.
</p>

</subsubsubsect>

<subsubsubsect id="mode-translucent">
<subhead><title>Translucent Mode</title></subhead>

<figure>
<caption><px>Translucent shading mode selection</px></caption>
<figureimage src="&FIG.mode_translucent;"/>
</figure>

<p>The <label>Translucent</label> shading mode (&IMG.MODE_ALPHA;)
colours shapes in a transparent version of the
colour selected by their style.
The degree of transparency is determined by how many points are
currently being plotted on top of each other,
and by the <label>Transparency Level</label> slider;
as you slide further to the right, points get more transparent.
Unlike <ref id="mode-transparent">transparent mode</ref>,
the transparency varies according to the current point density,
so you can usually leave the setting the same as you zoom 
in and out.
</p>

<p><strong>Exporting:</strong>
When the points are opaque, this mode works without problem for
both bitmapped and vector output, but when the transparency is set
there may be anomalies.
Transparent points are rendered in PDF output, though the 
transparency levels may not be exactly the same as on the screen.
This can be fixed by using the <label>Force Bitmap</label> option
in the <ref id="plot2-export" plaintextref="yes">Plot Export</ref> dialogue.
For PostScript, transparent points are rendered as opaque.
You can use <label>Force Bitmap</label> with PostScript which
will get transparency right for this layer, but then any earlier
layers will be completely obscured.
</p>

</subsubsubsect>

<subsubsubsect id="mode-transparent">
<subhead><title>Transparent Mode</title></subhead>

<figure>
<caption><px>Transparent shading mode selection</px></caption>
<figureimage src="&FIG.mode_transparent;"/>
</figure>

<p>The <label>Transparent</label> shading mode (&IMG.MODE_ALPHA_FIX;)
colours shapes in a transparent version of the
colour selected by their style.
The degree of transparency is determined by the
<label>Opaque Limit</label> slider - at the left end,
points are fully opaque and this is equivalent to
<ref id="mode-flat">Flat mode</ref>,
and as you slide further to the right,
the points get more transparent.
The higher the opaque limit, the more points have to be plotted
on top of each other to reach colour that fully obscures the background.
Unlike <ref id="mode-translucent">translucent mode</ref>,
transparency of each colour is fixed by the opaque limit,
rather than adjusting depending on the density of points currently plotted.
</p>

<p><strong>Exporting:</strong>
When the points are opaque, this mode works without problem for
both bitmapped and vector output, but when the transparency is set
there may be anomalies.
Transparent points are rendered in PDF output, though the 
transparency levels may not be exactly the same as on the screen.
This can be fixed by using the <label>Force Bitmap</label> option
in the <ref id="plot2-export" plaintextref="yes">Plot Export</ref> dialogue.
For PostScript, transparent points are rendered as opaque.
You can use <label>Force Bitmap</label> with PostScript which
will get transparency right for this layer, but then any earlier
layers will be completely obscured.
</p>

</subsubsubsect>

<subsubsubsect id="mode-auto">
<subhead><title>Auto Mode</title></subhead>

<figure>
<caption><px>Auto shading mode selection</px></caption>
<figureimage src="&FIG.mode_auto;"/>
</figure>

<p>The <label>Auto</label> shading mode (&IMG.MODE_AUTO;)
colours isolated points in their selected colour,
but where multiple points <em>from the same data set</em>
overlap it adjusts the colour by darkening it.
This means for that isolated points
(most or all points in a non-crowded plot, or outliers in a crowded plot)
it behaves just like <ref id="mode-flat">Flat</ref> mode,
but it's easy to see where overdense regions lie.
</p>

<p>This is like <ref id="mode-density">Density</ref> mode,
but with no user-configurable options.
</p>

<p>This is the default mode for 2d plots, since it gives you a good
first idea of what the data is doing.
For 3d plots it can be used, and it works well for single dataset plots,
but in the case of multiple datasets it can be misleading since the
coloured pixels can't be placed sensibly in the 3d space.
</p>

<p>The colour darkening is based on the asinh function;
the intention is that two points overlaid should be just enough
different in colour for the difference to be visible,
and the mapping is scaled so that if there are very dense regions
they will come out nearly black.
</p>

<p><strong>Exporting:</strong>
When exported to vector formats, the output is automatically forced to a
bitmap for Auto-mode layers.
In the case of PostScript, this completely obscures any previous layers.
</p>

</subsubsubsect>

<subsubsubsect id="mode-density">
<subhead><title>Density Mode</title></subhead>

<figure>
<caption><px>Density mode selection</px></caption>
<figureimage src="&FIG.mode_density;"/>
</figure>

<p>The <label>Density</label> shading mode (&IMG.MODE_DENSITY;)
uses a configurable colour map
to indicate how many points are plotted over each other.
Specifically, it colours each pixel according to how many times that
pixel has has been covered by one of the shapes plotted by the layer
in question.
To put it another way, it generates a false-colour density map
with pixel granularity using a smoothing kernel of the form of
the shapes plotted by the layer.
The upshot is that you can see the plot density of points or other
shapes plotted.
</p>

<p>This is like <ref id="mode-auto">Auto</ref> mode, but with more
user-configurable options.  The options are:
<dl>
<dt>Map</dt>
<dd><p>The colour map for displaying density values.
    There are two types, relative and absolute.
    Relative maps have names marked by a star ("*"), and alter the
    basic dataset colour, for instance by darkening or lightening it,
    while absolute maps (the rest) ignore the basic dataset colour altogether.
    For a single-dataset plot, the absolute maps are best, but for
    multiple subsets it may be less confusing to use a relative one.
    </p></dd>
<dt>Map Clip</dt>
<dd><p>Select only a part of the colour map selected above.
    By default the whole colour map is used, but if you want the range
    of colours in the plot to be formed from only a part of the colour
    band shown in the <label>Shader</label> control,
    you can move the handles in from the end of this slider.
    </p></dd>
<dt>Log</dt>
<dd><p>Selects whether the colour map should be applied linearly or
    logarithmically to the range of densities.  The default is logarithmic.
    </p></dd>
<dt>Flip</dt>
<dd><p>Selects whether the colour map should be applied forwards or
    backwards to the range of densities.
    </p></dd>
<dt>Sub-range</dt>
<dd><p>Adjusts the density range over which the colour
    map is applied.  By default the colour map is scaled using limits
    found from the data density in the plot (the most dense few pixels are
    ignored), but you can restrict the range using this slider.
    </p></dd>
</dl>
</p>

<p><strong>Exporting:</strong>
When exported to vector formats, the output is automatically forced to a
bitmap for Density-mode layers.
In the case of PostScript, this completely obscures any previous layers.
</p>

</subsubsubsect>

<subsubsubsect id="mode-aux">
<subhead><title>Aux Mode</title></subhead>

<figure>
<caption><px>Aux mode selection</px></caption>
<figureimage src="&FIG.mode_aux;"/>
</figure>

<p>The <label>Aux</label> shading mode (&IMG.MODE_AUX;)
colours each point according to the value of an additional
data coordinate.
The point colours then represent an additional dimension of the plot.
There is an additional option to draw the points with a fixed transparency.
</p>

<p>The shading is done according to a single fixed scale for all
the data in the plot.  When at least one Aux-mode layer is being plotted,
the <ref id="ShaderControl" plaintextref="yes">Aux Axis</ref>
control is visible
in the control panel, which allows you to configure the colour map,
range, ramp display etc.
</p>

<p>The options are:
<dl>
<dt>Aux</dt>
<dd><p>The auxiliary coordinate data values.
    Fill this in with a column name or expression from the table
    just like for a positional coordinate.
    </p></dd>
<dt>Opaque Limit</dt>
<dd><p>Determines transparency of the points.
    By default, they are fully opaque, but if you slide the slider to
    the right, they will become progressively more transparent.
    </p></dd>
</dl>
</p>

<p><strong>Exporting:</strong>
Transparent points are rendered in PDF output, though the 
transparency levels may not be exactly the same as on the screen.
This can be fixed by using the <label>Force Bitmap</label> option
in the <ref id="plot2-export" plaintextref="yes">Plot Export</ref> dialogue.
For PostScript, transparent points are rendered as opaque.
You can use <label>Force Bitmap</label> with PostScript which
will get transparency right for this layer, but then any earlier
layers will be completely obscured.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="HistogramPlotWindow">
<subhead><title>Histogram Plot Window</title></subhead>

<figure>
<caption><px>Histogram Plot Window</px></caption>
<figureimage src="&FIG.HistogramPlotWindow;"/>
</figure>

<p>The <label>Histogram Plot</label> (&IMG.PLOT2_HISTOGRAM;)
plots 1-dimensional histograms.
In many respects it is like the <ref id="PlanePlotWindow">Plane Plot</ref>,
but it has an additional fixed control
<ref id="ConfigControl_histobars">Bars</ref>
and the scrolling works a bit differently.
</p>

<p>See the <ref id="StackPlotWindow" plaintextref="yes">Window Overview</ref>
for features common to all plotting windows.
In addition, the histogram window lets you export the binned data as
a new table, either saving it or loading it directly into TOPCAT's
table list.
The following actions are available in the <label>Export</label> menu:
<dl>

<dt>&IMG.HISTO_SAVE; Save as Table</dt>
<dd><p>The bin counts/sums corresponding to the currently plotted histogram
    will be written to disk in tabular form.  The first two columns give
    the lower and upper bounds of each bin, and the subsequent columns
    give the occupancies of each bin for each plotted data set.
    If only one dataset is plotted, there will only be three columns.
    </p></dd>

<dt>&IMG.HISTO_IMPORT; Import as Table</dt>
<dd><p>Assembles a table as per the <label>Save</label> option above,
    but rather than writing it to disk imports it directly into TOPCAT,
    where it can be manipulated in all the usual ways.
    </p></dd>
</dl>
</p>

<p>The following subsections describe
<ref id="histogramNavigation">navigation</ref>,
<ref id="HistogramAxisControl">axis configuration</ref> and
<ref id="ConfigControl_histobars">bar configuration</ref>.
</p>

<p>The Histogram Plot offers only the following plot controls:
<ul>
<li>&CONTROL.histogram;</li>
<li>&CONTROL.function;</li>
</ul>
</p>

<subsubsubsect id="histogramNavigation">
<subhead><title>Histogram Navigation</title></subhead>

<p>For general comments on plot navigation, see <ref id="plot2Navigation"/>.
Additional configuration options are available in the <label>Navigation</label>
tab of the <ref id="HistogramAxisControl">Axes control</ref>.
</p>

<p>The navigation actions for this window are:
<dl>
<dt>&GESTURE.DRAG1;</dt>
<dd><p><em>Pan.</em>
    On the body of the plot this moves it around up/down/left/right.
    To move it only vertically, drag on the left of the Y axis.
    To move it only horizontally, drag below the X axis.
    You can configure dragging on the body of the plot to be only vertical
    or horizontal by setting the <label>Pan/Zoom Axes</label> in the
    <label>Navigation</label> axis configuration tab.
    </p></dd>
<dt>&GESTURE.DRAG3;</dt>
<dd><p><em>Stretch zoom.</em>
    On the body of the plot,
    dragging up/down stretches/squashes the plot vertically, and
    dragging left/right stretches/squashes it horizontally.
    To zoom only vertically, drag on the left of the Y axis.
    To zoom only horizontally, drag below the X axis.
    </p>
    <p>Zooming horizontally will normally adjust the width of the histogram
    bars appropriately.
    </p>
    <p>Normally, the zoom will be centered horizontally at the mouse position
    and vertically on the X axis, so the zoom will not move the bottom of
    the histogram.  You can adjust that with the <label>Anchor X/Y Axis</label>
    options in the <label>Navigation</label> axis configuration tab.
    </p></dd>
<dt>&GESTURE.WHEEL;</dt>
<dd><p><em>Isotropic zoom.</em>
    Spinning the mouse wheel forwards/backwards will zoom in/out
    just like dragging with the right button up-and-right or down-and-left.
    </p></dd>
</dl>
</p>

<p>You can also manually fix the plot bounds using the <label>Range</label>
tab of the <ref id="HistogramAxisControl">Axes control</ref>.
</p>

</subsubsubsect>

<subsubsubsect id="HistogramAxisControl">
<subhead><title>Histogram Axes Control</title></subhead>

<p>The Histogram Plot axis control is very similar to the
Plane Plot axis control
described in <ref id="PlaneAxisControl"/>.
The only difference is in the <label>Navigation</label> tab.
For the histogram, the <label>Anchor X Axis</label> option is
set <label>on</label> by default, since you will usually want
the Y=0 line to stay anchored to the bottom of the plot when zooming.
</p>

</subsubsubsect>

<subsubsubsect id="ConfigControl_histobars">
<subhead><title>Bars Control</title></subhead>

<p>The <label>Bars</label> control (&IMG.HISTOBARS;)
is found in the control stack of the Histogram window.
It configures the common placement and calculation of the bars for
all the histogram layers displayed.
It has the following fields:
<dl>
<dt>Bin Size</dt>
<dd><p>A scale for the width of bins that are shown on the screen.
    There are two ways to specify this.
    If the left-hand radio button is selected, the adjacent slider will
    adjust the bin size, which is also affected by the actual width of
    the plotting window in pixels.  Slide the slider left to get narrower
    bins or right to get wider ones.
    If the right-hand radio button is selected, you can enter a numeric
    value giving the actual width in data units of each bar
    (for a logarithmic X axis this value is a factor).
    </p></dd>
<dt>Bin Phase</dt>
<dd><p>Controls where the horizontal zero point for binning is set.
    For instance if your bin size is 1, it controls whether bins
    boundaries are at 0, 1, 2, ..  or 0.5, 1.5, 2.5, ... etc.
    If the slider is at either end of the scale, there will be a bin
    boundary at X=0 (linear X axis) or X=1 (logarithmic X axis).
    </p></dd>
<dt>Cumulative</dt>
<dd><p>If true, the bars plotted are calculated cumulatively;
    each bin includes the counts from all previous bins.
    </p></dd>
<dt>Normalized</dt>
<dd><p>If true, the counts in each plotted histogram are normalised to
    sum to a value of 1.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Bars fixed control in Histogram Window</px></caption>
<figureimage src="&FIG.ConfigControl_histobars;"/>
</figure>

</subsubsubsect>

</subsubsect>

<subsubsect id="PlanePlotWindow">
<subhead><title>Plane Plot Window</title></subhead>

<figure>
<caption><px>Plane Plot Window</px></caption>
<figureimage src="&FIG.PlanePlotWindow;"/>
</figure>

<p>The <label>Plane Plot</label> (&IMG.PLOT2_PLANE;)
plots 2-dimensional Cartesian positions on a plane.
The positional coordinates are <label>X</label> and <label>Y</label>.
To control the direction and linear/log scaling of the axes,
see the <label>Coords</label> tab of the
<ref id="PlaneAxisControl">Axes</ref> control.
</p>

<p>See the <ref id="StackPlotWindow" plaintextref="yes">Window Overview</ref>
for features common to all plotting windows.
The following subsections describe
<ref id="planeNavigation">navigation</ref> and
<ref id="PlaneAxisControl">axis configuration</ref>.
</p>

<p>The Plane Plot offers the following plot controls:
<ul>
<li>&CONTROL.single;, with these form options:
    <ul>
    <li>&FORM.mark;</li>
    <li>&FORM.size;</li>
    <li>&FORM.vector;</li>
    <li>&FORM.error;</li>
    <li>&FORM.ellipse;</li>
    <li>&FORM.line;</li>
    <li>&FORM.linearfit;</li>
    <li>&FORM.label;</li>
    <li>&FORM.contour;</li>
    </ul></li>
<li>&CONTROL.pair;, with the following plot controls:
    <ul>
    <li>&FORM.marks2;</li>
    <li>&FORM.link2;</li>
    </ul></li>
<li>&CONTROL.histogram;</li>
<li>&CONTROL.function;</li>
</ul>
</p>

<subsubsubsect id="planeNavigation">
<subhead><title>Plane Navigation</title></subhead>

<p>For general comments on plot navigation, see <ref id="plot2Navigation"/>.
Additional configuration options are available in the <label>Navigation</label>
tab of the <ref id="PlaneAxisControl">Axes control</ref>.
</p>

<p>The navigation actions for this window are:
<dl>
<dt>&GESTURE.DRAG1;</dt>
<dd><p><em>Pan.</em>
    On the body of the plot this moves it around up/down/left/right.
    To move it only vertically, drag on the left of the Y axis.
    To move it only horizontally, drag below the X axis.
    You can configure dragging on the body of the plot to be only vertical
    or horizontal by setting the <label>Pan/Zoom Axes</label> in the
    <label>Navigation</label> axis configuration tab.
    </p></dd>
<dt>&GESTURE.DRAG3;</dt>
<dd><p><em>Stretch zoom.</em>
    On the body of the plot,
    dragging up/down stretches/squashes the plot vertically, and
    dragging left/right stretches/squashes it horizontally.
    Zooming is around the mouse position at the start of the drag.
    To zoom only vertically, drag on the left of the Y axis.
    To zoom only horizontally, drag below the X axis.
    </p></dd>
<dt>&GESTURE.DRAG2;</dt>
<dd><p><em>Frame zoom.</em>
    On the body of the plot, dragging right-and-down or right-and-up
    drags out a frame;
    when the button is released, the plot will be zoomed in
    to cover the area enclosed by the frame.
    Dragging left (and up or down) does something like the opposite,
    you can zoom out using a similar (though not quite the same) mechanism.
    To zoom in/out only horizontally, drag right/left below the X axis.
    To zoom in/out only vertically, drag up/down on the left of the Y axis.
    </p></dd>
<dt>&GESTURE.WHEEL;</dt>
<dd><p><em>Isotropic zoom.</em>
    Spinning the mouse wheel forwards/backwards will zoom in/out
    around the mouse position,
    just like dragging with the right button up-and-right or down-and-left.
    </p></dd>
<dt>&GESTURE.CLICK1;</dt>
<dd><p><em>Select.</em>
    If there is a plotted point near the cursor,
    it will plot a marker on it and
    <ref id="activation" plaintextref="yes">activate</ref> it.
    </p></dd>
</dl>
</p>

<p>You can also manually fix the plot bounds using the <label>Range</label>
tab of the <ref id="PlaneAxisControl">Axes control</ref>.
</p>

</subsubsubsect>

<subsubsubsect id="PlaneAxisControl">
<subhead><title>Plane Axes Control</title></subhead>

<p>The <label>Axes</label> control (&IMG.AXIS_EDIT;) for the
plane plot window has six tabs.
</p>

<figure>
<caption><px>Coords tab of plane Axes control</px></caption>
<figureimage src="&FIG.PlaneAxisControl_coords;"/>
</figure>

<p>The <label>Coords</label> tab controls the axis coordinates.
It has the following options:
<dl>
<dt>X/Y Log</dt>
<dd><p>If selected, horizontal/vertical axis coordinates are logarithmic,
    otherwise they are linear.
    </p></dd>
<dt>X/Y Flip</dt>
<dd><p>If selected, horizontal/vertical axis coordinate axes run in the
    opposite direction to normal.
    </p></dd>
<dt>Aspect Lock</dt>
<dd><p>If selected, the number of pixels per unit is always the same
    on both axes, i.e. the unit square is always a square.
    Otherwise, there is no constraint on the relative sizes of the 
    X and Y axis units.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Navigation tab of plane Axes control</px></caption>
<figureimage src="&FIG.PlaneAxisControl_navigation;"/>
</figure>

<p>The <label>Navigation</label> tab controls details of how the
navigation works.
It has the following options:
<dl>
<dt>Pan/Zoom Axes</dt>
<dd><p>Normally, dragging with the left/right mouse buttons or using
    the mouse wheel on the
    main part of the plot will pan/zoom it in both X and Y directions.
    By unchecking the X or Y checkbox here, you can prevent pan/zoom in
    the corresponding direction, so if the Y box is unchecked,
    pan/zoom will only affect the vertical direction
    (note the same effect can be achieved by dragging to the left of the Y
    axis).
    </p></dd>
<dt>Anchor X/Y axis</dt>
<dd><p>Normally, zoom operations zoom around the position of the mouse
    at the start of the wheel/drag gesture.
    Checking these boxes fixes the X/Y reference coordinate for zooms to
    be the Y=0 or X=0 lines.  This can be useful if you want the X or Y
    axis to stay put (e.g. at the edge of the plot) during zoom actions.
    </p></dd>
<dt>Zoom Factor</dt>
<dd><p>Controls the factor by which each zoom action zooms the plot.
    Moving this slider to the left/right makes the mouse more/less sensitive
    (one wheel click or dragging a fixed distance has more/less zoom effect).
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Range tab of plane Axes control</px></caption>
<figureimage src="&FIG.PlaneAxisControl_range;"/>
</figure>

<p>The <label>Range</label> tab provides manual configuration of the
visible range of the plot.  Making changes to this tab will reset
the visible plot range, but not vice versa - zooming and panning
in the usual way will not change the settings of this panel.
</p>

<p>Filling in the <label>Minimum</label>/<label>Maximum</label>
fields for either or both axes will
constrain the corresponding range of the visible data.
The limits corresponding to any of those fields that are left blank
will initially be worked out from the data.
The <label>Subrange</label> double-sliders restrict the ranges
within the (explicit or automatic) min/max ranges.
Note you can move both sliders at once by grabbing a position between the two.
</p>

<p>The <label>Clear</label> button resets all the fields.
The <label>Submit</label> button updates the plot with the current values
in this tab, as does making any changes to it.
</p>

<figure>
<caption><px>Grid tab of plane Axes control</px></caption>
<figureimage src="&FIG.PlaneAxisControl_grid;"/>
</figure>

<p>The <label>Grid</label> tab configures the appearance of the axis grid.
It has the following options:
<dl>
<dt>Draw Grid</dt>
<dd><p>If true, grid lines will be drawn across the plot
    for every tick mark.
    </p></dd>
<dt>Grid Colour</dt>
<dd><p>Selects the colour with which grid lines will be drawn.
    </p></dd>
<dt>Label Colour</dt>
<dd><p>Selects the colour in which axis label text will be written.
    </p></dd>
<dt>Minor Ticks</dt>
<dd><p>If set, minor (unlabelled) tick marks will be drawn between the
    major (labelled) ones.
    </p></dd>
<dt>X/Y Tick Crowding</dt>
<dd><p>Use the slider to influence how many tick marks are draw on each axis.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Labels tab of plane Axes control</px></caption>
<figureimage src="&FIG.PlaneAxisControl_labels;"/>
</figure>

<p>The <label>Labels</label> tab controls the text labels on the axes.
If the <label>Auto</label> checkbox is set, the text will be taken
from one of the data coordinates being plotted on that axis.
To override those with your own axis labels, unset Auto and type
text in to the <label>Label</label> fields.
</p>

<figure>
<caption><px>Font tab</px></caption>
<figureimage src="&FIG.font_tab;"/>
</figure>

<p>The <label>Font</label> tab configures the font used for axis annotation.
It also affects some other things like the legend.
<dl>
<dt>Text Syntax</dt>
<dd><p>How to turn the text into characters on the screen.
    <label>Plain</label> and <label>Antialias</label> both take the
    text at face value, but Antialias smooths the characters.
    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.
    <label>LaTeX</label> interprets the text as LaTeX source code
    and typesets it accordingly.
    </p></dd>
<dt>Font Size</dt>
<dd><p>Size of the font in points.
    </p></dd>
<dt>Font Style</dt>
<dd><p>Style of the font.
    </p></dd>
<dt>Font Weight</dt>
<dd><p>Whether the font is plain, bold or italic.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Size tab</px></caption>
<figureimage src="&FIG.size_tab_insets;"/>
</figure>

<p>The <label>Size</label> tab allows you to set the geometry of the
generated plot in pixels.  By default, the plot is simply resized to
fit the current size and shape of the window.  However, if you fill
in the <label>Outer width</label> and/or <label>Outer height</label>
fields, the size will instead be fixed to the given dimension in pixels.
Note if you pick a large value, you may need to manually resize the
window to see all of the plot.
Similarly, the <label>Border</label> fields fix the number of pixels
surrounding the data region of the plot; if these are left blank,
as by default, these borders are sized to accommodate the things
that have to fit in them (such as axis annotations).
</p>

<p>The main use for this panel is to fix the size and alignment
of the generated images if you want to export a series of
similar plots.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="SkyPlotWindow">
<subhead><title>Sky Plot Window</title></subhead>

<figure>
<caption><px>Sky Plot Window</px></caption>
<figureimage src="&FIG.SkyPlotWindow;"/>
</figure>

<p>The <label>Sky Plot</label> (&IMG.PLOT2_SKY;)
plots longitude/latitude positions onto the celestial sphere.
It can plot to a number of projections
(currently Sin, Aitoff and Plate Carr&#x00e9;e).
</p>

<p>The positional coordinates are
<label>Longitude</label> and <label>Latitude</label>, specified in degrees.
When supplying them, you can specify an associated
<label>Data Sky System</label>
(Equatorial, Galactic, Supergalactic or Ecliptic2000).
Note that this is the sky system of the data coordinates,
not (necessarily) of the plot you want to see.
To specify the coordinates you want the data to be plotted on,
use the <label>View Sky System</label> option in the <label>Projection</label>
tab of the <ref id="SkyAxisControl">Axes</ref> control.
However, if you just want to view the data using the same system
as the coordinates you are supplying, you can ignore leave these
values as their default (both Equatorial) and no conversion will be done.
</p>

<p>See the <ref id="StackPlotWindow" plaintextref="yes">Window Overview</ref>
for features common to all plotting windows.
The following subsections describe
<ref id="skyNavigation">navigation</ref> and
<ref id="SkyAxisControl">axis configuration</ref>.
</p>

<p>The sky plot offers the following plot controls:
<ul>
<li>&CONTROL.single;, with these form options:
    <ul>
    <li>&FORM.mark;</li>
    <li>&FORM.size;</li>
    <li>&FORM.vector;</li>
    <li>&FORM.ellipse;</li>
    <li>&FORM.label;</li>
    <li>&FORM.contour;</li>
    </ul></li>
<li>&CONTROL.pair;, with the following plot controls:
    <ul>
    <li>&FORM.marks2;</li>
    <li>&FORM.link2;</li>
    </ul></li>
</ul>
</p>

<subsubsubsect id="skyNavigation">
<subhead><title>Sky Navigation</title></subhead>

<p>For general comments on plot navigation, see <ref id="plot2Navigation"/>.
Additional configuration options are available in the <label>Navigation</label>
tab of the <ref id="SkyAxisControl">Axes control</ref>.
</p>

<p>The navigation options for this window are:
<dl>
<dt>&GESTURE.DRAG1;</dt>
<dd><p><em>Pan.</em>
    In the Sin projection, this attempts to rotate the sphere, 
    with north staying vertical on the screen, in such a way that the
    same part of the sky stays under the cursor position.
    At low magnifications this is sometimes not possible;
    if the mouse starts on the sphere and ends up off it the navigation
    will be jerky.
    </p>
    <p>The Aitoff and Plate Car&#x00e9;e projections act like a piece of
    paper that can be dragged around in two dimensions in the usual way.
    </p></dd>
<dt>&GESTURE.WHEEL;</dt>
<dd><p><em>Zoom.</em>
    Spinning the mouse wheel forwards/backwards will zoom in/out around
    the mouse position.  For this Sin projection this will also have the
    effect of rotating the sphere to keep North vertical on the screen.
    </p></dd>
<dt>&GESTURE.DRAG3;</dt>
<dd><p><em>Stretch zoom.</em>
    Dragging with the right mouse button up-and-right/down-and-left
    has just the same effect as spinning the mouse button forwards/backwards.
    </p></dd>
<dt>&GESTURE.DRAG2;</dt>
<dd><p><em>Frame zoom.</em>
    Dragging with the middle button to the right (and either up or down)
    drags out a frame;
    when the button is released, the plot will be zoomed in
    to cover (roughly) the area enclosed by the frame.
    Dragging left (and either up or down) does something like the opposite,
    you can zoom out using a similar (though not quite the same) mechanism.
    </p></dd>
<dt>&GESTURE.CLICK1;</dt>
<dd><p><em>Select.</em>
    If there is a plotted point near the cursor,
    it will plot a marker on it and
    <ref id="activation" plaintextref="yes">activate</ref> it.
    </p></dd>
</dl>
</p>

<p>You can also navigate to a known sky position by coordinates or
object name using the <label>FOV</label>
tab of the <ref id="SkyAxisControl">Axes control</ref>.
</p>

</subsubsubsect>

<subsubsubsect id="SkyAxisControl">
<subhead><title>Sky Axes Control</title></subhead>

<p>The <label>Axes</label> control (&IMG.AXIS_EDIT;) for the
sky plot window has five tabs.
</p>

<figure>
<caption><px>Projection tab of the sky Axes control</px></caption>
<figureimage src="&FIG.SkyAxisControl_projection;"/>
</figure>

<p>The <label>Projection</label> tab controls how the sky position
coordinates are projected onto the screen.
<dl>
<dt>Projection</dt>
<dd><p>Selects the sky projection to use.
    The options are <label>Sin</label>, <label>Ait</label> for Aitoff and
    <label>Car</label> for Plate Car&#x00e9;e.
    Sin is rotatable, the other two are essentially flat all-sky projections.
    </p></dd>
<dt>Reflect longitude axis</dt>
<dd><p>Determines whether longitude increases left to right or right to left.
    </p></dd>
<dt>View Sky System</dt>
<dd><p>Determines the sky coordinate system in which the data positions will
    be viewed.  This interacts with the 
    <label>Data Sky System</label> selected in the 
    <label>Positions</label> tab of the 
    <ref id="GangLayerControl_single">table layer control</ref>
    for data coordinates;
    supplied data points are projected from the data system to the view 
    system before being plotted.
    If you have (for instance) data in equatorial coordinates that you
    want to view in galactic coordinates, then select the
    Data Sky System as Equatorial and the View Sky System as Galactic.
    If the data and view systems are the same, it's OK to leave both
    as their defaults, even if they're not equatorial - the only
    effect that the chosen Data and View sky systems has is from
    the transformation between them.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Navigation tab of sky Axes control</px></caption>
<figureimage src="&FIG.SkyAxisControl_navigation;"/>
</figure>

<p>The <label>Navigation</label> tab controls details of how the navigation
works.
It has the following option:
<dl>
<dt>Zoom Factor</dt>
<dd><p>Controls the factor by which each zoom action zooms the plot.
    Moving this slider to the left/right makes the mouse more/less sensitive
    (one wheel click or dragging a fixed distance has more/less zoom effect).
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Field Of View tab of the sky Axes control</px></caption>
<figureimage src="&FIG.SkyAxisControl_fov;"/>
</figure>

<p>The <label>FOV</label> (Field Of View) tab allows you to
enter a sky position or object name and a radius and positions
the view at that region.
Filling in the fields and hitting <label>Submit</label>
will reposition the sky view, but not vice versa;
normal pan/zoom operations will not affect the content of this panel.
<dl>
<dt>Object Name</dt>
<dd><p>If you fill this in with the name of a celestial object and hit
    the <label>Resolve</label> button, a Simbad query will execute
    to fill in the <label>RA</label> and <label>Dec</label> fields
    with its position.
    </p></dd>
<dt>RA/Dec</dt>
<dd><p>J2000 positions of the required field centre.
    These values can either be filled in by the object name resolution
    as described above, or by hand.
    </p></dd>
<dt>Radius</dt>
<dd><p>Gives the radius of the desired field of view.
    </p></dd>
<dt>Clear</dt>
<dd><p>Clears the fields in this tab.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Grid tab of the sky Axes control</px></caption>
<figureimage src="&FIG.SkyAxisControl_grid;"/>
</figure>

<p>The <label>Grid</label> tab controls how the sky coordinate axes
appear.
<dl>
<dt>Draw Grid</dt>
<dd><p>If selected, grid lines will be drawn on the plot.
    </p></dd>
<dt>Sexagesimal</dt>
<dd><p>If selected sky coordinate annotations of the grid will be in
    sexagesimal format, otherwise in decimal degrees.
    </p></dd>
<dt>Grid Colour</dt>
<dd><p>Selects the colour with which grid lines will be drawn.
    </p></dd>
<dt>Label Colour</dt>
<dd><p>Selects the colour in which axis label text will be written.
    </p></dd>
<dt>Grid Crowding</dt>
<dd><p>Use the slider to control how closely packed grid lines are
    on the axes.
    </p></dd>
<dt>Label Positioning</dt>
<dd><p>Controls whether and where the numeric annotations of the lon/lat
    axes are put.  The default option <label>Auto</label> 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.
    </p></dd>
<dt>Antialiasing</dt>
<dd><p>Controls whether grid lines will be drawn antialiased
    (smoothed) or not.  This option does not affect exported plots.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Font tab</px></caption>
<figureimage src="&FIG.font_tab;"/>
</figure>

<p>The <label>Font</label> tab configures the font used for axis annotation.
It also affects some other things like the legend.
<dl>
<dt>Text Syntax</dt>
<dd><p>How to turn the text into characters on the screen.
    <label>Plain</label> and <label>Antialias</label> both take the
    text at face value, but Antialias smooths the characters.
    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.
    <label>LaTeX</label> interprets the text as LaTeX source code
    and typesets it accordingly.
    </p></dd>
<dt>Font Size</dt>
<dd><p>Size of the font in points.
    </p></dd>
<dt>Font Style</dt>
<dd><p>Style of the font.
    </p></dd>
<dt>Font Weight</dt>
<dd><p>Whether the font is plain, bold or italic.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Size tab</px></caption>
<figureimage src="&FIG.size_tab_insets;"/>
</figure>

<p>The <label>Size</label> tab allows you to set the geometry of the
generated plot in pixels.  By default, the plot is simply resized to
fit the current size and shape of the window.  However, if you fill
in the <label>Outer width</label> and/or <label>Outer height</label>
fields, the size will instead be fixed to the given dimension in pixels.
Note if you pick a large value, you may need to manually resize the
window to see all of the plot.
Similarly, the <label>Border</label> fields fix the number of pixels
surrounding the data region of the plot; if these are left blank,
as by default, these borders are sized to accommodate the things
that have to fit in them (such as axis annotations).
</p>

<p>The main use for this panel is to fix the size and alignment
of the generated images if you want to export a series of
similar plots.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="CubePlotWindow">
<subhead><title>Cube Plot Window</title></subhead>

<figure>
<caption><px>Cube Plot Window</px></caption>
<figureimage src="&FIG.CubePlotWindow;"/>
</figure>

<p>The <label>Cube Plot</label> (&IMG.PLOT2_CUBE;)
plots 3-dimensional Cartesian positions in a 3-d space.
</p>

<p>The positional coordinates are
<label>X</label>, <label>Y</label> and <label>Z</label>.
To control the direction and linear/logarithmic scaling of the axes,
see the <label>Coords</label> tab of the
<ref id="CubeAxisControl">Axes</ref> control.
</p>

<p>See the <ref id="StackPlotWindow" plaintextref="yes">Window Overview</ref>
for features common to all plotting windows.
The following subsections describe
<ref id="cubeNavigation">navigation</ref> and
<ref id="CubeAxisControl">axis configuration</ref>.
</p>

<p>The cube plot offers the following plot controls:
<ul>
<li>&CONTROL.single;, with these form options:
    <ul>
    <li>&FORM.mark;</li>
    <li>&FORM.size;</li>
    <li>&FORM.vector;</li>
    <li>&FORM.error;</li>
    <li>&FORM.ellipse;</li>
    <li>&FORM.line;</li>
    <li>&FORM.label;</li>
    <li>&FORM.contour;</li>
    </ul></li>
<li>&CONTROL.pair;, with the following plot controls:
    <ul>
    <li>&FORM.marks2;</li>
    <li>&FORM.link2;</li>
    </ul></li>
</ul>
Note that use of the
<ref id="mode-auto">Auto</ref> and <ref id="mode-density">Density</ref>
shading modes can be confusing in 3 dimensions with multiple datasets.
This is because pixels based on density along a line of sight are not
located at any point on that line, so shaded pixels can't appear
at the "right" place in the 3-d space.  The same applies to a lesser
extent with contours.  They work fine with a single dataset though.
</p>

<subsubsubsect id="cubeNavigation">
<subhead><title>Cube Navigation</title></subhead>

<p>For general comments on plot navigation, see <ref id="plot2Navigation"/>.
Additional configuration options are available in the <label>Navigation</label>
tab of the <ref id="CubeAxisControl">Axes control</ref>.
</p>

<p>Navigation in three dimensions with a two-dimensional screen and mouse
is a bit of a challenge.  However, the actions listed below should make it
fairly straightforward to navigate around points in 3d space to zoom in
on the regions that you are interested in.
<dl>
<dt>&GESTURE.DRAG1;</dt>
<dd><p><em>Rotate.</em>
    Rotates the view cube about its center.
    </p></dd>
<dt>&GESTURE.WHEEL;</dt>
<dd><p><em>Isotropic zoom.</em>
    Spinning the mouse wheel forwards/backwards zooms the space in the
    view cube in/out around the cube center.  The mouse position does not
    affect it.
    </p></dd>
<dt>&GESTURE.DRAG3;</dt>
<dd><p><em>2d stretch zoom.</em>
    Dragging with the right button does a stretch zoom in the two dimensions
    best aligned with the plane of the screen.
    There is no movement in the third (mostly perpendicular to the screen)
    direction.
    The zoom is around a line defined by the position of the mouse at
    the start of the zoom, pointing along the third dimension. 
    You can stretch/squash in both directions by dragging the mouse
    up/down/left/right - it's easier to try it than to explain it.
    </p></dd>
<dt>&GESTURE.DRAG2;</dt>
<dd><p><em>2d pan.</em>
    Dragging with the center button pans the 3d space in the two dimensions
    best alighned with the plane of the screen.
    There is no movement in the third (mostly perpendicular to the screen)
    direction.
    </p></dd>
<dt>&GESTURE.CLICK1;</dt>
<dd><p><em>Select.</em>
    If there are plotted points near the cursor it will identify one,
    plot a marker on it, and
    <ref id="activation" plaintextref="yes">activate</ref> it.
    </p>
    <p>In 3d, it's not obvious which is the nearest point to a 2d cursor,
    since a screen position represents a line not a point.
    To break the degeneracy, the point used is the one nearest the 
    center of mass of plotted points along the line of sight represented
    by the cursor position.  The upshot of this is that if you click on
    an isolated point, you'll pick that point, and if you click on a 
    dense cluster, you'll get a point near the center (of mass) of that
    cluster.
    </p></dd>
<dt>&GESTURE.CLICK3;</dt>
<dd><p><em>Re-center.</em>
    Right-clicking identifies a position in a similar way to the
    left-click Select action, and then translates the plot so that point
    is at the center of the view cube.  This means that clicking on a
    cluster will put that cluster in the center of the cube.
    If you click on an empty region, a position half way between front
    and back of the cube at that X/Y position will be used.
    </p></dd>
</dl>
</p>

<p>You can also manually fix the plot bounds using the <label>Range</label>
tab of the <ref id="CubeAxisControl">Axes control</ref>.
</p>

</subsubsubsect>

<subsubsubsect id="CubeAxisControl">
<subhead><title>Cube Axes Control</title></subhead>

<p>The <label>Axes</label> control (&IMG.AXIS_EDIT;) for the
cube plot window has seven tabs.
</p>

<figure>
<caption><px>Coords tab of the cube Axes control</px></caption>
<figureimage src="&FIG.CubeAxisControl_coords;"/>
</figure>

<p>The <label>Coords</label> tab controls the axis coordinates.
It has the following options:
<dl>
<dt>X/Y/Z Log</dt>
<dd><p>If selected, X/Y/Z axis coordinates are logarithmic,
    otherwise they are linear.
    </p></dd>
<dt>X/Y/Z Flip</dt>
<dd><p>If selected, X/Y/Z axis coordinate axes run in the
    opposite direction to normal.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Navigation tab of the cube Axes control</px></caption>
<figureimage src="&FIG.CubeAxisControl_navigation;"/>
</figure>

<p>The <label>Navigation</label> tab controls details of how the
navigation works.
It has the following options:
<dl>
<dt>Zoom Axes</dt>
<dd><p>By default the <label>Auto</label> setting is in effect.
    This means that the mouse wheel zooms around the center of the cube,
    and right-button drag zooms in the two dimensions
    most closely aligned with the plane of the screen, with the reference
    position set by the initial position of the mouse.
    If <label>Auto</label> is unset,
    then all zoom operations are around the cube center,
    and affect the axes indicated by the <label>X/Y/Z</label> checkboxes.
    </p></dd>
<dt>Zoom Factor</dt>
<dd><p>Controls the factor by which each zoom action zooms the plot.
    Moving this slider to the left/right makes the mouse more/less sensitive
    (one wheel click or dragging a fixed distance has more/less zoom effect).
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Range tab of the cube Axes control</px></caption>
<figureimage src="&FIG.CubeAxisControl_range;"/>
</figure>

<p>The <label>Range</label> tab provides manual configuration of the
visible range of the plot.  Making changes to this tab will reset
the visible plot range, but not vice versa - zooming and panning
in the usual way will not change the settings of this panel.
</p>

<p>Filling in the <label>Minimum</label>/<label>Maximum</label>
fields for one or more axes will
constrain the corresponding range of the visible data.
The limits corresponding to any of those fields that are left blank
will initially be worked out from the data.
The <label>Subrange</label> double-sliders restrict the ranges
within the (explicit or automatic) min/max ranges.
Note you can move both sliders at once by grabbing a position between the two.
</p>

<p>The <label>Clear</label> button resets all the fields.
The <label>Submit</label> button updates the plot with the current values
in this tab, as does making any changes to it.
</p>

<figure>
<caption><px>View tab of the cube Axes control</px></caption>
<figureimage src="&FIG.CubeAxisControl_view;"/>
</figure>

<p>The <label>View</label> tab can configure how the cube containing
the data is viewed in the plot window, though it does not control
the content of the cube.
<dl>
<dt>Rotation about Z axis</dt>
<dd><p>Explicitly sets the rotation angle about the Z axis,
    regardless of its current value, which may have been set by
    mouse actions.
    </p></dd>
<dt>Rotation from vertical</dt>
<dd><p>Explicitly sets the rotation angle from vertical,
    regardless of its current value, which may have been set by
    mouse actions.
    </p></dd>
<dt>Zoom factor</dt>
<dd><p>Sets the magnification of the cube wireframe itself, without
    affecting the data volume it contains.  This cannot be done with
    the mouse.
    </p></dd>
<dt>X/Y/Z offset of centre</dt>
<dd><p>Controls where on the screen the cube wireframe is centred.
    This cannot be done with the mouse.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Grid tab of the cube Axes control</px></caption>
<figureimage src="&FIG.CubeAxisControl_grid;"/>
</figure>

<p>The <label>Grid</label> tab configures the appearance of the
cube wire frame enclosing the data volume.
<dl>
<dt>Draw wire frame</dt>
<dd><p>Whether the enclosing cube is drawn at all.
    </p></dd>
<dt>Minor Ticks</dt>
<dd><p>If set, minor (unlabelled) tick marks will be drawn between the
    major (labelled) ones.
    </p></dd>
<dt>X/Y/Z Tick Crowding</dt>
<dd><p>Use the slider to influence how many tick marks are draw on each axis.
    </p></dd>
<dt>Antialiasing</dt>
<dd><p>Controls whether grid lines will be drawn antialiased
    (smoothed) or not.  This option does not affect exported plots.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Labels tab of the cube Axes control</px></caption>
<figureimage src="&FIG.CubeAxisControl_labels;"/>
</figure>

<p>The <label>Labels</label> tab controls the text labels on the axes.
If the <label>Auto</label> checkbox is set, the text will be taken
from one of the data coordinates being plotted on that axis.
To override those with your own axis labels, unset Auto and type
text in to the <label>Label</label> fields.
</p>

<figure>
<caption><px>Font tab</px></caption>
<figureimage src="&FIG.font_tab;"/>
</figure>

<p>The <label>Font</label> tab configures the font used for axis annotation.
It also affects some other things like the legend.
<dl>
<dt>Text Syntax</dt>
<dd><p>How to turn the text into characters on the screen.
    <label>Plain</label> and <label>Antialias</label> both take the
    text at face value, but Antialias smooths the characters.
    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.
    <label>LaTeX</label> interprets the text as LaTeX source code
    and typesets it accordingly.
    </p></dd>
<dt>Font Size</dt>
<dd><p>Size of the font in points.
    </p></dd>
<dt>Font Style</dt>
<dd><p>Style of the font.
    </p></dd>
<dt>Font Weight</dt>
<dd><p>Whether the font is plain, bold or italic.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Size tab</px></caption>
<figureimage src="&FIG.size_tab_noinsets;"/>
</figure>

<p>The <label>Size</label> tab allows you to set the geometry of the
generated plot in pixels.  By default, the plot is simply resized to
fit the current size and shape of the window.  However, if you fill
in the <label>Outer width</label> and/or <label>Outer height</label>
fields, the size will instead be fixed to the given dimension in pixels.
Note if you pick a large value, you may need to manually resize the
window to see all of the plot.
</p>

<p>The main use for this panel is to fix the size
of the generated images if you want to export a series of
similar plots.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="SpherePlotWindow">
<subhead><title>Sphere Plot Window</title></subhead>

<figure>
<caption><px>Sphere Plot Window</px></caption>
<figureimage src="&FIG.SpherePlotWindow;"/>
</figure>

<p>The <label>Sphere Plot</label> (&IMG.PLOT2_SPHERE;)
plots spherical polar coordinates in an isotropic 3-dimensional space.
Although the supplied coordinates are spherical polar,
the visible space is not necessarily centred on the coordinate origin,
and the visible axes are Cartesian.
In many respects this works like the
<ref id="CubePlotWindow">Cube Plot Window</ref>
</p>

<p>The positional coordinates are
<label>Longitude</label> and <label>Latitude</label> (in degrees) and
<label>Radius</label>.
</p>

<p>See the <ref id="StackPlotWindow" plaintextref="yes">Window Overview</ref>
for features common to all plotting windows.
The following subsections describe
<ref id="sphereNavigation">navigation</ref> and
<ref id="SphereAxisControl">axis configuration</ref>.
</p>

<p>The sphere plot offers the following plot controls:
<ul>
<li>&CONTROL.single;, with these form options:
    <ul>
    <li>&FORM.mark;</li>
    <li>&FORM.size;</li>
    <li>&FORM.label;</li>
    <li>&FORM.contour;</li>
    </ul></li>
<li>&CONTROL.pair;, with the following plot controls:
    <ul>
    <li>&FORM.marks2;</li>
    <li>&FORM.link2;</li>
    </ul></li>
</ul>
Note that use of the
<ref id="mode-auto">Auto</ref> and <ref id="mode-density">Density</ref>
shading modes can be confusing in 3 dimensions with multiple datasets.
This is because pixels based on density along a line of sight are not
located at any point on that line, so shaded pixels can't appear
at the "right" place in the 3-d space.  The same applies to a lesser
extent with contours.  They work fine with a single dataset though.
</p>

<subsubsubsect id="sphereNavigation">
<subhead><title>Sphere Navigation</title></subhead>

<p>For general comments on plot navigation, see <ref id="plot2Navigation"/>.
Additional configuration options are available in the <label>Navigation</label>
tab of the <ref id="SphereAxisControl">Axes control</ref>.
</p>

<p>Navigation in three dimensions with a two-dimensional screen and mouse
is a bit of a challenge.  However, the actions listed below should make it
fairly straightforward to navigate around points in 3d space to zoom in
on the regions that you are interested in.
The actions are quite like for the <ref id="cubeNavigation">Cube Window</ref>,
but all zooming is isotropic.
<dl>
<dt>&GESTURE.DRAG1;</dt>
<dd><p><em>Rotate.</em>
    Rotates the view cube about its center.
    </p></dd>
<dt>&GESTURE.WHEEL;</dt>
<dd><p><em>Zoom.</em>
    Spinning the mouse wheel forwards/backwards zooms the space in the
    view cube in/out around the cube center.  The mouse position does not
    affect it.
    </p></dd>
<dt>&GESTURE.DRAG3;</dt>
<dd><p><em>Zoom.</em>
    Zooming up-and-right/down-and-left does just the same as spinning the
    mouse wheel forwards/backwards.
    </p></dd>
<dt>&GESTURE.DRAG2;</dt>
<dd><p><em>2d pan.</em>
    Dragging with the center button pans the 3d space in the two dimensions
    best alighned with the plane of the screen.
    There is no movement in the third (mostly perpendicular to the screen)
    direction.
    </p></dd>
<dt>&GESTURE.CLICK1;</dt>
<dd><p><em>Select.</em>
    If there are plotted points near the cursor it will identify one,
    plot a marker on it, and
    <ref id="activation" plaintextref="yes">activate</ref> it.
    </p>
    <p>In 3d, it's not obvious which is the nearest point to a 2d cursor,
    since a screen position represents a line not a point.
    To break the degeneracy, the point used is the one nearest the 
    center of mass of plotted points along the line of sight represented
    by the cursor position.  The upshot of this is that if you click on
    an isolated point, you'll pick that point, and if you click on a 
    dense cluster, you'll get a point near the center (of mass) of that
    cluster.
    </p></dd>
<dt>&GESTURE.CLICK3;</dt>
<dd><p><em>Re-center.</em>
    Right-clicking identifies a position in a similar way to the
    left-click Select action, and then translates the plot so that point
    is at the center of the view cube.  This means that clicking on a
    cluster will put that cluster in the center of the cube.
    If you click on an empty region, a position half way between front
    and back of the cube at that X/Y position will be used.
    </p></dd>
</dl>
</p>

<p>You can also manually fix the plot bounds using the <label>Range</label>
tab of the <ref id="SphereAxisControl">Axes control</ref>.
</p>

</subsubsubsect>

<subsubsubsect id="SphereAxisControl">
<subhead><title>Sphere Axes Control</title></subhead>

<p>The <label>Axes</label> control (&IMG.AXIS_EDIT;) for the
sphere plot window has five tabs.
</p>

<figure>
<caption><px></px></caption>
<figureimage src="&FIG.SphereAxisControl_navigation;"/>
</figure>

<p>The <label>Navigation</label> tab controls details of how the navigation
works.
It has the following option:
<dl>
<dt>Zoom Factor</dt>
<dd><p>Controls the factor by which each zoom action zooms the plot.
    Moving this slider to the left/right makes the mouse more/less sensitive
    (one wheel click or dragging a fixed distance has more/less zoom effect).
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Range tab of the sphere Axes control</px></caption>
<figureimage src="&FIG.SphereAxisControl_range;"/>
</figure>

<p>The <label>Range</label> tab provides manual configuration of
the data range of the plot.  Making changes to this tab will reset
the visible plot range, but not vice versa - zooming and panning
in the usual way will not change the settings of this panel.
Any values not filled in will be determined from the data.
The fields are:
<dl>
<dt>Cube Edge Length</dt>
<dd><p>Specifies the dimension along each side of the view cube in
    data units.
    </p></dd>
<dt>X/Y/Z Center</dt>
<dd><p>Gives the position of the center of the view cube in data
    coordinates.
    </p></dd>
</dl>
</p>

<p>The <label>Clear</label> button resets all the fields.
The <label>Submit</label> button updates the plot with the current values
in this tab, as does making any changes to it.
</p>

<figure>
<caption><px>View tab of the sphere Axes control</px></caption>
<figureimage src="&FIG.SphereAxisControl_view;"/>
</figure>

<p>The <label>View</label> tab can configure how the cube containing
the data is viewed in the plot window, though it does not control
the content of the cube.
<dl>
<dt>Rotation about Z axis</dt>
<dd><p>Explicitly sets the rotation angle about the Z axis,
    regardless of its current value, which may have been set by
    mouse actions.
    </p></dd>
<dt>Rotation from vertical</dt>
<dd><p>Explicitly sets the rotation angle from vertical,
    regardless of its current value, which may have been set by
    mouse actions.
    </p></dd>
<dt>Zoom factor</dt>
<dd><p>Sets the magnification of the cube wireframe itself, without
    affecting the data volume it contains.  This cannot be done with
    the mouse.
    </p></dd>
<dt>X/Y offset of centre</dt>
<dd><p>Controls where on the screen the cube wireframe is centred.
    This cannot be done with the mouse.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Grid tab of the sphere Axes control</px></caption>
<figureimage src="&FIG.SphereAxisControl_grid;"/>
</figure>

<p>The <label>Grid</label> tab configures the appearance of the
cube wire frame enclosing the data volume.
<dl>
<dt>Draw wire frame</dt>
<dd><p>Whether the enclosing cube is drawn at all.
    </p></dd>
<dt>Minor Ticks</dt>
<dd><p>If set, minor (unlabelled) tick marks will be drawn between the
    major (labelled) ones.
    </p></dd>
<dt>Tick Crowding</dt>
<dd><p>Use the slider to influence how many tick marks are draw on the axes.
    </p></dd>
<dt>Antialiasing</dt>
<dd><p>Controls whether grid lines will be drawn antialiased
    (smoothed) or not.  This option does not affect exported plots.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Font tab</px></caption>
<figureimage src="&FIG.font_tab;"/>
</figure>

<p>The <label>Font</label> tab configures the font used for axis annotation.
It also affects some other things like the legend.
<dl>
<dt>Text Syntax</dt>
<dd><p>How to turn the text into characters on the screen.
    <label>Plain</label> and <label>Antialias</label> both take the
    text at face value, but Antialias smooths the characters.
    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.
    <label>LaTeX</label> interprets the text as LaTeX source code
    and typesets it accordingly.
    </p></dd>
<dt>Font Size</dt>
<dd><p>Size of the font in points.
    </p></dd>
<dt>Font Style</dt>
<dd><p>Style of the font.
    </p></dd>
<dt>Font Weight</dt>
<dd><p>Whether the font is plain, bold or italic.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Size tab</px></caption>
<figureimage src="&FIG.size_tab_noinsets;"/>
</figure>

<p>The <label>Size</label> tab allows you to set the geometry of the
generated plot in pixels.  By default, the plot is simply resized to
fit the current size and shape of the window.  However, if you fill
in the <label>Outer width</label> and/or <label>Outer height</label>
fields, the size will instead be fixed to the given dimension in pixels.
Note if you pick a large value, you may need to manually resize the
window to see all of the plot.
</p>

<p>The main use for this panel is to fix the size
of the generated images if you want to export a series of
similar plots.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="TimePlotWindow">
<subhead><title>Time Plot Window</title></subhead>

<p><em>This plot window is experimental.
As currently implemented it lacks some important features.
It may be improved or withdrawn in a future version.
</em></p>

<figure>
<caption><px></px></caption>
<figureimage src="&FIG.TimePlotWindow;"/>
</figure>

<p>The <label>Time Plot</label> (&IMG.PLOT2_TIME;)
is intended for plotting time series data.
</p>

<p>The horizontal axis represents time, and can be labelled accordingly,
and the window can display functions of time, scatter plots and spectrograms.
In future versions it may be able to plot multiple time series plots
stacked vertically using the same horizontal axis,
but at present it doesn't do that.
</p>

<p>See the <ref id="StackPlotWindow" plaintextref="yes">Window Overview</ref>
for features common to all plotting windows.
The following subsections describe
<ref id="timeNavigation">navigation</ref> and
<ref id="TimeAxisControl">axis configuration</ref>.
</p>

<p>The Time Plot offers the following plot controls:
<ul>
<li>&CONTROL.single;, with these form options:
    <ul>
    <li>&FORM.line;</li>
    <li>&FORM.mark;</li>
    <li>&FORM.error; (vertical bars only)</li>
    <li>&FORM.label;</li>
    </ul>
    </li>
<li>&CONTROL.spectrogram;</li>
<li>&CONTROL.function;</li>
</ul>
</p>

<subsubsubsect id="timeNavigation">
<subhead><title>Time Navigation</title></subhead>

<p>For general comments on plot navigation, see <ref id="plot2Navigation"/>.
Additional configuration options are available in the <label>Navigation</label>
tab of the <ref id="TimeAxisControl">Axes control</ref>.
</p>

<p>The navigation actions for this window are:
<dl>
<dt>&GESTURE.DRAG1;</dt>
<dd><p><em>Pan.</em>
    On the body of the plot this usually moves it around left/right.
    By default, vertical movement is inhibited since you don't normally
    want it for a time plot.
    To pan vertically, drag on the left of the Y axis.
    It is also possible to configure panning on the body of the plot
    to be in both directions using the <label>Pan/Zoom Axes</label>
    in the <label>Navigation</label> axis configuration tab.
    </p></dd>
<dt>&GESTURE.DRAG3;</dt>
<dd><p><em>Stretch zoom.</em>
    On the body of the plot this usually stretches/squashes the plot
    centered on the horizontal position of the mouse.
    By default, vertical zooming is inhibited since you don't normally
    want it for a time plot.
    To zoom vertically, drag on the left of the Y axis. 
    It is also possible to configure zooming on the body of the plot
    to be in both directions using the <label>Pan/Zoom Axes</label>
    in the <label>Navigation</label> axis configuration tab.
    </p></dd>
<dt>&GESTURE.DRAG2;</dt>
<dd><p><em>Frame zoom.</em>
    On the body of the plot, dragging right usually drags out a frame;
    when the button is released, the plot will be zoomed in
    to cover the area enclosed by the frame.
    Dragging left does something like the opposite, you can zoom out
    using a similar (though not quite the same) mechanism.
    By default, vertical zooming is inhibited since you don't normally
    want it for a time plot.
    To zoom in/out vertically, drag up/down on the left of the Y axis.
    It is also possible to configure zooming on the body of the plot
    to be in both directions using the <label>Pan/Zoom Axes</label>
    in the <label>Navigation</label> axis configuration tab.
    </p></dd>
<dt>&GESTURE.WHEEL;</dt>
<dd><p><em>Zoom.</em>
    Spinning the mouse wheel forwards/backwards will zoom in/out
    around the mouse position,
    just like dragging with the right button up-and-right or down-and-left.
    </p></dd>
<dt>&GESTURE.CLICK1;</dt>
<dd><p><em>Select.</em>
    If there is a plotted point near the cursor,
    it will plot a marker on it and
    <ref id="activation" plaintextref="yes">activate</ref> it.
    </p></dd>
</dl>
</p>

<p>You can also manually fix the plot bounds using the <label>Range</label>
tab of the <ref id="PlaneAxisControl">Axes control</ref>.
</p>

</subsubsubsect>

<subsubsubsect id="TimeAxisControl">
<subhead><title>Time Axes Control</title></subhead>

<p>The <label>Axes</label> (&IMG.AXIS_EDIT;) for the
time plot window has six tabs.
</p>

<figure>
<caption><px>Coords tab of time Axes control</px></caption>
<figureimage src="&FIG.TimeAxisControl_coords;"/>
</figure>

<p>The <label>Coords</label> tab controls the vertical axis coordinates
(you can't flip or rescale the time axis).
It has the following options:
<dl>
<dt>Y Log</dt>
<dd><p>If selected, vertical axis coordinates are logarithmic,
    otherwise they are linear.
    </p></dd>
<dt>Y Flip</dt>
<dd><p>If selected, vertical axis coordinate axes increase down rather
    than up.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Navigation tab of time Axes control</px></caption>
<figureimage src="&FIG.TimeAxisControl_navigation;"/>
</figure>

<p>The <label>Navigation</label> tab controls details of how the
navigation works.
It has the following options:
<dl>
<dt>Pan/Zoom Axes</dt>
<dd><p>By default, dragging with the mouse or using the mouse wheel
    on the body of the plot
    will pan or zoom in the horizontal (time) direction only,
    which is usually what you want for a time series.
    Using this control you can make it work in the vertical direction as well.
    </p></dd>
<dt>Zoom Factor</dt>
<dd><p>Controls the factor by which each zoom action zooms the plot.
    Moving this slider to the left/right makes the mouse more/less sensitive
    (one wheel click or dragging a fixed distance has more/less zoom effect).
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Range tab of time Axes control</px></caption>
<figureimage src="&FIG.TimeAxisControl_range;"/>
</figure>

<p>The <label>Range</label> tab provides manual configuration of the
visible range of the plot.  Making changes to this tab will reset
the visible plot range, but not vice versa - zooming and panning
in the usual way will not change the settings of this panel.
</p>

<p>Filling in the <label>Minimum</label>/<label>Maximum</label>
fields for either or both axes will
constrain the corresponding range of the visible data.
The limits corresponding to any of those fields that are left blank
will initially be worked out from the data.
The <label>Subrange</label> double-sliders restrict the ranges
within the (explicit or automatic) min/max ranges.
Note you can move both sliders at once by grabbing a position between the two.
For the time axis, the range may be entered as an ISO-8601 date/time value.
</p>

<p>The <label>Clear</label> button resets all the fields.
The <label>Submit</label> button updates the plot with the current values
in this tab, as does making any changes to it.
</p>

<figure>
<caption><px>Grid tab of time Axes control</px></caption>
<figureimage src="&FIG.TimeAxisControl_grid;"/>
</figure>

<p>The <label>Grid</label> tab configures the appearance of the axis grid.
It has the following options:
<dl>
<dt>Time Format</dt>
<dd><p>Selects the representation for time/date in which the horizontal
    axis is labelled.
    Options are
    ISO-8601,
    decimal year,
    Modified Julian Day,
    and Unix (seconds since midnight on 1 Jan 1970).
    </p></dd>
<dt>Draw Grid</dt>
<dd><p>If true, grid lines will be drawn across the plot
    for every tick mark.
    </p></dd>
<dt>Minor Ticks</dt>
<dd><p>If set, minor (unlabelled) tick marks will be drawn between the
    major (labelled) ones.
    </p></dd>
<dt>Time/Y Tick Crowding</dt>
<dd><p>Use the slider to influence how many tick marks are drawn on each axis.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Labels tab of time Axes control</px></caption>
<figureimage src="&FIG.TimeAxisControl_labels;"/>
</figure>

<p>The <label>Labels</label> tab controls the text label on the Y axis
(the horizontal axis is not labelled).
If the <label>Auto</label> checkbox is set, the text will be taken
from one of the data coordinates being plotted on that axis.
To override that with your own axis label, unset Auto and type
text in to the <label>Y Label</label> field.
</p>

<figure>
<caption><px>Font tab</px></caption>
<figureimage src="&FIG.font_tab;"/>
</figure>

<p>The <label>Font</label> tab configures the font used for axis annotation.
It also affects some other things like the legend.
<dl>
<dt>Text Syntax</dt>
<dd><p>How to turn the text into characters on the screen.
    <label>Plain</label> and <label>Antialias</label> both take the
    text at face value, but Antialias smooths the characters.
    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.
    <label>LaTeX</label> interprets the text as LaTeX source code
    and typesets it accordingly.
    </p></dd>
<dt>Font Size</dt>
<dd><p>Size of the font in points.
    </p></dd>
<dt>Font Style</dt>
<dd><p>Style of the font.
    </p></dd>
<dt>Font Weight</dt>
<dd><p>Whether the font is plain, bold or italic.
    </p></dd>
</dl>
</p>

<figure>
<caption><px>Size tab</px></caption>
<figureimage src="&FIG.size_tab_insets;"/>
</figure>

<p>The <label>Size</label> tab allows you to set the geometry of the
generated plot in pixels.  By default, the plot is simply resized to
fit the current size and shape of the window.  However, if you fill
in the <label>Outer width</label> and/or <label>Outer height</label>
fields, the size will instead be fixed to the given dimension in pixels.
Note if you pick a large value, you may need to manually resize the
window to see all of the plot.
Similarly, the <label>Border</label> fields fix the number of pixels
surrounding the data region of the plot; if these are left blank,
as by default, these borders are sized to accommodate the things
that have to fit in them (such as axis annotations).
</p>

<p>The main use for this panel is to fix the size and alignment
of the generated images if you want to export a series of
similar plots.
</p>

</subsubsubsect>

</subsubsect>

</subsect>

<subsect id="GraphicsWindow">
<subhead><title>Old-Style Plot Windows</title></subhead>

<p><em>This section describes the old-style plotting windows used
as standard in TOPCAT versions 2 and 3.  Since version 4 (2013),
the visualisation has been rewritten, and the new standard plotting windows
are described in <ref id="plot2"/>.
The windows described in this section are mildly deprecated, and will
not be developed further.  Most of their capabilities are handled
better by the new-style plotting windows.
However, these ones are still functional and
if you want to use them you can find them in the <label>Graphics</label>
menu of the <ref id="ControlWindow">Control Window</ref>, below the
new-style plot options.
</em></p>

<p>Common features of the old-style plotting windows are described
in the first subsection below; the specific windows themselves
are described in the later subsections.
</p>

<subsubsect>
<subhead><title>Common Features</title></subhead>

<p>The various types of old-style plotting windows
have different characteristics
to fulfil their different functions, but they share a common way of
doing things.  Each window contains a number of controls including
toolbar buttons, menu items, column selectors and others.
In general any change that you make to any of the controls will 
cause the plot to be redrawn to take account of that change.
If this requires a read or re-read of the data, a progress 
bar at the bottom of the window may show this progressing - 
except for very large tables it is usually pretty fast.
</p>

<p>Each of the graphics windows is displayed by clicking its
menu item in the <label>Graphics</label> menu of the 
<ref id="ControlWindow">Control Window</ref>.
If one of the tables in the list is selected at the time (the Current Table)
the new plot window will initially be displayed showing data from 
some of its columns (generally the first few numeric columns) 
by way of illustration.  You will usually want to change the controls
so it displays the quantities you are interested in.
</p>

<p>The following subsections describe some of the features which 
work the same for most or all of the old-style graphics windows.
</p>


<subsubsubsect id="PointSelector">
<subhead><title>Dataset Selectors</title></subhead>

<p>All the old-style graphics windows provide one or more axes
on which to plot -
the histogram has 1, the 2d scatter and density plots have 2, the 3d scatter
plot has 3 and the spherical plot has 2 or 3.  In each case you select
one or more dataset to plot on these axes, and select what plotting
style to use for each set.  A dataset is typically a number of columns
from a table (the number matching the dimensionality of the plot) and
a selection of row subsets associated with that table.  You select this
and the plotting style(s) using the panel at the bottom of each plot
window.  Here is dataset selector for the 2d scatter plot:
</p>

<figure>
<caption><px>Default dataset selector from 2d scatter plot window</px></caption>
<figureimage src="&FIG.PointSelector;"/>
</figure>

<p>The different parts of this control work as follows:
<dl>

<dt>Data panel</dt>
<dd><p>The <label>Table</label> selector gives the identifier of the table
    (one of the ones loaded into TOPCAT) that the data comes from.
    </p>
    <p>The <label>Axis</label> selectors 
    (here <label>X Axis</label> and <label>Y Axis</label>) give the quantities
    to be plotted.  If you click the little down arrow at the right
    of each selector you get a list of all the numeric columns in the
    chosen table, from which you can select one.
    If you click the little left and right arrows to the right of the 
    selector it will cycle through all the columns in the table.
    However, if you prefer you can type in an expression to use here.
    This may be more convenient if there's a very long list of columns
    (another way to deal with this is to hide most of the columns using
    the <ref id="ColumnInfoWindow">Column Window</ref>).
    However, what you type in doesn't have to be a column name, it can
    be an algebraic expression based on columns in the table, or even
    a constant.
    In the example, the X axis is a straight column name, and the Y axis
    is an expression.  The expression language syntax is explained in
    <ref id="jel"/>.
    </p>
    <p>The <label>Log</label> checkbox for each axis is used to 
    select whether the scale should be logarithmic or linear.
    </p>
    <p>The <label>Flip</label> checkbox for each axis is used to select
    whether the axis values increase in the conventional direction
    (left to right, bottom to top) or its opposite.
    </p>
    <p>Some of the buttons in the toolbar shown will modify what is 
    visible in this panel, for instance inserting new selectors
    to allow selection of error values.  All the selectors work in the
    same way however.
    </p></dd>

<dt>Row Subsets panel</dt>
<dd><p>This defines which row subsets for will be plotted in this window,
    and what plotting style should be used for them.  In this case there
    are three defined subsets, All, galaxy and star.  The checkboxes on
    the left indicate which ones will be displayed - here, only the latter
    two.  Sets of points are generally plotted in the order they are 
    selected for viewing; since points plotted afterwards can obscure ones
    plotted before ("underneath") this makes a difference.
    If you want to see a set of points without it being obscured by other
    ones in the plot, then deselect it and reselect it again (clicking
    twice in the corresponding checkbox), and this will ensure that its
    points are plotted on top.
    </p>
    <p>The buttons to the right of each subset name show the symbol
    that is used in the plot to display the data from that subset,
    in this case a red cross and a blue circle.
    These are selected automatically when the subset is first selected
    for viewing (the initial default style set depends mainly on how many
    rows there are in the selected table - many rows gives small dots,
    few gives big ones).  However, you have a lot of freedom to configure
    how they appear.  If you click the button with the symbol on it
    a dialogue will pop up which allows you to select colour, shape, 
    transparency and so on, as well as error bar style if appropriate
    and things like whether fitted lines will be plotted for that subset.
    The options available differ according to the kind of plot, 
    and are described along with the different graphics windows 
    in the following subsections.
    The style window stays visible until you dismiss it, but if you
    click on another of the buttons in the Row Subsets panel its contents
    will change to allow you to select values for the corresponding
    subset.
    Most graphics windows have a <label>Marker Style</label> menu. 
    This allows you to change all the styles in the plot at once to
    be members of a uniform set, for instance different coloured pixels,
    or black open shapes.  If you select one of these it will overwrite
    the existing style selections, but they can be edited individually
    afterwards.
    </p></dd>

<dt>Dataset Tool Bar</dt>
<dd><p>The toolbar shown above the data panel in the figure 
    contains buttons which affect the dataset selector itself.  
    The first two buttons add and remove dataset <label>Tabs</label> 
    (see below) and are present for all plots.
    The other items configure optional selectors appearing in the
    <label>Data Panel</label> - the ones shown here are concerned with
    <ref id="auxAxes" plaintextref="yes">Auxiliary Axes</ref>,
    <ref id="labels" plaintextref="yes">Point Labels</ref> and
    <ref id="errorBars" plaintextref="yes">Error Bars</ref>,
    but not all the types of plot have exactly the same ones.
    </p></dd>

<dt>Tabs</dt>
<dd><p>The example shows two tabs: <label>Main</label> and <label>A</label>;
    the currently visible one is A.  You can select a tab by clicking
    on its name.  In each tab you select a table and a set of 
    columns/expressions, and if they are all filled in it will 
    contribute points (or bars, or whatever) to the plot.
    The Main dataset determines the initial values
    for the axis labels, but the data comes equally from all of them.
    The numerical values of the coordinates are treated the same for all the
    datasets, but their meanings might be different, for instance
    one dataset may be plotting V magnitude against ellipticity and another
    plotting B magnitude against ellipticity.
    </p>
    <p>The <label>Add Dataset</label> (&IMG.ADD_TAB;)
    and <label>Remove Dataset</label> (&IMG.REMOVE_TAB;) 
    buttons in the toolbar add a new tab or remove the selected one
    respectively.  
    Initially only the Main tab is present, and this one cannot be removed.
    </p></dd>

</dl>
</p>

<p>Sometimes (high-dimensional plots, auxiliary axes, error bars) 
a lot of information needs to be entered into the data panel,
and the bottom part of the window can get quite large.
Normally, the plot in the upper part of the window shrinks to accommodate it.
You can of course resize the window to gain more space, but if your
screen is small you may still end up with an uncomfortably small plot.
If this happens, you can use the following button from the main toolbar:
<dl>
<dt>&IMG.SPLIT; Split Window</dt>
<dd><p>When this toggle button is on, the dataset selector can be resized
    by dragging the bar between it and the plot itself up or down.
    If there is insufficient space for all the components in the selector,
    a scrollbar will appear.  When it is off (the default),
    the full height of the selector will be visible, and the plot will
    shrink to accommodate it.
    </p></dd>
</dl>
</p>


</subsubsubsect>

<subsubsubsect id="axisConfig">
<subhead><title>Axis Configuration and Zooming</title></subhead>

<p>In general terms the axes on which the graphics are plotted are
defined by the datasets you have selected.
The axis labels are set from the column names or expressions chosen
for the <label>Main</label> dataset, and the ranges are determined
so that all the data from the chosen datasets can be seen.
However, these things can be adjusted manually.
</p>

<p>The following features are available directly from the window for 
configuring axis range:
<dl>
<dt>X-Y Zoom</dt>
<dd><p>In some of the windows 
    (<ref id="PlotWindow">2d scatter plot</ref>,
     <ref id="HistogramWindow">histogram</ref> and 
     <ref id="DensityWindow">density map</ref>), 
    you can change both axis ranges by zooming in or out
    with the mouse on the plot surface itself. 
    To zoom in, place the mouse at the top left of the
    region you want to examine, press the button, drag it to the
    bottom right corner, and release the button.  To zoom out, drag
    up and left instead.
    A box is drawn as you drag so you can see what you're doing.
    </p></dd>

<dt>Centre Zoom</dt>
<dd><p>The <ref id="Cartesian3DWindow">3d</ref> and
    <ref id="SphereWindow">spherical</ref> plots allow you to zoom in
    on the central part of the window.  The 'active region' for
    dragging is to the left or right of the plot (the region on the right
    is rather thin, and does not include the width used by the legend).
    When the pointer is in these regions, the mouse cursor symbol 
    should change to indicate that zooming can be done.
    Drag down to zoom in and up to zoom out.
    </p>
    <p>An easier alternative for zooming in the 3D windows is to use the
    mouse wheel, if you have one: wheel forward to zoom in and 
    backward to zoom out.
    </p></dd>

<dt>Axis Zoom</dt>
<dd><p>In some of the windows
    (<ref id="PlotWindow">2d scatter plot</ref>,
     <ref id="HistogramWindow">histogram</ref>,
     <ref id="DensityWindow">density map</ref>,
     <ref id="LinesWindow">stacked lines</ref>)
    you can modify the range on each axis independently by dragging the
    mouse over where the axis is drawn.  The 'active region' for dragging
    is just below the X axis and just to the left of the Y axis, in the
    region where the numeric and text labels are written.
    When the pointer is in one of these regions, the mouse cursor
    symbol should change to indicate that zooming can be done.
    As for the X-Y Zoom, drag left-to-right or up-to-down
    to zoom in and right-to-left or down-to-up to zoom out.
    </p></dd>

<dt>Auxiliary (Colour) Axis Zoom</dt>
<dd><p>When <ref id="auxAxes">Auxilary Axes</ref> are in use, you can
    zoom in and out of them by dragging up and down on the colour bar
    to the right of the plot, in the same way as for a normal Axis 
    Zoom above.
    </p></dd>

<dt>&IMG.RESIZE; Rescale</dt>
<dd><p>If you find you're zoomed to a region you don't want to be in,
    you can use the Rescale toolbar button to return to the default 
    scale (full coverage).  Note this affects any auxiliary axes
    as well as the spatial ones.
    Some windows may have per-axis rescale buttons too 
    (&IMG.RESIZE_X;, &IMG.RESIZE_Y;).
    </p></dd>
</dl>
</p>

<p>For more control over axis range and labelling, use the
<label>Configure Axes and Title</label> (&IMG.AXIS_EDIT;) toolbar button,
which will pop up a dialogue like the following:
</p>
<figure>
<caption><px>Axis Configuration Dialogue for 2-d axes</px></caption>
<figureimage src="&FIG.AxisWindow;"/>
</figure>

<p>You can fill in these values for each axis as follows:
<dl>
<dt>Label</dt>
<dd><p>For each axis the label box contains the text used to annotate
    the axis in the plot.  By default this is the same as the text
    in the <label>Main</label> dataset column selector 
    (usually a column name), followed by the units if known.
    However, you can change it by typing whatever text you like.
    </p></dd>

<dt>Range</dt>
<dd><p>The range boxes allow you to specify the lower and upper limits
    of each axis.  By default these are blank, meaning that the plot
    will size its axes so that all the data can be seen.  However, if
    you fill in one or both of the boxes with a suitable numeric value,
    the lower/upper bound will be fixed at that.  Note that the lower
    bound (left box) must be numerically less than the upper bound
    (right box).
    </p></dd>
</dl>
Both values are reset if the plot's axis is changed (a new column or
expression is selected for the Main dataset), or if the range is 
reset in some other way (e.g. by zooming).
</p>

<p>The plot title may also be set in the <label>Plot Title</label> panel
of this window:
<dl>
<dt>Title</dt>
<dd><p>Any text entered here will be displayed at the top of the plot
    to provide a title.
    </p></dd>
</dl>
</p>

</subsubsubsect>


<subsubsubsect id="errorBars">
<subhead><title>Error Bars</title></subhead>

<p>TOPCAT provides quite flexible graphical representation of
symmetric or asymmetric errors in 1, 2 and 3 dimensions.
The plots with error bar support are the
<ref id="PlotWindow">2D</ref>, <ref id="Cartesian3DWindow">3D</ref> and
<ref id="SphereWindow">spherical</ref> scatter plots and the
<ref id="LinesWindow">stacked lines plot</ref>.
</p>

<p>By default, error bar drawing is switched off.  The simplest way
to activate it is to use the relevant error bar button(s) 
in the data selector tool bar (the one below the plot).
For the Cartesian (2D, 3D, lines) plots, some or all of 
the following buttons are present:
<dl>
<dt>&IMG.ERROR_X; X symmetric errors</dt>
<dt>&IMG.ERROR_Y; Y symmetric errors</dt>
<dt>&IMG.ERROR_Z; Z symmetric errors</dt>
</dl>
Any combination of them can be active at once.
Clicking one of these buttons toggles symmetric error bar drawing 
for that axis on or off.  When it is on, an additional column selector
will appear to the right of the main column selector for the axis
in question.  If you fill this in with a column name or expression
which gives the error for that axis, then the error bars will be
plotted.
TOPCAT may make a guess based on column names and UCDs about which 
columns provide error values for which other columns, so the error
selector may get filled in automatically.  However, in most cases you
will need to provide the error values by selecting a column yourself, 
and occasionally you may need to correct TOPCAT's guesses.
</p>

<p>Here is a 2D plot in which symmetric X and asymmetric Y 
errors are being used:
</p>

<figure>
<caption><px>Plot window with symmetric X and asymmetric Y errors</px></caption>
<figureimage src="&FIG.PlotWindow_err;"/>
</figure>

<p>You can see that with the error column selector, the panel 
has become too wide for the window so a scrollbar has appeared at the 
bottom - you can scroll this left and right or enlarge the window 
to see the parts that you need to.
</p>

<p>For the <ref id="SphereWindow">spherical plot</ref> 
the following error toggle buttons are present:
<dl>
<dt>&IMG.ERROR_TANGENT; tangential isotropic errors</dt>
<dt>&IMG.ERROR_Z; radial symmetric errors</dt>
</dl>
These work in a similar way to the Cartesian erors above, 
except that the tangential one adds a 
single column selector, with an associated unit selector, 
near the latitude and longitude selectors to determine
the isotropic angular size of error small circles.
</p>

<p>If you want to use <label>asymmetric</label> 
or one-sided errors, use the options in the <label>Errors</label> menu
instead of the toolbar buttons.  For instance the options for
X axis error bars in the 2D scatter plot are:
<dl>
<dt>&IMG.ERROR_NONE; None</dt>
<dt>&IMG.ERROR_SYMMETRIC; Symmetric</dt>
<dt>&IMG.ERROR_LOWER; Lower Only</dt>
<dt>&IMG.ERROR_UPPER; Upper Only</dt>
<dt>&IMG.ERROR_BOTH; Lower &amp; Upper</dt>
</dl>
These give you different column selector boxes, but work in much
the same way as the symmetric ones.
</p>

<p>There are many options for the plotting style of one, two and three
dimensional error bars, including capped and uncapped bars, crosshairs, 
ellipses and rectangles.  
This plotting style is controlled from the plot window's
<label>Style Editor</label> window (see e.g. <ref id="MarkStyleEditor"/>),
which can be viewed by clicking on the marker icon in the Row Subsets
panel at the bottom right of the window.  The available error bar 
styles will depend on which axes currently have errors; if none do, then
the error bar selector will be disabled.
You can also use the <label>Error Style</label> menu to change the error 
style for all the visible datasets at once.
</p>

</subsubsubsect>

<subsubsubsect id="labels">
<subhead><title>Point Labels</title></subhead>

<p>On the 2-d and 3-d scatter plots you can write text labels adjacent
to plotted points.  To do this click the <label>Draw Labels</label>
(&IMG.LABEL;) button in the dataset toolbar (below the plotting area
in the plot window).  This will reveal a new <label>Point Labels</label>
selector below the existing spatial ones.
Using this you can select any of the table columns (not just the
numeric ones as for the other selectors), or give a string or 
numeric expression involving them.  When this selector is filled
in, every point in the dataset which has a non-blank value for
this quantity will have it written next to the point on the display.
</p>

<figure>
<caption><px>Point Labelling for Messier objects
             in the spherical plot</px></caption>
<figureimage src="&FIG.SphereWindow_labels;"/>
</figure>

<p>In this example the NAME column has been selected,
so that each point plotted (in this case all the Messier objects)
is labelled with its name.
As you can see, where many labels are plotted near to each other
they can get in each others' way.  In some cases TOPCAT will
omit plotting labels in crowded regions, in others not - but in any
case if you have labels too tightly grouped they are unlikely
to be legible.
</p>

</subsubsubsect>

<subsubsubsect id="auxAxes">
<subhead><title>Auxiliary Axes</title></subhead>

<p>TOPCAT can plot data in one, two or three spatial dimensions,
but sometimes the the data which you need to 
visualise is of higher dimensionality.  For this purpose, 
some of the plotting windows (2D and 3D scatter plots) allow you
to control the colouring of plotted points according to 
values from one or more additional columns (or calculated expressions),
which gives you more visual information about the data you are examining.
</p>

<p>To use this facility, click the <label>Add auxiliary axis</label>
(&IMG.ADD_COLORS;) button in the dataset toolbar (below the plot area
in a plot window).
A new axis selector will appear below the existing spatial ones,
labelled <label>Aux 1 Axis</label>.  It has log and flip checkboxes 
like the spatial axes, and to the right (you may need to widen the
window or use the scrollbar at the bottom to see it) is a selector depicting a 
number of colourmaps to choose from - the default one resembling a 
rainbow is usually quite suitable, but you can pick others.
If you enter a column name or expression into the selector, each 
plotted point will be coloured according to the value of that quantity
in the corresponding row of data.  If that quantity is null for a row,
the corresponding point will not be plotted. 
A scale on the right of the plot indicates how the colour map 
corresponds to numeric values.
To remove the auxiliary axis and go back to normally-coloured points,
simply click the <label>Remove auxiliary axis</label> (&IMG.REMOVE_COLORS;)
button.
</p>

<figure>
<caption><px>3D plot of simulation data showing X, Y, Z spatial position
         with the auxiliary axis indicating timestep.</px></caption>
<figureimage src="&FIG.Cartesian3DWindow_aux;"/>
</figure>

<p>There are two types of colour maps you can choose from: 
<label>colour fixing</label> and <label>colour modifying</label>.
The fixing ones are easiest to understand: the original colour of
the point (as drawn in the legend) is ignored, 
and it is coloured according to the relevant
value on the selected auxiliary axis.
The colour modifying maps take the original colour and affect it
somehow, for instance by changing its transparency or its blue
component.  These are marked with an asterisk ("*") in the
colour map selector.  They can be used to convey more information but
are often harder to interpret visually - for one thing the shading of
the colour bar in the legend will not correspond exactly to the colours
of the plotted points.
</p>

<p>By using modifying colour maps it is possible to perform plots with
more than one auxiliary axis - typically the first one will be a 
fixing map and subsequent ones will be modifying.  So the first
auxiliary axis could have the (fixing) Rainbow map, and the second could
have the (modifying) Transparency map.  The colour alterations are
applied in order.  It is possible, but pointless, to have multiple
fixing maps applied to the same points - the last-numbered one will
determine the colour and earlier ones will get ignored.
Multiple aux axes can be obtained by clicking the 
<label>Add auxiliary axis</label> button more than once.
When combining several maps some thought has to be given to which 
ones to use - some good combinations are the three RGB ones or
the three YUV ones.
</p>

<p>A fairly wide range of colour maps of both kinds is provided by default.
If these do not suit your needs, it is possible to provide your own
custom colour fixing maps using the <label>lut.files</label> system 
property - see <ref id="jvmProperties"/>.
</p>

<p>It is easy to generate attractive screenshots using auxiliary axes.
Making visual sense of the results is a different matter.
One visualisation expert tried to dissuade their introduction in TOPCAT
on the grounds that the graphics they produce are too hard for 
humans to interpret - I hope that these plots can assist with some 
analysis, but it is a somewhat experimental feature which may or 
may not end up being widely useful.
The maximum number of auxiliary axes which can
be used together is currently three.  This could be increased on request,
but if you feel you can generate an intelligible plot using more than 
this then you're considerably smarter than me.
</p>


</subsubsubsect>


<subsubsubsect id="plotSubsets">
<subhead><title>Defining Subsets by Region</title></subhead>

<p>When quantities are plotted in one of the graphics windows it becomes
easy to see groupings of the data which might not otherwise be apparent;
a cluster of (X,Y) points representing a group of rows may correspond
to a physically meaningful grouping of objects which you would like
to treat separately elsewhere in the program, for instance
by calculating statistics on just these rows, writing them out to
a new table, or plotting them in a different colour on graphs
with different coordinates.
This is easily accomplished by creating a new
<ref id="subsets">Row Subset</ref> containing the grouped points,
and the graphics windows provide ways of doing this.
</p>

<p>In some of the plots 
(<ref id="HistogramWindow">Histogram</ref>
 <ref id="PlotWindow">2d Scatter plot</ref>
 <ref id="DensityWindow">Density map</ref> and
 <ref id="SphereWindow">Spherical plot</ref>)
you can set the axis ranges (either manually or by zooming with the
mouse - see <ref id="axisConfig"/>) 
so that only the points you want to identify are visible,
and then click the 
<label>New Subset From Visible</label> toolbar button
(the icon is &IMG.VISIBLE_SUBSET;, &IMG.RANGE_SUBSET; or &IMG.XRANGE_SUBSET; 
depending on the plot type).
This defines a subset consisting of all the 
points that are visible on the current plot.
This is only useful if the group you are interested in
corresponds to a rectangular region in the plotting space.
</p>

<p>A more flexible way is to draw a region or regions
on the plot which identify the points you are interested in.
To do this, hit the
<label>Draw Subset Region</label> (&IMG.BLOB_SUBSET;)
toolbar button.  Having done this, you can drag the mouse around
on the plot (keep the left mouse button down while you move)
to encircle the points that you're interested in.
As you do so, a translucent grey blob will be left behind -
anything inside the
blob will end up in the subset.  You can draw one or many blobs,
which may be overlapping or not.  If you make a mistake while
drawing a sequence of blobs, you can click the right mouse button,
and the most recently added blob will disappear.
When you're in this region-drawing mode,
you can't zoom or resize the window or change the characteristics
of the plot, and the <label>Draw Subset Region</label> button
appears with a tick over it (&IMG.BLOB_SUBSET_END;) to remind you
you're in it.  Here's what the plot looks like while you're drawing:
</p>
<figure>
<caption><px>Region-Drawing Mode</px></caption>
<figureimage src="&FIG.PlotWindow_blob;"/>
</figure>
<p>When you're happy with the region you've defined, click the
&IMG.BLOB_SUBSET_END; toolbar button again.
</p>

<p>In either case, when you have indicated that you want to define a 
new row subset, a dialogue box will pop up to ask you its name.
As described in <ref id="subsetDef"/>, it's a good idea to use a
name which is just composed of letters, numbers and underscores.
You can optionally select a subset name which has been used before
from the list, which will overwrite the former contents of that subset.
When you enter a name and hit the <label>OK</label> button, 
the new subset will be created and the points in it will be 
shown straight away on the plot using a new symbol.  
As usual, you can toggle whether the points in this subset are displayed
using the <label>Row Subsets</label> box at the bottom of the Plot Window.
</p>

</subsubsubsect>

<subsubsubsect id="exportGraphics">
<subhead><title>Exporting Graphics</title></subhead>

<p>All the old-style graphics windows have
the following export options in the toolbar:
<dl>
<dt>&IMG.PDF; Export as PDF</dt>
<dt>&IMG.IMAGE; Export as GIF</dt>
</dl>
and additionally, the <label>Export</label> menu contains:
<dl>
<dt>&IMG.PRINT; Export as Encapsulated PostScript</dt>
<dt>&IMG.PRINT_ZIP; Export as Gzipped Encapsulated PostScript</dt>
<dt>&IMG.JPEG; Export as JPEG</dt>
<dt>&IMG.IMAGE; Export as PNG</dt>
</dl>
These can be used to export the currently visible plot to an external 
graphics format for later use.
</p>

<p>Exporting to the pixel-based formats (GIF, JPEG, PNG) is fairly
straightforward: each pixel on the screen appears as one pixel
in the output file.  PNG is the most capable, but it is not supported
by all image viewers.  GIF works well in most cases, but if there are
more than 255 colours some of the colour resolution will be lost.  
JPEG can preserve a wide range of colours, but does not support 
transparency and is lossy, so close inspection of image features 
will reveal blurring.
</p>

<p>When exporting to Portable Document Format (PDF) or
Encapsulated PostScript (EPS), which are vector graphics formats,
there are a few things to consider:
<dl>
<dt>Positional Quantisation</dt>
<dd><p>The output file will render text, lines and
    markers properly, with smooth edges rather than steps where pixel
    boundaries would be on the screen.  However, the <em>positional</em>
    resolution is the same as it would be on the screen, so if you
    have a 400-pixel high plot for instance, there are only 400 possible
    Y coordinates at which a marker can be plotted.  In general this 
    is not obvious by looking at the output plot, but you may find it
    helpful to increase the size of the plot on the screen by resizing 
    the window before performing an export to EPS.  This reduces the
    effect of the positional quantisation, but note it will also have
    the effect of making the text labels proportionally smaller to the
    graphics.
    </p></dd>

<dt>Transparency</dt>
<dd><p>For technical reasons transparent markers cannot easily
    be rendered when a plot is exported to PostScript.  In some cases
    the plot is done using a bitmap in the PostScript output to permit
    transparency and in some cases the points are just plotted opaque.
    Try it and see; if the points come out opaque instead
    of transparent you may need to export to GIF instead.
    Better workarounds may be provided in future releases.
    </p></dd>

<dt>File Size</dt>
<dd><p>In some cases (2D and 3D scatter plots with many thousands of points)
    output EPS files can get extremely large; the size scales
    with the number of points drawn, currently with a factor of a few
    hundred bytes per point.  In some cases you can work round this by
    plotting some points as transparent so that the plot is rendered
    as a bitmap (see the discussion of transparency above) which 
    scales as the number of pixels rather than the number of points.
    The Gzipped EPS format helps somewhat (though can be slow); 
    PDF output is better still.  Even PDF files may be unmanageably large
    for very many points however.
    </p></dd>
</dl>
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="HistogramWindow">
<subhead><title>Histogram (old-style)</title></subhead>

<p><em>This section describes an old-style plotting window.
The standard plotting windows are described in <ref id="plot2"/>.
</em></p>

<figure>
<caption><px>Histogram Window</px></caption>
<figureimage src="&FIG.HistogramWindow;"/>
</figure>

<p>The histogram window lets you plot histograms of one or more 
columns or derived quantities.
You can display it using the <label>Histogram</label> (&IMG.HISTOGRAM;)
item in the <ref id="ControlWindow">Control Window</ref>'s
<label>Graphics</label> menu.
</p>

<p>You select the quantity or quantities to plot using the
<ref id="PointSelector" plaintextref="yes">dataset selector</ref>
at the bottom of the window.
You can configure the axes, including <strong>zooming</strong> in and out,
with the mouse (drag on the plot or the axes) 
or manually as described in <ref id="axisConfig"/>.
</p>

<p>The <label>Bin Placement</label> box below the main plot controls
where the bars are drawn.  Select the horizontal range of each bar 
using the <label>Width</label> entry box - either type in the value 
you want or use the tiny up/down arrows at the right to increase/decrease
the bin size.
The <label>Offset</label> checkbox on the left determines where the zero
point on the horizontal axis falls in relation to the bins; 
if the box is checked then zero (or one for logarithmic X axis) 
is in the centre of a bin, and if it's unchecked then zero (or one) 
is on a bin boundary.
</p>

<p>The following buttons are available on the toolbar:
<dl>

<dt>&IMG.SPLIT; Split Window</dt>
<dd><p>Allows the dataset selector to be resized by dragging a separator 
    between it and the plot area.  Good for small screens.
    </p></dd>

<dt>&IMG.REDO; Replot</dt>
<dd><p>Redraws the current plot.  It is usually not necessary to
    use this button, since if you change any of the plot characteristics
    with the controls in this window the plot will be redrawn
    automatically.  However if you have changed the data, e.g. by
    editing cells in the <ref id="TableViewerWindow">Data Window</ref>,
    the plot is not automatically redrawn (since this is potentially an
    expensive operation and you may not require it).
    Clicking this button redraws the plot taking account of any changes
    to the table data.
    </p></dd>

<dt>&IMG.AXIS_EDIT; Configure Axes and Title</dt>
<dd><p>Pops up a dialogue to allow manual configuration of axis ranges,
    axis labels and plot title - see <ref id="axisConfig"/>.
    </p></dd>

<dt>&IMG.PDF; Export as PDF</dt>
<dd><p>Pops up a dialogue which will write the current plot as a PDF file.
    </p></dd>

<dt>&IMG.IMAGE; Export as GIF</dt>
<dd><p>Pops up a dialogue which will output the current plot to a GIF file.
    The output file is just the same as the plotted image that you see.
    Resize the plotting window before the export to control the size
    of the output GIF.
    </p></dd>

<dt>&IMG.RESIZE; Rescale</dt>
<dd><p>Rescales the axes so that the width and height are sufficient to
    accommodate all the non-zero bars in the histogram for all the currently
    selected datasets.
    By default the plot will be scaled like this, but it it may have changed
    because of changes in the subset selection or from zooming in or out.
    </p></dd>

<dt>&IMG.RESIZE_X; Rescale X</dt>
<dd><p>Rescales the horizontal axis to accommodate all the 
    currently plotted bars.
    The vertical axis scaling is not changed.
    </p></dd>

<dt>&IMG.RESIZE_Y; Rescale Y</dt>
<dd><p>Rescales the vertical axis to accommodate all the
    currently plotted bars.
    The horizontal axis scaling is not changed.
    </p></dd>

<dt>&IMG.GRID_ON; Grid</dt>
<dd><p>Toggles whether a grid is drawn over the plotting surface or not.
    </p></dd>

<dt>&IMG.LEGEND; Show Legend</dt>
<dd><p>Toggles whether a legend showing how each data set is represented
    is visible to the right of the plot.  Initially the legend is shown
    only if more than one data set is being shown at once.
    </p></dd>

<dt>&IMG.CUMULATIVE; Cumulative Plot</dt>
<dd><p>Toggles whether the histogram should be normal or cumulative.
    Normally the height of each bar is determined by counting the
    number of points which fall into the range on the X axis that it covers.
    For a cumulative plot, the height is determined by counting all the
    points between negative infinity and the upper bound of the range on
    the X axis that it covers.
    </p></dd>

<dt>&IMG.NORMALISE; Normalisation</dt>
<dd><p>Toggles whether histograms are normalised.
    When selected, each dataset will be normalised so that the sum of
    the counts of all its bars over the whole range of data is equal to one.
    </p></dd>

<dt>&IMG.YLOG; Log Y Axis</dt>
<dd><p>Toggles whether the Y axis is scaled logarithmically or not.
    </p></dd>

<dt>&IMG.RANGE_SUBSET; Subset From Visible</dt>
<dd><p>Defines a new <label>Row Subset</label> consisting of only the
    data in the bars which are visible in the current plot.
    See <ref id="plotSubsets"/> for more explanation.
    </p></dd>
</dl>
</p>

<p>The <label>Dataset Toolbar</label> contains the following options:
<dl>

<dt>&IMG.ADD_TAB; / &IMG.REMOVE_TAB; Add/Remove dataset</dt>
<dd><p>Adds/removes tabs in which the data for extra datasets can be entered.
    See <ref id="PointSelector"/>.
    </p></dd>

<dt>&IMG.WEIGHT; Weight Counts</dt>
<dd><p>If this toggle button is on, an additional <label>Weight Axis</label>
    selector appears below the <label>X Axis</label> selector.
    If this is filled in with a column name or expression, then instead of
    simply accumulating the number of points per bin, the Y axis will
    show the sum over the weighting quantity for points in each bin.
    Not having a weight axis is equivalent to filling in its value with
    the quantity 1.
    Note that with weighting, the figure drawn is no longer strictly speaking
    a histogram.
    </p>
    <p>When weighted, bars can be of negative height.  An anomaly of the
    plot as currently implemented is that the Y axis never descends below
    zero, so any such bars are currently invisible.  
    This may be amended in a future release
    (contact the author to vote for such an amendment).
    </p></dd>
</dl>
</p>

<p>The <label>Export</label> menu contains additional image export
options and the following options specific to the histogram:
<dl>

<dt>&IMG.SAVE; Save as Table</dt>
<dd><p>The bin counts/sums corresponding to the currently plotted histogram
    will be written to disk in tabular form.  The first two columns give
    the lower and upper bounds of each bin, and the subsequent columns
    give the occupancies of each bin for each plotted data set.
    If only one dataset is plotted, there will only be three columns.
    </p></dd>

<dt>&IMG.IMPORT; Import as Table</dt>
<dd><p>Assembles a table as per the <label>Save</label> option above,
    but rather than writing it to disk imports it directly into TOPCAT,
    where it can be manipulated in all the usual ways.
    </p></dd>

</dl>
</p>

<p>You have considerable freedom to configure how the bars are drawn;
controlling this is described in the following subsection.
</p>

<subsubsubsect id="BarStyleEditor">
<subhead><title>Histogram Style Editor</title></subhead>

<p>The bins in a histogram can be represented in many different ways.
A representation of how a bar will be displayed is shown on a button
to the right of the name of each visible subset, at the bottom right
of the histogram window.  If you click this button the following 
dialogue will pop up which enables you to change the appearance.
</p>

<figure>
<caption><px>Style editor dialogue for histogram bars</px></caption>
<figureimage src="&FIG.BarStyleEditor;"/>
</figure>

<p>The <label>Legend</label> box defines how the selected set will 
be identified in the legend which appears alongside the plot 
(though the legend will only be visible if <label>Show Legend</label> 
(&IMG.LEGEND;) is on):
<dl>
<dt>Icon</dt>
<dd><p>Displays the icon which will be shown to identify the points in
    the selected set.  Its appearance depends on the selections you
    make in the rest of this dialogue window.
    </p></dd>

<dt>Label</dt>
<dd><p>Gives the name written in the legend to label the subset.
    By default this is derived from the Row Subset's name and, if it's
    not part of the main dataset, the name of the dataset's tab.
    You can type in a new value to change what is written in the legend.
    </p></dd>

<dt>Hide Legend</dt>
<dd><p>If this checkbox is selected, then no entry for the selected set
    will appear in the legend.
    </p></dd>
</dl>
</p>

<p>The <label>Bars</label> panel describes the form of the bars to be
plotted for each data set.
<dl>
<dt>Colour</dt>
<dd><p>Selects the colour for the bar or line which will represent this set.
    </p></dd>

<dt>Bar Form</dt>
<dd><p>Selects the style of bar which will be plotted.
    Available styles are filled rectangles, open rectangles, stepped lines
    and spikes.
    </p></dd>

<dt>Bar Placement</dt>
<dd><p>Selects where each bar will be placed on the X axis within the
    ordinate region which it represents.  There are currently two options:
    <label>Over</label> means that it covers the whole of its range,
    and <label>Adjacent</label> means that it covers only a proportion of
    its range, so that multiple datasets plotted on the same graph don't
    obscure each other (if 2 sets are plotted, the first one will take the
    left half and the second will take the right half of each bin region,
    and so on).  In the case that there is only a single data set plotted,
    it doesn't matter which of these is chosen.
    </p></dd>

<dt>Line Thickness</dt>
<dd><p>Determines the thickness in pixels of any lines which are drawn.
    Only applies to those <label>Bar Form</label>s which use lines rather
    than solid blocks.
    </p></dd>

<dt>Dash</dt>
<dd><p>Determines the dash style (solid, dotted, dashed or dot-dashed) for
    any lines which are drawn.  Only applies to those <label>Bar Form</label>s
    which use lines rather than solid blocks.
    </p></dd>
    
</dl>
</p>

<p>Any changes you make in this window are reflected in the plot straight
away.  If you click the <label>OK</label> button at the bottom, the window
will disappear and the changes remain.  If you click <label>Cancel</label>
the window will disappear and any changes you made will be discarded.
</p>

<p>You can also change all the plotting styles at once by using the
<label>Bar Style</label> menu in the histogram window.
Here you can select a standard group of styles (e.g. all filled adjacent
bars with different colours) for the plotted sets.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="PlotWindow">
<subhead><title>2D Plot (old-style)</title></subhead>

<p><em>This section describes an old-style plotting window.
The standard plotting windows are described in <ref id="plot2"/>.
</em></p>

<figure>
<caption><px>Plot Window</px></caption>
<figureimage src="&FIG.PlotWindow;"/>
</figure>

<p>The plot window allows you to do 2-dimensional scatter plots of
one or more pair of table columns (or derived quantities).
You can display it using the <label>Plot</label> (&IMG.PLOT;) item
in the <ref id="ControlWindow">Control Window</ref>'s
<label>Graphics</label> menu.
</p>

<p>On the plotting surface a marker is plotted for each row in the
selected dataset(s)
at a position determined by the
values in the table columns selected to provide the X and Y values.
A marker will only be plotted if both the X and Y values are not blank.
Select the quantities to plot and the plotting symbols with the 
<ref id="PointSelector" plaintextref="yes">dataset selector</ref>
at the bottom.
You can configure the axes, including <strong>zooming</strong> in and out,
with the mouse (drag on the plot or the axes) 
or manually as described in <ref id="axisConfig"/>.
</p>

<p>Clicking on any of the plotted points will <label>activate</label> it - 
see <ref id="activation"/>.
</p>

<p>The following buttons are available on the toolbar:
<dl>

<dt>&IMG.SPLIT; Split Window</dt>
<dd><p>Allows the dataset selector to be resized by dragging a separator 
    between it and the plot area.  Good for small screens.
    </p></dd>

<dt>&IMG.REDO; Replot</dt>
<dd><p>Redraws the current plot.  It is usually not necessary to 
    use this button, since if you change any of the plot characteristics
    with the controls in this window the plot will be redrawn
    automatically.  However if you have changed the data, e.g. by
    editing cells in the <ref id="TableViewerWindow">Data Window</ref>,
    the plot is not automatically redrawn (since this is potentially an
    expensive operation and you may not require it).
    Clicking this button redraws the plot taking account of any changes
    to the table data.
    </p></dd>

<dt>&IMG.AXIS_EDIT; Configure Axes and Title</dt>
<dd><p>Pops up a dialogue to allow manual configuration of axis ranges,
    axis labels and plot title - see <ref id="axisConfig"/>.
    </p></dd>

<dt>&IMG.PDF; Export as PDF</dt>
<dd><p>Pops up a dialogue which will write the current plot as a PDF file.
    In general this is a faithful and high quality rendering of what
    is displayed in the plot window.  However, if plotting is being done
    using the transparent markers, the markers will
    be rendered as if they were opaque.
    Plots with very many points can result in rather large output PDFs.
    </p></dd>

<dt>&IMG.IMAGE; Export as GIF</dt>
<dd><p>Pops up a dialogue which will output the current plot to a GIF file.
    The output file is just the same as the plotted image that you see.
    Resize the plotting window before the export to control the size 
    of the output GIF.
    </p></dd>

<dt>&IMG.RESIZE; Rescale</dt>
<dd><p>Rescales the axes of the current plot so that it contains all
    the data points in the currently selected subsets.
    By default the plot will be scaled like this, but it it may have changed
    because of changes in the subset selection or from zooming in or out.
    </p></dd>

<dt>&IMG.GRID_ON; Grid</dt>
<dd><p>Toggles whether a grid is drawn over the plotting surface or not.
    </p></dd>

<dt>&IMG.LEGEND; Show Legend</dt>
<dd><p>Toggles whether a legend showing how each data set is represented
    is visible to the right of the plot.  Initially the legend is shown
    only if more than one data set is being shown at once.
    </p></dd>

<dt>&IMG.BLOB_SUBSET; Draw Subset Region</dt>
<dd><p>Allows you to draw a region on the screen defining a new 
    <ref id="subsets">Row Subset</ref>.  When you have finished 
    drawing it, click this button again to indicate you're done.
    See <ref id="plotSubsets"/> for more details.
    </p></dd>

<dt>&IMG.VISIBLE_SUBSET; Subset From Visible</dt>
<dd><p>Defines a new <label>Row Subset</label>
    consisting of only the points which
    are currently visible on the plotting surface.
    See <ref id="plotSubsets"/> for more explanation.
    </p></dd>

</dl>
</p>

<p>The <label>Dataset Toolbar</label> contains the following options:
<dl>

<dt>&IMG.ADD_TAB; / &IMG.REMOVE_TAB; Add/Remove dataset</dt>
<dd><p>Adds/removes tabs in which the data for extra datasets can be entered.
    See <ref id="PointSelector"/>.
    </p></dd>

<dt>&IMG.ADD_COLORS; / &IMG.REMOVE_COLORS; Add/Remove auxiliary axis</dt>
<dd><p>Adds/removes a selector for entering an auxiliary axis to modify
    point colours etc.
    See <ref id="auxAxes"/>.
    </p></dd>

<dt>&IMG.LABEL; Toggle point labelling</dt>
<dd><p>Allows text labels to be drawn near plotted points.
    See <ref id="labels"/>.
    </p></dd>

<dt>&IMG.ERROR_X; / &IMG.ERROR_Y; Toggle X/Y error bars</dt>
<dd><p>Switches between drawing symmetric error bars and no error bars
    in the X and Y directions respectively.
    Other options are available in the <label>Errors</label> menu.
    See <ref id="errorBars"/>.
    </p></dd>

</dl>
</p>

<p>You have considerable freedom to configure how the points are
plotted including the shape, colour and transparency of symbols,
the type of lines which join them if any, and the representation of
error bars if active.  These options are described in the following
subsection.
</p>

<subsubsubsect id="MarkStyleEditor">
<subhead><title>Plot Style Editor</title></subhead>

<p>When plotting points in a scatter plot there are many different
ways that each point can be displayed.  By default, TOPCAT chooses
a set of markers on the basis of how many points there are in the
table and uses a different one for each plotted set.  The marker for
each set is displayed in a button to the right of its name in the 
dataset selector panel at the bottom of the plot window.  If you 
click this button the following dialogue will pop up which enables
you to change the appearance.
</p>

<figure>
<caption><px>Style editor dialogue for 2d scatter plot</px></caption>
<figureimage src="&FIG.MarkStyleEditor;"/>
</figure>

<p>The <label>Legend</label> box defines how the selected set will 
be identified in the legend which appears alongside the plot 
(though the legend will only be visible if <label>Show Legend</label> 
(&IMG.LEGEND;) is on):
<dl>
<dt>Icon</dt>
<dd><p>Displays the icon which will be shown to identify the points in
    the selected set.  Its appearance depends on the selections you
    make in the rest of this dialogue window.
    </p></dd>

<dt>Label</dt>
<dd><p>Gives the name written in the legend to label the subset.
    By default this is derived from the Row Subset's name and, if it's
    not part of the main dataset, the name of the dataset's tab.
    You can type in a new value to change what is written in the legend.
    </p></dd>

<dt>Hide Legend</dt>
<dd><p>If this checkbox is selected, then no entry for the selected set
    will appear in the legend.
    </p></dd>
</dl>
</p>

<p>The <label>Marker</label> box defines how the markers plotted for
each data point will appear:
<dl>
<dt>Shape</dt>
<dd><p>Choose from a variety of shapes such as open or filled 
    circles, squares, crosses etc.
    </p></dd>

<dt>Size</dt>
<dd><p>Choose the size of the marker; the value given is approximate radius
    in pixels.  If a size of zero is chosen, then the shape doesn't matter,
    the points will be plotted as single pixels.
    </p></dd>

<dt>Colour</dt>
<dd><p>Choose the colour in which the markers, and
    any line if one is drawn, will be plotted.
    </p></dd>

<dt>Transparency</dt>
<dd><p>Choose transparency of the plotted symbols.
    The scale on the slider is logarithmic, with 1 at the left hand end.
    The actual value chosen is an integer written at the right of the
    slider.  This number gives the number of markers for this set which
    need to be plotted in the same position to result in fully opaque
    pixels - any fewer and the background, or other markers plotted
    underneath, will show through to some extent. 
    Setting this to some value greater than 1 is very useful if you
    have a very large number of points being plotted (especially if it's
    comparable with the number of the pixels on the screen), since it
    enables to you distinguish regions where there are lots of points
    on top of each other from those where there are only a few.
    </p></dd>

<dt>Error Bars</dt>
<dd><p>If <ref id="errorBars">error bars</ref> are active for this plot,
    allows you to select the way they will appear.  The options which
    can be selected here will depend on whether X and/or Y errors are
    in use.
    </p></dd>

<dt>Hide Markers</dt>
<dd><p>This check box is only enabled if a line and/or error bars 
    are being plotted; it allows the markers to be invisible, 
    so that only the line/error bars are seen.
    </p></dd>

</dl>
</p>

<p>The <label>Line</label> box determines if any lines are drawn associated
with the current set and if so what their appearance will be.
<dl>
<dt>Thickness</dt>
<dd><p>Selects the line thickness in pixels.
    </p></dd>

<dt>Dash</dt>
<dd><p>Selects a dash pattern (solid, dotted, dashed or dot-dashed) for
    the line.
    </p></dd>

<dt>Type</dt>
<dd><p>The other radio buttons determine what kind of line, if any,
    will be plotted for these points.  There are three options:
    <dl>
    <dt>None</dt>
    <dd><p>No line is drawn - this is the default.
        </p></dd>
    <dt>Dot to Dot</dt>
    <dd><p>A straight line segment is drawn between each of the points.
        If the points effectively form an ordered set of samples of a 
        function, this will result in a more-or-less smooth drawing of
        that function on the plot.  Note that the lines are drawn in
        the order that the points appear in the basic table, and if
        this doesn't match the 'ordinate' order the result will be a mess.
        Really, the drawing order ought to be the table's current sort
        order - that it is not is a misfeature which may be corrected
        at some point.
        Note also that if you try this with a huge table you're likely
        to get a result which (a) is messy and (b) takes a very long time
        to draw.
        </p></dd>
    <dt>Linear Correlation</dt>
    <dd><p>If you select this option then a linear regression line will
        be plotted.  The correlation coefficients will also be displayed
        to the right of the radio button (you may need to resize the
        window to see them all).  The values cited are
        <m>m</m> (gradient), <m>c</m> (intercept) and 
        <m>r</m> (product moment correlation coefficient).
        You can cut and paste from this text.
        </p>
        <p><strong>Note</strong> that for both the plotted line and the
        quoted coefficients the data is taken only from the points which
        are currently visible - that means that if you've zoomed the
        axes to exclude some of the data points, they will not be
        contributing to the calculated statistics.
        </p></dd>
    </dl>
    </p></dd>
</dl>
</p>

<p>Any changes you make in this window are reflected in the plot straight
away.  If you click the <label>OK</label> button at the bottom, the window
will disappear and the changes remain.  If you click <label>Cancel</label>
the window will disappear and any changes you made will be discarded.
</p>

<p>You can also change all the plotting styles at once by using the
<label>Marker Style</label> menu in the plot window.
Here you can select a standard group of styles (e.g. all open 2-pixel 
markers with different colours and shapes) for the plotted sets.
Similarly, error styles can be changed all at once using the 
<label>Error Style</label> menu.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="LinesWindow">
<subhead><title>Stacked Line Plot (old-style)</title></subhead>

<p><em>This section describes an old-style plotting window.
The standard plotting windows are described in <ref id="plot2"/>,
though note that at time of writing (v4.1) no equivalent new-style
plotting window is available for plotting stacked lines.
</em></p>

<figure>
<caption><px>Stacked Lines Window</px></caption>
<figureimage src="&FIG.LinesWindow;"/>
</figure>

<p>The stacked line plot window allows you to plot one or more ordinate (Y)
quantities against a monotonic abscissa (X) quantity.  
For clarity, the different plots are displayed on vertically 
displaced graphs which share the same X axis.
You can display this window using the <label>Lines</label> (&IMG.STACK;)
item in the <ref id="ControlWindow">Control Window</ref>'s
<label>Graphics</label> menu.
</p>

<p>The display initially holds a single X-Y graph, usually with lines
connecting adjacent points.  The points will be reordered before drawing
if necessary so that the line is displayed as a function of X, rather
than of an invisible third independent variable
(in the <ref id="PlotWindow">Scatter Plot</ref> this isn't done which
can lead to lines being scribbled all over the plot).
If one of the columns in the table appears to represent a time value,
this will be selected as the default X axis.  Otherwise, the 
'magic' <label>index</label> variable will be used, which represents
the row number.  Of course, these can be changed from their default
values using the selectors in the usual way.
</p>

<p>To add a new graph with a different Y axis, use the
<label>Add Dataset</label> (&IMG.ADD_TAB;) button in the 
<label>Dataset Toolbar</label> at the bottom of the window.
This has a slightly different effect from what it does in the other
plot windows, in that it inserts a new plotting region with its own 
Y axis at the top of the plot on which the specified data is drawn, 
rather than only causing a new set of points to be plotted on the 
existing plot region.
Thus all the datasets appear in their own graphs with their own Y axes
(though if you have multiple row subsets plotted for the same 
dataset they will appear on the same part of the plot as usual).
To remove one of the graphs, select its tab and use the
<label>Remove Dataset</label> (&IMG.REMOVE_TAB;) button as usual.
</p>

<p><label>Zooming</label> can only be done on one axis at a time
rather than dragging out an X-Y region on the plot surface, since 
there isn't a single Y axis to zoom on.
To zoom the X axis in/out, position the mouse just below the X axis
at the bottom of the plot and drag right/left.
To zoom one of the Y axes in or out, position the mouse just to the
left of the Y axis you're interested in and drag down/up.
To set the ranges manually, use the <label>Configure Axes and Title</label>
(&IMG.AXIS_EDIT;) button as usual, but note that there is one
label/range setting box for each of the Y axes.
These things work largely as described in <ref id="axisConfig"/>,
as long as you bear in mind that the range of each of the Y axes
is treated independently of the others.
</p>

<p>Clicking on any of the points will <label>activate</label> it -
see <ref id="activation"/>.
</p>

<p>The following buttons are available on the toolbar:
<dl>

<dt>&IMG.SPLIT; Split Window</dt>
<dd><p>Allows the dataset selector to be resized by dragging a separator 
    between it and the plot area.  Good for small screens.
    </p></dd>

<dt>&IMG.REDO;</dt>
<dd><p>Redraws the current plot.  It is usually not necessary to 
    use this button, since if you change any of the plot characteristics
    with the controls in this window the plot will be redrawn
    automatically.  However if you have changed the data, e.g. by
    editing cells in the <ref id="TableViewerWindow">Data Window</ref>,
    the plot is not automatically redrawn (since this is potentially an
    expensive operation and you may not require it).
    Clicking this button redraws the plot taking account of any changes
    to the table data.
    </p></dd>

<dt>&IMG.AXIS_EDIT; Configure Axes and Title</dt>
<dd><p>Pops up a dialogue to allow manual configuration of the range
    and label for the X axis and each of the Y axes, as well as a plot title - 
    see <ref id="axisConfig"/>. 
    </p></dd>

<dt>&IMG.PDF; Export as PDF</dt>
<dd><p>Pops up a dialogue which will write the current plot as a PDF file.
    </p></dd>

<dt>&IMG.IMAGE; Export as GIF</dt>
<dd><p>Pops up a dialogue which will output the current plot to a GIF file.
    The output file is just the same as the plotted image that you see.
    Resize the plotting window before the export to control the size
    of the output GIF.
    </p></dd>

<dt>&IMG.RESIZE; Rescale</dt>
<dd><p>Rescales all the plots so that all points in the plotted datasets 
    can be seen.  The X axis and all the Y axes are rescaled to fit the data.
    </p></dd>

<dt>&IMG.RESIZE_X; Rescale X Axis</dt>
<dd><p>Rescales the X axis only.  The X axis is rescaled to cover the 
    lowest and highest values on any of the plotted datasets, but the
    Y ranges are left as they are.
    </p></dd>

<dt>&IMG.RESIZE_Y; Rescale Y Axes</dt>
<dd><p>Rescales the Y axes only.  Each of the plotted Y axes are 
    independently rescaled so that they cover the lowest and highest 
    values within the currently visible X range.
    </p></dd>

<dt>&IMG.GRID_ON; Full Grid</dt>
<dd><p>Toggles whether X and Y grid lines are drawn over the plots or not.
    If this is selected, the single y=0 grid line (see next item)
    will automatically be deselected.
    </p></dd>

<dt>&IMG.LEGEND; Show Legend</dt>
<dd><p>Toggles whether a legend showing how each data set is represented
    is visible to the right of the plot.  Initially the legend is shown
    only if more than one data set is being shown at once.
    </p></dd>

<dt>&IMG.Y0_LINE; y=0 Grid Lines</dt>
<dd><p>Toggles whether a single horizontal line at y=0 is drawn.
    If this is selected, the full grid (see previous item)
    will automatically be deselected.
    </p></dd>

<dt>&IMG.Y_CURSOR; Show Vertical Crosshair</dt>
<dd><p>Toggles whether a vertical line follows the mouse when it is
    positioned over the plot.  This can be useful to compare features
    in different graphs at the same X coordinate position.
    </p></dd>

<dt>&IMG.ANTIALIAS; Antialias</dt>
<dd><p>Toggles whether lines are drawn with antialiasing. 
    Antialiasing means smoothing lines so that they appear less pixelised,
    and generally improves the aesthetic appearance of the plot,
    but in some circumstances it might look better not antialiased.
    The state of this button does not affect images exported to postscript.
    </p></dd>

<dt>&IMG.XRANGE_SUBSET; Subset From X Range</dt>
<dd><p>Defines a new <label>Row Subset</label> in each of the plotted
    tables consisting of only the points in the currently visible range
    on the horizontal axis.  Points will be included even if they are
    outside the current ranges of the Y axes.
    </p></dd>

</dl>
</p>

<p>The <label>Dataset Toolbar</label> contains the following options:
<dl>

<dt>&IMG.ADD_TAB; / &IMG.REMOVE_TAB; Add/Remove dataset</dt>
<dd><p>Adds/removes a dataset for plotting, which both adds/removes a 
    tab from the dataset selector and adds/removes a plot in the currently
    visible stack in the plotting area.  See above for more explanation.
    </p></dd>

<dt>&IMG.ERROR_X; / &IMG.ERROR_Y; Toggle X/Y error bars</dt>
<dd><p>Switches between drawing symmetric error bars and no error bars
    in the X and Y directions respectively.
    Other options are available in the <label>Errors</label> menu.
    See <ref id="errorBars"/>.
    </p></dd>

</dl>
</p>

<p>You can determine how the data are plotted using lines and/or markers
as described in the following subsection.
</p>

<subsubsubsect id="LinesStyleEditor">
<subhead><title>Lines Style Editor</title></subhead>

<p>The default plotting style for the stacked lines plot is a simple
black line for each graph.  Since the plots typically do not overlap 
each other, this is in many cases suitable as it stands.  However,
you can configure the plotting style so that the points are plotted
with markers as well as or instead of lines, and change the colours, 
marker shapes, line styles etc.  The style for each row subset is
displayed in a button to the right of its name in the bottom right
of the plotting window.  If you click this button the following 
dialogue will pop up which entables you to configure the plotting style.
</p>

<figure>
<caption><px>Stacked Line Plot Style Editor</px></caption>
<figureimage src="&FIG.LinesStyleEditor;"/>
</figure>

<p>The <label>Legend</label> box defines how the selected set will 
be identified in the legend which appears alongside the plot 
(though the legend will only be visible if <label>Show Legend</label> 
(&IMG.LEGEND;) is on):
<dl>
<dt>Icon</dt>
<dd><p>Displays the icon which will be shown to identify the points in
    the selected set.  Its appearance depends on the selections you
    make in the rest of this dialogue window.
    </p></dd>

<dt>Label</dt>
<dd><p>Gives the name written in the legend to label the subset.
    By default this is derived from the Row Subset's name and, if it's
    not part of the main dataset, the name of the dataset's tab.
    You can type in a new value to change what is written in the legend.
    </p></dd>

<dt>Hide Legend</dt>
<dd><p>If this checkbox is selected, then no entry for the selected set
    will appear in the legend.
    </p></dd>
</dl>
</p>

<p>The <label>Display</label> box defines how the markers plotted for
each data point will appear:
<dl>
<dt>Colour</dt>
<dd><p>Choose the colour in which the lines and/or markers will be plotted.
    </p></dd>

<dt>Line/Markers</dt>
<dd><p>Select from the radio buttons whether you want just lines between
    the data points, or markers at each point, or both.
    </p></dd>

<dt>Error Bars</dt>
<dd><p>If <ref id="errorBars">error bars</ref> are active for this plot,
    allows you to select the way they will appear.  The options which
    can be selected here will depend on whether X and/or Y erors are
    in use.
    </p></dd>
</dl>
</p>

<p>The <label>Line</label> box defines how the lines joining the points
will look.  These controls will only be active if the Display selection
is <label>Line</label> or <label>Both</label>.
<dl>
<dt>Thickness</dt>
<dd><p>Determines line thickness.
    </p></dd>

<dt>Dash</dt>
<dd><p>Determines line dash pattern.
    </p></dd>
</dl>
</p>

<p>The <label>Markers</label> box defines how markers at the data points
will look.  These controls will only be active if the Display selection
is <label>Markers</label> or <label>Both</label>.
<dl>
<dt>Size</dt>
<dd><p>Determines the size of the markers in pixels.  If a size of zero
    is chosen then the shape doesn't matter, the points will be plotted
    as single pixels.
    </p></dd>

<dt>Shape</dt>
<dd><p>Determines the shape of the markers from a selection such as 
    open or filled circles, squares, crosses etc.
    </p></dd>
</dl>
</p>

<p>Any changes you make in this window are reflected in the plot straight
away.  If you click the <label>OK</label> button at the bottom, the window
will disappear and the changes remain.  If you click <label>Cancel</label>
the window will disappear and any changes you made will be discarded.
</p>

<p>You can also change all the plotting styles at once by using the
<label>Line Style</label> menu in the stacked lines plot window.
Here you can select a standard group of styles 
(e.g. dashed lines, coloured lines) for the plotted sets.
Similarly, error styles can be changed all at once using the 
<label>Error Style</label> menu.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="Cartesian3DWindow">
<subhead><title>3D Plot (old-style)</title></subhead>

<p><em>This section describes an old-style plotting window.
The standard plotting windows are described in <ref id="plot2"/>.
</em></p>

<figure>
<caption><px>3D scatter plot window</px></caption>
<figureimage src="&FIG.Cartesian3DWindow;"/>
</figure>

<p>The 3D plot window draws 3-dimensional scatter plots of one or more
triples of table columns (or derived quantities) on Cartesian axes.
You can display it using the <label>3D</label> (&IMG.PLOT3D;) item
in the <ref id="ControlWindow">Control Window</ref>'s
<label>Graphics</label> menu.
</p>

<p>On the display a marker is plotted for each row in the selected
dataset(s) at a position determined by the values in the table columns
selected to provide the X, Y and Z values.
A marker will only be plotted if none of the X, Y and Z values are blank.
Select the quantities to plot and the plotting symbols with the
<ref id="PointSelector" plaintextref="yes">dataset selector</ref> 
at the bottom.
</p>

<p>The 3D space can be rotated by dragging the mouse around on the
surface - it will rotate around the point in the centre of the
plotted cube.  The axis labels try to display themselves the right
way up and in a way which is readable from the viewing point if possible,
which means they move around while the rotation is happening.
By default the points are rendered as though the 3D space is filled
with a 'fog', so that more distant points appear more washed out - 
this provides a visual cue which can help to distinguish the depth
of plotted points.  However, you can turn this off if you want.
If there are many points, then you may find that they're not all plotted
while a drag-to-rotate gesture is in progress.  This is done to cut down on 
rendering time so that GUI response stays fast.  When the drag is
finished (i.e. when you release the mouse button) all the points will
come back again.
</p>

<p><label>Zooming</label> is also possible.  You can zoom in around the
centre of the plot so that the viewing window only covers the middle.
The easiest way to do this is to use the mouse wheel if you have one -
wheel forward to zoom in and backward to zoom out.
Alternatively you can do it by dragging on the region to the left of
the plot, like the <label>Axis Zoom</label> in some of the 2-d plots.
Drag the mouse down to zoom in or up to zoom
out on this part of the window.  Currently it is only possible
to zoom in/out around the centre of the plot.
When zoomed you can use the 
<label>Subset From Visible</label> (&IMG.VISIBLE_SUBSET;) toolbar button
to define a new <label>Row Subset</label> consisting only of the
points which are currently visible.
See <ref id="plotSubsets"/> for more explanation.
</p>

<p>Clicking on any of the plotted points will <label>activate</label> it - 
see <ref id="activation"/>.
</p>

<p>The following buttons are available on the toolbar:
<dl>

<dt>&IMG.SPLIT; Split Window</dt>
<dd><p>Allows the dataset selector to be resized by dragging a separator 
    between it and the plot area.  Good for small screens.
    </p></dd>

<dt>&IMG.REDO; Replot</dt>
<dd><p>Redraws the current plot.  It is usually not necessary to
    use this button, since if you change any of the plot characteristics
    with the controls in this window the plot will be redrawn
    automatically.  However if you have changed the data, e.g. by
    editing cells in the <ref id="TableViewerWindow">Data Window</ref>,
    the plot is not automatically redrawn (since this is potentially an
    expensive operation and you may not require it).
    Clicking this button redraws the plot taking account of any changes
    to the table data.
    </p></dd>

<dt>&IMG.AXIS_EDIT; Configure Axes and Title</dt>
<dd><p>Pops up a dialogue to allow manual configuration of axis ranges,
    axis labels and plot title - see <ref id="axisConfig"/>.
    </p></dd>

<dt>&IMG.PDF; Export as PDF</dt>
<dd><p>Pops up a dialogue which will write the current plot as a PDF file.
    In general this is a faithful and high quality rendering of what
    is displayed in the plot window.  However, if plotting is being done
    using the transparent markers, the markers will
    be rendered as if they were opaque.
    Plots with very many points can result in rather large output PDFs.
    </p></dd>

<dt>&IMG.IMAGE; Export as GIF</dt>
<dd><p>Pops up a dialogue which will output the current plot to a GIF file.
    The output file is just the same as the plotted image that you see.
    Resize the plotting window before the export to control the size
    of the output GIF.
    </p></dd>

<dt>&IMG.RESIZE; Rescale</dt>
<dd><p>Rescales the axes of the current plot so that it contains all
    the data points in the currently selected subsets.
    By default the plot will be scaled like this, but it it may have changed
    because of changes in the subset selection.
    </p></dd>

<dt>&IMG.XYZ; Reorient</dt>
<dd><p>Reorients the axes of the current plot to their default position.
    This can be useful if you've lost track of where you've rotated
    the plot to with the mouse.  This also resets the zoom level to 
    normal if you've changed it.
    </p></dd>

<dt>&IMG.NORTH; Stay Upright</dt>
<dd><p>Toggle button which when selected ensures that the Z axis is 
    oriented vertically on the screen at all times.
    By default this is off which means you can drag the axes round to
    any orientation, but it can be convenient to switch it on to keep
    the plot pointing in a sensible direction.
    </p></dd>

<dt>&IMG.GRID_ON; Grid</dt>
<dd><p>Toggles whether the cubic frame bounding the plot is drawn or not.
    </p></dd>

<dt>&IMG.LEGEND; Show Legend</dt>
<dd><p>Toggles whether a legend showing how each data set is represented
    is visible to the right of the plot.  Initially the legend is shown
    only if more than one data set is being shown at once.
    </p></dd>

<dt>&IMG.FOG; Fog</dt>
<dd><p>Toggles whether rendering is done as if the space is filled with fog.
    If this option is selected, distant points will appear more washed out
    than near ones.
    </p></dd>

<dt>&IMG.BLOB_SUBSET; Draw Subset Region</dt>
<dd><p>Allows you to draw a region on the screen defining a new
    <ref id="subsets">Row Subset</ref>.  When you have finished
    drawing it, click this button again to indicate you're done.
    The subset will include points at all depths in the viewing direction
    which fall in the region you have drawn.
    See <ref id="plotSubsets"/> for more details.
    </p></dd>

<dt>&IMG.VISIBLE_SUBSET; Subset From Visible</dt>
<dd><p>Defines a new <label>Row Subset</label>
    consisting of only the points which
    are currently visible on the plotting surface.
    See <ref id="plotSubsets"/> for more explanation.
    </p></dd>
</dl>
</p>

<p>The following additional item is available as a menu item only:
<dl>
<dt>&IMG.ANTIALIAS; Antialias</dt>
<dd><p>Toggles whether the axes and their annotations are drawn antialiased.
    Antialiased lines are smoother and generally look more pleasing, 
    especially for text at a sharp angle, but it can slow the rendering 
    down a bit.
    </p></dd>
</dl>
</p>

<p>The <label>Dataset Toolbar</label> contains the following options:
<dl>

<dt>&IMG.ADD_TAB; / &IMG.REMOVE_TAB; Add/Remove dataset</dt>
<dd><p>Adds/removes tabs in which the data for extra datasets can be entered.
    See <ref id="PointSelector"/>.
    </p></dd>

<dt>&IMG.ADD_COLORS; / &IMG.REMOVE_COLORS; Add/Remove auxiliary axis</dt>
<dd><p>Adds/removes a selector for entering an auxiliary axis to modify
    point colours etc.
    See <ref id="auxAxes"/>.
    </p></dd>

<dt>&IMG.LABEL; Toggle point labelling</dt>
<dd><p>Allows text labels to be drawn near plotted points.
    See <ref id="labels"/>.
    </p></dd>

<dt>&IMG.ERROR_X; / &IMG.ERROR_Y; / &IMG.ERROR_Z; Toggle X/Y/Z error bars</dt>
<dd><p>Switches between drawing symmetric error bars and no error bars
    in the X, Y and Z directions respectively.
    Other options are available in the <label>Errors</label> menu.
    See <ref id="errorBars"/>.
    </p></dd>

</dl>
</p>

<p>You have considerable freedom to configure how the points are plotted
including the shape, colour and transparency of symbols and the
representation of error bars if used.  These options are described
in the following subsection.
</p>

<subsubsubsect id="MarkStyleEditorNoLines">
<subhead><title>3D Plot Style Editor</title></subhead>

<p>When plotting points in a 3D plot there are many different
ways that each point can be displayed.  By default, TOPCAT chooses
a set of markers on the basis of how many points there are in the
table and uses a different one for each plotted set.  The marker for
each set is displayed in a button to the right of its name in the 
dataset selector panel at the bottom of the plot window.  If you 
click this button the following dialogue will pop up which enables
you to change the appearance.
</p>

<figure>
<caption><px>Style editor dialogue for 3d plots</px></caption>
<figureimage src="&FIG.MarkStyleEditorNoLines;"/>
</figure>

<p>The <label>Legend</label> box defines how the selected set will 
be identified in the legend which appears alongside the plot 
(though the legend will only be visible if <label>Show Legend</label> 
(&IMG.LEGEND;) is on):
<dl>
<dt>Icon</dt>
<dd><p>Displays the icon which will be shown to identify the points in
    the selected set.  Its appearance depends on the selections you
    make in the rest of this dialogue window.
    </p></dd>

<dt>Label</dt>
<dd><p>Gives the name written in the legend to label the subset.
    By default this is derived from the Row Subset's name and, if it's
    not part of the main dataset, the name of the dataset's tab.
    You can type in a new value to change what is written in the legend.
    </p></dd>

<dt>Hide Legend</dt>
<dd><p>If this checkbox is selected, then no entry for the selected set
    will appear in the legend.
    </p></dd>
</dl>
</p>

<p>The <label>Marker</label> box defines how the markers plotted for
each data point will appear:
<dl>
<dt>Shape</dt>
<dd><p>Choose from a variety of shapes such as open or filled 
    circles, squares, crosses etc.
    </p></dd>

<dt>Size</dt>
<dd><p>Choose the size of the marker; the value given is approximate radius
    in pixels.  If a size of zero is chosen, then the shape doesn't matter,
    the points will be plotted as single pixels.
    </p></dd>

<dt>Colour</dt>
<dd><p>Choose the colour in which the markers will be plotted.
    </p></dd>

<dt>Transparency</dt>
<dd><p>Choose transparency of the plotted symbols.
    The scale on the slider is logarithmic, with 1 at the left hand end.
    The actual value chosen is an integer written at the right of the
    slider.  This number gives the number of markers for this set which
    need to be plotted in the same position to result in fully opaque
    pixels - any fewer and the background, or other markers plotted
    underneath, will show through to some extent. 
    Setting this to some value greater than 1 is very useful if you
    have a very large number of points being plotted (especially if it's
    comparable with the number of the pixels on the screen), since it
    enables to you distinguish regions where there are lots of points
    on top of each other from those where there are only a few.
    If a finite transparency is set, you may find it useful to turn off
    fogging (see above).
    </p></dd>

<dt>Error Bars</dt>
<dd><p>If <ref id="errorBars">error bars</ref> are active for this plot,
    allows you to select the way they will appear.  The options which
    can be selected here will depend on whether X, Y and/or Z errors are
    in use.
    </p></dd>

<dt>Hide Markers</dt>
<dd><p>This check box is only enabled if error bars 
    are being plotted; it allows the markers to be invisible, 
    so that only the error bars are seen.
    </p></dd>
</dl>
</p>

<p>Any changes you make in this window are reflected in the plot straight
away.  If you click the <label>OK</label> button at the bottom, the window
will disappear and the changes remain.  If you click <label>Cancel</label>
the window will disappear and any changes you made will be discarded.
</p>

<p>You can also change all the plotting styles at once by using the
<label>Marker Style</label> menu in the plot window.
Here you can select a standard group of styles (e.g. all open 2-pixel 
markers with different colours and shapes) for the plotted sets.
Similarly, error styles can be changed all at once using the 
<label>Error Style</label> menu.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="SphereWindow">
<subhead><title>Spherical Plot (old-style)</title></subhead>

<p><em>This section describes an old-style plotting window.
The standard plotting windows are described in <ref id="plot2"/>.
</em></p>

<figure>
<caption><px>Spherical plot window</px></caption>
<figureimage src="&FIG.SphereWindow;"/>
</figure>

<p>The spherical plot window draws 3-dimensional scatter plots
of datasets from one or more tables on spherical polar axes,
so it's suitable for displaying the position of coordinates on
the sky or some other spherical coordinate system, such as the
surface of a planet or the sun.
You can display it using the <label>Sphere</label> (&IMG.SPHERE;) item
in the <ref id="ControlWindow">Control Window</ref>'s
<label>Graphics</label> menu.
</p>

<p>In most respects this window works like the 
<ref id="Cartesian3DWindow">3D Plot</ref> window,
but it uses spherical polar axes rather than Cartesian ones,
You have to fill in the 
<ref id="PointSelector" plaintextref="yes">dataset selector</ref>
at the bottom with longitude- and latitude-type coordinates
from the table.  
Selectors are included to indicate the units of those coordinates.
If TOPCAT can locate columns in the table which appear to represent
Right Ascension and Declination, these will be filled in automatically.
If only these two are filled in, then the points will be plotted on
the surface of the unit sphere - this is suitable if you just want to
inspect the positions of a set of objects in the sky.
</p>

<p>If the <label>Radial Coordinates</label> (&IMG.RADIAL;) button is 
activated, you can optionally fill in a value in the 
<label>Radial Axis</label> selector as well.
In this case points will be plotted in the interior of the sphere, 
at a distance from the centre given by the value of the radial coordinate.
</p>

<p>The 3D space can be rotated by dragging the mouse around on the
surface - it will rotate around the centre of the sphere.
By default the points are rendered as though the 3D space is filled
with a 'fog', so that more distant points appear more washed out - 
this provides a visual cue which can help to distinguish the depth
of plotted points.  However, you can turn this off if you want.
If there are many points, then you may find that they're not all plotted
while a drag-to-rotate gesture is in progress.  This is done to cut down on 
rendering time so that GUI response stays fast.  When the drag is
finished (i.e. when you release the mouse button) all the points will
come back again.
</p>

<p><label>Zooming</label> is also possible.  You can zoom in around the
centre of the plot so that the viewing window only covers the middle.
The easiest way to do this is to use the mouse wheel if you have one -
wheel forward to zoom in and backward to zoom out.
Alternatively you can do it by dragging on the region to the left of
the plot, like the <label>Axis Zoom</label> in some of the 2-d plots.
Drag the mouse down to zoom in or up to zoom
out on this part of the window.  Currently it is only possible
to zoom in/out around the centre of the plot.
When zoomed you can use the 
<label>Subset From Visible</label> (&IMG.VISIBLE_SUBSET;) toolbar button
to define a new <label>Row Subset</label> consisting only of the
points which are currently visible.
See <ref id="plotSubsets"/> for more explanation.
</p>

<p>Clicking on any of the plotted points will <label>activate</label> it - 
see <ref id="activation"/>.
</p>

<p>The following buttons are available on the toolbar:
<dl>

<dt>&IMG.SPLIT; Split Window</dt>
<dd><p>Allows the dataset selector to be resized by dragging a separator 
    between it and the plot area.  Good for small screens.
    </p></dd>

<dt>&IMG.REDO; Replot</dt>
<dd><p>Redraws the current plot.  It is usually not necessary to
    use this button, since if you change any of the plot characteristics
    with the controls in this window the plot will be redrawn
    automatically.  However if you have changed the data, e.g. by
    editing cells in the <ref id="TableViewerWindow">Data Window</ref>,
    the plot is not automatically redrawn (since this is potentially an
    expensive operation and you may not require it).
    Clicking this button redraws the plot taking account of any changes
    to the table data.
    </p></dd>

<dt>&IMG.AXIS_EDIT; Configure Axes and Title</dt>
<dd><p>Pops up a dialogue to allow manual configuration of axis ranges,
    axis labels and plot title - see <ref id="axisConfig"/>.  
    The only configurable axis range is the upper limit of the radial axis.
    </p></dd>

<dt>&IMG.PDF; Export as PDF</dt>
<dd><p>Pops up a dialogue which will write the current plot as a PDF file.
    In general this is a faithful and high quality rendering of what
    is displayed in the plot window.  However, if plotting is being done
    using the transparent markers, the markers will
    be rendered as if they were opaque.
    Plots with very many points can result in rather large output PDFs.
    </p></dd>

<dt>&IMG.IMAGE; Export as GIF</dt>
<dd><p>Pops up a dialogue which will output the current plot to a GIF file.
    The output file is just the same as the plotted image that you see.
    Resize the plotting window before the export to control the size
    of the output GIF.
    </p></dd>

<dt>&IMG.RESIZE; Rescale</dt>
<dd><p>Rescales the axes of the current plot so that it contains all
    the data points in the currently selected subsets.
    By default the plot will be scaled like this, but it it may have changed
    because of changes in the subset selection.
    </p></dd>

<dt>&IMG.XYZ; Reorient</dt>
<dd><p>Reorients the axes of the current plot to their default position.
    This can be useful if you've lost track of where you've rotated
    the plot to with the mouse.  This also resets the zoom level to 
    normal if you've changed it.
    </p></dd>

<dt>&IMG.NORTH; Stay Upright</dt>
<dd><p>Toggle button which when selected ensures that the north pole 
    (latitude = +90 degrees) is oriented vertically on the screen at all times.
    By default this is on.
    </p></dd>

<dt>&IMG.GRID_ON; Grid</dt>
<dd><p>Toggles whether the spherical wire frame bounding the plot 
    is drawn or not.
    </p></dd>

<dt>&IMG.LEGEND; Show Legend</dt>
<dd><p>Toggles whether a legend showing how each data set is represented
    is visible to the right of the plot.  Initially the legend is shown
    only if more than one data set is being shown at once.
    </p></dd>

<dt>&IMG.FOG; Fog</dt>
<dd><p>Toggles whether rendering is done as if the space is filled with fog.
    If this option is selected, distant points will appear more washed out
    than near ones.
    </p></dd>

<dt>&IMG.BLOB_SUBSET; Draw Subset Region</dt>
<dd><p>Allows you to draw a region on the screen defining a new
    <ref id="subsets">Row Subset</ref>.  When you have finished
    drawing it, click this button again to indicate you're done.
    The subset will include points at all depths in the viewing direction
    which fall in the region you have drawn.
    See <ref id="plotSubsets"/> for more details.
    </p></dd>

<dt>&IMG.VISIBLE_SUBSET; Subset From Visible</dt>
<dd><p>Defines a new <label>Row Subset</label>
    consisting of only the points which
    are currently visible on the plotting surface.
    See <ref id="plotSubsets"/> for more explanation.
    </p></dd>

</dl>
</p>

<p>The following additional item is available as a menu item only:
<dl>
<dt>&IMG.ANTIALIAS; Antialias</dt>
<dd><p>Toggles whether the axes and their annotations are drawn antialiased.
    Antialiased lines are smoother and generally look more pleasing, 
    especially for text at a sharp angle, but it can slow the rendering 
    down a bit.
    </p></dd>
</dl>
</p>

<p>The <label>Dataset Toolbar</label> contains the following options:
<dl>

<dt>&IMG.ADD_TAB; / &IMG.REMOVE_TAB; Add/Remove dataset</dt>
<dd><p>Adds/removes tabs in which the data for extra datasets can be entered.
    See <ref id="PointSelector"/>.
    </p></dd>

<dt>&IMG.ADD_COLORS; / &IMG.REMOVE_COLORS; Add/Remove auxiliary axis</dt>
<dd><p>Adds/removes a selector for entering an auxiliary axis to modify
    point colours etc.
    See <ref id="auxAxes"/>.
    </p></dd>

<dt>&IMG.LABEL; Toggle point labelling</dt>
<dd><p>Allows text labels to be drawn near plotted points.
    See <ref id="labels"/>.
    </p></dd>

<dt>&IMG.RADIAL; Toggle Radial Coordinates</dt>
<dd><p>When activated, a column selector labelled <label>Radial Axis</label>
    will be visible below the Longitude and Latitude Axis selectors.
    This enables you to enter a value for the radial coordinate of each 
    point.  If this is disabled, or if it has a blank value, then all
    the points will have an assumed radial coordinate of unity and will
    be plotted on the surface of the sphere.
    </p></dd>

<dt>&IMG.ERROR_TANGENT; Toggle tangential error bars</dt>
<dd><p>When activated, an additional column selector appears in the 
    dataset panel to the right of the Longitude and Latitude selectors,
    along with its own unit selector.  You can fill this in with an
    isotropic error value representing the radius of a small circle
    associated with the selected points, in units of arcsec, arcmin, 
    degrees or radians.  This will cause 2-d error bars to be plotted.
    You can configure their appearance (e.g. crosshairs, ellipses, 
    rectangles, ...) using the 
    <ref id="MarkStyleEditorNoLines">style editor</ref> in the usual way.
    See <ref id="errorBars"/> for more information.
    </p></dd>

<dt>&IMG.ERROR_Z; Toggle radial error bars</dt>
<dd><p>Switches radial error bars on and off.  See <ref id="errorBars"/>.
    This button will only be enabled if the Radial Coordinates are in use.
    </p></dd>
</dl>
</p>

<p>You have considerable freedom to configure how points are plotted
including the shape, colour and transparency of symbols and the representation
of errors if used.  This works exactly as for the 
<ref id="Cartesian3DWindow">Cartesian 3D plot</ref> as described in
<ref id="MarkStyleEditorNoLines"/>.
</p>


</subsubsect>


<subsubsect id="DensityWindow">
<subhead><title>Density Map (old-style)</title></subhead>

<p><em>This section describes an old-style plotting window.
The standard plotting windows are described in <ref id="plot2"/>.
</em></p>

<figure>
<caption><px>Density map window in RGB mode</px></caption>
<figureimage src="&FIG.DensityWindow;"/>
</figure>

<p>The density map window plots a 2-dimensional density map of 
one or more pairs of table columns (or derived quantities);
the colour of each pixel displayed is determined by the number of 
points in the data set which fall within its bounds.
Another way to think of this is as a histogram on a 2-dimensional
grid, rather than a 1-dimensional one as in the 
<ref id="HistogramWindow">Histogram Window</ref>.
You can optionally weight these binned counts with another value 
from the table.
</p>

<p>Density maps are suitable when you have a very large number of points
to plot, since in this case it's important to be able to see not just 
whether there is a point at a given pixel, but how many points fall
on that pixel.  To a large extent, the transparency features of the
other 2d and 3d plotting windows address this issue, but the 
density map gives you a bit more control.  It can also export
the result as a FITS image, which can then be processed or viewed
using image-specific software such as GAIA or Aladin.
</p>

<p>This window can be operated in two modes:
<dl>
<dt>Indexed Mode</dt>
<dd><p>Each pixel represents a single scalar value, corresponding to a 
    count or sum as indicated by the selected dataset(s).  If multiple
    datasets are being plotted at once, the values from each will be
    summed to give the result at each point.  The mapping from numeric
    value to pixel colour at each point on the plot is determined by
    the colour map selected in the <label>Indexed Colours</label> 
    selector below the plot.  In this case the style editor colour selectors
    have no effect and are disabled.
    A fairly wide range of colour maps is provided by default.
    If these do not suit your needs, it is possible to provide your own
    custom colour maps using the <label>lut.files</label> system property -
    see <ref id="jvmProperties"/>.
    </p></dd>

<dt>RGB Mode</dt>
<dd><p>Each pixel has up to three independent contributions, its 
    intensity in Red, Green and Blue channels.  These can come from
    different datasets, as configured in the 
    <ref id="DensityStyleEditor">style editor</ref>.  If more than one
    dataset is assigned the same colour, the contributions are summed
    for that channel. 
    In this case the Indexed Colours colour map selector has no effect
    and is disabled.
    </p></dd>
</dl>
Switch between the modes using the <label>RGB</label> (&IMG.COLOR;) button.
</p>

<p>You can configure the axes, including <strong>zooming</strong> in and out,
with the mouse (drag on the plot or the axes) 
or manually as described in <ref id="axisConfig"/>.
</p>

<p>Two controls specific to this window are shown below the plot itself:
<dl>

<dt>Cut Percentile Levels</dt>
<dd><p>This controls how the number of counts in each pixel maps 
    to a brightness.  
    There are two sliders, one for the lower bound and one for the upper bound.
    They are labelled (logarithmically) with percentile values.
    If the upper one is set to 90, it means that any pixel above the 90th
    percentile of the pixels in the image in terms of count level will be
    shown with maximum brightness, and similarly for the lower one.
    These values apply independently to each colour channel if more than
    one is in use.
    Immediately below the sliders, the pixel values which correspond to 
    minimum and maximum brightness are displayed.  In indexed mode there is
    one range, and in RGB mode there may be up to three.
    If the image is not fairly completely covered, this control doesn't
    give you as much freedom as you might like - the user interface may
    be improved in future releases.
    </p></dd>

<dt>Indexed Colours</dt>
<dd><p>When in indexed (non-RGB) mode only, this allows you to select 
    a colour map which determines how pixel values (counts or sums per bin) 
    are turned into colours on the screen.  The lowest value corresponds to
    the colour at the left side of the icon and the highest value to the right
    side.  In RGB mode this is disabled.
    </p></dd>

</dl>
</p>


<p>The following buttons are available on the toolbar:
<dl>

<dt>&IMG.SPLIT; Split Window</dt>
<dd><p>Allows the dataset selector to be resized by dragging a separator 
    between it and the plot area.  Good for small screens.
    </p></dd>

<dt>&IMG.REDO; Replot</dt>
<dd><p>Redraws the current plot.  It is usually not necessary to 
    use this button, since if you change any of the plot characteristics
    with the controls in this window the plot will be redrawn
    automatically.  However if you have changed the data, e.g. by
    editing cells in the <ref id="TableViewerWindow">Data Window</ref>,
    the plot is not automatically redrawn (since this is potentially an
    expensive operation and you may not require it).
    Clicking this button redraws the plot taking account of any changes
    to the table data.
    </p></dd>

<dt>&IMG.AXIS_EDIT; Configure Axes and Title</dt>
<dd><p>Pops up a dialogue to allow manual configuration of axis ranges,
    axis labels and plot title - see <ref id="axisConfig"/>.
    </p></dd>

<dt>&IMG.PDF; Export as PDF</dt>
<dd><p>Pops up a dialogue which will write the current plot as a PDF file.
    </p></dd>

<dt>&IMG.IMAGE; Export as GIF</dt>
<dd><p>Pops up a dialogue which will output the current plot to a GIF file.
    The output file is just the same as the plotted image that you see.
    Resize the plotting window before the export to control the size
    of the output GIF.
    </p></dd>

<dt>&IMG.FITS; Export as FITS</dt>
<dd><p>Pops up a dialogue which will output the plotted map as a FITS array.
    If only one channel is visible (either one colour channel or indexed
    mode) then the output FITS file will be a 2d array with dimensions the
    same as the displayed image.  If there are multiple RGB channels then
    the output array will be 3d with the third dimension having an extent
    of 2 or 3, depending on the number of colour channels visible.
    In either case the FITS file will have a single (primary) HDU.
    Basic coordinate system information, as well as DATAMIN and DATAMAX cards,
    will be written to the header.
    The type of the output array will be double precision for weighted 
    values, or some integer type of sufficient length for unweighted ones.
    </p></dd>

<dt>&IMG.RESIZE; Rescale</dt>
<dd><p>Rescales the axes of the current plot so that it contains all
    the data points in the currently selected subsets.
    By default the plot will be scaled like this, but it it may have changed
    because of changes in the subset selection or from zooming in or out.
    </p></dd>

<dt>&IMG.COLOR_LOG; Log Intensity</dt>
<dd><p>Toggles between linear and logarithmic mapping for colour intensity
    as a function of number of counts.
    </p></dd>

<dt>&IMG.COLOR; Colour</dt>
<dd><p>Toggles between indexed and RGB modes (see the explanation above).
    </p></dd>

<dt>&IMG.LEGEND; Show Legend</dt>
<dd><p>Toggles whether a legend showing how each data set is represented
    is visible to the right of the plot.  Initially the legend is shown
    only if more than one data set is being shown at once.
    </p></dd>

<dt>&IMG.ROUGH; Bigger Pixels</dt>
<dd><p>Increments the size of screen pixel corresponding to one density
    map bin.
    </p></dd>

<dt>&IMG.FINE; Smaller Pixels</dt>
<dd><p>Decrements the size of screen pixel corresponding to one density
    map bin.
    </p></dd>

<dt>&IMG.BLOB_SUBSET; Draw Subset Region</dt>
<dd><p>Allows you to draw a region on the screen defining a new 
    <ref id="subsets">Row Subset</ref>.  When you have finished 
    drawing it, click this button again to indicate you're done.
    See <ref id="plotSubsets"/> for more details.
    </p></dd>

<dt>&IMG.VISIBLE_SUBSET; Subset From Visible</dt>
<dd><p>Defines a new <label>Row Subset</label>
    consisting of only the points which
    are currently visible on the plotting surface.
    See <ref id="plotSubsets"/> for more explanation.
    </p></dd>
</dl>
</p>

<p>The <label>Dataset Toolbar</label> contains the following options:
<dl>

<dt>&IMG.ADD_TAB; / &IMG.REMOVE_TAB; Add/Remove dataset</dt>
<dd><p>Adds/removes tabs in which the data for extra datasets can be entered.
    See <ref id="PointSelector"/>.
    </p></dd>

<dt>&IMG.WEIGHT; Weight Counts</dt>
<dd><p>If this toggle button is on, an additional <label>Weight Axis</label>
    selector appears below the <label>X Axis</label> selector.
    If this is filled in with a column name or expression, then instead of
    simply accumulating the number of points per bin, each pixel will
    represent the sum over the weighting quantity for points in each bin.
    Not having a weight axis is equivalent to filling in its value with
    the quantity 1.
    Note that with weighting, the figure drawn is no longer strictly speaking
    a histogram or density map.
    </p></dd>

</dl>
</p>

<p>The <label>Export</label> menu provides a number of ways to export the
displayed image for external viewing or analysis.
As well as options to export as GIF, JPEG, EPS and FITS,
there is also the option to transmit the FITS image to one or
all applications listening using the SAMP or PLASTIC tool interoperability 
protocol which will receive images.
In this way you can transmit the image directly to SAMP/PLASTIC-aware
image manipulation tools such as GAIA or Aladin.
See <ref id="interop"/> for more information about tool interoperability.
</p>

<p>How to set the colour channel corresponding to each dataset is
explained in the following subsection.
</p>

<subsubsubsect id="DensityStyleEditor">
<subhead><title>Density Style Editor</title></subhead>

<p>For a density map in RGB mode, each dataset
is assigned a colour channel to which it contributes.  A representation
of this is displayed in a button to the right of its name in the dataset
selector panel at the bottom of the density map window.
If you click this button the following dialogue will pop up which
enables you to change the colour channel.
</p>

<figure>
<caption><px>Style editor dialogue for density map</px></caption>
<figureimage src="&FIG.DensityStyleEditor;"/>
</figure>

<p>The <label>Legend</label> box defines how the selected set will 
be identified in the legend which appears alongside the plot 
(though the legend will only be visible if <label>Show Legend</label> 
(&IMG.LEGEND;) is on):
<dl>
<dt>Icon</dt>
<dd><p>Displays the icon which will be shown to identify the points in
    the selected set.  Its appearance depends on the selections you
    make in the rest of this dialogue window.
    </p></dd>

<dt>Label</dt>
<dd><p>Gives the name written in the legend to label the subset.
    By default this is derived from the Row Subset's name and, if it's
    not part of the main dataset, the name of the dataset's tab.
    You can type in a new value to change what is written in the legend.
    </p></dd>

<dt>Hide Legend</dt>
<dd><p>If this checkbox is selected, then no entry for the selected set
    will appear in the legend.
    </p></dd>
</dl>
</p>

<p>The <label>Channel</label> selector allows you to select either 
the Red, Green or Blue channel for this dataset to contribute to.
Note that this is only enabled in RGB mode; in indexed mode
it has no effect and is disabled.
</p>

</subsubsubsect>

</subsubsect>

</subsect>

<subsect id="LoadWindow">
<subhead><title>Load Window</title></subhead>

<figure>
<caption><px>Load Window</px></caption>
<figureimage src="&FIG.LoadWindow;"/>
</figure>

<p>The Load Window is used for loading tables from an external location
(e.g. disk or URL) into TOPCAT.  It is obtained using the 
<label>Load Table</label> button (&IMG.LOAD;) in the 
<ref id="ControlWindow">Control Window</ref> toolbar or
<label>File</label> menu.
</p>

<p>This dialogue allows you to specify a new table to open in a number of
different ways, described below.
If you perform a successful load using any of these options,
a new entry or entries will be added into the Table List in the Control Window,
which you can then use in the usual ways.
If you choose a location which can't be turned into a table
(for instance because the file doesn't exist),
a window will pop up telling you what went wrong.
The panel at the bottom of the window displays progress for tables
currently loading; it is used to show progress for tables loaded
from other sources too, for instance received via SAMP or specified
on the command line.
</p>

<p>In the simplest case, you can type a name into the 
<label>Location</label> field and hit return or the <label>OK</label>
button.  This location can be a filename or a URL,
possibly followed by a '<code>#</code>' character and a 
'fragment identifier' to indicate where in the file or URL the table is
located; the details of what such fragment identifiers mean can be
found in the relevant subsection within <ref id="inFormats"/>.
Allowed URL types are described in <ref id="tableLocation"/>.
You should select the relevant table format from the 
<label>Format</label> selector box - you can leave it on 
<label>(auto)</label> for loading FITS tables or VOTables,
but for other formats such as ASCII or CSV you must select the right one
explicitly (again, see <ref id="inFormats"/> for details).
</p>

<p>There are many other ways of loading tables however,
described in the following subsections.
The <label>Filestore Browser</label> and <label>System Browser</label>
buttons are always visible below the location field.
Depending on startup options, there may be other buttons here.
There are also a number of toolbar buttons
which display various load dialogues; the <label>DataSources</label>
contains all of these along with some lesser-used ones.
The following subsections describe most of the available options,
though others may be available in your installation.
</p>

<p>The options available on the toolbar by default are these:
<ul>
<li>&IMG.FILESTORE_DIALOG;
    <ref id="FilestoreTableLoadDialog">Filestore Browser</ref></li>
<li>&IMG.SYSTEM;
    <ref id="SystemTableLoadDialog">System Browser</ref></li>
<li>&IMG.TREE_DIALOG;
    <ref id="TreeTableLoadDialog">Hierarchy Browser</ref></li>
<li>&IMG.SQL_DIALOG;
    <ref id="SQLTableLoadDialog">SQL Query</ref></li>
<li>&IMG.CONE_DIALOG;
    <ref id="ConeSearchDialog">Cone Search</ref></li>
<li>&IMG.SIAP_DIALOG;
    <ref id="SiapTableLoadDialog">Simple Image Access (SIA) Query</ref></li>
<li>&IMG.SSAP_DIALOG;
    <ref id="SsapTableLoadDialog">Simple Spectral Access (SSA) Query</ref></li>
<li>&IMG.TAP_DIALOG;
    <ref id="TapTableLoadDialog">Table Access Protocol (TAP) Query</ref></li>
<li>&IMG.VIZIER;
    <ref id="VizierTableLoadDialog">VizieR Catalogue Service Query</ref></li>
<li>&IMG.GAVO;
    <ref id="GavoTableLoadDialog">GAVO Millennium Database Query</ref></li>
<li>&IMG.BASTI;
    <ref id="BaSTITableLoadDialog">BaSTI Theory Database Query</ref></li>
</ul>
</p>

<p>All of these load dialogues have an <label>OK</label> button.
Once you click it, whatever load you have specified will start.
If the load takes more than a few hundreths of a second,
a progress bar will appear in the <label>Loading Tables</label> panel 
of the load window, as in the screenshot above.
This will report on how many rows have been loaded, and if known,
how many there are in total.  If you want to interrupt the load 
for any reason while it is in progress, click the <label>Cancel</label>
button, and the load will cease.  If the load completes without 
cancellation, a new table will appear in the Table List of the
main <ref id="ControlWindow">Control Window</ref>, ready for use.
</p>

<p>By default, when a table load has completed, both the Load Window
itself and whichever specific load dialogue window you used will close.
If you don't want this to happen use the 
<label>Stay Open</label> (&IMG.KEEP_OPEN;) item
in the <label>Window</label> menu or
toolbar of the Load Window and/or specific load dialogue.
If this is selected, the window will not automatically close.
This can be very convenient if you want to load many tables from
a similar place, for instance several files from the same directory
or several cone searches to different services.
</p>

<subsubsect id="FilestoreTableLoadDialog">
<subhead><title>Filestore Browser</title></subhead>

<figure>
<caption><px>Filestore Browser window</px></caption>
<figureimage src="&FIG.FilestoreTableLoadDialog;"/>
</figure>

<p>By clicking the <label>Filestore Browser</label> button 
or toolbar button (&IMG.FILESTORE_DIALOG;) in the
<ref id="LoadWindow">Load Window</ref>,
you can obtain a file browser which will
display the files in a given directory.
The way this window works is almost certainly familiar to you 
from other applications.
</p>

<p>Unlike a standard file browser however, it can also 
browse files in remote filestores: currently supported are 
MySpace and SRB.  MySpace is a distributed storage system 
developed for use with the Virtual Observatory by the 
<webref url="http://www.astrogrid.org">AstroGrid</webref> project,
and SRB 
(<webref url="http://www.sdsc.edu/srb/">Storage Resource Broker</webref>) 
is a similar general purpose system developed at SDSC.
To make use of these facilities, select the relevant entry from
the selector box at the top of the window as illustrated above;
this will show you a <label>Log In</label> button which prompts you
for username, password etc, and you will then be able to browse
the remote filestore as if it were local.  The same button can be
used to log out when you are finished, but the session will be 
logged out automatically when TOPCAT ends in any case.
Access to remote filesystems is dependent on certain optional
components of TOPCAT, and it may not be available if you
have the topcat-lite configuration.
</p>

<p>The browser initially displays the current directory, but this can be
changed by typing a new directory into the <label>File Name</label> field,
or moving up the directory hierarchy using the selector box at the top,
or navigating the file system by clicking the up-directory button
or double-clicking on displayed directories.
The initial default directory can be changed by setting the 
<code>user.dir</code> 
<ref id="jvmProperties" plaintextref="yes">system property</ref>.
</p>

<p>All files are shown, and there is no indication of which ones represent
tables and which do not.  To open one of the displayed files as a table,
double-click on it or select it by clicking once and click the
<label>Open Table</label> button.  
The <label>Table Format</label> selector must be set correctly:
the "(auto)" setting will automatically detect the format of 
VOTable or FITS tables,
otherwise you will need to select the option describing the format of
the file you are attempting to load (see <ref id="inFormats"/>).
If you pick a file which cannot be converted
into a table an error window will pop up.
</p>

<p>In most cases, selecting the file name and possibly the format
is all you need to do.  However, the <label>Position in file</label>
field allows you to add information about where in the file the
table you want is situated.  The meaning of this varies according to
the file format: for FITS files, it is the index or EXTNAME of the HDU 
containing the table you're after (see <ref id="inFits"/> for details),
and for VOTables it is the index of the TABLE element
(the first TABLE encountered is numbered 0).  If you leave this blank,
you will get all the tables in the file; this is usually just one table, 
since most file formats cannot accommodate more than one table per file, 
and even for those which can (FITS and VOTable) most files contain 
only a single file in any case.
</p>

<p>For a more table-aware view of the file system, use the
<ref id="TreeTableLoadDialog" plaintextref="yes">Hierarchy Browser</ref> 
instead.
</p>

</subsubsect>

<subsubsect id="SystemTableLoadDialog">
<subhead><title>System Browser</title></subhead>

<p>By clicking the <label>System Browser</label> button or toolbar button
(&IMG.SYSTEM;) in the 
<ref id="LoadWindow">Load Window</ref>,
you can use your Operating System's native file browser to choose
a file to load from.
What this looks like is entirely dependent on your OS;
it may or may not contain system-specific features like shortcuts to
commonly-used directories.
</p>

<p>Since TOPCAT has no control over the way this dialogue looks,
it cannot contain the <label>Table Format</label> selector, and 
certain other things such as load cancel may not work as well as
for the other dialogue types.  To select the table format, you
will need to use the selector in the main <label>Load Window</label>.
</p>

</subsubsect>

<subsubsect id="TreeTableLoadDialog">
<subhead><title>Hierarchy Browser</title></subhead>

<figure>
<caption><px>File load Hierarchy Browser window</px></caption>
<figureimage src="&FIG.TreeTableLoadDialog;"/>
</figure>

<p>By selecting the <label>Hierarchy Browser</label> button
(&IMG.TREE_DIALOG;) 
from the <ref id="LoadWindow">Load Window</ref>'s toolbar
or <label>DataSources</label> menu,
you can obtain a browser which presents a table-aware
hierarchical view of the file system.
(Note that a freestanding version of this panel with additional
functionality is available in the separate
<webref url="http://www.starlink.ac.uk/treeview/">Treeview</webref>
application).
</p>

<p>This browser resembles the 
<ref id="FilestoreTableLoadDialog">Filestore Browser</ref>
in some ways, but with important differences:
<ul>
<li>It shows the file system in a 'tree-like' fashion, so that multiple
    levels of the hierarchy are displayed at once</li>
<li>It understands which items in the hierarchy represent tables
    that can be automatically detected and
    which represent other kinds of object (for instance directories,
    zip files, or plain text files)</li>
<li>It can look inside hierarchical files, so for instance it can
    investigate a Tar or Zip archive which may contain table entries,
    or display multiple tabular HDUs in a FITS file, or multiple
    TABLE elements at different levels in a VOTable document</li>
</ul>
</p>

<p>The main part of the window shows a "tree" representation of the
hierarchy, initially rooted at the current directory
(the initial directory can be changed by setting the 
<code>user.dir</code> 
<ref id="jvmProperties" plaintextref="yes">system property</ref>).
Each line displayed represents a "node" which may be a file or
some other type of item (for instance an HDU in a FITS file or an
entry in a tar archive).  The line contains a little icon
which indicates what kind of node it is and a short text string which
gives its name and maybe some description.
Nodes which represent tables are indicated by the 
&IMG.TABLE; icon.
For nodes which have some internal structure there is also a
"handle" which indicates whether they are
collapsed (&IMG.COLLAPSED;) or expanded (&IMG.EXPANDED;).
You can examine remote filespaces (MySpace, SRB) 
as well as local ones in the same way as with the 
<ref id="FilestoreTableLoadDialog">Filestore Browser</ref>.
</p>

<p>If you select a node by clicking on it, it will be highlighted
and some additional description will appear in the panel below the
hierarchy display.  The text is in <strong>bold</strong> if the node in
question can be opened as a table, and non-bold if it is some
non-table item.
</p>

<p><strong>Note:</strong> an important restriction of this browser
is that it will only pick up tables which can be identified 
automatically - this includes FITS and VOTable files, but does not
include text-based formats such as ASCII and Comma-Separated Values.
If you want to load one of the latter types of table, you will need
to use one of the other load methods and specify table format explicitly.
</p>

<p>You can see how this browser works on an example directory of tables
as described in <ref id="demoData"/>.
</p>

<p>Note that this window requires certain optional 
components of the TOPCAT installation,
and will not be available if you have the topcat-lite configuration.
</p>

<subsubsubsect>
<subhead><title>Navigation</title></subhead>

<p>Navigation is a bit different from navigation in the 
<label>File Browser</label> window.
To expand a node and see its contents, click on its handle
(clicking on the handle when it is expanded will collapse it again).
When you have identified the table you want to open, highlight it
by clicking on it, and then click the <label>Open Table</label> button
at the bottom.
</p>

<p>To move to a different directory, i.e. to change the root of the tree
which is displayed, use one of the buttons above the tree display:
<dl>
<dt>Selector box</dt>
<dd><p>Allows you to move straight to any directory higher up than the
    current one.
    </p></dd>

<dt>&IMG.TV_UP; Up</dt>
<dd><p>Moves to the parent of the current directory.
    </p></dd>

<dt>&IMG.TV_DOWN; Down</dt>
<dd><p>Moves to the currently selected (highlighted) node.
    </p></dd>

<dt>&IMG.HOME; Home</dt>
<dd><p>Moves to the user's home directory.
    </p></dd>
</dl>
Alternatively, you can type in a new directory
in the <label>Go to</label> field at the bottom of the window.
</p>

<p>(In fact the above navigation options are not restricted to changing
the root to a new directory, they can move to any node in the
tree, for instance a level in a Tar archive.)
</p>

</subsubsubsect>

<subsubsubsect>
<subhead><title>Table Searches</title></subhead>

<p>There are two more buttons in the browser, <label>Search Selected</label>
and <label>Search Tree</label>.  These do a recursive search for tables in all
the nodes starting at the currently selected one or the current
root respectively.
What this means is that the program will investigate the whole
hierarchy looking for any items which can be used as tables.
If it finds any it will open up the tree so that they are visible
(note that this doesn't mean that the only nodes revealed will
be tables, ancestors and siblings will be revealed too).
This can be useful if you believe there are a few tables buried
somewhere in a deep directory structure or Tar archive, but you're
not sure where.  Note that this may be time-consuming - a busy
cursor is displayed while the search is going on.
Changing the root of the tree will interrupt the search.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="SQLTableLoadDialog">
<subhead><title>SQL Query</title></subhead>

<figure>
<caption><px>SQL Query Dialogue</px></caption>
<figureimage src="&FIG.SQLTableLoadDialog;"/>
</figure>

<p>If you want to 
<ref id="inSql" plaintextref="yes">read a table from an SQL database</ref>,
you can use a specialised dialogue to specify the SQL query by selecting
<label>SQL Query</label> button from the
<ref id="LoadWindow">Load Window</ref>'s 
toolbar (&IMG.SQL_DIALOG;) or <label>DataSources</label> menu.
</p>

<p>This provides you with a list of fields to fill in which make
up the query, as follows:
<dl>
<dt>Protocol</dt>
<dd><p>The name of the appropriate JDBC sub-protocol.
    This is defined by the JDBC driver that you are using, and is
    for instance "<code>mysql</code>" for MySQL's Connector/J driver
    or "<code>postgresql</code>" for PostgreSQL's JDBC driver.
    </p></dd>

<dt>Host</dt>
<dd><p>The hostname of the machine on which the database resides
    (may be "<code>localhost</code>" if the database is local).
    </p></dd>

<dt>Database name</dt>
<dd><p>The name of the database.
    </p></dd>

<dt>User name</dt>
<dd><p>The username under which you wish to access the database.
    This is not strictly necessary if there is no access control for
    the database in question.
    </p></dd>

<dt>Password</dt>
<dd><p>The password for the given username.  Again, whether this is
    necessary depends on the access policy of the database.
    </p></dd>

<dt>SQL Query</dt>
<dd><p>The text of the query which will define the resulting table.
    If you want to look at a table named XXX as it exists in the database,
    you can write something like "<code>SELECT * from XXX</code>".
    In principle any SQL query on the database can be used here,
    but the details of what SQL syntax is permitted may be restricted
    by the JDBC driver you are using.
    </p></dd>
</dl>
</p>

<p>There are a number of criteria which must be satisfied for SQL
access to work within TOPCAT (installation of appropriate drivers
and so on) - see <ref id="jdbcConfig"/>.  If you don't take
these steps, this dialogue may be inaccessible.
</p>

<p>The way that this dialogue contacts the database makes some assumptions
about how the JDBC driver works which are not always true,
so for some databases and drivers it may not be possible to get it to work.
It may be improved in the future; if you have particular problems,
please contact the author or the mailing list.
</p>

</subsubsect>

<subsubsect>
<subhead><title>Cone Search</title></subhead>
<p>See <ref id="ConeSearchDialog"/> for details.
</p>
</subsubsect>

<subsubsect>
<subhead><title>SIA Query</title></subhead>
<p>See <ref id="SiapTableLoadDialog"/> for details.
</p>
</subsubsect>

<subsubsect>
<subhead><title>SSA Query</title></subhead>
<p>See <ref id="SsapTableLoadDialog"/> for details.
</p>
</subsubsect>

<subsubsect>
<subhead><title>TAP Query</title></subhead>
<p>See <ref id="TapTableLoadDialog"/> for details.
</p>
</subsubsect>

<subsubsect id="VizierTableLoadDialog">
<subhead><title>VizieR Catalogue Service Query</title></subhead>

<figure>
<caption><px>VizieR load dialogue</px></caption>
<figureimage src="&FIG.VizierTableLoadDialog;"/>
</figure>

<p>The VizieR query dialogue can be opened using the
<label>VizieR Catalogue Service</label> button (&IMG.VIZIER;)
in the <ref id="LoadWindow">Load Window</ref>'s toolbar 
or the <ref id="ControlWindow">Control Window</ref>'s <label>VO</label> menu.
It allows you to make queries directly to the 
<webref url="http://vizier.u-strasbg.fr/">VizieR</webref> 
service operated by 
<webref url="http://cdsweb.u-strasbg.fr/">CDS</webref>.
VizieR is a comprehensive library of very many published astronomical 
catalogues.
These items can equally be accessed from the web or other interfaces,
but this load dialogue makes it convenient to load data directly from
VizieR into TOPCAT.
</p>

<p>Note that VizieR's idea of a catalogue is more complex than a single
table; this means that in some cases querying one of VizieR's catalogues 
may result in more than one table being loaded into TOPCAT
(the <label>Sub-Table Details</label> checkbox described below 
can help to control this).
</p>

<p>The dialogue consists of four parts: the 
<label>VizieR Server</label>,
<label>Row Selection</label>,
<label>Column Selection</label> and
<label>Catalogue Selection</label> panels,
arranged top to bottom in the window.
These are described below.
</p>

<p>The <label>VizieR Server</label> panel allows you to specify which
VizieR server you want to use for data download.
By default the server at CDS is used, but there are mirrors elsewhere,
whose URLs can be chosen from the selector.
If you see a popup window complaining that the server cannot be contacted,
you can choose a different one; you might also want to select one that 
is close to you for performance reasons.
</p>

<p>The <label>Row Selection</label> panel specifies which rows you 
want to retrieve from the catalogue that you will select.
You can choose one of the two radio buttons according to the kind
of query that you want to make:
<dl>
<dt>Cone Selection</dt>
<dd><p>In this case you must give a central sky position and the search
    radius to define a cone-shaped region of interest.  Rows within that
    range will be returned.
    For the central position you can either fill in the <label>RA</label>
    and <label>Dec</label> fields directly, or you can fill in the 
    <label>Object Name</label> field and hit the <label>Resolve</label>
    button; in the latter case, a SIMBAD query will be made to determine
    the coordinates corresponding to the named object.
    </p></dd>
<dt>All Rows</dt>
<dd><p>Alternatively, you can choose to download the whole catalogue
    without spatial restrictions.
    </p></dd>
</dl>
In either case, the <label>Maximum Row Count</label> selector indicates
the largest number of rows which will be returned.
If your query requests more rows than the limit given, extra rows will
simply be omitted from the returned result (the limit seems to be approximate).
It is possible to choose any value for this field, including very 
large ones or the special value "unlimited"; however consider 
before doing this whether you want to download a potentially very
large data set.
The server may in any case time out in the case of a very long 
connection, so it is probably not possible, even if it were desirable,
to download for instance the entire 2MASS point source catalogue.
</p>

<p>The <label>Column Selection</label> panel gives you some control
over which columns will be included in the loaded table.
This will include some or all of the columns the table has in the
VizieR archive, and perhaps some standard ones added automatically 
by the service.
The options are currently:
<dl>
<dt>standard</dt>
<dd><p>Contains a selection of those columns considered most interesting by 
    the service.
    </p></dd>
<dt>default</dt>
<dd><p>Contains the 'standard' columns plus numeric "_RAJ2000" and "_DEJ2000"
    positional columns inserted by the service;
    if the query is a Cone Selection rather than All Rows, it also contains
    a column "_r" inserted by the service giving the distance between the
    selected position and the row's position.
    </p></dd>
<dt>all</dt>
<dd><p>Contains all the columns from the archived catalogue.
    </p></dd>
</dl>
VizieR experts may fill in custom column requirements here by typing them
into the selector box rather than choosing one of the 
predefined options, for instance
<code>-out.add=_GLON,_GLAT</code> would add galactic coordinates to the
standard set; see 
<webref url="http://vizier.u-strasbg.fr/doc/asu-summary.htx"/>
for more details on VizieR hacking.
(In fact, this trick can be used to add VizieR parameters unrelated to
column selection as well).
</p>

<p>The <label>Catalogue Selection</label> panel offers several 
different ways to identify which of the catalogues in the VizieR archive
you want to query.  In all cases you will be presented with a
<ref id="JTable">JTable</ref> 
of VizieR catalogues, and you must select one by clicking on 
the relevant row.  You can sort within the displayed table by
clicking on the column header.
<label>Note: </label> for some of these options it is necessary to
fill in the Row Selection panel before you can operate them
(the controls will be disabled if no row selection has been made).
That is because the catalogues listed will depend on the region you
are going to query; VizieR is smart enough to know which catalogues
have some coverage in the region in question.
The options for catalogue selection are as follows:
<dl>
<dt>By Category</dt>
<dd><p>You may select one or more terms from one or more of the 
    presented lists of predefined keywords in the categories 
    <label>Wavelength</label>, <label>Mission</label> and
    <label>Astronomy</label> to restrict the catalogues
    that you are interested in.  How you select multiple entries from the
    same list is platform-dependent, but CTRL-click may work.
    When you have made your selections, hit the 
    <label>Search Catalogues</label> button, and those catalogues in the 
    categories you have identified, and with coverage in the region
    defined by the Row Selection panel, will be listed below the
    category selection panel.
    Select one of these by clicking on it.
    The <label>Sub-Table Details</label> checkbox controls whether the
    list displays only top-level VizieR catalogues 
    (each of which may contain multiple tables) 
    or entries for each table within each catalogue as well.
    The <label>Include Obsolete Tables</label> checkbox controls whether
    just the most current, or all versions of each catalogue are shown.
    </p></dd>
<dt>By Keyword</dt>
<dd><p>A <label>Keywords</label> text field is shown; you may enter
    a space-separated list of words which will be matched against 
    catalogue names and descriptions.
    When you have entered the search terms, hit the
    <label>Search Catalogues</label> button, and those catalogues 
    which match your terms, and with coverage in the region
    defined by the Row Selection panel, will be listed below the 
    Keywords field.
    Select one of these by clicking on it.
    The <label>Sub-Table Details</label> checkbox controls whether the
    list displays only top-level VizieR catalogues 
    (each of which may contain multiple tables) 
    or entries for each table within each catalogue as well.
    The <label>Include Obsolete Tables</label> checkbox controls whether
    just the most current, or all versions of each catalogue are shown.
    </p></dd>
<dt>Surveys</dt>
<dd><p>A (fairly short) list of large surveys held by VizieR is presented
    in a table.
    An indication of the size of each, in terms of number of
    thousands of rows, is given.
    Select one of these by clicking on it.
    </p></dd>
<dt>Missions</dt>
<dd><p>A (fairly short) list of data holdings at VizieR originating 
    from large missions is presented in a table.
    An indication of the size of each, in terms of number of
    thousands of rows, is given.
    Select one of these by clicking on it.
    </p></dd>
</dl>
</p>

<p>Depending on the type of catalogue search you make, various attributes
of the catalogues in question will be listed in the table for selection:
<dl>
<dt>Name</dt>
<dd><p>Unique VizieR identifier for the catalogue</p></dd>
<dt>Description</dt>
<dd><p>Short description of contents</p></dd>
<dt>KRows</dt>
<dd><p>Approximate number of thousands of rows</p></dd>
<dt>Rows</dt>
<dd><p>Approximate number of rows</p></dd>
<dt>Tables</dt>
<dd><p>Number of sub-tables contained within the VizieR catalogue</p></dd>
<dt>Popularity</dt>
<dd><p>A measure of the number of queries on the catalogue served by
    VizieR</p></dd>
<dt>Density</dt>
<dd><p>A measure of the number of sources per unit solid angle
    on the sky</p></dd>
<dt>Wavelengths</dt>
<dd><p>Keywords describing wavelength regimes covered</p></dd>
<dt>Astronomy</dt>
<dd><p>Keywords describing subject domain</p></dd>
</dl>
</p>

<p>When you have made your selection of rows, columns and catalogue
you can hit the <label>OK</label> button and TOPCAT will attempt to
contact the VizieR service to load the resulting table or tables.
You can cancel a request in progress with the <label>Cancel</label> button.
</p>

<p>CDS make the following request:
<blockquote>
<em>
If the access to catalogues with VizieR was helpful for your 
research work, the following acknowledgment would be appreciated: 
"This research has made use of the VizieR catalogue access tool, 
CDS, Strasbourg, France". 
The original description of the VizieR service was published in 
<webref url="http://adswww.harvard.edu/abs/2000A%26AS..143...23O"
        >A&amp;AS 143, 23 (2000)</webref>. 
</em>
</blockquote>
</p>

</subsubsect>

<subsubsect id="GavoTableLoadDialog">
<subhead><title>GAVO Millennium Database Query</title></subhead>

<figure>
<caption><px>GAVO load dialogue with an example query on the milli-Millennium
         database</px></caption>
<figureimage src="&FIG.GavoTableLoadDialog;"/>
</figure>

<p>This dialogue, selected from the 
<ref id="LoadWindow">Load Window</ref>'s toolbar
button (&IMG.GAVO;) or the main <label>VO</label> menu,
permits direct queries to the services provided by
<webref url="http://www.g-vo.org/">GAVO</webref>,
the German Astrophysical Virtual Observatory.
The main databases of general interest available through these services
are the <label>Millennium Simulation</label> results,
documented at <webref url="http://gavo.mpa-garching.mpg.de/Millennium/Help"/>.
</p>

<p>To make a query, fill in the fields as required:
<dl>
<dt>Base URL</dt>
<dd><p>This determines the database to be queried.  The following options
    are available:
    <dl>
    <dt>Milli-Millennium
        (<code>http://gavo.mpa-garching.mpg.de/Millennium</code>)</dt>
    <dd><p>Public simulation results database, containing a fraction of the
        full simulation results.  
        No username or password is required (the User and Password
        boxes will be disabled).
        </p></dd>
    <dt>Millennium
        (<code>http://gavo.mpa-garching.mpg.de/MyMillennium</code>)</dt>
    <dd><p>Full, protected simulation results database.  
        The username and password must be filled in for these queries.
        Registration is by application to GAVO.
        </p></dd>
    <dt>Other</dt>
    <dd><p>Other GAVO-provided services can be accessed from this dialogue
        by entering the relevant base URL here -- users of these services
        will know what they are.  They may or may not require a username and
        password.
        </p></dd>
    </dl>
    </p></dd>

<dt>User</dt>
<dt>Password</dt>
<dd><p>Registration information if required
    (dependent on base URL as above).
    </p></dd>

<dt>SQL Query</dt>
<dd><p>The text of an SQL query on the database in question.
    </p></dd>

</dl>
Then click the <label>OK</label> button, and the query will execute and
load the results into TOPCAT.  Clicking <label>Cancel</label> while it
is in progress will stop it running.
</p>

<p>The <label>HaloSamples</label> and <label>GalaxySamples</label> menus
provide some examples of
queries on the Milli-Millennium database (these have been copied from 
the <webref url="http://gavo.mpa-garching.mpg.de/Millennium/"
            >GAVO query page</webref>).
If you select one of these the <label>SQL Query</label> panel will be
filled in accordingly.
</p>

<p>Much more documentation, including tutorials and descriptions of the 
database schemas, is available on the GAVO website, at
<webref url="http://gavo.mpa-garching.mpg.de/Millennium/Help"/>.
</p>

</subsubsect>

<subsubsect id="BaSTITableLoadDialog">
<subhead><title>BaSTI Theory Database Query</title></subhead>

<figure>
<caption><px>BaSTI load dialog query tab</px></caption>
<figureimage src="&FIG.BaSTITableLoadDialog;"/>
</figure>

<p>This dialogue,selected from the
<ref id="LoadWindow">Load Window</ref>'s toolbar button (&IMG.BASTI;)
or the main <label>VO</label> menu,
allows direct queries to the BaSTI
<em>(Bag of Stellar Tracks and Isochrones)</em> database
hosted by the INAF-Teramo Astronomical Observatory.
You can find
<webref url="http://albione.oa-teramo.inaf.it/"
        >more detailed documentation</webref>
on the web site.
</p>

<p>This load dialogue has two tabs:
a <label>Query</label> tab to input search parameters, and
a <label>Results</label> tab to display the results table with one row
for each table resulting from the user's query.
</p>

<p>The <label>Query</label> tab
contains a set of parameters by which the query will be constrained,
some aids to help the user while preparing the selection and two buttons.
The <label>Reset</label> button simply clears query inputs and 
(if present) user's selections in the Results tab.
The <label>Submit</label> button performs the query and switches 
the dialog to the Results tab.
As an aid to allow a refined query without too much recursive steps,
at the bottom center of the tab,
a counter displays how many rows (i.e. resulting tables) the output will count. Remembering that the results will contain 30 rows at maximum,
the user can than refine his/her constrains to reduce the number of 
results.
</p>

<p>To do so the query helps the user in two ways mainly:
automatically unselecting the unavailable
parameters for a specific query 
(e.g. the mass range for an isochrone search) and displaying,
for the ranged parameters, the value limits for that parameter,
this happens just moving the mouse cursor over the input area.
</p>

<p>Here follows a short description of the query parameters,
for full details refer to the
<webref url="http://albione.oa-teramo.inaf.it">BaSTI</webref> main site.
<dl>
<dt>Data Type</dt>
<dd><p>The type of simulation desired: isochrones, tracks or summary tables.
    This field is the only mandatory to submit a query.
    </p></dd>
<dt>Scenario</dt>
<dd><p>Stellar evolution scenario, i.e. canonical simulation or 
    including overshooting calculations.
    </p></dd>
<dt>Type</dt>
<dd><p>Type of track simulation: normal or including the Asymptotic Giant
    Branch (AGB) simulation.
    </p></dd>
<dt>Mass Loss</dt>
<dd><p>Selects which value the Mass Loss parameter should have:
    0.2 or 0.4 are the available choices.
    </p></dd>
<dt>Photometric System</dt>
<dd><p>A set of photometric systems is used to <em>colour</em>
    the stellar simulated tracks for comparison with observational data.
    This dropdown input allows for a selection within them.
    </p></dd>
<dt>Mixture</dt>
<dd><p>Stellar abundances mixture: scaled solar values or alpha enhanced.
    </p></dd>
<dt>Age</dt>
<dd><p>Age range, in values of Gyr, for the isochrones.
    </p></dd>
<dt>Mass</dt>
<dd><p>Mass range, in values of Solar Masses.
    </p></dd>
<dt>Z</dt>
<dd><p>Initial metal abundance range.
    </p></dd>
<dt>Y</dt>
<dd><p>Initial Helium abundance range.
    </p></dd>
<dt>[Fe/H]</dt>
<dd><p>Iron over Hydrogen logarithmic ratio.
    </p></dd>
<dt>[M/H]</dt>
<dd><p>Metals over Hydrogen logarithmic ratio.
    </p></dd>
</dl>
</p>

<p>Once the Query panel has been filled in, hit the <label>Submit</label>
button.  This will show the <label>Results</label> tab.
This displays  a table where each row refers to an available result from the BaSTI database as constrained by the user's query. 
On top of the table the number of results identified by the
query is recalled.
The user now can switch back to refine the query or selected 
(mouse clicking) the table/s he/she wants to load into TOPCAT.
Once the selection is ready (CTRL+click or SHIFT+click for multiple
selections) pressing the <label>OK</label> button will load the 
tables into TOPCAT.
</p>

</subsubsect>


<subsubsect id="demoData">
<subhead><title>Example Tables</title></subhead>

<p>Provided with TOPCAT are some example tables,
which you can access in a number of ways.
The simplest thing is to start up TOPCAT with the 
"<code>-demo</code>" flag on the command line, which will cause
the program to start up with a few demonstration tables already loaded in.
</p>

<p>You can also load examples in from the <label>Examples</label> menu 
in the <ref id="LoadWindow">Load Window</ref> however.
This contains the following options:
<dl>

<dt>Load Example Table</dt>
<dd><p>Loads in a single example table.
    </p></dd>

<dt>Browse Demo Data</dt>
<dd><p>Pops up a 
    <ref id="TreeTableLoadDialog" plaintextref="yes">Hierarchy Browser</ref>
    looking at a hierarchy of tables in different formats.
    This option is designed to show some of the organisational
    complexity which TOPCAT can handle when browsing tables.
    </p></dd>

</dl>
</p>

<p>Note these examples are a bit of a mixed bag, and are not all
that exemplary in nature.  They are just present to allow you to 
play around with some of TOPCAT's features if you don't have any
real data to hand.
</p>

</subsubsect>

</subsect>


<subsect id="SaveQueryWindow">
<subhead><title>Save Window</title></subhead>

<figure>
<caption><px>Save Window</px></caption>
<figureimage src="&FIG.SaveQueryWindow;"/>
</figure>

<p>The Save Window is used to write tables out,
and it is accessed using the <label>Save Table</label> button (&IMG.SAVE;)
in the <ref id="ControlWindow">Control Window</ref>'s toolbar or 
<label>File</label> menu.
</p>

<p>The window consists of two parts.
At the top is the <label>Content Panel</label>,
which is used to determine exactly what table or tables are going to be saved,
and below it is the <label>Destination Panel</label>,
which is used to determine where they will be saved to.
These panels are described separately in the subsections below.
</p>

<p>For large tables, a progress bar will be displayed
indicating how near the save is to completion.
It is not advisable to edit tables which are being saved 
during a save operation.
</p>

<p>In some cases, saving the table to a file with the same name 
as it was loaded from can cause problems 
(e.g. an application crash which loses the data unrecoverably).
In other cases, it's perfectly OK.  The main case in which it's
problematic is when editing an uncompressed FITS binary table on disk.
TOPCAT will attempt to warn you if it thinks you are doing something
which could lead to trouble; ignore this at your own risk.
</p>

<p>If you save a table to a format other than the one from which it was loaded,
or if some new kinds of metadata have been added,
it may not be possible to express all the data and metadata from the table
in the new format.
Some message to this effect may be output in such cases.
</p>

<p>There is no option to compress files on output.
You can of course compress them yourself once they have been written,
but note that this is not usually a good idea for FITS files,
since it makes them much slower to read (for TOPCAT at least).
</p>

<subsubsect>
<subhead><title>Content Panel</title></subhead>

<p>The Content Panel is the upper part of the save window,
and it is used to select what table or tables you want to save.
The options are described in the following subsections.
</p>

<subsubsubsect>
<subhead><title>Current Table</title></subhead>

<p>The <label>Current Table</label> save option 
saves the table currently selected in the 
<ref id="ControlWindow">Control Window</ref>.
What is written is the
<ref id="apparent">Apparent Table</ref> corresponding to the current table,
which takes into account any modifications you have made to 
its data or appearance this session.
The current <label>Row Subset</label> and <label>Sort Order</label>
are displayed in this window as a reminder of what you're about to save.
Information about Row Subsets themselves and hidden columns will not
be saved, though you can save information about subset membership
by creating new boolean columns based on subsets
using the "To Column" button (&IMG.TO_COLUMN;) from the
<ref id="SubsetWindow">Subsets Window</ref>.
Alternatively you could use the Session Save option described below.
</p>

</subsubsubsect>

<subsubsubsect>
<subhead><title>Multiple Tables</title></subhead>

<p>The <label>Multiple Tables</label> save option allows you to save 
multiple tables to the same file.
If a FITS or VOTable based output format is used, this means that
when the file is loaded back into TOPCAT, all the saved tables will
be individually loaded in.
</p>

<p>The list of loaded tables is shown, with a column of checkboxes
on the left.  By default these are selected, but you can select or
unselect them by clicking.  When the save is performed, only those
tables with the checkbox selected will be saved.
</p>

<p>As with the Current Table save, it is the
<ref id="apparent">Apparent Table</ref> in each case which is saved,
so that only unhidden columns, and rows in the Current Subset will be
included.
On the right hand side of the table is information to remind you 
which row subset and ordering will be saved.
</p>

</subsubsubsect>

<subsubsubsect>
<subhead><title>Session</title></subhead>

<p>The <label>Session</label> save option allows you to save much 
of the information
about the loaded tables in your current TOPCAT session.
Unlike the <label>Current Table</label> or <label>Multiple Tables</label> 
options, the whole of each loaded table, along with other
information about your use of it, is saved, rather than just the
<ref id="apparent">Apparent Table</ref>.
The saved items include:
<ul>
<li>All rows, not just those in the current Row Subset</li>
<li>All visible and hidden columns,
    along with their order and visibility status</li>
<li>All defined Row Subsets</li>
<li>The current Sort Order</li>
<li>The current Row Subset</li>
<li>The label</li>
<li>Whether row selection causes a SAMP broadcast</li>
</ul>
</p>

<p>The list of loaded tables is shown, with a column of checkboxes
on the left.  By default these are selected, but you can select or
unselect them by clicking.  When the save is performed, only those
tables with the checkbox selected will be saved.
</p>

<p>The tables are saved as a multi-table 
<ref id="outFits">fits-plus</ref> (recommended) or 
<ref id="outVotable">VOTable</ref> file.
This is a normal multi-table file in that any FITS or VOTable 
reader can read the tables it contains, but it contains some specialised
metadata encoding information of special significance to TOPCAT,
marking it as a saved session.
The upshot is that if you save a file in this way and then load it back into
TOPCAT, the tables it loads will appear in very much the same
state as when you saved them, in terms of defined and current subsets,
row order, visible and invisible columns, and so on.
If you process it with some application other than TOPCAT, it will look
quite like the table you saved, but with some additional data and metadata.
</p>

<p>Note however that the reloaded state is not identical to that before saving.
One important difference is that columns and row subsets 
which were defined algebraically are saved and restored as fixed values,
so it is no longer possible to edit the expressions.
Another is that only state belonging to tables is saved, so that
for instance plots will not be restored.
Table activation actions are not saved either.
It is possible that some of this may be changed in future releases.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="TableSaveChooser">
<subhead><title>Destination Panel</title></subhead>

<p>The Destination Panel is the lower part of the save window,
and is used to select where and how the table or tables should be saved.
</p>

<p>The <label>Output Format</label> selector is used to choose
the format in which the table will be written from one of the 
<ref plaintextref="yes" id="outFormats">supported output formats</ref>.
The available selections are somewhat different depending on what it is you
are saving; for instance some formats cannot accommodate multiple tables,
so these formats are not offered for the Multiple Table save.
If the "(auto)" option is used, an attempt is made to guess the 
format based on the filename given;
for instance if you specify the name "out.fits" a FITS binary table
will be written.
</p>

<p>You can specify the location of the output table in these ways,
which are described in the following sections:
<ul>
<li>Type in the location directly in the 
    <ref id="saveString" plaintextref="yes">Output Location field</ref>
    as a filename or a URL as described in section 
    <ref id="tableLocation"/></li>
<li>Use the <label>Filestore Browser</label> button or toolbar button
    (&IMG.FILESTORE_DIALOG;) to get a
    <ref id="FilestoreTableSaveDialog" plaintextref="yes">browser</ref>
    that shows you local and remote files</li>
<li>Use the <label>System Browser</label> button or toolbar button
    (&IMG.SYSTEM;) to get a
    <ref id="SystemTableSaveDialog" plaintextref="yes">native browser</ref>
    that uses your OS's standard file saving interface</li>
<li>Use the <label>SQL table</label> toolbar button
    (&IMG.SQL_DIALOG;) to get the 
    <ref id="SQLWriteDialog" plaintextref="yes">SQL Output Dialogue</ref></li>
</ul>
</p>

<subsubsubsect id="saveString">
<subhead><title>Enter Location</title></subhead>

<p>You can specify where to save a table by typing its location
directly into the <label>Output Location</label> field of the
Save Table window.
This will usually be the name of a new file to
write to, but could in principle be a URL or a SQL specifier.
</p>

</subsubsubsect>

<subsubsubsect id="FilestoreTableSaveDialog">
<subhead><title>Filestore Browser</title></subhead>

<figure>
<caption><px>Filestore Browser for table saving</px></caption>
<figureimage src="&FIG.FilestoreTableSaveDialog;"/>
</figure>

<p>By clicking the <label>Browse Filestore</label> button in the
<label>Save Table</label> window,
you can obtain a browser which will display the
files in a given directory.
</p>

<p>The browser initially displays the current directory, but this can be
changed by typing a new directory into the <label>File Name</label> field,
or moving up the directory hierarchy using the selector box at the top,
or navigating the file system by clicking the up-directory button
or double-clicking on displayed directories.
The initial default directory can be changed by setting the
<code>user.dir</code> 
<ref id="jvmProperties" plaintextref="yes">system property</ref>.
</p>

<p>The browser can display files in remote filestores such as on
MySpace or SRB servers; see the section on the load filestore
browser (<ref id="FilestoreTableLoadDialog"/>) for details.
</p>

<p>To save to an existing file, select the file name and click the
<label>OK</label> button at the bottom; this will overwrite that file.
To save to a new file, type it into the <label>File Name</label> field;
this will save the table under that name into the directory which is displayed.
You can (re)set the format in which the file will be written using
the <label>Output Format</label> selector box on the right
(see <ref id="outFormats"/> for discussion of output formats).
</p>

</subsubsubsect>

<subsubsubsect id="SystemTableSaveDialog">
<subhead><title>System Browser</title></subhead>

<p>By clicking the <label>System Browser</label> button or toolbar button
(&IMG.SYSTEM;) in the
<ref id="SaveQueryWindow">Save Window</ref>,
you can use your Operating System's native file browser to decide where
to save a file.
What this looks like is entirely dependent on your OS;
it may or may not contain system-specific features like shortcuts to
commonly-used directories.
</p>

<p>Since TOPCAT has no control over the way this dialogue looks,
it cannot contain the <label>Output Format</label> selector,
and certain other things such as save cancel may not work as well as
for the other dialogue types.  To select the output table format, you
will need to use the selector in the <label>Save Window</label>.
</p>

</subsubsubsect>

<subsubsubsect id="SQLWriteDialog">
<subhead><title>SQL Output Dialogue</title></subhead>

<figure>
<caption><px>SQL table writing dialogue</px></caption>
<figureimage src="&FIG.SQLWriteDialog;"/>
</figure>

<p>If you want to 
<ref id="outSql" plaintextref="yes">write a table to an SQL database</ref>,
you can use a specialised dialogue to specify the table destination by clicking
the <label>SQL Table</label> button in the <label>Save Table</label>
window.
</p>

<p>This provides you with a list of fields to fill in which define
the new table to write, as follows:
<dl>
<dt>Protocol</dt>
<dd><p>The name of the appropriate JDBC sub-protocol.
    This is defined by the JDBC driver that you are using, and is
    for instance "<code>mysql</code>" for MySQL's Connector/J driver
    or "<code>postgresql</code>" for PostgreSQL's JDBC driver.
    </p></dd>

<dt>Host</dt>
<dd><p>The hostname of the machine on which the database resides
    (may be "<code>localhost</code>" if the database is local).
    </p></dd>

<dt>Database name</dt>
<dd><p>The name of the database.
    </p></dd>

<dt>New table name</dt>
<dd><p>The name of a new table to write into the given database.
    Subject to user privileges,
    this will overwrite any existing table in the database which has the
    same name, so should be used with care.
    </p></dd>

<dt>User name</dt>
<dd><p>The username under which you wish to access the database.
    This is not strictly necessary if there is no access control for
    the database in question.
    </p></dd>

<dt>Password</dt>
<dd><p>The password for the given username.  Again, whether this is
    necessary depends on the access policy of the database.
    </p></dd>

<dt>Write Mode</dt>
<dd><p>Options for writing the table to the database.  Choose one of:
    <dl>
    <dt>create</dt>
    <dd><p>A new table is created for the output.
        If one with the given name already exists, an error results.
        </p></dd>
    <dt>dropcreate</dt>
    <dd><p>A new table is created for the output.
        If one with the given name already exists, it is dropped first.
        </p></dd>
    <dt>append</dt>
    <dd><p>The results are appended to an existing table with the given name.
        If the table has the wrong number or types of columns,
        an error results.
        </p></dd>
    </dl>
    </p></dd>
</dl>
</p>

<p>There are a number of criteria which must be satisfied for SQL
access to work within TOPCAT (installation of appropriate drivers
and so on) - see the section on 
<ref id="jdbcConfig" plaintextref="yes">JDBC configuration</ref>.
If you don't take these steps, this dialogue may be inaccessible.
</p>

</subsubsubsect>

</subsubsect>

</subsect>

<subsect id="match-windows">
<subhead><title>Match Windows</title></subhead>

<p>This section documents the windows used to crossmatch 
rows either between two or more local tables or within a single table.
This topic is discussed in more detail in <ref id="join"/>.
Windows for other kinds of joins are described elsewhere:
concatenation in <ref id="ConcatWindow"/> and matching with 
remote tables via VO services in <ref id="vo-windows"/>
and against VizieR and SIMBAD via the CDS X-Match service in
<ref id="CdsUploadMatchWindow"/>.
</p>

<p>The <ref id="match-windows-common">next subsection</ref>
describes the features which are common to the different types of 
match window, and the following subsections detail the operation
of each distinct match window
(<ref id="MatchWindow1">internal</ref>, 
 <ref id="MatchWindow">pair</ref> and 
 <ref id="MatchWindowN">multi-table</ref>).
</p>

<subsubsect id="match-windows-common">
<subhead><title>Common Features</title></subhead>

<subsubsubsect id="matchCriteria">
<subhead><title>Match Criteria</title></subhead>

<figure>
<caption>
<px>Match Criteria panel.
The details will differ depending on what match type is chosen.</px>
</caption>
<figureimage src="&FIG.ParameterPanel;"/>
</figure>

<p>The match criteria box allows you to specify what counts as a match
between two rows.
It has two parts.
First, you must select one of the options in the <label>Algorithm</label>
selector.  This effectively selects the coordinate space in which rows
will be compared with each other.  Depending on the chosen value,
a number of fields will be displayed below, which you must fill in
with values that determine how close two rows have to be in terms
of a metric on that space to count as a match.
</p>

<p>The following match types (algorithm values) are offered:
<dl>

<dt>Sky</dt>
<dd><p>Comparison of positions on the celestial sphere.
    In this case you will need to specify columns giving
    Right Ascension and Declination
    for each table participating in the match.
    The Max Error value you must fill in is the 
    maximum separation of matched points around a great circle.
    </p></dd>

<dt>Sky with Errors</dt>
<dd><p>The matching is like that for the <label>Sky</label> option above,
    but an error radius (positional uncertainty) is given for each
    row in the input tables, rather than just a single value for the whole
    match.
    Along with the Right Ascension and Declination columns,
    you also specify an Error column which gives the error radius
    corresponding to that position.
    Two rows are considered to match when the separation between the
    two RA,Dec positions is no larger than the sum of the two
    Error values for the corresponding rows.
    The Scale value should be set to a rough average of the per-row errors.
    It is used only to set a sensible default for the Healpix-k
    tuning parameter, and its value does not affect the result.
    If Healpix-k is set directly (see <ref id="matchTuning"/>),
    Scale is ignored.
    <strong>Note:</strong> the semantics of this matcher have changed
    slightly since version 3.8 of TOPCAT and earlier. 
    In earlier versions the single parameter was named Max Error
    and provided an additional constraint on the maximum accepted separation
    between matched objects.  For most uses, the old and new behaviours are
    expected to give the same results, but in cases of difference, the new
    behaviour is more likely what you want.
    </p></dd>

<dt>Sky Ellipses</dt>
<dd><p>Compares elliptical regions on the sky for overlap.
    You will need to specify columns giving the central position,
    major and minor radii, and position angle of the ellipse.
    Two rows are considered to match if there is any overlap between the
    ellipses.  The goodness of match is a normalised generalisation of the
    symmetrical case used by the <label>Sky with Errors</label> option above.
    The position angle is measured from north to the semi-major axis,
    in the direction towards the positive RA axis.
    The Scale value should be set to a rough average of the major radii;
    It is used only to set a sensible default for the Healpix-k
    tuning parameter, and its value does not affect the result.
    If Healpix-k is set directly (see <ref id="matchTuning"/>),
    Scale is ignored.
    The calculations are approximate since in some cases they rely on
    projecting the ellipses onto a Cartesian tangent plane before evaluating
    the match, so for larger ellipses the criterion will be less exact.
    For objects the size of most observed stars or galaxies,
    this approximation is not expected to be problematic.
    </p></dd>

<dt>Sky 3D</dt>
<dd><p>Comparison of positions in the sky taking account of 
    distance from the observer.
    In this case you will need to specify columns giving
    Right Ascension and Declination in angular units, 
    as well as distance from the origin in arbitrary units
    for each table participating in the match.
    The Error value is a maximum separation in Cartesian space 
    of matched points in the same units as the radial distance.
    </p></dd>

<dt>Exact Value</dt>
<dd><p>Requires exact matching of values.
    In this case you will need to specify the column containing the match key
    for each table participating in the match;
    this might typically be an object name or index number.
    Two rows count as matching if they have exactly the same entry in
    the specified field, except rows with a null value in that column,
    which don't match any other row.  Note that the values must also
    be of the same type, so for instance a Long (64-bit) integer 
    value will not match an Integer (32-bit) value.
    </p></dd>

<dt>N-dimensional Cartesian</dt>
<dd><p>Comparison of positions in an isotropic N-dimensional Cartesian space.
    In this case you will need to specify N columns giving
    coordinates for each table participating in the match.
    The Error value is the maximum spatial separation of matched points.
    Currently the highest dimensionality you can select is 3-d -
    does anyone want a higher number?
    </p></dd>

<dt>N-dimensional Cartesian, Anisotropic</dt>
<dd><p>Comparison of positions in an N-dimensional Cartesian space
    with an anisotropic metric.
    In this case you will need to specify N columns giving coordinates
    for each table participating in the match,
    and an error distance for each of these dimensions.
    Points P1 and P2 are considered to match if P2 falls within
    the ellipsoid with radii given by the error distances, centered on P1.
    This kind of match will typically be used for non-'spatial' spaces,
    for instance (magnitude,redshift) space, in which the metrics in 
    different dimensions are not related to each other.
    Currently the highest dimensionality you can select is 4-d -
    does anyone want a higher number?
    </p></dd>

<dt>N-dimensional Cuboids</dt>
<dd><p>This matching is like that for <label>N-dimensional Cartesian</label>
    above, but points are considered to match if they fall within the same
    cuboid rather than ellipsoid.  The error values are the half-axis
    lengths of the cuboid, like rectangular "radii".
    This kind of match is suitable for grouping items into regularly-spaced
    pixels, though it's not a very efficient way of doing that.
    </p></dd>

<dt>N-dimensional Cartesian with Errors</dt>
<dd><p>The matching is like that for the <label>N-dimensional Cartesian</label>
    option above, but an error radius (positional uncertainty) is given
    for each row in the input tables, rather than just a single value
    for the whole match.
    Along with the Cartesian coordinate columns, you also specify an Error
    column which gives the error radius corresponding to that position.
    Two rows are considered to match when the separation between the
    two positions is no larger than the sum of the two Error values
    for the corresponding rows.
    The Scale parameter should be approximately the characteristic size
    of the per-object error values.
    Its value, in conjunction with the Bin Factor tuning parameter,
    affects the performance of the match but not the result.
    </p></dd>

<dt>2-d Cartesian Ellipses</dt>
<dd><p>Compares elliptical regions in the plane for overlap.
    You will need to specify columns giving the central position,
    major and minor radii, and orientation angle of the ellipse.
    Two rows are considered to overlap if there is any overlap between the
    ellipses.  The goodness of match is a generalisation of the symmetrical
    case used by the <label>2-d Cartesian with Errors</label> option above.
    The orientation angle is measured anticlockwise from the X-axis
    to the ellipse major axis.
    The Scale parameter should be set to a rough average of the major radii.
    Its value, in conjunction with the Bin Factor tuning parameter,
    affects the performance of the match but not the result.
    </p></dd>

<dt>Sky + X</dt>
<dd><p>Comparison of positions on the celestial sphere with an additional
    numeric constraint.
    This is a combination of the Sky and 
    1-d Cartesian matches above, so the columns you need
    to supply are RA, Dec and one extra, and the errors are 
    angular separation on the sky and the error in the extra column.
    A match is registered if it matches in both of the constituent tests.
    You could use this for instance to match objects which are both close
    on the sky and have similar luminosities.
    </p></dd>

<dt>Sky + XY</dt>
<dd><p>Comparison of positions on the celestial sphere with an additional
    2-d anisotropic Cartesian constraint.
    This is a combination of the Sky and 2-d Anisotropic Cartesian
    matches above, so the columns you need to supply are
    RA, Dec and two extra, and the errors are 
    angular separation on the sky and the error radii corresponding to
    the extra columns.
    A match is registered if it matches in both of the constituent tests.
    You could use this for instance to match objects which are both close
    on the sky and have similar luminosities and redshifts.
    </p></dd>

<dt>HTM</dt>
<dd><p>Performs sky matching in just the same way as the <label>Sky</label>
    option above, but using a different algorithm (pixelisation of the
    celestial sphere is performed using the Hierarchical Triangular Mesh
    rather than the HEALPix scheme).  The results in both cases 
    should be identical, but HTM is much slower.  Hence, this option
    is only useful for debugging.  It may be withdrawn in future releases.
    </p></dd>

</dl>
</p>

<p>Depending on the match type, the units of the error value(s) you enter
may be significant.  In this case, there will be a unit selector
displayed alongside the entry box.  You must choose units which 
are correct for the number you enter.
</p>

<p>More information is available in the GUI as a tooltip by hovering with
the mouse pointer over the field in question.
</p>

<p>See <ref id="matchTuning"/> for information on optional
<em>tuning parameters</em> which are sometimes displayed in this panel.
</p>

<p>The matching framework is capable of performing even more complicated
types of match, for instance Sky + 6-dimensional anisotropic Cartesian.
These are not offered purely to avoid complicating the GUI.
More flexible matching requirements in this in and other respects
can be achieved by using the matching commands in 
<webref url="http://www.starlink.ac.uk/stilts/">STILTS</webref>
instead.
</p>

</subsubsubsect>


<subsubsubsect id="matchColumnSelect">
<subhead><title>Column Selection Boxes</title></subhead>

<figure>
<caption>
<px>Column Selection Box.
The details will differ depending on what match type is chosen.</px>
</caption>
<figureimage src="&FIG.TupleSelector;"/>
</figure>

<p>The column selection boxes allow you to select which of the
columns in the input tables will provide the data
(the coordinates which have to match).
For each table you must select the names of the required columns;
the ones you need to select will depend on the 
<ref id="matchCriteria">match criteria</ref> you have chosen.
</p>

<p>For some columns, such as Right Ascension and Declination in sky matches,
units are important for the columns you select.
In this case, there will be a selector box for the units alongside
the selector box for the column itself.  You must ensure that the
correct units have been selected, or the results of the match will be 
rubbish.
</p>

<p>In some cases these column and/or unit selectors may have a value filled in
automatically (if the program thinks it can guess appropriate ones)
but you should ensure that it has guessed correctly in this case.
Only suitable columns are available for choosing from these column
selectors; in most cases this means numeric ones.
</p>

<p>Instead of selecting a column name from the list provided in these
boxes, you may type in an expression.  This can be a column name,
or an algebraic expression based on column names, or even a constant.
The expression language syntax is described in <ref id="jel"/>.
</p>

</subsubsubsect>


<subsubsubsect id="matchTuning">
<subhead><title>Tuning</title></subhead>

<p>This subsection describes the use of two toolbar buttons available
in the match windows:
<dl>
<dt>&IMG.TUNING; Tuning Parameters</dt>
<dd><p>Displays <em>tuning parameters</em> alongside match parameters
    in the Match Criteria panel.
    </p></dd>
<dt>&IMG.PROFILE; Full Profiling</dt>
<dd><p>Increases the amount of timing and memory use information displayed
    in the Logging Panel.
    </p></dd>
</dl>
</p>

<p>The parameters such as Max Error visible by default in the 
<ref id="matchCriteria">Match Criteria</ref> panel
define what counts as a match
and must be filled in for the match to proceed.
</p>

<p>Optionally, you can see and adjust another set of parameters 
known as <em>Tuning parameters</em>.
These will not affect the result of the match, but may affect 
its performance, in terms of how much CPU time and memory it takes.
Most of the time, you can forget about this option, since TOPCAT
attempts to pick reasonable defaults, but if your match is very
slow (especially if it's unexpectedly slow given the sizes of the
tables involved), or if it's failing with messages about running
out of memory, then adjusting the tuning parameters may help.
</p>

<p>To view the tuning parameters, use the 
<label>Tuning Parameters</label> (&IMG.TUNING;) toolbar button or 
menu item.  This will add display of tuning parameters to the
match parameters in the Match Criteria panel.
Suggested values are filled in by default, and may be affected by
the match parameters that you fill in; you can play around with
different values and see the effect on match performance.
If you do this, it is useful to use also the
<label>Full Profiling</label> (&IMG.PROFILE;) toolbar button to
turn on full profiling.  This will cause additional information
on the amount of CPU time and memory used by each step to be
displayed in the logging panel at the bottom.  There is a small
penalty in CPU time required to gather this information, which
is one reason it is not turned on by default.
</p>

<p>What tuning parameters are available depends on the match type
you have chosen.  Some additional description is available as 
tooltips if you hover over the query field.
In most cases, they are one or other of the following:
<dl>
<dt>HEALPix k</dt>
<dd><p>Used for sky-like matches.
    <m>k</m> is an integer value which determines the size of pixels into 
    which the celestial sphere is decomposed for binning rows.
    The legal range is between 0 (corresponding to a pixel size around
    60 degrees) and 20 (around 0.2 arcsec).
    In HEALPix language, k is log<sub>2</sub>(<m>N</m><sub>side</sub>).
    </p></dd>
<dt>Scale Factor</dt>
<dd><p>Used for Cartesian-like matches.
    The scale factor is a floating point 
    value which determines the size of the notional N-dimensional pixels
    into which the space is decomposed for binning rows,
    as a multiple of the match error.
    The smallest legal value is 1.
    </p></dd>
</dl>
In either case, the number of rows per bin should be not too large,
and not too small (though exactly what that means in quantitative terms is
another matter).  Larger bins/pixels generally mean less memory use
and more CPU time, though that's not always the case.
</p>

<p>Even if you happen to have a good understanding of 
<ref id="matchAlgorithm">how the matching algorithm works</ref>
(and you probably don't), this kind of tuning is a bit of a black art, 
and depends considerably on the details of the particular match. 
In some cases however it is quite
possible to improve the time taken by a match, or the size of 
table which can be matched in a given amount of memory, by a
factor of several.
If you want to try to improve performance, try the default, 
adjust the tuning parameters slightly, look at how the performance
changes by examining the logging output, and maybe repeat to taste.
</p>

<p>Another thing which can affect speed and memory usage is whether
your Java Virtual Machine is running in 32-bit or 64-bit mode.
There are pros and cons of each - sometimes one will be better,
sometimes the other.  If you need to improve performance, experiment!
</p>

</subsubsubsect>

</subsubsect>


<subsubsect id="MatchWindow">
<subhead><title>Pair Match Window</title></subhead>

<figure>
<caption><px>Pair Match Window</px></caption>
<figureimage src="&FIG.MatchWindow;"/>
</figure>

<p>The Pair Match Window allows you to join two tables together
side-by-side, aligning rows by matching values in some of their
columns between the tables.  It can be obtained using the
<label>Pair Match</label> (&IMG.MATCH2;) button in the 
<ref id="ControlWindow">Control Window</ref> toolbar or 
<label>Joins</label> menu.
</p>

<p>In a typical scenario you might have two tables each representing
a catalogue of astronomical objects, and you want a
third table with one row for each object which has an entry in both
of the original tables.  An object is defined as being the same one
in both tables if the co-ordinates in both rows are "similar",
for instance if the
difference between the positions indicated by RA and Dec columns
differ by no more than a specified angle on the sky.
Matching rows to produce the join requires you to specify the criteria
for rows in both tables to refer to the same object and
what to do when one is found - the options are discussed in
more detail in <ref id="pairMatch"/>.
</p>

<p>The result is created from the <ref id="apparent">Apparent</ref>
versions of the tables being joined, so that any row subsets,
hidden columns, or sorts currently in force will be reflected in the
output.
Progress information on the match, which may take a little while,
is provided in the logging window and by a progress bar at the bottom
of the window.  When it is completed, you will be informed by a
popup window which indicates that a new table has been created.
This table will be added to the list in the Control Window and can
be examined, manipulated and saved like any other.
In some cases, some additional columns will be added to the 
output table which give you more information about how it
has progressed (see <ref id="matchRowSelect"/>.
</p>

<p>The Match Window provides a set of controls which allow you
to choose how the match is done and what the results will look like.
It consists of these main parts:
<dl>

<dt><ref id="matchCriteria">Match Criteria box</ref></dt>
<dd><p>Allows you to define what counts as a match between two rows.
    </p></dd>

<dt><ref id="matchColumnSelect">Column Selection boxes</ref></dt>
<dd><p>Allows you to select which tables are to be joined and which 
    columns in them supply the matching coordinates.
    </p></dd>

<dt><ref id="matchRowSelect">Output Rows selector</ref></dt>
<dd><p>Allows selection of which rows are to be included in the output
    table (for instance whether only those rows matching in both tables
    should be output or not).
    </p></dd>

<dt>Log window</dt>
<dd><p>Reports on progress as the match is taking place.  The progress bar
    at the bottom of the window also provides an indication of how
    far through each stage processing has got.
    </p></dd>

<dt>Control buttons</dt>
<dd><p>The <label>Go</label> button starts the search when you are
    happy with the selections that you have made, and the
    <label>Stop</label> button interrupts it midway if you decide
    you no longer want the results (closing the Match Window also
    interrupts the calculation).
    </p></dd>

</dl>
</p>

<p>For information on the 
<label>Tuning Parameters</label> (&IMG.TUNING;) and
<label>Full Profiling</label> (&IMG.PROFILE;) toolbar buttons,
see <ref id="matchTuning"/>.
</p>


<subsubsubsect id="matchRowSelect">
<subhead><title>Output Rows Selector Box</title></subhead>

<figure>
<caption><px>Pair match Output Rows Selector Box</px></caption>
<figureimage src="&FIG.PairMatchSpec;"/>
</figure>

<p>When the match is complete a new table will be created which 
contains rows determined by the matches which have taken place.
The <label>Output Rows</label> selector box allows you to choose on what 
basis the rows will be included in the output table as a function
of the matches that were found.
</p>

<p>In all cases each row will refer to only one matched
(or possibly unmatched) "object", so that any non-blank columns
in a given row come from only rows in the input tables
which match according to the specified <ref id="matchCriteria">criteria</ref>.
However, you have two choices to make about which rows are produced.
</p>

<p>The <label>Match Selection</label> selector allows you to choose
what happens when a row in one table can be matched by 
more than one row in the other table.  There are four options:
<dl>
<dt>All matches</dt>                      <!-- ALL -->
<dd><p>Every match between the two tables is included in the result.
    Rows from both of the input tables may appear multiple times in the result.
    </p></dd>
<dt>Best match, symmetric</dt>            <!-- BEST -->
<dd><p>The best pairs are selected in a way which treats the two tables
    symmetrically.
    Any input row which appears in one result pair is disqualified
    from appearing in any other result pair, so each row
    from both input tables will appear in at most one row in the result.
    </p></dd>
<dt>Best match for each Table 1 row</dt>  <!-- BEST1 -->
<dd><p>For each row in table 1, only the best match from table 2
    will appear in the result. Each row from table 1 will appear a maximum
    of once in the result, but rows from table 2 may appear multiple times.
    </p></dd>
<dt>Best match for each Table 2 row</dt>  <!-- BEST2 -->
<dd><p>For each row in table 2, only the best match from table 1
    will appear in the result. Each row from table 2 will appear a maximum
    of once in the result, but rows from table 1 may appear multiple times.
    </p></dd>
</dl>
The "best" match in these options generally means "closest" - it is the one
with the lowest match score, where the definition of this score
is determined by the match criteria you have selected.
The differences between the various <label>Best match...</label> options
are a bit subtle.
In cases where it's obvious which object in each table is the best match
for which object in the other, choosing between these options will not
affect the result. However, in crowded fields (where the distance between
objects within one or both tables is typically similar to or smaller than
the specified match radius) it will make a difference. In this case one
of the asymmetric options is usually most appropriate,
but you'll need to think about which of them suits your requirements.
The performance (time and memory usage) of the match may also differ
between these options, especially if one table is much larger than the other.
</p>

<p>The <label>Join Type</label> selector allows you to choose what
output rows result from a match in the input tables.
<dl>
<dt>1 and 2</dt>
<dd><p>The output table contains only rows which have an entry from 
    both of the input tables, so that every output row represents an
    actual matched pair.
    This corresponds to an SQL <em>inner join</em>.
    </p></dd>

<dt>All from 1</dt>
<dd><p>All of the matched rows are present in the output as for
    <label>1 and 2</label>, but additionally the unmatched rows from
    the first table are present with the columns from the second
    table blank.
    This corresponds to an SQL <em>left outer join</em>.
    </p></dd>

<dt>All from 2</dt>
<dd><p>As for <label>All from 1</label> but the other way round.
    This corresponds to an SQL <em>right outer join</em>.
    </p></dd>

<dt>1 or 2</dt>
<dd><p>Every row, matched and unmatched, from both of the input 
    tables appears in the output.
    This is the union of rows from <label>All from 1</label> and
    <label>All from 2</label>.
    This corresponds to an SQL <em>full outer join</em>.
    </p></dd>

<dt>1 not 2</dt>
<dd><p>This presents all the rows in the first table which
    do <em>not</em> have matches in the second table.
    Consequently, it only contains columns from the first table, since
    all the entries from the second one would be blank in any case.
    </p></dd>

<dt>2 not 1</dt>
<dd><p>The same as <label>1 not 2</label> but the other way round.
    </p></dd>

<dt>1 xor 2</dt>
<dd><p>The "exclusive or" of the match - the output only contains 
    rows from the first table which don't have matches in the second
    table and vice versa.  It is the union of <label>1 not 2</label>
    and <label>2 not 1</label>.
    </p></dd>
    
</dl>
</p>

<p>Note that the choices of which <label>Match Selection</label> and
<label>Join Type</label> to use are somewhat interlinked, and
some combinations may not be very meaningful.
</p>

<p>In most cases
(all the above except for <label>1 not 2</label> and <label>2 not 1</label>),
the set of columns in the output table contains
all the columns from the first table followed by all the columns
from the second table.  If this causes a clash of column names,
offending columns will be renamed with a trailing "<code>_1</code>" or 
"<code>_2</code>".
Depending on the details of the match however,
some additional useful columns may be added:
<dl>
<dt>Match Score</dt>
<dd><p>For rows that represent a match, a numeric value representing
    how good the match was will usually be present.  This is typically
    a separation in real or notional space - for instance for a 
    <label>Sky</label> match it is the distance between the two matched
    celestial positions in arcseconds along a great circle.  It will
    always be greater than or equal to zero, and a smaller value 
    represents a better match.  The name and exact meaning of this
    column depends on the match criteria - examine its description 
    in the <ref id="ColumnInfoWindow">Columns Window</ref> for details.
    </p></dd>

<dt>GroupSize, GroupID</dt>
<dd><p>If some of the rows match more than once
    (which may happen for any of the Match Selection options above
    apart from <label>BEST</label>), two columns named 
    <label>GroupID</label> and <label>GroupSize</label> will be added.
    These allow you to identify which matches are multiple.
    In the case of rows which represent a unique match, they are blank.
    But for rows which represent a set of multiple matches, the 
    GroupSize value tells you how many rows participate in this match,
    and the GroupID value is an integer which is the same for 
    all the rows which participate in the same match.
    So if you do a sort on the GroupID value, you'll see all the rows
    in the first non-unique match group together,
    followed by all the rows in the second non-unique group...
    and after them all the unique matches.
    </p></dd>

</dl>
</p>

<p>Here is an example.  If your input tables are these:
<verbatim>
      X          Y         Vmag
      -          -         ----
   1134.822    599.247     13.8
    659.68    1046.874     17.2
    909.613    543.293      9.3
</verbatim>
and
<verbatim>
     X           Y         Bmag
     -           -         ---- 
   909.523     543.800     10.1
   1832.114    409.567     12.3
   1135.201    600.100     14.6
    702.622   1004.972     19.0
</verbatim>
then a Cartesian match of the two sets of X and Y values with an error of 1.0
using the <label>1 and 2</label> option would give you a result like this:
<verbatim>
     X_1       Y_1         Vmag    X_2        Y_2         Bmag    Separation
     ---       ---         ----    ---        ---         ----    ----------
   1134.822    599.247     13.8   1135.201    600.100     14.6     0.933
    909.613    543.293      9.3    909.523    543.800     10.1     0.515
</verbatim>
using <label>All from 1</label> would give you this:
<verbatim>
     X_1       Y_1         Vmag    X_2        Y_2         Bmag    Separation
     ---       ---         ----    ---        ---         ----    ----------
   1134.822    599.247     13.8    1135.201   600.100     14.6     0.933
    659.68    1046.874     17.2
    909.613    543.293      9.3     909.523   543.800     10.1     0.515
</verbatim>
and <label>1 not 2</label> would give you this:
<verbatim>
     X         Y           Vmag
     -         -           ----
    659.68    1046.874     17.2
</verbatim>
</p>

</subsubsubsect>

</subsubsect>


<subsubsect id="MatchWindow1">
<subhead><title>Internal Match Window</title></subhead>

<figure>
<caption><px>Internal Match Window</px></caption>
<figureimage src="&FIG.MatchWindow1;"/>
</figure>

<p>The Internal Match Window allows you to perform matching between
rows of the same table, grouping rows that have the same or similar 
values in specified columns and producing a new table as a result.
It can be obtained by using the <label>Internal Match</label>
(&IMG.MATCH1;) item in the <ref id="ControlWindow">Control Window</ref>'s
<label>Joins</label> menu.
</p>

<p>You might want to use this functionality to remove all rows which
refer to the same object from an object catalogue, 
or to ensure that only one entry exists for each object,
or to identify groups of several "nearby" objects in some way.
</p>

<p>The result is created from the <ref id="apparent">Apparent</ref>
versions of the tables being joined, so that any row subsets,
hidden columns, or sorts currently in force will be reflected in the
output.
Progress information on the match, which may take some time,
is provided in the logging window and by a progress bar at the bottom
of the window.  When it is completed, you will be informed by a
popup window which indicates that a new table has been created.
This table will be added to the list in the Control Window and can
be examined, manipulated and saved like any other.
</p>

<p>The window has the following parts:
<dl>

<dt><ref id="matchCriteria">Match Criteria box</ref></dt>
<dd><p>Allows you to define what counts as a match between two rows.
    </p></dd>

<dt><ref id="matchColumnSelect">Column Selection box</ref></dt>
<dd><p>Allows you to select which table to operate on and which columns
    supply the matching coordinates.
    </p></dd>

<dt><ref id="matchInternalAction">Match Action box</ref></dt>
<dd><p>Allows you to select what will be done (what new table will be
    created) when the matching groups of rows have been identified.
    </p></dd>

<dt>Log Panel</dt>
<dd><p>Displays progress as the match is taking place.  The progress bar
    at the bottom of the window also provides an indication of how
    far through each stage processing has got.
    </p></dd>

<dt>Control buttons</dt>
<dd><p>The <label>Go</label> button starts the search when you are
    happy with the selections that you have made, and the
    <label>Stop</label> button interrupts it midway if you decide
    you no longer want the results (closing the Match Window also
    interrupts the calculation).
    </p></dd>

</dl>
</p>

<p>For information on the 
<label>Tuning Parameters</label> (&IMG.TUNING;) and
<label>Full Profiling</label> (&IMG.PROFILE;) toolbar buttons,
see <ref id="matchTuning"/>.
</p>


<subsubsubsect id="matchInternalAction">
<subhead><title>Internal Match Action Box</title></subhead>

<figure>
<caption><px>Internal Match Action Box</px></caption>
<figureimage src="&FIG.IntraMatchSpec;"/>
</figure>

<p>The Internal Match Action box gives a list of options for what
will happen when an internal match calculation has completed.
In each case a new table will be
created as a result of the match.  The options for what it will look like
are these:
<dl>

<dt>Mark Groups of Rows</dt>
<dd><p>The result is a table the same as the input table but with two
    additional columns: <label>GroupID</label> and <label>GroupSize</label>.
    Each group of rows which matched is assigned a unique integer,
    recorded in the GroupId column, and the size of each group is
    recorded in the GroupSize column.
    Rows which don't match any others (singles) have null values in
    both these columns.
    So for example by sorting the resulting table
    on GroupID you can group rows that match next to each other;
    or by sorting on GroupSize you can see all the pairs, followed by
    all the triples, ...
    </p>
    <p>You can use this information in other ways, for instance if you
    create a new <ref id="subsets">Row Subset</ref> using the expression
    "<code>GroupSize == 5</code>" you could select only those
    rows which form part of 5-object clusters.
    </p></dd>

<dt>Eliminate All Grouped Rows</dt>
<dd><p>The result is a new table containing only "single" rows, that is
    ones which don't match any other rows in the table according to the
    match criteria.  Any rows which match are thrown out.
    </p></dd>

<dt>Eliminate All But First of Each Group</dt>
<dd><p>The result is a new table in which only one row (the first in the
    input table order) from each group of matching ones is retained.
    A subsequent internal match with the same criteria would therefore
    show no matches.
    </p></dd>

<dt>New Table With Groups of Size N</dt>
<dd><p>The result is a new "wide" table consisting of matched rows in
    the input table stacked next to each other.
    Only groups of exactly N rows in the input table are used to
    form the output table; each row of the output table consists of
    the columns of the first group member, followed by the columns of
    the second group member and so on.  The output table therefore has
    N times as many columns as the input table.
    The column names in the new table have "_1", "_2", ...
    appended to them to avoid duplication.
    </p></dd>

</dl>
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="MatchWindowN">
<subhead><title>Multiple Match Window</title></subhead>

<p>The Multiple Match Window allows you to perform matching between 
more than two tables.
It can be obtained by using the <label>Triple Match</label>,
<label>Quadruple Match</label> etc (&IMG.MATCHN;) items
in the <ref id="ControlWindow">Control Window</ref>'s 
<label>Joins</label> menu.
</p>

<p>The result is created from the <ref id="apparent">Apparent</ref>
versions of the tables being joined, so that any row subsets,
hidden columns, or sorts currently in force will be reflected in the
output.
Progress information on the match, which may take some time,
is provided in the logging window and by a progress bar at the bottom
of the window.  When it is completed, you will be informed by a
popup window which indicates that a new table has been created.
This table will be added to the list in the Control Window and can
be examined, manipulated and saved like any other.
</p>

<p>The window has the following parts:
<dl>

<dt><ref id="matchCriteria">Match Criteria box</ref></dt>
<dd><p>Allows you to define what counts as a match between two rows.
    </p></dd>

<dt><ref id="matchColumnSelect">Column Selection box</ref></dt>
<dd><p>Allows you to select which table to operate on and which columns
    supply the matching coordinates.
    </p></dd>

<dt><ref id="matchNAction">Match Action box</ref></dt>
<dd><p>Allows selection of which rows are to be included in the output table
    (for instance whether only those matches which appear in all input
    tables should result in output rows).
    </p></dd>

<dt>Log window</dt>
<dd><p>Reports on progress as the match is taking place.  The progress bar
    at the bottom of the window also provides an indication of how
    far through each stage processing has got.
    </p></dd>

<dt>Control buttons</dt>
<dd><p>The <label>Go</label> button starts the search when you are
    happy with the selections that you have made, and the
    <label>Stop</label> button interrupts it midway if you decide
    you no longer want the results (closing the Match Window also
    interrupts the calculation).
    </p></dd>

</dl>
</p>

<p>For information on the
<label>Tuning Parameters</label> (&IMG.TUNING;) and
<label>Full Profiling</label> (&IMG.PROFILE;) toolbar buttons,
see <ref id="matchTuning"/>.
</p>


<subsubsubsect id="matchNAction">
<subhead><title>Multiple Match Action Box</title></subhead>

<figure>
<caption><px>Multiple Match Action Box</px></caption>
<figureimage src="&FIG.InterMatchSpec;"/>
</figure>

<p>The Multiple Match Action Box allows you to choose which rows
appear in the output table following a successful multi-table match.
For each input table you have two options to choose from:
<dl>

<dt>Matched Rows Only</dt><!-- MultiJoinType.MATCH -->
<dd><p>Rows will appear in the output table only if they contain an
    entry from the table in question (but see below).
    </p></dd>

<dt>All Rows</dt><!-- MultiJoinType.ALWAYS -->
<dd><p>Rows will appear in the output table if they contain an entry
    from the table in question, regardless of constraints on other
    input tables (overrides the previous option).
    </p></dd>

</dl>
</p>

<p>At present the multi-table options available within TOPCAT are not
so comprehensive as those provided by the corresponding STILTS
command 
<webref url="http://www.starlink.ac.uk/stilts/sun256/tmatchn.html"
        ><code>tmatchn</code></webref>.
This may be improved in future.
</p>

</subsubsubsect>


</subsubsect>


</subsect>

<subsect id="vo-windows">
<subhead><title>VO Data Access Windows</title></subhead>

<p>Several windows in TOPCAT allow access to standard Virtual Observatory
(VO) services.
These share the idea of querying the <em>Registry</em> for suitable
data services, selecting one of the services thus returned, and then
submitting one or more queries to that data service to generate a
tabular result.  
These ideas are explained in more detail in <ref id="vo"/>,
while the current section describes the windows.
The <ref id="vo-windows-common">next subsection</ref> 
describes the components from which these windows are put together.
All the windows contain a <ref id="RegistryPanel">registry query panel</ref>
to select a suitable data access service. 
The positional query windows also contain either a
<ref id="DalQueryLoadDialog">single</ref> or a
<ref id="DalMultiPanel">multiple</ref> search panel,
and the TAP window contains its own custom panel,
to define the actual query or queries to submit to the selected service.
The windows themselves are described in the following subsections.
</p>

<p>TOPCAT also provides access to two important services provided by
the CDS (Centre de Donn&#x00e9;es astronomiques de Strasbourg):
the
<ref id="VizierTableLoadDialog">VizieR Catalogue Service Query</ref> and
<ref id="CdsUploadMatchWindow">CDS X-Match Upload Window</ref>.
These are not strictly speaking Virtual Observatory services,
but since they provide access to the comprehensive VizieR archive
of astronomical tables they can provide similar or superior
functionality to their VO counterparts, so it's worth being aware of them.
</p>

<subsubsect id="vo-windows-common">
<subhead><title>Common Features</title></subhead>

<p>This section describes the graphical components which make up the 
VO data access windows.
</p>

<subsubsubsect id="RegistryPanel">
<subhead><title>Registry Query Panel</title></subhead>

<figure>
<caption><px>Registry Query Panel</px></caption>
<figureimage src="&FIG.RegistryPanel;"/>
</figure>

<p>The Registry Query Panel appears in all VO query windows and 
allows you to search for entries
in <ref id="registry">the Registry</ref> representing data services
of the type appropriate to the window.
Note that if you know the service URL for the service that you want
to use, you don't need to use this panel at all; you can simply 
fill in the URL in the lower part of the window.
</p>

<p>The top part of this panel 
contains the fields you can fill in to query the registry
for services matching your constraints.
This consists of the following parts:
<dl>
<dt>Registry</dt>
<dd><p>This determines the registry that will be queried for
    suitable data services.  You can select from the available options,
    or enter a URL corresponding to some other registry service that 
    you know about.  The default is currently the GAVO registry, which at 
    time of writing usually works pretty well, but other registries may
    have somewhat different data holdings.  Some registries don't work
    very well, so you may have trouble if you use other ones.
    </p>
    <p>To the right of this box is a selector that allows you to choose
    between two registry protocol options: <label>RegTAP</label> and
    <label>RI1.0</label>, corresponding to the IVOA
    <webref url="http://www.ivoa.net/documents/RegTAP/index.html"
            >Relational Registry</webref> and
    <webref url="http://www.ivoa.net/documents/RegistryInterface/"
            >Registry Interface 1.0</webref>
    standards respectively.
    At the time of writing (June 2014), RI1.0
    is being phased out, and RegTAP is recommended.  It is in any case
    considerably faster and more reliable than RI1.0.
    Unless you are a registry enthusiast, sticking to RegTAP is recommended.
    </p>
    <p>The <label>Update Registry List</label> item in the 
    <label>Registry</label> menu queries the currently selected registry
    for other registries, and adds more entries to the selector box
    as appropriate;
    the little round indicator between the URL and protocol selectors
    indicates progress of this query.
    </p></dd>
<dt>Keywords</dt>
<dd><p>Fill this in with keywords appropriate to the services you want to
    find.  The format is space-separated words, and there is no wildcarding.
    So for instance if you want to find services relating to quasars
    in Sloan data you could enter the terms "SDSS QSO".  
    These terms are matched against certain fields of each registry entry
    (as determined by the Match Fields checkboxes below)
    of each registry entry to see if it matches.
    Usually one or two short words is the appropriate level of detail.
    If no keywords are filled in, all the appropriate services are retrieved.
    Some experimentation may be required to specify a query with a reasonable
    number of results; if your query returns no results, try fewer or more
    general terms, and if it returns too many, try more or more specific ones.
    </p></dd>
<dt>And/Or button</dt>
<dd><p>This determines whether a registry entry is considered to match 
    the chosen keywords if it matches all of them, or at least one of them.
    Clicking it toggles between "And" and "Or".
    The default is "And", meaning that all keywords must be matched 
    (against any of the selected match fields) for a selection.
    </p></dd>
<dt>Match Fields</dt>
<dd><p>This line contains a number of checkboxes which allow you to
    define which fields in each registry record will be compared against the
    keywords you have entered when looking for matches.
    The contents of the <label>Short Name</label>, <label>Title</label>,
    <label>Subjects</label>, <label>ID</label> and <label>Publisher</label>
    fields are visible in the table of results.
    <label>Description</label> is a free-form, often long, description of
    the resource; it can be useful, but can often accidentally contain text
    which causes unwanted matches.
    By default the Short Name, Title, Subjects and ID fields are matched - 
    click the checkboxes to change the selection
    </p></dd>
<dt>Submit Query button</dt>
<dd><p>When the other fields have been filled in, hit the Submit button
    and the registry will be searched to find data services that match
    the constraints you have given.
    </p></dd>
</dl>
</p>

<p>In some cases, when the window first appears, it will automatically 
query the registry for all known services of the appropriate type.
This is currently the case for SIA and SSA services, since there is
a manageable number of these.  There are thousands of cone searches
however, so for the cone search windows you need to fill in a query
and submit it yourself.
In either case, you can resubmit a query 
(hit the <label>Cancel Query</label> button first if necessary)
to make another selection of registry entries.
</p>

<p>When the query completes, a table of matching entries is displayed
below the Submit button.  The number of resources found is displayed
at the bottom, labelled <label>Resource Count</label>.
The table contains one row for each matching entry, i.e. each service of
the appropriate type that you can submit your data query to.
The columns in the table give a short name, title, description and
some other information about each service.
You can sort the table rows according to the entries in different
columns by clicking on the column header; click again on the same
header to reverse the sort order.  A little up/down arrow in a 
column header indicates that that column is currently determining
the sort order.  
You can adjust the columns which are visible using the <label>Columns</label>
menu, or drag the columns sideways to change their order in the 
<ref id="JTable">usual way</ref>.
</p>

<p>You should select the service that you want to query for data by clicking
on it.
When this is done, you will see one or more rows appear in a second table
underneath the first one.  In most cases, this contains a single row
which will be automatically selected.
However, some registry entries have multiple data services associated
with a single record - in this case you should select the
appropriate entry from the lower table as well.
</p>

<p>Once you have selected a data service in this way, its service URL
will be entered in the lower part of the window (not shown in the
figure above) and you are ready to perform the actual single or multiple 
data query.
</p>

<p>If a SAMP hub is running (see <ref id="interop"/>),
it is possible to exchange lists of resources
between this window and other applications.
If another application sends a suitable message to TOPCAT, and the
resources are of an appropriate type, and the window is visible at the time,
the received list can be loaded and displayed here,
replacing any which are currently displayed.
You can control whether incoming lists are accepted and displayed in this
way using the <label>Accept Resource Lists</label> toggle,
either using the checkbox just above the resource display panel,
or using the corresponding item in the <label>Interop</label> menu.
If you wish to send your selection to one or more other applications
which can make use of them, use the 
Broadcast Resource List (&IMG.BROADCAST;) or Send Resource List (&IMG.SEND;)
options in the <label>Interop</label> menu.
</p>

</subsubsubsect>

<subsubsubsect id="DalQueryLoadDialog">
<subhead><title>Single Positional Search Panel</title></subhead>

<figure>
<caption><px>Single Positional Search Panel</px></caption>
<figureimage src="&FIG.DalTableLoadDialog;"/>
</figure>

<p>The Single Positional Search Panel appears in VO-based table load dialogues
and is used to specify data queries on a single region of the sky.  
The purpose is to load a new table 
(containing entries representing catalogue entries, images or spectra).
To use it you must fill in the <label>URL</label> field and
the position definition, and then hit the <label>OK</label> button.
</p>

<p>
<dl>
<dt>URL</dt>
<dd><p>This must contain the service URL for the data service that you
    are querying.  Usually, this will be filled in by selecting one
    of the services obtained by the 
    <ref id="RegistryPanel">registry query</ref>.
    However, you can fill it in manually with the URL of a service you
    know about if you prefer.  If you know what you're doing,
    it's also possible to doctor a service URL
    filled in by the registry selection, for instance by adding
    <code>&amp;name=value</code> parameters to it.
    </p></dd>
<dt>Object Name</dt>
<dd><p>You can fill this in with the name of an object to be resolved
    by SIMBAD, and hit the <label>Resolve</label> button, which will
    fill in the coordinates in the RA and Dec fields below.
    If you enter the RA and Dec manually, you don't need to use this field.
    </p></dd>
<dt>RA and Dec</dt>
<dd><p>Fill in the central position in terms of J2000 Right Ascension
    and Declination that you are interested in here.
    You can either do it manually, or by using the <label>Object Name</label>
    field as above.
    Select the units as appropriate.
    </p></dd>
<dt>Radius</dt>
<dd><p>Indicates how large is the region you are interested in.
    This field has slightly different appearance and meaning for the different
    data service types; hover over it with the mouse to see a tooltip with
    the details.  For SIA and SSA, but not for Cone Search, it is permissible
    to leave it blank (though certain services don't seem to like that).
    Select the units as appropriate.
    </p></dd>
</dl>
</p>

<p>When the fields are filled in, hit the <label>OK</label> button and
wait for the new table defined by your query parameters to load.
If you get bored waiting (the service may be down, or just very slow, or you
may have submitted a query with a very large return set),
you can hit the <label>Cancel</label> button,
and perhaps adjust the parameters and try again.
</p>

<p>If a SAMP hub is running (see <ref id="interop"/>),
then other running clients may be able to fill in the RA and Dec
coordinates.  For instance clicking on a sky position in an image
viewing tool might fill in the sky position you clicked on.
Usually this will happen automatically.
This is often convenient, but may not be what you want.
You can control whether incoming coordinate settings are accepted in this way
using the <label>Accept Sky Positions</label> toggle below the
Resolve button, or using the corresponding item in the 
<label>Interop</label> menu.
</p>

</subsubsubsect>

<subsubsubsect id="DalMultiPanel">
<subhead><title>Multiple Positional Search Panel</title></subhead>

<figure>
<caption><px>Multiple Positional Search Panel</px></caption>
<figureimage src="&FIG.DalMultiPanel;"/>
</figure>

<p>The Multiple Positional Search Panel appears in VO-based multiple query
windows which specify a procedure in which
one query is made for each row of an input table.
Each of the input rows defines a (probably small) region on the sky.
The purpose is to find data records (about catalogue entries, images
or spectra) in a remote catalogue corresponding to each row of a
local catalogue.  As such, it is used to define a kind of join, 
of a local <ref id="apparent">Apparent Table</ref>
with a remote one, where the remote one is exposed
via a VO data service.
</p>

<p>To use it you must fill in the <label>URL</label> field to select
the remote service, and 
fields defining how each row of the input table can be turned into
a positional query.  You also need to define what form the result
will be returned in.
These parts are described below.
</p>

<p>The URL field specifies the data service which is to be queried:
<dl>
<dt>URL</dt>
<dd><p>This must contain the service URL for the data service that you
    are querying.  Usually, this will be filled in by selecting one
    of the services obtained by the
    <ref id="RegistryPanel">registry query</ref>.
    However, you can fill it in manually with the URL of a service you
    know about if you prefer.  If you know what you're doing,
    it's also possible to doctor a service URL
    filled in by the registry selection, for instance by adding
    <code>&amp;name=value</code> parameters to it.
    </p></dd>
</dl>
</p>

<p>The following fields define what queries are to be sent to the service:
<dl>
<dt>Input Table</dt>
<dd><p>Select one of the tables loaded into TOPCAT whose row positions
    you want to search around.
    </p></dd>
<dt>RA and Dec columns</dt>
<dd><p>Fill these in with the columns in the input table which contain
    J2000 Right Ascension and Declination
    (you can perform coordinate conversions using the 
    <ref id="SkyColumnQueryWindow">Sky Coordinates Window</ref> if required).
    Select the units as appropriate.
    If the input table has appropriate metadata, the correct values may
    be filled in by default, but it may occasionally guess wrong, so
    it's wise to check that they are filled in correctly.
    </p></dd>
<dt>Search Radius column</dt>
<dd><p>Fill this in with a value that represents the size of search that
    you want to make around each row's position.
    You can either use a constant value, or a column name, or any 
    numeric algebraic expression based on the table (see <ref id="jel"/>).
    Select units as appropriate.
    This field has slightly different appearance and meaning for the different
    data service types; hover over it with the mouse to see a tooltip with
    the details.  For SIA and SSA, but not for Cone Search, it is permissible
    to leave it blank (though certain services don't seem to like that).
    Select the units as appropriate.
    </p></dd>
</dl>
</p>

<p>The Output Mode selector indicates what will be done with the result.
<dl>
<dt>Output Mode</dt>
<dd><p>When the queries have been performed, there are different ways that
    the results can be returned.  Since the operation here is basically
    a crossmatch between a local table and a remote one, this effectively
    describes what sort of join is to be done.
    The options are as follows:
    <dl>
    <dt>New joined table with best matches</dt>
    <dd><p>A new table will be generated, containing one row for each 
        row in the input table which returned at least one search result
        from the remote table.  The best (closest) match will be included;
        any others will be discarded.
        The new table will have all the columns of the input table 
        and all the columns returned by the data service.
        </p></dd>
    <dt>New joined table with all matches</dt>
    <dd><p>A new table will be generated, containing one row for each 
        search result returned.  Rows from the input table will be duplicated
        where more than one search result was returned corresponding to
        that row.
        The new table will have all the columns of the input table 
        and all the columns returned by the data service.
        </p></dd>
    <dt>New joined table, one row per input row</dt>
    <dd><p>A new table will be generated containing the same number of rows
        as the input table.  If any search results were returned for each row,
        the best (closest) one is included.  Any others will be discarded,
        and cells will be empty for rows with no search results.
        The new table will have all the columns of the input table 
        and all the columns returned by the data service.
        </p></dd>
    <dt>Add subset for matched rows</dt>
    <dd><p>No new table will be generated, but a new subset will be added
        to the table which includes only those rows which returned at
        least one search result.
        </p></dd>
    </dl>
    </p></dd>
</dl>
</p>

<p>The final controls adjust the details of how the individual queries
are submitted to the remote service.
<dl>
<dt>Parallelism</dt>
<dd><p>Controls how many cone search queries are running at once.
    By making several queries to the service concurrently, the time it
    takes to fill in the whole table can be much quicker than making the
    query for the first row, waiting for the result, making the query for
    the second row, etc.  The value here is approximately how many 
    queries will be run at the same time.  Increasing the value might
    make your multiple query run faster; or it might overload the server
    and make you unpopular with the service administrator, or result in
    your query taking longer or failing altogether, or both.
    The default value of 5 is probably reasonable, but experiment with
    adjusting it if you want.
    </p></dd>
<dt>Error Handling</dt>
<dd><p>Determines what happens if one of the queries fails with an error.
    The options are:
    <dl>
    <dt>abort</dt>
    <dd><p>terminate the operation; the whole multiple search fails</p></dd>
    <dt>ignore</dt>
    <dd><p>treat a failed query the same as one which returns zero rows</p></dd>
    <dt>retry N times</dt>
    <dd><p>try N times to get a non-fail result</p></dd>
    <dt>retry indefinitely</dt>
    <dd><p>keep trying for a non-fail result</p></dd>
    </dl>
    The best setting for this depends on the way the service is set up;
    the default is <label>abort</label>, but 
    for unreliable or poorly implemented services it may be better to 
    continue operation in the face of a few failures.
    </p></dd>
</dl>
</p>

<p>When all of the fields are filled in (defaults can be used for many
of them), hit the <label>Go</label> button, and the search will commence.
It may be quite slow; a progress bar is shown at the bottom of the window.
When it completes, a popup window summarising the result will be shown.
If you get bored waiting, you can hit the <label>Cancel</label> button,
and perhaps adjust the parameters and try again.
</p>

</subsubsubsect>

</subsubsect>

<subsubsect id="ConeSearchDialog">
<subhead><title>Cone Search</title></subhead>

<figure>
<caption><px>Cone table load dialogue</px></caption>
<figureimage src="&FIG.ConeSearchDialog;"/>
</figure>

<p>The cone search load dialogue can be opened using the 
<label>Cone Search</label> button
(&IMG.CONE_DIALOG;) from the Load Window's toolbar or the Control Window's
<label>VO</label> menu.
It allows you to query one of a number of external web services for
objects from a given catalogue in a given region of the sky.
Data held by cone search services are effectively source catalogues
with sky position columns.
</p>

<p>The window consists of a
<ref id="RegistryPanel">Registry Query Panel</ref> at the top, and a
<ref id="DalQueryLoadDialog">Single Positional Search Panel</ref> below.
</p>

</subsubsect>

<subsubsect id="SiapTableLoadDialog">
<subhead><title>Simple Image Access (SIA) Query</title></subhead>

<figure>
<caption><px>SIA query load dialog</px></caption>
<figureimage src="&FIG.SiapTableLoadDialog;"/>
</figure>

<p>The SIA query load dialogue can be opened using the 
<label>SIA Query</label> button (&IMG.SIAP_DIALOG;) 
from the Load Window's toolbar or the Control Window's
<label>VO</label> menu.
It allows you to query one of a number of external web services for
images covering a given region of the sky.
</p>

<p>The window consists of a
<ref id="RegistryPanel">Registry Query Panel</ref> at the top, and a
<ref id="DalQueryLoadDialog">Single Positional Search Panel</ref> below.
The <label>Angular Size</label> may be set to zero; this means that
any image covering the chosen position will be selected.
There is additionally an <label>Image Format</label> selector which
allows you to restrict the result to contain only images in certain
formats (the default is set to only FITS).
</p>

<p>The result of a successful query 
is a table in which each row represents an image that
can be downloaded from a remote site; one of the columns contains
the image URL, and the other columns contain associated metadata
such as image format, size, shape and so on.
Different services provide different kinds of answer to these queries;
some may have a static list of observed or reduced FITS files, and others
may generate images on the fly.
See the 
<webref url="http://www.ivoa.net/Documents/latest/SIA.html">SIA</webref>
standard, and individual registry records, for details.
A useful thing to do with the resulting table might be to set its
Activation Action to the <label>View URL as Image</label> option
using the <ref id="ActivationQueryWindow">Activation Window</ref>.
</p>

</subsubsect>

<subsubsect id="SsapTableLoadDialog">
<subhead><title>Simple Spectral Access (SSA) Query</title></subhead>

<figure>
<caption><px>SSA query load dialog</px></caption>
<figureimage src="&FIG.SsapTableLoadDialog;"/>
</figure>

<p>The SSA query load dialogue can be opened using the 
<label>SSA Query</label> button (&IMG.SSAP_DIALOG;)
from the Load Window's toolbar or the Control Window's
<label>VO</label> menu.
It allows you to query one of a number of external web services for
spectra in a given region of the sky.
</p>

<p>The window consists of a
<ref id="RegistryPanel">Registry Query Panel</ref> at the top, and a
<ref id="DalQueryLoadDialog">Single Positional Search Panel</ref> below.
The SSA specification says that the <label>Diameter</label> field
may be left blank, in which case the service "should supply a default 
value intended to find nearby objects".
However, experience shows that this doesn't always work, so it may be
best to fill this in.
There is additionally a <label>Spectrum Format</label> selector which
allows you to restrict the result to contain only spectra in certain
formats.  By default, the service chooses which formats to return.
</p>

<p>The result of a successful query
is a table in which each row represents a spectrum that can be 
downloaded from a remote site; one of the columns contains
the spectrum download URL, and the other columns contain associated metadata
such as spectrum format, WCS, provenance information and so on.
See the 
<webref url="http://www.ivoa.net/Documents/latest/SSA.html">SSA</webref>
standard for details.
A useful thing to do with the resulting table might be to set its
Activation Action to the <label>View URL as Spectrum</label> option
using the <ref id="ActivationQueryWindow">Activation Window</ref>.
</p>

</subsubsect>

<subsubsect id="ConeMultiWindow">
<subhead><title>Multiple Cone Search</title></subhead>

<figure>
<caption><px>Multiple cone search window</px></caption>
<figureimage src="&FIG.ConeMultiWindow;"/>
</figure>

<p>The multiple cone search window can be opened using the 
<label>Multicone</label> button (&IMG.MULTICONE;) 
in the Control Window's toolbar, or its
<label>VO</label> or <label>Joins</label> menus.
It allows you to select one of a number of external web services which
provide remote catalogue queries, and execute a query for each row
of an input table.
This effectively allows you to perform a positional crossmatch between a 
local table and a remote one.
</p>

<p>The window consists of a
<ref id="RegistryPanel">Registry Query Panel</ref> at the top, and a
<ref id="DalMultiPanel">Multiple Positional Search Panel</ref> below.
</p>

<p>The search panel includes a <label>Verbosity</label> selector as well 
as the normal features: this allows you to choose options for how many columns
will appear in the output table, from 1 (minimum) to 3 (maximum).
Some services will take notice of this parameter and return narrower
or wider tables respectively, and others will ignore it.
</p>

<p>The following item is available in the toolbar and <label>Search</label>
menu:
<dl>
<dt>&IMG.FOOTPRINT; Use Service Coverage</dt>
<dd><p>If this option is selected, then the search attempts to query
    the service for the sky coverage it represents, if that information
    is available.  Then it only dispatches queries for positions in the
    input table which fall within that coverage region, since any
    queries outside that region are bound to return an empty result.
    Depending on the coverage, this can substantially reduce the number
    of queries made, and hence the time taken.  If there is no overlap
    between the input table and service coverage, the query is bound to
    return no results at all, and the time will be reduced effectively
    to zero.
    </p>

    <p>When in operation (i.e. when this option is selected and the
    service provides coverage information) the coverage of the
    service, input table and their overlap is summarised with small
    (Mollweide equatorial) all-sky icons
    in blue, red and magenta respectively, as in the
    screenshot above.  This makes it easy to see the sky regions in
    which results may be obtained, and also the amount by which
    this option reduces useless queries.
    </p>

    <p>Currently, this option effectively works only for cone searches
    provided by CDS's VizieR service (publisher "CDS")
    which provide coverage information using Multi-Order Coverage maps (MOCs).
    For non-VizieR services this option has no effect.
    </p></dd>
</dl>
</p>

</subsubsect>

<subsubsect id="SiaMultiWindow">
<subhead><title>Multiple SIA Query</title></subhead>

<figure>
<caption><px>Multiple SIA window</px></caption>
<figureimage src="&FIG.SiaMultiWindow;"/>
</figure>

<p>The multiple Simple Image Access window can be opened using the 
<label>Multiple SIA</label> button (&IMG.MULTISIA;) from the Control Window's 
<label>VO</label> or <label>Joins</label> menus.
It allows you to select one of a number of external web services which
provide queries on remotely accessible image holdings, and execute
a query for each row of an input table.
</p>

<p>The window consists of a
<ref id="RegistryPanel">Registry Query Panel</ref> at the top, and a
<ref id="DalMultiPanel">Multiple Positional Search Panel</ref> below.
The <label>Search Radius column</label> may be set to zero; this means that
any image covering the chosen position will be selected.
There is additionally an <label>Image Format</label> selector which
allows you to restrict the result to contain only images in certain
formats (the default is set to only FITS).
</p>

<p>The result of each single successful query
is a table in which each row represents an image that
can be downloaded from a remote site; one of the columns contains
the image URL, and the other columns contain associated metadata
such as image format, size, shape and so on.
Different services provide different kinds of answer to these queries;
some may have a static list of observed or reduced FITS files, and others
may generate images on the fly.
See the 
<webref url="http://www.ivoa.net/Documents/latest/SIA.html">SIA</webref>
standard, and individual registry records, for details.
</p>

<p>Note that some services return multiple images at the same positions
but at different wavelengths.  In this case TOPCAT's criterion for
the "best" match (the one closest to the central query position)
may not make much sense.  For this reason, take care if using the
"New joined table with best matches" or 
"New joined table, one row per input row" output modes.
</p>

<p>One use of this function is to add some columns to an existing table which 
contain URLs of images from a given server corresponding to the
sky positions of those rows.
Having done this you might want to set the resulting table's
Activation Action to the <label>View URL as Image</label> option
using the <ref id="ActivationQueryWindow">Activation Window</ref>.
</p>

</subsubsect>


<subsubsect id="SsaMultiWindow">
<subhead><title>Multiple SSA Query</title></subhead>

<figure>
<caption><px>Multiple SSA window</px></caption>
<figureimage src="&FIG.SsaMultiWindow;"/>
</figure>

<p>The multiple Simple Spectral Access window can be opened using the
<label>Multiple SSA</label> button (&IMG.MULTISSA;) from the Control Window's
<label>VO</label> or <label>Joins</label> menus.
It allows you to select one of a number of external web services which
provide queries on remotely accessible spectral data holdings, and execute
a query for each row of an input table.
</p>

<p>The window consists of a
<ref id="RegistryPanel">Registry Query Panel</ref> at the top, and a
<ref id="DalMultiPanel">Multiple Positional Search Panel</ref> below.
The SSA specification says that the <label>Search Radius</label> column
may be left blank, in which case the service "should supply a default
value intended to find nearby objects".
However, experience shows that this doesn't always work so it may be
best to fill this in.
There is additionally a <label>Spectrum Format</label> selector which
allows you to restrict the result to contain only spectra in certain
formats.  By default, the service chooses which formats to return.
</p>

<p>The result of each single successful query
is a table in which each row represents a spectrum that
can be downloaded from a remote site; one of the columns contains
the specturm URL, and the other columns contain associated metadata
such as spectrum format, WCS, provenance information and so on.
See the
<webref url="http://www.ivoa.net/Documents/latest/SSA.html">SSA</webref>
standard for details.
</p>

<p>One use of this function is to add some columns to an existing table which
contain URLs of spectra from a given server corresponding to the
sky positions of those rows.
Having done this you might want to set the resulting table's
Activation Action to the <label>View URL as Spectrum</label> option
using the <ref id="ActivationQueryWindow">Activation Window</ref>.
</p>

</subsubsect>

<subsubsect id="TapTableLoadDialog">
<subhead><title>Table Access Protocol (TAP) Query</title></subhead>

<figure>
<caption><px>Table Access Protocol Window</px></caption>
<figureimage src="&FIG.TapTableLoadDialog;"/>
</figure>

<p>The Table Access Protocol (TAP) load window can be opened using the
<label>TAP Query</label> button (&IMG.TAP_DIALOG;)
in the Control Window's toolbar or <label>VO</label> menu,
or the Load Window's toolbar.
It allows you to use the TAP protocol to
make freeform queries of remote database services 
using an SQL-like language.
This is a powerful capability, giving you full access to
remote data holdings; it's similar to systems like SDSS's
<webref url="http://cas.sdss.org/CasJobs/">CasJobs</webref>,
but using the IVOA-endorsed TAP standard means that you can use
the same interface for many different remote datasets.
</p>

<p>TAP is more involved than the other VO protocols implemented by TOPCAT,
and this window is correspondingly more complicated than the Cone, SIA
and SSA dialogues, though it does share some features with them.
</p>

<p>In order to interrogate the remote database you will have to
write queries in Astronomical Data Query Language (ADQL).
This is a powerful tool, but to do complicated things in it 
is not trivial.  ADQL is essentially a particular dialect of SQL,
so if you know SQL already, you should be able to write ADQL queries.
If you have used systems like SDSS's CasJobs, the concept
should be quite familiar.
A tutorial on writing ADQL/SQL is beyond the scope of this manual,
but the <ref id="TapTableLoadDialog_query">Enter Query</ref> tab
provides an <label>Examples</label> menu which
will give you a good start in using it.
You can find a nice introduction written by Markus Demleitner of GAVO
at <webref url="http://docs.g-vo.org/adql"/>.
</p>

<p>Once your query is written, you can submit it in either
<em>synchronous</em> or <em>asynchronous</em> mode.
Synchronous queries begin to execute right away and must be relatively short;
asynchronous queries are submitted to a server, run for a potentially 
long time, and retrieve the result later.
</p>

<p>The window is composed of four tabs, of which you can see one at a time.
You will use two or three of them when submitting a TAP query.
Each tab is described in more detail in the following subsections,
but an overview of their operation is like this:
<dl>
<dt><ref id="TapTableLoadDialog_service">Select Service</ref> tab</dt>
<dd><p>Chooses the TAP service you wish to query, either using a registry
    search or by entering the service URL directly.
    Once you have chosen a service you can move to the
    <label>Enter Query</label> tab.
    </p></dd>
<dt><ref id="TapTableLoadDialog_query">Enter Query</ref> tab</dt>
<dd><p>Displays information about the service and the tables it holds,
    and allows you to enter the text of the query and submit the job.
    If the job is submitted synchronously, load will begin directly,
    but in the asynchronous case, you will move to the
    <label>Running Jobs</label> tab.
    </p></dd>
<dt><ref id="TapTableLoadDialog_jobs">Running Jobs</ref> tab</dt>
<dd><p>Shows a list of the asynchronous query jobs you have submitted,
    with details on their progress.
    </p></dd>
<dt><ref id="TapTableLoadDialog_resume">Resume Job</ref> tab</dt>
<dd><p>Optionally allows you to resume an asynchronous query
    started in some earlier session.
    </p></dd>
</dl>
</p>

<p>When you first visit this window, the <label>Select Service</label>
tab will be visible, and when an asynchronous query has been submitted the
<label>Running Jobs</label> tab will be visible.
If you want to submit another query to the same service,
or use a different service,
just select <label>Enter Query</label> or 
<label>Select Service</label> respectively,
by clicking on the appropriate tab at the top.
</p>

<p>This window offers one menu additional to the standard
<ref id="RegistryPanel">VO windows</ref> menus:
<dl>
<dt>Deletion menu</dt>
<dd><p>Allows you to choose when asynchronously submitted jobs will
    by default be
    deleted from the server.  Once they are deleted they will no longer
    be visible in the <label>Running Jobs</label> tab.  If they are not
    deleted in this way, they will stay on the server until they are
    deleted according to the server's deletion policy.  Choose one of
    the available options:
    <ul>
    <li><strong>On Completion:</strong>
        deleted when it has completed with either success or error status
        </li>
    <li><strong>On Exit:</strong>
        deleted when TOPCAT shuts down
        </li>
    <li><strong>Never:</strong>
        not deleted (except according to server policy)
        </li>
    </ul>
    You can override these settings once a job has started
    by using the controls at the bottom of the 
    <ref id="TapTableLoadDialog_jobs">running jobs</ref> tab.
    The settings in this menu affect the default value of the
    <label>Delete On Exit</label> checkbox.
    If you want to <ref id="TapTableLoadDialog_resume">resume</ref>
    the job in a later session, you'll have to make sure that the
    job is not deleted on completion or exit.
    </p></dd>
</dl>
</p>

<p>The additional menu items are:
<dl>
<dt>&IMG.KEEP_OPEN;: Stay Open</dt>
<dd><p>Makes sure that the window is not automatically closed after it
    loads a table.
    </p></dd>
<dt>&IMG.REDO;: Reload</dt>
<dd><p>Reloads information displayed in the window from the server.
    This may be updating job status information or reloading table
    or service metadata; the exact behaviour depends on which tab
    is currently visible.
    </p></dd>
</dl>
</p>

<p><strong>Note:</strong> The TAP dialogue has been introduced at version
3.8 of TOPCAT, at a time
when most available TAP services are quite new and may not fully conform
to the standard, and usage patterns are still settling down.
For this reason you may find that some TAP services visible do not
behave quite as expected; it is also possible that in future versions
the user interface will change in line with changing service profiles
or in the light of user experience.
</p>

<subsubsubsect id="TapTableLoadDialog_service">
<subhead><title>Select Service tab</title></subhead>

<figure>
<caption><px>TAP window with Select Service tab visible</px></caption>
<figureimage src="&FIG.TapTableLoadDialog_service;"/>
</figure>

<p>The <label>Select Service</label> tab of the TAP load dialogue
allows you to choose which TAP service you wish to query.
You need to do this before submitting a new TAP query.
This tab is essentially the same as the 
<ref id="RegistryPanel">Registry Query Panel</ref> of the other
VO query windows.
Having queried the registry, click on one of the rows to enter its
service URL in the <label>TAP URL</label> field at the bottom.
</p>

<p>If you know the URL of the TAP service you wish to query, you can
enter it directly into the <label>TAP URL</label> field without a 
registry search.
</p>

<p>At time of writing, there are only a couple of dozen TAP services 
registered, and it is feasible to query the registry for them all,
by clicking the <label>Submit Query</label> button without entering
any search terms.
Note however that for technical reasons (the registry records for 
some of these services are large) the search can take a while
(typically 30sec on a fast link).
</p>

<p>Once a service URL has been chosen in one of these ways, you can
click the <label>Enter Query</label> button at the bottom 
(or equivalently the tab header at the top), 
and you will be moved to the
<ref id="TapTableLoadDialog_query">Enter Query</ref> tab.
</p>

</subsubsubsect>

<subsubsubsect id="TapTableLoadDialog_query">
<subhead><title>Enter Query tab</title></subhead>

<figure>
<caption><px>TAP window with Enter Query tab visible</px></caption>
<figureimage src="&FIG.TapTableLoadDialog_query;"/>
</figure>

<p>The <label>Enter Query</label> tab of the TAP load dialogue
displays information about the service you have selected to query,
principally what tables are available and what columns they have,
and allows you to enter the query text and some additional options
about how the query is to be executed.
The panel has three parts: 
<label>Table Metadata</label>,
<label>Service Capabilities</label>, and
<label>ADQL Text</label>.
</p>

<p>The <label>Table Metadata</label> panel displays information about
the tables held by the selected service.
When the panel is first displayed the service is contacted to obtain
this information, and a progress bar will appear until it has arrived.
If the service does not provide it in an appropriate form, nothing
can be shown; it's still possible to submit a query, but you'll need
some other way of knowing what tables and columns are available.
Once the metadata has loaded, the following information will be
available:
<dl>
<dt>Service</dt>
<dd><p>The service URL selected in the Select Service tab.
    It also notes the number of tables available from this service.
    </p></dd>
<dt>Table</dt>
<dd><p>This selector contains an entry for each table contained in the
    remote database.  There may be just one, or there may be hundreds.
    When you select one, information about it is displayed below.
    An expanded title or description may also be displayed next to the
    selector - hovering over this description with the mouse 
    may provide further detail in a tool tip.
    </p></dd>
<dt>Columns</dt>
<dd><p>Tabulates metadata about each of the columns in the remote
    table selected in the Table selector above.
    Column names, types, descriptions, UCDs etc are shown.
    Columns which are known to be indexed within the remote database
    have the "Indexed" column ticked; this may help to to formulate
    efficient queries.
    </p></dd>
<dt>Foreign Keys</dt>
<dd><p>If the service provides information about foreign keys
    (links between fields in different tables in the database)
    they will be tabulated here.  They may help you to formulate
    efficient queries.
    </p></dd>
</dl>
</p>

<p>The <label>Service Capabilities</label> panel shows capability
metadata that the service provides about itself; again, this has to
be loaded from the server and may not appear immediately.
It contains the following information:
<dl>
<dt>Query Language</dt>
<dd><p>Shows what query languages, and what versions, are available.
    If there is more than one listed, you can choose which language
    you want to submit your query in, but if you choose something
    which is not a variant of ADQL it may not work.
    </p></dd>
<dt>Max Rows</dt>
<dd><p>Selector which shows the maximum number of output rows 
    that the service is
    willing to deliver as the result of a query under normal circumstances.
    Entries in this list value may be marked "(default)" or "(max)".
    You can change this value by typing in a different number, as long as
    it does not exceed the server's maximum.
    This value is here to protect the user, as well as the service, from
    inadvertently requesting an unduly large output table.
    Note that if the construction "<code>TOP nnn</code>" is used in the ADQL,
    the <code>nnn</code> limit may override the value supplied here.
    </p></dd>
<dt>Uploads</dt>
<dd><p>Indicates if table uploads are permitted, and perhaps what is the
    largest upload size (in terms of rows and/or bytes) which will be
    accepted.
    See below for more about table uploads.
    </p></dd>
</dl>
</p>

<p>The <label>ADQL Text</label> panel is where you can enter the actual
query text for the request.
It has the following parts:
<dl>
<dt>Synchronous checkbox</dt>
<dd><p>Determines whether your job will be executed on the server in
    synchronous or asychronous mode (check the box for synchronous).
    Synchronous means that TOPCAT sends the query to the server and
    waits for the result as the response of the same HTTP request.
    It's simpler and faster, but if the job takes a long time,
    the request may time out and the results be lost.
    In asynchronous mode TOPCAT sends the query to the server and gets
    a message back telling it where to look for information about the
    job's progress; TOPCAT then keeps polling the server to find out 
    when it has completed.
    Synchronous is suitable for short jobs (it may typically execute
    with a few seconds less delay), but for longer jobs aysnchronous is
    more reliable.  It is possible to submit an asynchronous job
    on one day from one machine, and pick up the results on a different
    day from another machine, using another invocation of TOPCAT or of
    a different application altogther.
    </p></dd>
<dt>Examples button</dt>
<dd><p>This button presents you with a short menu of example queries.
    These are tailored to the table metadata obtained for this service,
    and, where appropriate, to the table currently selected by the
    Table selector and/or the table list in the Control Window,
    so they should in most cases be runnable as they stand
    (though there is no guarantee they will produce useful results).
    A better idea though is to use them as starting points for your
    own queries.  By picking one which is something like what you want
    to do, you can hopefully work out the syntax for the query you need
    without having to read the ADQL specification.
    Some of the options in the list may be disabled,
    depending on what capabilities the service has declared.
    In some cases, especially ones using geometric functions, the
    service may reject the example, since TOPCAT can't always tell
    which functions are supported by the server.
    </p></dd>
<dt>Clear button</dt>
<dd><p>Clicking this button clears any text currently shown in the
    text entry field.
    </p></dd>
<dt>Parse Errors button</dt>
<dd><p>If a syntax error is detected in the entered ADQL text, it
    will be highlighted in the text field, and this button will be
    enabled.  Clicking this button will show a popup window with 
    more detail on the error.
    </p></dd>
<dt>Text entry field</dt>
<dd><p>This is where you enter the text of the ADQL query you wish to make.
    The syntax of ADQL (Astronomical Data Query Language) is defined by an
    <webref url="http://www.ivoa.net/Documents/latest/ADQL.html"
            >IVOA Recommendation</webref>;
    it is effectively a dialect of SQL, but a good way to write a query
    is to start with one of the examples from the <label>Examples</label>
    button above.
    If any errors are detected in the syntax of the ADQL as entered,
    they are highlighted in pink as in the figure above.
    </p></dd>
</dl>
</p>

<p>Some services permit <label>Table Uploads</label>
(at time of writing only the GAVO service implements this capability,
but hopefully more will do so in future).
What this means is that you can upload tables from TOPCAT into the
remote database and perform queries on your table directly.
In this way you can perform joins between your own tables
(anything loaded into TOPCAT) and any of the tables in the remote
database.  This is extremely powerful feature.
To take advantage of it, you just need to use a special form for
the table name to reference a TOPCAT-based table:
you write "<code>TAP_UPLOAD.t&lt;n&gt;</code>", where
<code>&lt;n&gt;</code> is the ID number of the table in TOPCAT,
that is the number before the colon in the 
<ref id="ControlWindow">Control Window</ref> Table List.
So, if a table identified as "<code>1: messier.xml</code>"
in the table list, you can reference it in ADQL as
"<code>TAP_UPLOAD.t1</code>".
Note the table uploaded in this way is the 
<ref id="apparent">Apparent Table</ref> corresponding to the
given ID number.
</p>

<p>As you enter the query text, it will be checked for syntax errors.
If an error is found, the place in the text which appears to have caused it
will be highlighted in pink (as in the figure above).
To see more detail on the error, click the <label>Parse Errors</label> button.
The checking itself is reasonably reliable, but the position of the
highlighted error, and the text of the error message, can sometimes
be a bit misleading, so don't take the details too seriously.
The error highlighting is just used as a warning, you are not prevented
from submitting a query marked as erroneous, since
in some cases TAP services may accept ADQL which is not strictly correct,
and in some cases the error checking may not be perfect.
</p>

<p>Having entered suitable query text,
click the <label>OK</label> button at the bottom of the window
to submit the job.  When you do this, one of two things will happen.
In synchronous mode, the <ref id="LoadWindow">Load Window</ref> will appear,
and the progress will indicate when loading is complete in the normal way.
In asynchronous mode, you will be taken to the
<ref id="TapTableLoadDialog_jobs">Running Jobs</ref> tab
where you can see the progress of your submitted job.
</p>


</subsubsubsect>

<subsubsubsect id="TapTableLoadDialog_jobs">
<subhead><title>Running Jobs tab</title></subhead>

<figure>
<caption><px>TAP window with Running Jobs tab visible</px></caption>
<figureimage src="&FIG.TapTableLoadDialog_jobs;"/>
</figure>

<p>The <label>Running Jobs</label> tab of the TAP load dialogue
shows a list of the asynchronous jobs you have submitted,
with information about their current progress.
</p>

<p>The upper part of the screen shows a list of the jobs submitted,
along with a one-word summary of their status (their <em>Phase</em>).
If one of these jobs is selected, its details will be shown in the 
lower part.  By default the most recently submitted job will be shown,
but you can select a job by clicking on it.
</p>

<p>The information displayed is retrieved from the server, and
can only be seen as long as the job has not been deleted,
either by you the user, or as a result of server policy
(for instance a maximum job lifetime).
The following items, if provided by the service, are shown:
<dl>
<dt>URL</dt>
<dd><p>The URL at which the job information is held on the server.
    This value can be used later in the 
    <ref id="TapTableLoadDialog_resume">Resume Job</ref> tab,
    or entered directly into a web browser to see job information.
    </p></dd>
<dt>Phase</dt>
<dd><p>The current stage of job processing.
    This usually progresses in the sequence QUEUED, EXECUTING, COMPLETED
    (or ERROR).
    </p></dd>
<dt>Job ID</dt>
<dd><p>Job identifier, unique to the server.   Forms part of the URL.
    </p></dd>
<dt>Run ID</dt>
<dd><p>Run identifier, often blank.
    </p></dd>
<dt>Owner Id</dt>
<dd><p>Owner identifier, blank unless user authentication is in use.
    </p></dd>
<dt>Max Duration</dt>
<dd><p>The maximum amount of time in seconds that the server will allow
    the job to run for.  This is "wall-clock" time rather than CPU time.
    </p></dd>
<dt>Start Time</dt>
<dd><p>Time at which actual processing of the job (as opposed to queuing)
    started.
    </p></dd>
<dt>End Time</dt>
<dd><p>Time at which processing of the job finished.
    </p></dd>
<dt>Destruction Time</dt>
<dd><p>Time in the future at which the server will delete the job,
    if it has not been manually removed by then.
    </p></dd>
<dt>Error</dt>
<dd><p>Message and possibly other information about error status if an
    error occurred during processing.  This will normally be blank
    unless <label>Phase</label> has the value "ERROR".
    </p></dd>
<dt>Parameters</dt>
<dd><p>Displays parameters which were supplied to define the job to the server.
    This will normally include the text of the ADQL being executed.
    </p></dd>
</dl>
You can cut and paste from these items, so for instance if you 
want to take the URL and paste it into a web browser you can do.
</p>

<p>There are three buttons at the bottom of the screen which affect the
status of the currently displayed job:
<dl>
<dt>Abort</dt>
<dd><p>This button stops the job from executing.  It cannot be restarted.
    The job still exists on the server however, so it can be examined
    in this window.
    </p></dd>
<dt>Delete</dt>
<dd><p>This button stops the job as for Abort, but also removes all trace of it
    from the server.  No details can be seen any more.
    </p></dd>
<dt>Delete On Exit</dt>
<dd><p>This checkbox determines whether the job will be deleted from the server
    when TOPCAT exits.  If you want to come back to a long-running job
    in a later session, you should uncheck this so that the job
    remains on the server.
    The default action is normally that jobs are deleted on exit
    (i.e. this box starts off checked), but you can change the default
    by using the <label>Deletion</label> menu.
    </p></dd>
</dl>
</p>

<p>If no jobs are currently visible (none have been submitted or they
have all been deleted), this tab is inaccessible.
</p>

</subsubsubsect>

<subsubsubsect id="TapTableLoadDialog_resume">
<subhead><title>Resume Job tab</title></subhead>

<figure>
<caption><px>TAP window with Resume Job tab visible</px></caption>
<figureimage src="&FIG.TapTableLoadDialog_resume;"/>
</figure>

<p>The <label>Resume Job</label> tab of the TAP load dialogue
allows you to continue execution of an asynchronous job which was started
outside of this run of TOPCAT, either during an earlier TOPCAT run,
or using some other mechanism.
This may be useful if you have submitted a long-running job
on an earlier day or on a different machine and want to monitor
its progress or pick up the results.
</p>

<p>To use it, enter the Job URL into the <label>URL</label> field
at the top and click the <label>View</label> button.
If a job with that URL exists, its details will be displayed 
in the panel below, in the same format as for the 
<ref id="TapTableLoadDialog_jobs">Running Jobs</ref> tab.
</p>

<p>Depending on whether the job has completed or not, either the
<label>Resume</label> or <label>Load Result</label> button at the
bottom of the window will be enabled.
You can click the appropriate one either to monitor its progress
further or to pick up the completed result.
</p>

</subsubsubsect>

</subsubsect>

</subsect>


<subsect>
<subhead><title>Other Windows</title></subhead>

<subsubsect id="CdsUploadMatchWindow">
<subhead><title>CDS Upload X-Match Window</title></subhead>

<figure>
<caption><px>CDS Upload X-Match Window</px></caption>
<figureimage src="&FIG.CdsUploadMatchWindow;"/>
</figure>

<p>The CDS Upload X-Match Window allows you to join a local table
with any table provided by the 
<webref url="http://vizier.u-strasbg.fr/">VizieR</webref>
database of astronomical tables or with
<webref url="http://simbad.u-strasbg.fr/">SIMBAD</webref>.
You can access the window from the main
<ref id="ControlWindow">Control Window</ref> using the
<label>CDS Upload Match</label> button (&IMG.CDSXMATCH;)
in the toolbar, or the <label>Joins</label> or <label>VO</label> menus.
This window is an interface to the excellent
<webref url="http://cdsxmatch.u-strasbg.fr/">CDS X-Match service</webref>
provided by the Centre de Donn&#x00e9;es astronomiques de Strasbourg
(<webref url="http://cds.u-strasbg.fr">CDS</webref>).
The service is very fast, and in most cases it is the best way to
match a local table against a large external table hosted by a service.
In particular, it is almost certainly much better than using
the <ref id="ConeMultiWindow">Multi-Cone</ref> window,
though it's less flexible than <ref id="TapTableLoadDialog">TAP</ref>.
</p>

<p>The local table is uploaded to the X-Match service in blocks,
and the matches for each block are retrieved in turn and eventually
stitched together to form the final result.
The tool only uploads sky position and an identifier for each row of
the input table, but all columns of the input table are reinstated
in the result for reference.  These details are mostly transparent
when using the service, though it may help to understand how the progress
bar moves.
</p>

<p>The window has three panels, described below.
</p>

<p>The <label>Remote Table</label> panel allows you to select the
CDS table against which to match.
The table must be entered by name in the <label>VizieR Table ID/Alias</label>
field, and may be in one of the following forms:
<ul>
<li>"simbad", to indicate the 
    <webref url="http://simbad.u-strasbg.fr/simbad/">SIMBAD database</webref>
    of known astronomical objects.
    </li>
<li>A VizieR table identifier, for instance "II/246/out".
    <em>Note</em> these must name the table not just the catalogue
    (which may contain several tables), so for instance "II/246" will not work.
    No help is currently provided in this window to search for these IDs,
    you have to use one of the services or web pages provide by CDS to
    locate them.
    A good tip is the table searching facility at the TAPVizieR service,
    <webref url="http://tapvizier.u-strasbg.fr/adql/"/>.
    </li>
<li>A VizieR table alias, for instance "2mass".
    A few tens of these are defined for the largest
    and most-used tables in VizieR, and these can be selected by clicking
    on the selection box.
    </li>
</ul>
</p>

<p>When a table name has been entered, additional information
(Name, Alias, Description and Row Count)
will be downloaded from CDS and displayed in the lower part of the
Remote Table panel.  If nothing shows up here, then the table name
is not legal for the X-Match service, and the <label>Go</label> button
will be disabled.
</p>

<p>Sky coverage information is also displayed, including the proportion
of the sky covered by the table and a graphical indication of the
covered regions on the sky.
</p>

<p>The <label>Local Table</label> panel allows you to indicate the
local table (the one loaded into TOPCAT) that you want to match.
You must select the required table and indicate its Right Ascension
and Declination columns.
</p>

<p>The <label>Match Parameters</label> panel supplies the other information
about how the match will operate:
<dl>
<dt>Radius</dt>
<dd><p>The maximum distance between a local table and remote table position
    to count as a match.  There is a maximum enforced on this value by
    the CDS X-Match service, currently 2 arcminutes.
    </p></dd>
<dt>Find mode</dt>
<dd><p>Determines in what form the result is generated and used.
    The following options are available:
    <dl>
    <dt>Best</dt>
    <dd><p>Load a new table with one row for each local row that matches
        a remote row, giving the closest match.  Unmatched local rows
        are not included.
        </p></dd>
    <dt>All</dt>
    <dd><p>Load a new table with one row for each remote row that matches
        a local row.  The match is symmetric between local and remote tables.
        </p></dd>
    <dt>Each</dt>
    <dd><p>Load a new table with the same number of rows as the local table,
        in the same order.  The best remote match, if any, appears alongside
        the local row, but if there is no match the remote columns are blank.
        </p></dd>
    <dt>Best Remote</dt>
    <dd><p>Load a new table with one row for each remote table row that
        matches the local table.
        <em>Note</em> there is currently a bug in this mode;
        if the match is done in N blocks then a remote row may appear 
        up to N times rather than just one.  This may be fixed in
        a future release, but to avoid it you can make sure that the
        <label>Block size</label> is greater than the row count.
        </p></dd>
    <dt>Add Subset</dt>
    <dd><p>No new table is loaded,
        but a new <ref id="subsets">Row Subset</ref> is added to the
        local table indicating which rows had at least one match to the
        remote table.
        </p></dd>
    </dl>
    </p></dd>
    <dt>Rename columns</dt>
    <dd><p>If columns from two input tables are combined, it's possible
        that some may share the same name.  Multiple columns in a table
        with the same name can cause confusion, so this selector allows
        you to determine whether and how such name clashes are dealt with.
        Columns from the remote table can be renamed by appending a
        specified suffix, either always or only in case of duplicate names.
        </p></dd>
    <dt>Block size</dt>
    <dd><p>The number of rows uploaded to the X-Match service at a time.
        This should not affect the result, though it may affect performance.
        </p>
        <p>Large blocksizes tend to be good (up to a point) for
        reducing the total amount of time a large xmatch operation takes,
        but they can make it harder to see the job progressing.
        There is also the danger (for ALL-type find modes)
        of exceeding the return size limit, which will result in
        truncation of the returned result.
        At time of writing, the upload limit is 100Mbyte (about 3Mrow),
        and the maximum return size is 2Mrow.
        </p></dd>
</dl>
</p>

<p>When all the fields have been filled in, hit the <label>Go</label>
button and the match will start; progress will be logged in the progress
bar at the bottom of the window.  To stop the match before it has
completed, hit the <label>Stop</label> button.
Note that the <label>Go</label> button is only enabled when a legal
table name has been entered at the top.
</p>

<p>The remote table in most cases contains only a subset of the
the columns in the relevant VizieR table, including the most useful ones.
The service currently provides no straightforward way to acquire columns
which are not returned by default.
</p>

<p>The following item is available in the toolbar and <label>Search</label>
menu:
<dl>
<dt>&IMG.FOOTPRINT; Use Service Coverage</dt>
<dd><p>If this option is selected, then the sky coverage of the
    service is used to pre-filter local table rows.
    In this case those rows that fall outside the coverage area of
    the remote table are not uploaded for matching, since it is
    known that they will not match.  This option should therefore
    not affect the result, but improve performance, and as such
    should generally be turned on (the default).
    </p></dd>
</dl>
</p>

<p><strong>Acknowledgement</strong>: CDS note that if the use of the
X-Match service is useful to your research, they would appreciate
the following acknowledgement:
<blockquote>
<em>
  "This research made use of the cross-match service provided by
  CDS, Strasbourg."
</em>
</blockquote>
</p>

</subsubsect>

<subsubsect id="ConcatWindow">
<subhead><title>Concatenation Window</title></subhead>

<figure>
<caption><px>Concatenation Window</px></caption>
<figureimage src="&FIG.ConcatWindow;"/>
</figure>

<p>The Concatenation Window allows you to join two tables together
top-to-bottom.  It can be obtained using the 
<label>Concatenate Tables</label> button (&IMG.CONCAT;) in the
<ref id="ControlWindow">Control Window</ref> <label>Joins</label> menu.
</p>

<p>When two windows are concatenated
all the rows of the first ("base") table are followed by all
the rows of the second ("appended") table.  The result is a new
table which has a number of rows equal to the sum of the two it has
been made from.  
The columns in the resulting table are the same as those of the base table.
To perform the concatenation, you have to specify which columns from the
appended table correspond to which ones in the base table.  Of course,
this sort of operation only makes sense if at least some of the columns in
both tables have the same meaning.
This process is discussed in more detail in <ref id="concat"/>.
</p>

<p>The concatenation window allows you to select the base and appended
tables, and for each column in the base table to specify which column
in the appended table corresponds to it.  You may select a blank for
this, in which case the column in question will have all null entries
in the resulting table.
In some cases these column selectors may have a value filled in
automatically if the program thinks it can guess appropriate ones,
but you should ensure that it has guessed correctly in this case.
Only suitable columns are available for choosing from these column
selectors; in most cases this means numeric ones.
</p>

<p>When you have filled in the fields to your satisfaction, hit
the <label>Concatenate</label> button at the bottom of the window,
and a new table will be created and added to the table list
in the <ref id="ControlWindow">Control Window</ref> 
(a popup window will inform you this has happened).
</p>

<p>The result is created from the 
<ref id="apparent" plaintextref="yes">Apparent</ref>
versions of the base and appended tables, so that any row subsets,
hidden columns, or sorts currently in force will be reflected in the
output.
</p>

</subsubsect>


<subsubsect id="ActivationQueryWindow">
<subhead><title>Activation Window</title></subhead>

<figure>
<caption><px>Activation Window</px></caption>
<figureimage src="&FIG.ActivationQueryWindow;"/>
</figure>

<p>The Activation Window allows you to configure an action to perform
when a table row is <ref plaintextref="yes" id="activation">activated</ref>
by clicking on a row in the Data Window or a point in the Plot Window.
It can be obtained by clicking the <label>Activation Action</label>
selector at the bottom of the properties panel in the Control Window.
</p>

<p>You have various options for how to define the action.
On the left of the window is a list of options; you have to choose
one of these to determine what kind of action will take place.
When you click on one of these options the corresponding 
controls on the right hand side will become enabled:
use these to select the details of the action and then 
click the <label>OK</label> button so that subsequent 
activation events will cause the action you have defined
(or <label>Cancel</label> so that they won't).
When you click OK the <label>Activation Action</label>
in the control window will indicate the action you have configured.
</p>

<p>The available options are as follows:
<dl>

<dt>No Action</dt>
<dd><p>If this is selected, no special action will take place when a 
    row is activated.  This is the default.
    </p></dd>

<dt>Display Cutout Image</dt>
<dd><p>This option presents an easy-to-use way of popping up a
    cutout image from an image server displaying a region of sky
    around an activated row.
    You need to select the columns in your table which 
    represent Right Ascension and Declination, including the units 
    in which they are entered in the table (TOPCAT may be able to
    guess some or all of this information based on column names, UCDs
    and unit values, in which case it will enter its guesses in the
    selectors for you to accept or change).
    You also need to select the size in pixels of the image you want 
    to see and the name of the survey which will supply the image 
    from one of the listed ones:
    <ul>
    <li>SuperCOSMOS All-Sky Blue</li>
    <li>SuperCOSMOS All-Sky Red</li>
    <li>2MASS Quick-Look J-band</li>
    <li>2MASS Quick-Look H-band</li>
    <li>2MASS Quick-Look K-band</li>
    <li>SDSS Colour Images (note does not provide all-sky coverage)</li>
    </ul>
    When you activate the row, the program will attempt to contact the
    web server which provides these images, retrieve the image, and
    display it in an image viewer window.
    Unfortunately at present the viewer window is an internal one;
    it does not display in an external SAMP/PLASTIC viewer.
    </p></dd>

<dt>View URL as Image</dt>
<dd><p>This option is suitable if one of the columns in your table 
    gives the location (filename or URL) of an image file.
    The image may be in FITS, GIF, JPEG or PNG format, optionally 
    compressed using gzip, Unix compress, or bzip2 format.
    Select the column which contains the location, and activating a 
    row will pop up an image viewer to display it
    (if the table is the result of a single or multiple SIA query,
    the correct column will probably be filled in automatically).
    The <label>Image Viewer</label> selector allows you to choose one 
    of the options in <ref id="imageViewers"/> or, if you are registered
    with a SAMP or PLASTIC hub, any SAMP/PLASTIC image viewer 
    which is also registered - see <ref id="interop"/>.
    </p></dd>

<dt>View URL as Spectrum</dt>
<dd><p>This option is suitable if one of the columns in your table
    gives the location (filename or URL) of a spectrum file,
    and you wish to display the spectra in an external SAMP- or
    PLASTIC-compatible spectrum viewer, such as
    <webref url="http://www.starlink.ac.uk/splat/">SPLAT</webref> or
    <webref url="http://esavo.esa.int/vospec/">VOSpec</webref>.
    First select the column which contains the 
    <label>Spectrum Location</label>
    (if the table is the result of a single or multiple SSA query,
    the correct column will probably be filled in automatically).
    Then choose the <label>Spectrum Viewer</label> appropriately.
    Once this is done, activating a
    row will try to send the corresponding spectrum to the selected
    viewer application(s).
    The details of what data formats are acceptable depend on the
    viewer application, but FITS, VOTable and some ASCII table
    variants are usually OK.
    Note that TOPCAT, as well as a suitable spectrum viewer, 
    must be connected to a running SAMP or PLASTIC hub for this to work
    (see <ref id="interop"/>) - there is no internal spectrum viewer.
    </p></dd>

<dt>View URL as Web Page</dt>
<dd><p>This option is suitable if one of the columns in your table
    gives the location (filename or URL) of a web page; this should
    normally be in HTML or plain text, but depending on what browser
    you use other kinds of document may be supported.
    Select the column which contains the location and the browser
    which you would like to use for display, and activating a row
    will try to pop up a browser window to display it.
    See <ref id="documentViewers"/> for more information about browsers.
    </p></dd>

<dt>Transmit Row</dt>
<dd><p>This option causes the row number of an activated row
    to be transmitted to one or more other applications using an
    appropriate SAMP or PLASTIC message.
    This will only work if TOPCAT is registered with a SAMP/PLASTIC hub, and
    so are one or more other applications which understand that message,
    and the other application(s) know about the table in question,
    for instance because it has previously been sent to/from TOPCAT.
    You may specify that either a single application, or all appropriate ones,
    will receive the messages.
    See <ref id="interop"/> for more explanation.
    </p></dd>

<dt>Transmit Coordinates</dt>
<dd><p>This option causes the sky position of an activated row 
    to be transmitted to 
    one or more other applications using an appropriate SAMP or PLASTIC 
    message.
    This will only work if TOPCAT is registered with a SAMP/PLASTIC hub, and
    so are one or more other applications which understand that message.
    An example might be a sky viewing application such as Aladin which 
    can point to a particular region of sky whenever you activate a point.
    You need to specify the columns which represent (J2000) 
    Right Ascension and Declination, and optionally a particular listener
    to receive the messages (otherwise all registered ones will).
    See <ref id="interop"/> for more explanation.
    </p></dd>

<dt>Execute Custom Code</dt>
<dd><p>This option must be used if none of the others 
    (which are fairly restrictive) do what you want.
    It is highly flexible, but not so easy to use.
    What you have to do is to write an expression following the rules
    in <ref id="jel"/> involving some
    of the column names which will be invoked when a row is activated.
    This expression will typically have the effect of popping up
    an image or a spectrum in a viewer,
    but, especially if you link in your own functions 
    (see <ref id="jelExtend"/>) it can do pretty much anything.
    </p>
    <p>Functions which are expected to be useful for activation actions
    are described in <ref id="activationJel"/> and include some
    general-purpose ones 
    (<code>displayImage</code> and <code>displaySpectrum</code> to display
    an image or spectrum in an external viewer) as well as a few 
    which are relevant to particular survey data, for instance the
    <code>spectra2QZ()</code> function, which will pop up a spectrum
    viewer displaying all the spectra related to a given row of 2QZ
    survey data based on the contents of its NAME column.
    </p></dd>

</dl>
</p>

<p>As the above list shows, most of the activation actions you can
define result in a viewer window of some kind popping up.
Exactly what kind of viewer is used depends on how TOPCAT is set up
and in some cases on your choices.  More details of the viewer
programs available are given in the following subsections.
If these don't do what you want, you can use the 
<label>Execute Custom Code</label> option, perhaps in conjunction with
<ref id="jelExtend">user-defined</ref> functions or the 
<code>System</code> <code>exec()</code> functions
described in <ref id="activationJel"/>, to invoke your own.
</p>

<subsubsubsect id="imageViewers">
<subhead><title>Image Viewer Applications</title></subhead>

<p>If you choose the <label>Display Cutout Image</label> or
<label>View URL as Image</label> option in the 
<ref id="ActivationQueryWindow">Activation Window</ref>,
then activating a row will display an image in an image viewer.
</p>

<p>The default image viewer is 
<webref plaintextref="yes" url="http://www.starlink.ac.uk/sog/">SoG</webref>,
an astronomical image viewer based on JSky, which offers 
colourmap manipulation, image zooming, graphics overlays, and other features.
For this to work JAI, otherwise known as
<webref plaintextref="yes" url="http://java.sun.com/products/java-media/jai/"
        >Java Advanced Imaging</webref> must be installed.
JAI is a free component available from Sun, but not a part of the Java 2
Standard Edition by default.  In operation, SoG looks like this:
</p>

<figure>
<caption><px>SoG Image Viewer</px></caption>
<figureimage src="&FIG.SoG;"/>
</figure>

<p>If JAI or the SoG classes themselves are absent, a fallback viewer
which just displays the given image in a basic graphics window 
with no manipulation facilities is used.
The fallback image viewer looks like this:
</p>

<figure>
<caption><px>Fallback Image Viewer</px></caption>
<figureimage src="&FIG.ImageWindow;"/>
</figure>

</subsubsubsect>

<subsubsubsect id="spectrumViewers">
<subhead><title>Spectrum Viewers</title></subhead>

<p>If you choose the <label>View URL as Spectrum</label> option in
the <ref id="ActivationQueryWindow">Activation Window</ref>,
then activating a row will display a spectrum in a spectrum viewer.
</p>

<p>The default spectrum viewer is 
<webref plaintextref="yes" url="http://www.starlink.ac.uk/splat/"
        >SPLAT</webref>,
a sophisticated multi-spectrum analysis program.
This requires the presence of a component named JNIAST, which may
or may not have been installed with TOPCAT (it depends on some
non-Java, i.e. platform-specific code).  
There is currently no fallback spectrum viewer, so if JNIAST is 
not present, then spectra cannot be displayed. 
In this case it will not be possible to select the
<label>Display Named Spectrum</label> item in the 
Activation Window.
An example of SPLAT display of multiple spectra is shown below.
</p>

<figure>
<caption><px>SPLAT Spectrum Viewer</px></caption>
<figureimage src="&FIG.Splat;"/>
</figure>

<p>Full documentation for SPLAT is available on-line within the program,
or in <docxref doc="sun243"/>.
</p>

</subsubsubsect>

<subsubsubsect id="documentViewers">
<subhead><title>Web Browsers</title></subhead>

<p>If you choose the <label>View URL as Web Page</label> option in
the <label>Activation Window</label>,
then activating a row will display the web page whose URL 
is in one of the columns in a web browser.
You are given the option of what browser you would like to use in this case.
</p>

<p>The default <label>basic browser</label> option uses a simple
browser which can view HTML or plain text pages and has forward and
back buttons which work as you'd expect.  In many cases this is fine
for viewing HTML pages, and it is available regardless of the system
that you are running TOPCAT on.  It looks like this:
</p>

<figure>
<caption><px>Basic HTML browser</px></caption>
<figureimage src="&FIG.HtmlWindow;"/>
</figure>

<p>In some circumstances, it's possible to use your normal web browser
for web page display instead.  
The list of browsers currently includes Firefox, Mozilla
and Netscape as well as the basic one.  Selecting these will generally
only work if (1) the browser you select is installed and on your path, 
(2) you're on some Unix-like operating system,
(3) the browser is already running when the action is invoked.
In this case, the selected URL should be displayed in an existing
browser window rather than opening a new one.
Doing it this way has the advantage that your browser can probably 
display many types of document (perhaps using plugins) as well as HTML.
</p>

</subsubsubsect>

</subsubsect>


<subsubsect id="SampWindow">
<subhead><title>SAMP Window</title></subhead>

<p>The SAMP Window displays the status of SAMP messaging and allows some
control over its configuration.  SAMP is a messaging protocol which
allows TOPCAT to exchange information with other desktop applications -
see <ref id="interop"/> for details.
</p>

<p>The main part of the window is a tabbed panel which displays the
status of the SAMP connection in detail.
</p>

<p>The first tab is labelled <label>Clients</label>:
</p>
<figure>
<caption><px>SAMP Window Clients tab</px></caption>
<figureimage src="&FIG.SampWindow_clients;"/>
</figure>
<p>This displays details of all applications (including TOPCAT itself)
which are currently registered with the hub.
If you select a client in the list on the left hand side of the panel,
you will see its details on the right hand side.
This includes its <label>Metadata</label>
(which may include things like its name, author, documentation URL etc) 
and its <label>Subscriptions</label> which describes what types of messages
(MTypes) it will respond to.
Also in the list on the left is for each application a graphical 
indication of messages recently received by/sent from it,
in which TOPCAT is the other partner.
These are represented by little arrows before/after the little circle
following the application name.
In the figure, a message is currently in progress from TOPCAT to Aladin.
More detail on this is shown in the other tabs.
</p>

<p>The other two tabs are labelled <label>Received Messages</label>
and <label>Sent Messages</label>.  They look very similar to each other:
</p>
<figure>
<caption><px>SAMP Window Sent Messages tab</px></caption>
<figureimage src="&FIG.SampWindow_msgs;"/>
</figure>
<p>They display details of SAMP messages recently sent from or received by
TOPCAT.
A table near the top contains one row for each message.
Shown in different columns are the message's MType (which describes the message 
semantics), the application receiving/sending it from/to TOPCAT, 
and a summary of its status.  If you click on the row, 
all the details of the message, including its content and that of the 
response if one has been received, are visible in the lower panel.
Messages remain in this table for a few seconds after they have completed,
but are eventually removed to avoid clutter.
</p>

<p>The following toolbar button is available:
<dl>

<dt>&IMG.CONNECT; Connect/Disconnect</dt>
<dd><p>This button controls connection to the SAMP hub; without a connection
    no SAMP commmunication can take place.
    If a hub is running, clicking this button toggles whether TOPCAT is
    connected or not.
    </p>
    <p>If no hub is running, clicking this button will pop up a dialogue box 
    which allows you to start a hub.  You are given the option to start either
    an <label>internal</label> or an <label>external</label> hub.
    An internal one runs in the same Java Virtual Machine as TOPCAT itself,
    and an external one runs in a separate process.
    The main important difference is that an internal hub will shut down
    when TOPCAT does, while an external hub will keep running until it is
    shut down explicitly.  If an external hub is started, a window which
    shows its status is displayed on the screen; closing this window 
    (which does not belong to TOPCAT) will shut down the hub.
    </p></dd>

</dl>
</p>

<p>More facilities may be introduced into this window in future releases.
</p>

</subsubsect>


<subsubsect id="HelpWindow">
<subhead><title>Help Window</title></subhead>

<figure>
<caption><px>Help Window</px></caption>
<figureimage src="&FIG.HelpWindow;"/>
</figure>

<p>The help window is a browser for displaying help information on TOPCAT;
it can be obtained by clicking the <label>Help</label> (&IMG.HELP;) button
that appears in the toolbar of most windows.
It views the text contained in this document, so it may be what you are
looking at now.
</p>

<p>The panel on the right hand side displays the currently selected section
of help text itself.  The panel on the left gives a couple of ways of
selecting this view:
<dl>
<dt>&IMG.HELP_SEARCH; Text Search</dt>
<dd><p>Allows you to search for words in the manual.
    Enter a word or words as search terms, and a list of sections which 
    fully or partially match your search terms will be displayed.
    You can click on one of these to take you to the section that
    has been found.
    </p></dd>
<dt>&IMG.HELP_TOC; Table of Contents</dt>
<dd><p>A hierarchical view of the available help topics.
    This is the table of contents of the manual;
    clicking on an entry will take you to the relevant section.
    </p></dd>
</dl>
</p>

<p>The bar in between the two panels can be dragged with the mouse
to affect the relative sizes of
these windows.
</p>

<p>The toolbar contains these extra buttons:
<dl>
<dt>&IMG.BACKWARD; Back</dt>
<dd><p>Moves backward through the list of topics in the order you have
    looked at them.
    </p></dd>

<dt>&IMG.FORWARD; Forward</dt>
<dd><p>Moves forward through the list of topics in the order you have
    looked at them.
    </p></dd>

<dt>&IMG.PRINT; Print</dt>
<dd><p>Pops up a dialogue to permit printing of the current page to a
    file or printer (but see below).
    </p></dd>

<dt>&IMG.PAGE_SETUP; Page Setup</dt>
<dd><p>Pops up a dialogue to do printer setup.
    </p></dd>

<dt>&IMG.TO_BROWSER; To Browser</dt>
<dd><p>Displays the currently displayed help page in your normal WWW browser.
    </p></dd>
</dl>
</p>

<p>Although the printing buttons work, if you want to print out the
whole of this document rather than just a few sections you may be better off
printing the PDF version, 
or printing the single-page HTML version through a web browser.
The most recent version of these should be available
on the web at
<webref url="http://www.starlink.ac.uk/topcat/sun253/sun253.html"/> and
<webref url="http://www.starlink.ac.uk/topcat/sun253.pdf"/>;
you can also find the HTML version in the topcat jar file at
<code>uk/ac/starlink/topcat/help/sun253.html</code>
or, if you have a full TOPCAT installation, in 
<code>docs/topcat/sun253/sun253.html</code> and
<code>docs/topcat/sun253.pdf</code>
(the single-page HTML version is available 
<webref url="sun253.html">here</webref> in the HTML version).
</p>

<p>The help browser is an HTML browser and some of the hyperlinks in
the help document point to locations outside of the help document
itself.  Selecting these links will go to the external documents.
When the viewer is displaying an external document, its URL will
be displayed in a line at the bottom of the window.  You can cut
and paste from this using your platform's usual mechanisms for this.
</p>

</subsubsect>

<subsubsect id="ParameterQueryWindow">
<subhead><title>New Parameter Window</title></subhead>

<figure>
<caption><px>New Parameter dialogue window</px></caption>
<figureimage src="&FIG.ParameterQueryWindow;"/>
</figure>

<p>The New Parameter window allows you to enter a new table parameter
to be added to a table.
It can be obtained by clicking the <label>New Parameter</label> (&IMG.ADD;)
button in the <ref id="ParameterWindow"/>.
A parameter is simply a fixed value attached to a table and can contain
information which is a string, a scalar, an array... in fact exactly
the same sorts of values which can appear in table cells.
</p>

<p>The window is pretty straightforward to use: fill in the fields
and click <label>OK</label> to complete the addition.
The <label>Type</label> selector allows you to select what kind of
value you have input.  The only compulsory field is
<label>Parameter Name</label>; any of the others may be left blank,
though you will usually want to fill in at least the <label>Value</label>
field as well.  Often, the parameter will have a string value, 
in which case the <label>Units</label> field is not very relevant.
</p>

</subsubsect>


<subsubsect id="SyntheticColumnQueryWindow">
<subhead><title>Synthetic Column Window</title></subhead>

<figure>
<caption><px>Synthetic Column dialogue window</px></caption>
<figureimage src="&FIG.SyntheticColumnQueryWindow;"/>
</figure>

<p>The Synthetic Column Window allows you to define a new "Synthetic" column,
that is one whose values are defined using an algebraic expression 
based on the values of other columns in the same row.
The idea is that the value of the cells in a given row in this column
will be calculated on demand as a function of the values of cells
of other columns in that row.  You can think of this as providing
functionality like that of a column-oriented spreadsheet.
You can activate the dialogue using the 
<label>Add Column</label> (&IMG.ADD;) or
<label>Replace Column</label> (&IMG.MODIFY;) buttons in the
<ref id="ColumnInfoWindow">Columns Window</ref> or from the 
(right-click) popup menu in the <ref id="TableViewerWindow">Data Window</ref>.
</p>

<p>The window consists of a number of fields you must fill in to 
define the new column:
<dl>
<dt>Name</dt>
<dd><p>The name of the new column.  This should preferably be unique
    (different from all the other column names).  It will be easier to
    use it in <ref id="jel">algebraic expressions</ref> if it is also:
    <ul>
    <li>Different from other columns even apart from upper/lower case
        distinctions</li>
    <li>In the form of a java identifier (starts with a letter, continues
        with alphanumerics including underscore)</li>
    <li>Not too long</li>
    </ul>
    </p></dd>

<dt>Expression</dt>
<dd><p>This is the algebraic expression which defines the values that the
    cells in the new column of the table will have.  The rules for
    writing algebraic expressions are described in <ref id="jel"/>,
    and detailed documentation of the functions you can use can be 
    seen in the <ref id="MethodWindow">Available Functions Window</ref>,
    which you can see by clicking the <label>Show Functions</label>
    (&IMG.FUNCTION;) button on the toolbar.
    </p></dd>

<dt>Units</dt>
<dd><p>The units of the column.  If the quantity it represents is dimensionless
    or you don't know the units, this can be left blank.  It would be
    a good idea to use a similar format for the units to that used for
    the existing columns in the table.
    </p></dd>

<dt>Description</dt>
<dd><p>A short textual description of what the values contained by this
    column are.  May be left blank.
    </p></dd>

<dt>UCD</dt>
<dd><p>A <webref url="http://vizier.u-strasbg.fr/doc/UCD.htx"
                 >Unified Content Descriptor</webref>
    for the column; a UCD is a semantic label
    attached to the column indicating what kind of quantity it contains
    by picking one option from a list defined by the
    <webref url="http://cdsweb.u-strasbg.fr/">CDS</webref>.
    The list of known UCDs is available via a selection box, or you
    can type a UCD in by hand.  You may leave this blank if the you do not
    wish to assign a UCD to the column.
    A brief description of the UCD selected is visible below
    selection box itself.
    </p></dd>

<dt>Index</dt>
<dd><p>Determines the position in the displayed table at which the new
    column will initially appear.
    </p></dd>
</dl>
Of these, the <label>Expression</label> is the only one which must be
filled in.  
</p>

<p>Having filled in the form to your satisfaction, hit the
<label>OK</label> button at the bottom and the new column will be
added to the table.  If you have made some mistake in filling in 
the fields, a popup window will give you a message describing the
problem.  This message may be a bit arcane - try not to panic and
see if you can rephrase the expression in a way that the parser might
be happier with.  If you can't work out the problem, it's time to
consult your friendly local Java programmer (failing that, your
friendly local C programmer may be able to help) or, by all means,
contact the author.
</p>

<p>If you wish to add more metadata items you can edit the appropriate
cells in the <ref id="ColumnInfoWindow">Columns Window</ref>.
You can edit the expression of an existing synthetic column in the same way.
</p>

<p>Once created, a synthetic column is added to the
<ref id="apparent">Apparent Table</ref> and behaves just like any other;
it can be moved, hidden/revealed, used in expressions for other
synthetic columns and so on.
If the table is saved the new column and its contents will
be written to the new output table.
</p>

</subsubsect>

<subsubsect id="SkyColumnQueryWindow">
<subhead><title>Sky Coordinates Window</title></subhead>

<figure>
<caption><px>Sky Coordinates Window</px></caption>
<figureimage src="&FIG.SkyColumnQueryWindow;"/>
</figure>

<p>The Sky Coordinates Window allows you to add new columns to a table, 
representing coordinates in a chosen sky coordinate system.
The table must already contain columns which represent sky coordinates;
by describing the systems of the existing and of the new coordinates,
you provide enough information to calculate the values in the new columns.
You can activate this dialogue using the
<label>New Sky Coordinate Columns</label> (&IMG.ADDSKY;) button
in the <ref id="ColumnInfoWindow">Columns Window</ref>.
</p>

<p>The dialogue window has two halves; on the left you 
give the existing columns which represent sky coordinates,
their coordinate system (ICRS, fk5, fk4, galactic, supergalactic or ecliptic)
and the units (degrees, radians or sexagesimal) that they are in.
Note that the columns available for selection will depend on the
units you have selected; for degrees or radians only numeric columns
will be selectable, while for sexagesimal (dms/hms) units only 
string columns will be selectable.
On the right you make the coordinate system and units selections
as before, but enter the names of the new columns in the text fields.
Then just hit the <label>OK</label> button, and the new columns
will be appended at the right of the table.
</p>

</subsubsect>

<subsubsect id="SyntheticSubsetQueryWindow">
<subhead><title>Algebraic Subset Window</title></subhead>

<figure>
<caption><px>Algebraic Subset dialogue window</px></caption>
<figureimage src="&FIG.SyntheticSubsetQueryWindow;"/>
</figure>

<p>The Algebraic Subset Window allows you to define a new 
<ref id="subsets">Row Subset</ref> which uses an algebraic expression
to define which rows are included.  The expression must be a 
boolean one, i.e. its value is either true or false for each row of
the table.
You can activate this dialogue using the
<label>Add Subset</label> (&IMG.ADD;) button in the
<ref id="SubsetWindow">Subsets Window</ref>.
</p>

<p>The window consists of two fields which must be filled in to 
define the new subset:
<dl>

<dt>Subset Name</dt>
<dd><p>The name of the new subset.  This should preferably be unique
    (different from existing subset names).  It will be easier to
    use it in other expressions if it is also:
    <ul>
    <li>Different from other columns even apart from upper/lower case
        distinctions</li>
    <li>In the form of a java identifier (starts with a letter, continues
        with alphanumerics including underscore)</li>
    <li>Not too long</li>
    </ul>
    </p></dd>

<dt>Expression</dt>
<dd><p>This is a boolean expression which defines the subset;
    it is a function of the values of any combination of the columns;
    only rows for which it evaluates to true will be included in the subset.
    The values of the other columns in the same row are referenced
    using their names or &column.id.char;ID identifiers,
    and other subsets may be
    referenced using their names or &subset.id.char;ID identifiers.
    The rules for expression syntax are described in <ref id="jel"/>,
    and detailed documentation of the functions you can use can be 
    seen in the <ref id="MethodWindow">Available Functions Window</ref>,
    which you can see by clicking the <label>Show Functions</label>
    (&IMG.FUNCTION;) button on the toolbar.
    </p></dd>

</dl>
</p>

<p>Having filled in the form to your satisfaction, hit the
<label>OK</label> button at the bottom and the new subset will be
added to the list that can be seen in the 
<ref id="SubsetWindow">Subsets Window</ref> where it behaves like any other.
If you have made some mistake in filling in
the fields, a popup window will give you a message describing the
problem.
</p>


</subsubsect>

<subsubsect id="MethodWindow">
<subhead><title>Available Functions Window</title></subhead>

<figure>
<caption><px>Available Functions Window</px></caption>
<figureimage src="&FIG.MethodWindow;"/>
</figure>

<p>This window displays all the functions (Java methods) which are
available for use when writing 
<ref id="jel" plaintextref="yes">algebraic expressions</ref>.
This includes both the built-in expressions and any 
<ref id="jelExtend">extended ones</ref> you might have added.
You can find this window by using the 
<label>Show Functions</label> (&IMG.FUNCTION;) button in the
<ref id="SyntheticColumnQueryWindow">Synthetic Column</ref> or 
<ref id="SyntheticSubsetQueryWindow">Algebraic Subset</ref>
window toolbars.
</p>

<p>On the left hand side of the window is a tree-like representation
of the functions you can use.  Each item in this tree is one of the
following:
<dl>

<dt>&IMG.FOLDER_NODE; Folder</dt>
<dd><p>A group of classes.  There's only one of these, marked 
    "Activation Functions", and it contains functions which are only
    available for use in 
    <ref plaintextref="yes" id="activation">Activation Actions</ref>.
    When defining a new synthetic columns or algebraic subsets they
    are not used.
    </p></dd>

<dt>&IMG.LIBRARY_NODE; Class</dt>
<dd><p>A set of functions and/or constants; 
    it doesn't matter what class a function
    is in when you use it, but since the functions in a class are 
    usually related this makes it easier to find the one you're looking
    for in this window.
    </p></dd>

<dt>&IMG.FUNCTION_NODE; Function</dt>
<dd><p>A function that you can use in an expression.
    </p></dd>

<dt>&IMG.CONSTANT_NODE; Constant</dt>
<dd><p>A constant value which you can refer to by name in an expression
    (as long as it doesn't clash with a column name).
    </p></dd>

</dl>
</p>

<p>Of these, the Folder and Class items have a 'handle' (&IMG.COLLAPSED;),
which means that they contain other items 
(classes and functions/constants respectively).
By clicking on the handle (or equivalently double-clicking on the name)
you can toggle whether the item is open (so you can see its contents)
or closed (so you can't).  So to see the functions in a class,
click on its handle and they will be revealed.
</p>

<p>You can click on any of these items and information about it 
will appear in the right hand panel.  In the case of functions
this describes the function, its arguments, what it does, and
how to use it.  The explanations should be fairly self-explanatory;
for instance the description in the figure above indicates that
you could use the invocation <code>skyDistanceDegrees(RA1,DEC1,RA2,DEC2)</code> 
as the expression for a new table column which gives the angular distance
between two sky positions represented by columns with the names RA1, DEC1
and RA2, DEC2.
Examples of a number of these functions are given in 
<ref id="jelExamples"/>.
</p>

<p>There are two menu/toolbar actions:
<dl>

<dt>&IMG.SYNTAX; Syntax Help</dt>
<dd><p>Displays the section of the manual which discusses the general
    syntax used for algebraic expressions, including what operators are
    available, what the rules are for referring to columns, etc.
    The help is displayed in the <ref id="HelpWindow">Help Window</ref>
    (and can from there be passed to a browser if that's more convenient).
    The displayed material is simply a shortcut to <ref id="jel"/> in
    this document.
    </p></dd>

<dt>&IMG.ADD; Add Class</dt>
<dd><p>Allows you to add the name of a class to those available.
    You should enter the fully-qualified class name (i.e. including the
    dot-separated package path).  The class that you specify must be
    on the class path which was current when TOPCAT was started,
    as explained in <ref id="jvmClasspath"/>.
    Note however it would be more usual to specify these using
    the system property <code>jel.classes</code> or 
    <code>jel.classes.activation</code> at startup,
    as described in <ref id="jelExtend"/>.
    </p></dd>

</dl>
</p>

<p>Classes added either using the <label>Add Class</label> action above or
the <code>jel.classes</code> or <code>jel.classes.activation</code>
system properties will be visible in the tree in this window,
but they may not have proper documentation
(clicking on them may not reveal a description in the right hand panel).
</p>

</subsubsect>

<subsubsect id="LogWindow">
<subhead><title>Log Window</title></subhead>

<figure>
<caption><px>Log Window</px></caption>
<figureimage src="&FIG.LogWindow;"/>
</figure>

<p>The log window can be obtained using the <label>View Log</label>
option on the <label>File</label> menu of the 
<ref id="ControlWindow">Control Window</ref>.
</p>

<p>This window displays any log messages which the application has
generated.  Depending on whether the <code>-verbose</code> flag has
been specified, some or all of these messages may have been written
to console as well (if there is a console - this depends on how you
have invoked TOPCAT).  
Under some circumstances, messages way back in the list may not be
displayed.
</p>

<p>To clear the display of all the existing messages you can use
the <label>Clear Log</label> button (&IMG.CLEAR;).
</p>

<p>The messages displayed here are those written through Java's
<webref url="&URL.J2SE_DOCS;guide/util/logging/index.html"
        >logging system</webref>
- in general they are intended for 
debugging purposes and not for users to read, but if something 
unexpected is happening, or if you are filing a bug report, 
it may provide some clues about what's going on.
Although it tries not to disturb things too much, TOPCAT's 
manipulation of the logging infrastructure affects how it is 
set up, so if you have customised your logging setup using,
e.g., the <code>java.util.logging.config.*</code> system 
properties, you may find that it's not behaving exactly as
you expected.  Sorry.
</p>

</subsubsect>

</subsect>

</sect>

<sect id="funcs">
<subhead><title>Algebraic Functions</title></subhead>

<p>This appendix lists the functions which can be used in algebraic
expressions (see <ref id="jel"/>).  They are listed in two sections:
the first gives the functions available for use anywhere an expression
can be used, and the second gives those only for use
in defining custom 
<ref id="activation" plaintextref="yes">Activation Actions</ref>.
</p>

<p>Note that although all the available functions are listed here
with short descriptions, their full explanation, including parameter
descriptions and examples, is only available from the 
<ref id="MethodWindow" plaintextref="yes">Available Functions Window</ref>,
obtained using the &IMG.FUNCTION; toolbar button.
</p>

<subsect id="generalJel">
<subhead><title>General Functions</title></subhead>

<p>The following functions can be used anywhere that you can write
an algebraic expression in TOPCAT.  They will typically be used for
defining new synthetic columns or algebraically-defined row subsets.
More complete documentation of them is available from within TOPCAT
in the <ref id="MethodWindow">Available Functions Window</ref>.
</p>

&general.runtime.method.docs;

</subsect>

<subsect id="activationJel">
<subhead><title>Activation Functions</title></subhead>

<p>The following functions can be used only for defining custom
<ref id="activation" plaintextref="yes">Activation Actions</ref> -
they mostly deal with causing something to happen, such as 
popping up an image display window.
They generally return a short string, which will be logged to the user
to give an indication of what happened (or didn't happen, or should
have happened).
More complete documentation of them is available from within TOPCAT
in the <ref id="MethodWindow">Available Functions Window</ref>.
</p>

&activation.runtime.method.docs;

</subsect>

</sect>

<sect id="release">
<subhead><title>Release Notes</title></subhead>

<p>This is TOPCAT, Tool for OPerations on Catalogues And Tables.
It is a general purpose viewer and editor for astronomical tabular data.
<dl>
<dt>Author</dt>
<dd><p>Mark Taylor (Bristol University)</p></dd>

<dt>Email</dt>
<dd><p><webref url="mailto:m.b.taylor@bristol.ac.uk"
                          >m.b.taylor@bristol.ac.uk</webref></p></dd>

<dt>WWW</dt>
<dd><p><webref url="http://www.starlink.ac.uk/topcat/"/></p></dd>
</dl>
User comments, suggestions, requests and bug reports to the above address
are welcomed.
</p>

<p>Related software products are
<dl>
<dt><webref url="http://www.starlink.ac.uk/stil/">STIL</webref></dt>
<dd><p>The Starlink Tables Infrastructure Library, which provides the
    table handling classes on which TOPCAT is based.
    </p></dd>

<dt><webref url="http://www.starlink.ac.uk/stilts/">STILTS</webref></dt>
<dd><p>The STIL Tool Set, which provides some command-line table manipulation
    and analysis tools based on STIL.  This is a non-GUI
    counterpart to TOPCAT, providing many of the same facilities 
    (matching, row selection, format conversion, plotting etc) but in a form 
    which can be incorporated into scripts, web services, etc.
    </p></dd>
</dl>
</p>

<p>See the TOPCAT web page, <webref url="http://www.starlink.ac.uk/topcat/"/>
for the latest news and releases.
</p>

<subsect id="ack">
<subhead><title>Acknowledgements</title></subhead>

<p>TOPCAT was initially (2003-2005) developed under the UK 
<webref url="http://en.wikipedia.org/wiki/Starlink_Project"
        >Starlink</webref> project
(1980-2005, R.I.P.).
Since then it has been supported by 
grant PP/D002486/1 from the 
UK's Particle Physics and Astronomy Research Council,
the <webref url="http://eurovotc.org/">VOTech</webref> project (from EU FP6),
the <webref url="http://www.astrogrid.org/">AstroGrid</webref> project
    (from PPARC/STFC),
the <webref url="http://cds.u-strasbg.fr/twikiAIDA/bin/view/EuroVOAIDA/WebHome"
            >AIDA</webref> project (from EU FP7),
grants ST/H008470/1, ST/I00176X/1, ST/J001414/1 and ST/L002388/1
from the UK's Science and Technology Facilities Council
(<webref url="http://www.stfc.ac.uk/">STFC</webref>),
the <webref url="http://www.g-vo.org/">GAVO</webref> project
(BMBF Bewilligungsnummer 05A08VHA),
the <webref url="http://www.esa.int/">European Space Agency</webref>,
and the FP7 project 
<webref url="https://gaia.am.ub.es/Twiki/bin/view/GENIUS">GENIUS</webref>.
All of this support is gratefully acknowledged.
</p>

<p>Nearly all of this work has been done in the Astrophysics Group
of the School of Physics, in the University of Bristol, UK,
although the University of Cambridge and the University of Heidelberg
have also been involved.
</p>

<p>Inspiration for some of TOPCAT's features has been taken from the
following pre-existing tools:
<ul>
<li><webref url="http://cm.bell-labs.com/who/tkh/mirage/index.html"
            >Mirage</webref>
    (Bell labs)</li>
<li><webref url="http://vo.iucaa.ernet.in/~voi/voplot.htm">VOPlot</webref>
    (VO-India)</li>
</ul>
</p>

<p>Apart from the excellent Java 2 Standard Edition itself, 
the following external libraries provide parts of TOPCAT's
functionality:
<ul>
<li><webref url="http://www.gnu.org/software/jel/">JEL</webref>
    (Konstantin Metlov, GNU) for algebraic expression evaluation</li>
<li><webref url="http://home.fnal.gov/~kuropat/HEALPIX/PixTools.html"
            >PixTools</webref>
    (Nikolay Kuropatkin, Fermilab EAG)
    for HEALPix-based celestial sphere row matching</li>
<li><webref url="http://trac.us-vo.org/project/nvo/wiki/IVOARegistry"
            >IVOARegistry</webref>
    (NVO) for ADQL/X-&gt;S translations in registry searches</li>
<li><webref url="http://www.sdss.jhu.edu/htm/">HTM</webref>
    (Sloan Digital Sky Survey) for HTM-based celestial sphere row matching
    (now deprecated within TOPCAT)</li>
<li><webref url="http://ptolemy.eecs.berkeley.edu/java/ptplot5.2/ptolemy/plot/doc/index.htm">Ptplot</webref>
    (Ptolemy) for some 2D axis plotting</li>
<li><webref url="http://itextpdf.com/">iText</webref>
    for PDF output</li>
<li><webref url="http://www.jibble.org/epsgraphics/">EPSGraphics2D</webref>
    (Jibble) for encapsulated postscript output</li>
<li><webref url="http://www.acme.com/java/software/Acme.JPM.Encoders.GifEncoder.html">GifEncoder</webref>
    (Acme) for GIF output</li>
<li><webref url="http://skyservice.pha.jhu.edu/develop/vo/ivoafits/"
            >IVOA FITS Package</webref>
    (Sloan Digital Sky Survey) for simple (non-SoG) display of FITS images</li>
<li><webref url="http://cdsportal.u-strasbg.fr/adqltuto/"
            >ADQL</webref> (Gr&#x00e9;gory Mantelet, CDS)
            for ADQL parsing</li>
<li><webref url="http://cds.u-strasbg.fr/resources/doku.php?id=moc"
            >MOC</webref> (CDS)
            Multi-Order Coverage HEALPix maps for footprint manipulation</li>
<li><webref url="http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/java/"
            >nom.tam.fits</webref> (NASA) for parts of FITS I/O</li>
<li><webref url="http://skyview.gsfc.nasa.gov/jar/jar.html"
            >Skyview in a Jar</webref> (NASA) for sky axis drawing</li>
<li><webref url="http://forge.scilab.org/index.php/p/jlatexmath/"
            >JLaTeXMath</webref> (Scilab) for LaTeX typesetting in plots</li>
<li><webref url="http://www.jidesoft.com/products/oss.htm"
            >JIDE Common Layer</webref> (Jidesoft)
            for double-ended slider controls</li>
<li><webref url="http://browserlaunch2.sourceforge.net/"
            >BrowserLauncher2</webref> for launching default web browser</li>
</ul>
</p>

<p>Contributed code from the following people is gratefully acknowledged:
<ul>
<li>Thomas Boch (CDS), for the VizieR load dialogue.</li>
<li>Gerard Lemson (MPE, Garching) for the GAVO load dialogue.</li>
<li>Marco Molinaro (INAF-OATS) for the BaSTI load dialogue.</li>
</ul>
</p>

<p>The TOPCAT logo in use since version 4 was kindly drawn by Phil Hall.
</p>

<p>TOPCAT has benefitted from, and is largely shaped by, advice,
comments and feedback from very many users, testers and developers.
Some of the notable contributers are these:
<ul>
<li>Alasdair Allan (Starlink, Exeter)</li>
<li>Mark Allen (CDS)</li>
<li>Heinz Andernach (Guanajuato)</li>
<li>Thomas Boch (CDS)</li>
<li>Laurent Bourges (JMMC)</li>
<li>Danny Boxhoorn (Kapteyn, Groningen)</li>
<li>Baptiste Cecconi (LESIA)</li>
<li>Igor Chilingarian (CfA)</li>
<li>Malcolm Currie (Starlink, RAL)</li>
<li>Clive Davenhall (Royal Observatory Edinburgh)</li>
<li>Luke Davies (Bristol)</li>
<li>Christoph Deil (MPI Heidelberg)</li>
<li>Markus Demleitner (ARI Heidelberg)</li>
<li>Sebastien Derriere (CDS)</li>
<li>Peter Draper (Starlink, Durham)</li>
<li>Pierre Fernique (CDS)</li>
<li>Shashikiran Ganesh (PRL, India)</li>
<li>David Giaretta (Starlink, RAL)</li>
<li>Eduardo Gonzalez-Solares (IoA)</li>
<li>Norman Gray (Starlink, Glasgow)</li>
<li>Phil Hall (Son of Ken)</li>
<li>Haggis Harris (Bath)</li>
<li>Evanthia Hatziminaoglou (ESO)</li>
<li>Avon Huxor (Bristol/ARI)</li>
<li>Jonathan Irwin (Cambridge)</li>
<li>Tim Jenness (JACH)</li>
<li>JJ Kavelaars (NRC)</li>
<li>Gerard Lemson (MPE Garching)</li>
<li>Bob Mann (Royal Observatory Edinburgh)</li>
<li>Gr&#x00e9;gory Mantelet (ARI)</li>
<li>Ben Maughan (Bristol)</li>
<li>Richard McMahon (IoA)</li>
<li>Guillaume Mella (JMMC)</li>
<li>David Mills (Bristol)</li>
<li>Douglas Morgan (Bristol)</li>
<li>August Muench (CfA)</li>
<li>Simon Murphy (ANU)</li>
<li>Fran&#x00e7;ois Ochsenbein (CDS)</li>
<li>Clive Page (Leicester)</li>
<li>Menelaus Perdikeas (ESAC)</li>
<li>Fran&#x00e7;ois-Xavier Pineau (CDS)</li>
<li>Roy Platon (RAL)</li>
<li>James Price (Bristol)</li>
<li>Anita Richards (Jodrell Bank)</li>
<li>Aaron Robotham (Bristol)</li>
<li>Yannick Roehlly (OAMP)</li>
<li>Mike Read (ROE)</li>
<li>Mattia Vaccari (Western Cape)</li>
<li>Juande Sandander Vela (IAA-CSIC)</li>
<li>Mike Watson (Leicester)</li>
<li>Ivan Zolotukhin (SAI MSU)</li>
<li>Jonathan Zwart (Columbia)</li>
</ul>
</p>

<p>If you use this software in published work, the following citation
would be appreciated:
<blockquote>
<webref url="http://adsabs.harvard.edu/abs/2005ASPC..347...29T"
                                          >2005ASPC..347...29T</webref>:
M. B. Taylor, "TOPCAT &amp; STIL: Starlink Table/VOTable Processing Software",
in Astronomical Data Analysis Software and Systems XIV,
eds. P Shopbell et al., ASP Conf. Ser. 347, p. 29 (2005)
</blockquote>
</p>

</subsect>

<subsect id="versions">
<subhead><title>Version History</title></subhead>

<p>Releases to date have been as follows:
<dl>

<dt>Version 0.3b (4 June 2003)</dt>
<dd><p>First public release
</p></dd>

<dt>Version 0.4b (8 July 2003)</dt>
<dd><p>
<ul>
<li>Row subset count column in subsets window.</li>
<li>Fixed and improved broken Parameter window.</li>
<li>Fixed output of table name and parameters.</li>
<li>Output to LaTeX <code>tabular</code> environment now available.</li>
<li>SQL access buttons now greyed out when no JDBC drivers are present.</li>
<li>UCD selection now available from New Synthetic Column dialogue.</li>
<li>Column metadata display made more logical and flexible.</li>
<li>Column cardinality now calculated in Stats window.</li>
<li>Sythetic column expressions and most other column metadata now
    editable.</li>
<li>Null value support in evaluated expressions.</li>
<li>Integral example data provided.</li>
<li>Hierarchical browser for tables available in load dialogue.</li>
</ul>
</p></dd>

<dt>Version 0.4-1b (10 July 2003)</dt>
<dd><p>
<ul>
<li>Fixed a VOTable output bug (not escaping XML special characters).</li>
<li>Fixed a serious FITS output bug.</li>
<li>Improved bad value handling for FITS tables.</li>
</ul>
</p></dd>

<dt>Version 0.5b (20 October 2003)</dt>
<dd><p>
<ul>
<li>Can now read plain text format tables.</li>
<li>FITS files of arbitrary size can now be read
    (they are not loaded into memory).</li>
<li>TOPCAT can now run without errors in a secure environment
    (e.g. as an unsigned jar file under WebStart).  Of course some actions
    such as Save Table are unavailable in this context.</li>
<li>Files compressed with Unix <code>compress</code> now work
    (as well as gzip and bzip2).</li>
<li>Added hierarchy browser to load dialog.</li>
<li>Added integral demo data (accessible from load dialog).</li>
<li>Can now drag tables from
    <webref url="http://www.starlink.ac.uk/treeview/">Treeview</webref>
    into TOPCAT load dialog (or load button).</li>
<li>Some bugfixes.</li>
</ul>
</p></dd>

<dt>Version 0.5-1 (18 November 2003)</dt>
<dd><p>
<ul>
<li>Rewrite of FITS binary table access for big efficiency improvements.</li>
<li>It's now possible to plug in user-defined algebraic methods at runtime.</li>
<li>Improved unit testing leads to some bugfixes.</li>
</ul>
</p></dd>

<dt>Version 1.1-0 (21 April 2004)</dt>
<dd><p>
<ul>
<li>User interface redesigned - now based around Control Window 
    not table browser (much easier to work with multiple tables).</li>
<li>Extensive facilities for table joining by matching rows between 
    multiple tables or within a single one.</li>
<li>Documentation much improved and available on- or off-line as 
    <docxref doc="sun253"/>.</li>
<li>Self-contained table access library 
    <webref url="http://www.starlink.ac.uk/stil/">STIL</webref> now provided
    as a separate product.</li>
<li>Tables can be concatenated.</li>
<li>Better top-level control over window proliferation.</li>
<li>Columns can now be hidden/revealed not just deleted.</li>
<li>Additional output formats/variants supported:
    <ul>
    <li>VOTable using BINARY or FITS encoding, inline or by reference</li>
    <li>Machine-readable plain ASCII stream</li>
    <li>HTML &lt;TABLE&gt; element or document</li>
    </ul>
</li>
<li>Hybrid DOM/SAX parsing of VOTables for improved efficiency/memory usage.</li>
<li>New flag <code>-demo</code> starts up with demo data.</li>
<li>Miscellaneous efficiency improvements and bug fixes.</li>
</ul>
</p></dd>

<dt>Version 1.1-3 (5 May 2004)</dt>
<dd><p>
<ul>
<li>Functions provided for radians&lt;-&gt;sexagesimal conversion</li>
</ul>
</p></dd>

<dt>Version 1.3 (20 October 2004)</dt>
<dd><p>This version has introduced many improvements in scalability,
efficiency and functionality.  TOPCAT is now quite happy with tables
of a million rows or more (and hundreds of columns) even on systems 
with quite modest memory/CPU resources.
The main improvements are as follows:
<dl>

<dt>Plotting</dt>
<dd><p>
    <ul>
    <li>Plotting is much faster and can handle many more points</li>
    <li>Subsets can be selected from plot window by tracing out a 
        non-rectangular region</li>
    <li>You have more choice over plotting symbols
        (including semi-transparent ones)</li>
    <li>Finally X or Y axes can be flipped!</li>
    <li>Export to encapsulated PostScript is of improved quality
        (though for many points file sizes can get large)</li>
    <li>Export to GIF format is available</li>
    <li>Regression lines can be plotted and coefficients displayed
        (experimental capability - could be improved)</li>
    </ul>
    </p></dd>

<dt>Table Formats</dt>
<dd><p>
    <ul>
    <li>"<code>-disk</code>" flag allows use of disk backing storage for
        large tables</li>
    <li>New 'FITS-plus' format stores rich table/column metadata in a
        FITS file</li>
    <li>VOTable handler now fully VOTable 1.1 and 1.0 compatible</li>
    <li>VOTable parsing now works with Java 5.0 platform</li>
    <li>Comma-Separated Value format now supported for input and output</li>
    <li>ASCII input handler rewritten to cope with much larger tables</li>
    <li>ASCII handler now understands d/D as exponent letter as well as e/E</li>
    <li>ASCII handler now uses Short/Float not Integer/Double where 
        appropriate to save memory</li>
    <li>ASCII format fixed bug for -0 degrees/hours in sexagesimal
        angles</li>
    <li>Null handling improved for FITS &amp; VOTable formats</li>
    <li>FITS files store column descriptions in TCOMMx headers</li>
    <li>Better error messages for unparsable tables</li>
    </ul>
    </p></dd>

<dt>Table Joins</dt>
<dd><p>
    <ul>
    <li>Various efficiency improvements and reductions in memory 
        requirements</li>
    <li>In cases of multiple possible matches, the closest is now chosen
        rather than picking one at random</li>
    <li>Pair match now adds column containing score for each match
        (distance between points)</li>
    <li>Units can be selected RA/Dec columns and match errors 
        (so it doesn't need to be all in radians)</li>
    <li>New match types suitable for multivariate matching 
        (anistropic Cartesian, Sky+X, Sky+XY)</li>
    </ul>
    </p></dd>

<dt>Data/Metadata Manipulation</dt>
<dd><p>
    <ul>
    <li>Can add/remove table parameters</li>
    <li>One-step column replacement dialogue from data or column 
        windows</li>
    <li>Synthetic column expressions now written out to column
        descriptions</li>
    </ul>
    </p></dd>

<dt>GUI Navigation and Display</dt>
<dd><p>
    <ul>
    <li>Improved rendering of numbers in tables (esp. Floats)</li>
    <li>Better detection of displayed table column widths</li>
    <li>New Control Window option on File menus</li>
    <li>Better window resizing for some dialogue boxes</li>
    <li>Less confusing error messages in many places</li>
    </ul>
    </p></dd>

<dt>Algebraic Expressions</dt>
<dd><p>
    <ul>
    <li>All available functions are now fully documented in help document
        and interactive Method Window</li>
    <li>Many new trig, coordinate, type conversion, string manipulation 
        functions</li>
    <li>Big performance improvements for null values</li>
    </ul>
    </p></dd>

<dt>Activation Actions</dt>
<dd><p>
    <ul>
    <li>Clicking a point in the plot highlights the corresponding row in the
        data window and vice versa</li>
    <li>Row selection can trigger display sky cutout region display</li>
    <li>Row selection can trigger user-defined actions on activation</li>
    </ul>
    </p></dd>

</dl>
</p>

<p>In addition, the following incompatibilities and changes have been
introduced since the last version:
<ul>
<li>The input format for tables can now be specified in the load window
    (via a selection box) or on the command line
    (using the "<code>-f</code>" flag).  FITS files and VOTables can
    still be identified automatically (i.e. it's not necessary to 
    specify format in this case) but ASCII tables cannot:
    you <em>must</em> now specify the format when loading ASCII tables.
    This change allows better error messages and support for 
    more text-like formats.</li>
<li>Algebraic expressions referencing row subsets now use the 
    underscore character ("_") rather than the hash character ("#")
    to indicate a subset ID.</li>
<li>Classes containing user-supplied functions for algebraic expressions
    are now specified using the properties "<code>jel.classes</code>"
    and "<code>jel.classes.activation</code>", 
    not "<code>gnu.jel.static.classes</code>".</li>
<li>The default output format for FITS tables is now the so-called
    "FITS-plus" format, which has a BINTABLE in its first extension 
    as before, but the text of a VOTable stored in its primary HDU.  
    This can store more metadata for TOPCAT, but should behave just
    the same for other FITS-compatible applications.
    The old behaviour can be restored if desired by specifying "FITS-basic" 
    format.</li>
</ul>
</p></dd>

<dt>Version 1.3-1 (10 November 2004)</dt>
<dd><p>Minor changes:
<ul>
<li>2MASS cutout servers now available from Activation Window</li>
<li>Added Starlink logo to all windows</li>
</ul>
</p></dd>

<dt>Version 1.3-2 (6 Dec 2004)</dt>
<dd><p>Bug fix:
<ul>
<li>Error in parsing empty VOTable TD elements fixed.</li>
</ul>
</p></dd>

<dt>Version 1.4 (4 Feb 2005)</dt>
<dd><p><dl>

    <dt>Load Dialogues</dt>
    <dd><p>The graphical table load dialogue has been overhauled, and now
        has two main new features.  First, it has been rewritten so that
        the GUI does not freeze during a long load; it is still currently
        not possible to interact with other TOPCAT windows while a load is
        taking place, but you can now cancel a load that is in progress.
        </p>

        <p>Secondly, the provision of load dialogues has been modularised,
        and a number of new dialogues provided.  The new ones are:
        <ul>
        <li><ref id="ConeSearchDialog">Cone Search</ref></li>
        <li>MySpace Browser</li>
        <li>Registry Query</li>
        <li>SIAP Query</li>
        </ul>
        If the required classes are present, you can acquire tables from 
        these external sources as well as the traditional methods of loading
        from disk etc.  New command line flags corresponding to each 
        of these have been added to ensure that they are present and
        make them prominent in the load dialogue. 
        Furthermore it is possible to plug in additional load dialogues at
        runtime using the <code>startable.load.dialogs</code> system property.
        </p>

        <p>The appearance of the <label>Load Window</label>
        has changed; now only the <label>File Browser</label> button
        is visible along with the <label>Location</label> field in the
        body of the window, but the <label>DataSources</label> menu
        can be used to display other available table import dialogues.
        </p></dd>


    <dt>Packaging</dt>
    <dd><p>The program can now be obtained in two standalone forms:
        <code>topcat-full.jar</code> and <code>topcat-lite.jar</code>.
        The former is much larger than before (11 Mbyte), 
        since it contains a number
        of classes to support custom load dialogues such as the MySpace
        browser and web service interaction, as well as the SoG classes.
        The latter contains only the classes for the core functionality,
        and is much smaller (3 Mbyte).
        </p></dd>

    <dt>Explode Array Column action</dt>
    <dd><p>There is now a new button in the 
        <ref id="ColumnInfoWindow">Columns Window</ref> which replaces an
        array-valued column with a scalar column for each of its elements.
        </p></dd>

    <dt>Paste'n'Load</dt>
    <dd><p>You can now load a table by pasting its filename or URL as
        text into the table list in the Control Window (using the X selection
        on X-windows - not sure if or how this works on other platforms).
        </p></dd>

    <dt>Help message</dt>
    <dd><p>The result of <code>topcat -help</code> is now more comprehensive,
        describing briefly what each option does and listing system
        properties as well as arguments/flags proper.
        </p></dd>

    </dl></p></dd>

<dt>Version 1.4-1 (8 February 2005)</dt>
<dd><p>
    <ul>
    <li>Added Search Column item to Data Window column popup menu</li>
    </ul>
    </p></dd>

<dt>Version 1.5 (17 March 2005)</dt>
<dd>
<p><dl>
  <dt>File Access</dt>
  <dd><p>Load dialogues have changed again somewhat, and save 
      dialogues as well.
      The default file browser in both cases is now a
      <em>Filestore Browser</em>,
      which is very much like the standard file browser, but can browse files
      in remote filesystems as well; currently supported are files in 
      AstroGrid's 
      <webref url="http://www.astrogrid.org/maven/docs/HEAD/mySpace/"
              >MySpace</webref>
      or on an 
      <webref url="http://www.sdsc.edu/srb/">SRB</webref>
      (Storage Resource Broker) server.
      You can now save files to these remote locations as well as
      load from them.
      </p>

      <p>In addition, the save dialogue now displays the current row
      subset and sort order - this makes it easier to see and/or
      change the details of the table you're about to save.
      </p>
  </dd>

  <dt>BugFixes</dt>
  <dd><p>A few more minor changes have been made.
    <ul>
      <li>Error display dialogue boxes have been improved in some places</li>
      <li>Various bugs relating to JDBC database access have been fixed</li>
      <li>Some minor issues relating to VOTables with single-character
          columns have been addressed</li>
    </ul>
  </p></dd>
</dl></p>
</dd>

<dt>Version 1.6 (30 June 2005)</dt>
<dd><p><dl>

  <dt>Activation Actions</dt>
  <dd><p>Some more activation functionality has been added:
    <ul>
      <li>New <label>View URL as Web Page</label> option introduced in 
          Activation Window</li>
      <li>New <label>System</label> class of activation functions containing
          <code>exec</code> functions which execute commands on the local
          operating system</li>
      <li>New <label>Browsers</label> class of activation functions for 
          displaying URLs in web browsers (external or basic fallback one)</li>
    </ul>
  </p></dd>

  <dt>Algebraic Functions</dt>
  <dd><p>New <label>Times</label> class added containing functions for
      converting between Modified Julian Day and ISO 8601 format epochs.
      </p></dd>

  <dt>Sky Matching</dt>
  <dd><p>The default sky matching algorithm now uses HEALPix rather than
      HTM for assigning sky pixels to RA,Dec positions.  This gives much
      faster sky matches in most cases, and uses somewhat less memory 
      so can be used on larger tables.  It has also fixed a bug
      which missed out some possible matches.  HTM-based matching 
      is currently still provided as an option, but this is mainly
      for debugging purposes and may be withdrawn in the future.
      </p></dd>

  <dt>Logging</dt>
  <dd><p>The message logging has been tidied up.  The main observable
      consequence of this is that fewer untidy messages are written to
      the console when TOPCAT is run from a standalone jar file
      rather than a full starjava installation.
      By specifying the new <code>-verbose</code> (or <code>-v</code>) 
      flag one or more times you can get those messages back.
      The messages (in fact all logging messages at any level) 
      can also be viewed from the GUI by using the new
      <label>File</label>|<label>Show Log</label> menu option from the
      Control Window.
      </p></dd>

  <dt>SOAP Services</dt>
  <dd><p>TOPCAT now acts as a SOAP server; SOAP requests can now be made
      to a running instance of TOPCAT to get it to display tables by 
      location or by sending XML for a VOTable direct.  Because of 
      limitations in Axis, this latter method won't work for arbitrarily
      large tables.
      </p></dd>

  <dt>Documentation changes</dt>
  <dd><p>The <code>tablecopy</code> tool is no longer covered in this
      document; it is replaced by the <code>tcopy</code> tool in 
      the separate
      <webref url="http://www.starlink.ac.uk/stilts/" plaintextref="yes"
              >STILTS</webref> package.
      There has also been some reorganisation of this document, mainly
      in the appendices.
      </p></dd>

  <dt>Minor changes</dt>
  <dd><p>
    <ul>
      <li>Added <code>-version</code> flag</li>
      <li>Added (dummy) <label>Print</label> option to Data Window.
          This just presents a message to the effect that you should save
          to a printable format.</li>
      <li>Fixed a bug which gave errors when expressions contained a 
          <code>NULL_</code> test on the first column of a table.</li>
      <li>Modified one of the demo tables to contain a column with URLs
          in it.</li>
    </ul>
  </p></dd>

</dl></p></dd>

<dt>Version 1.6-1 (7 July 2005)</dt>
<dd><p>Bugfixes:
<ul>
<li>Work around AstroGrid/Sun bug which prevented loading short VOTables 
    from MySpace.</li>
<li>Ensure that filestore browsers are kept up to date when dialogues are
    displayed.</li>
</ul>
</p></dd>

<dt>Version 1.7 (30 September 2005)</dt>
<dd><p><dl>

  <dt>Crossmatching</dt>
  <dd><p>There have been major improvements in the flexibility, and 
      minor improvements to performance, of two-table crossmatching.
      <ul>
      <li>New match algorithm <label>Sky with Errors</label> introduced.
          This allows you to specify a column giving the maximum 
          permissible match error (so it can vary per row) rather 
          than a fixed value for the whole table.</li>
      <li>In the case of multiple possible matches between the two tables,
          instead of automatically giving you only the closest match, you can
          now select whether you'd like only the closest one or all 
          those which fit your criteria.</li>
      <li>You can now specify which rows you want to see in the output:
          1 and 2, 1 or 2, All from 1, All from 2, 1 not 2, 2 not 1, 1 xor 2.
          This is pretty much all the possibilities which make sense, 
          and in particular allows you to do 'left outer joins'
          (1 not 2).</li>
      <li>The match score column which results from most matches
          now comes (a) in sensible units where possible (e.g. arcseconds
          not radians) and (b) with metadata which tells you what its
          meaning and units are.</li>
      <li>More information is available in added columns after the match;
          as well as the match score, information about matched groups
          is inserted where appropriate.</li>
      <li>The "Spherical Polar" match algorithm is now rebadged as the
          hopefully less confusing "Sky 3d".</li>
      </ul>
      Similar changes for 1-table and multi-table matches should follow
      in future versions.
      </p></dd>

  <dt>MySpace Access</dt>
  <dd><p>MySpace I/O has been re-implemented to use the ACR rather than
      the (now deprecated) CDK classes it was using before.  As well
      as probably being more reliable and less likely to break with 
      future changes in MySpace server protocols, this gives the benefit
      of single sign on.  The effect of this is that you will need to have
      the AstroGrid desktop running on your machine before you can 
      access MySpace from TOPCAT.
      </p></dd>

  <dt>Algebraic functions</dt>
  <dd><p><ul>
    <li>Added Julian Epoch and Besselian Epoch conversion functions to
        <code>Times</code> class.</li>
    <li>Added <code>RANDOM</code> special function.</li>
  </ul></p></dd>

  <dt>Miscellaneous</dt>
  <dd><p><ul>
    <li>When you select a column in the Columns window, it now scrolls the
        table in the Data Window so that the selected column is visible.
        This is a boon when dealing with tables that have very many
        columns.</li>
    <li>String "<code>null</code>" interpreted as a blank value in ASCII 
        tables.</li>
    <li>Added new activation action to launch system default browser.</li>
  </ul></p></dd>

  <dt>Bugfixes</dt>
  <dd><p><ul>
    <li>Fixed some relatively harmless bugs to do with actions available
        when you select the dummy "Index" column.  You can now unsort 
        from a popup menu in the table viewer window.</li>
    <li>Believed to work fine with Java 1.5 now (there were previously
        some issues with MySpace at Java 1.5).</li>
    <li>Fixed bug in ASCII input handler which misidentified blank lines,
        or DOS-format line ends, as end of file.</li>
  </ul></p></dd>

</dl></p></dd>

<dt>Version 1.7-1 (4 October 2005)</dt>
<dd><p>Bugfixes:
<ul>
<li>Fixed broken MySpace access on MS Windows.</li>
</ul>
</p></dd>

<dt>Version 1.8 (13 October 2005)</dt>
<dd><p>
<ul>
<li>Added <label>Sky Coordinates Window</label>; it's now easy to 
    add new sky coordinate columns based on old ones in different
    coordinate systems.</li>
<li><code>roundDecimal</code> and <code>formatDecimal</code> functions
    introduced for more control over visual appearance of numeric values.</li>
<li>Now copes with 'K'-format FITS binary table columns (64-bit integers).</li>
<li>Modifications to JNLP files.</li>
</ul>
</p></dd>

<dt>Version 2.0 (3 February 2006)</dt>
<dd><p>A major upgrade of TOPCAT's visualisation capabilities has taken
    place in this release.  There are considerable improvements in 
    functionality, flexibility and efficiency over previous versions:
    <dl>

    <dt>New graphics windows</dt>
    <dd><p> In addition to the 2-d scatter plot from previous versions,
        the following visualisation windows are now available:
        <ul>
        <li><ref id="HistogramWindow">Histogram</ref> (1-d)</li>
        <li><ref id="Cartesian3DWindow">3-d Cartesian scatter plot</ref></li>
        <li><ref id="SphereWindow">3-d Spherical scatter plot</ref>
            (with optional radial dimension)</li>
        <li><ref id="DensityWindow">2-d Density map</ref> (2-d histogram)</li>
        </ul>
        The new 3-d functionality does <em>not</em> require you to install
        Java3D or any other third-party 3D toolkit to work (nor does it
        take advantage of any such toolkit which may be present).
        </p></dd>

    <dt>Multi-dataset/multi-table plotting</dt>
    <dd><p>The plot windows are no longer associated with a single table.
        All of them allow you to display data from different tables,
        or from different tuples of columns of the same table, 
        on the same plot.
        You can layer as many plots as you like on the same axes,
        using different plotting styles for the different datasets.
        As before, you can still display data from different subsets
        of the same table and same columns using different styles.
        </p></dd>

    <dt>Plotting Styles</dt>
    <dd><p>All the graphics windows allow you to set the plotting style
        for each data set individually, using a wide range of options
        including colour, line width, marker size, (histogram) bar style, etc.
        This allows you considerable control over the visual details of the
        plots.
        </p></dd>

    <dt>Transparent markers</dt>
    <dd><p>All the 2-d and 3-d scatter plots allow you to render points
        using markers of variable transparency.  In a crowded plot, this
        allows you to see much more information than using opaque points,
        since you can get some idea of how many points (of different data
        sets) have been drawn at a given point on the plotting surface.
        </p></dd>

    <dt>Line drawing &amp; linear correlation</dt>
    <dd><p>The 2-d scatter plot can now optionally plot lines associated
        with data sets.  It can either draw straight line segments joining
        all the plotted points in a set, or draw per-dataset linear 
        correlation lines.  In the latter case it will report line 
        gradient, intercept and correlation coefficient.
        </p></dd>

    <dt>Improved column selection</dt>
    <dd><p>The selector boxes for selecting which columns to plot are
        now 'editable' - that is, instead of selecting the column from
        a drop down list it is now also possible to type an expression 
        into them instead.  This may be more convenient if there is a
        very long list of columns.  It also means that you can use an
        algebraic expression based on the names of one or more columns
        instead of a simple column name.
        The selectors also have small arrow boxes next to them which 
        makes it easy to cycle through the list of known columns.
        These features are also available at some other places in the
        program where a column value is required.
        </p></dd>

    <dt>Manual axis configuration</dt>
    <dd><p>As well as zooming in and out using the mouse, you can now 
        set the axis limits by typing them into an
        <ref id="axisConfig">axis dialogue box</ref>.
        You can also set the text which will form the axis annotation
        on the plot.
        </p></dd>

    <dt>Status line</dt>
    <dd><p>Most plots now feature a panel at the bottom of the window
        indicating how many points have been plotted and the current
        position of the mouse pointer (if any) on the plotting surface.
        </p></dd>

    <dt>Performance</dt>
    <dd><p>Scatter plots of large datasets now use considerably less memory
        and around an order of magnitude less CPU time than previously
        (a 2-d million point replot now takes about 1 second - plotting
        it the first time may be rather longer since it needs to acquire
        the data which may be I/O intensive).
        </p></dd>
        
    </dl>
    </p>

    <p>Some non graphics-related improvements have also been made as follows:
    <ul>
    <li>Selection of a subset in the Control Window now triggers its selection
        in other windows (plot, statistics, subsets).  The same thing doesn't
        happen the other way around, since that might lead to confusing 
        consequences.
        </li>
    <li>Boolean columns now display null values distinctly from false ones.
        Additionally, null/false distinctions are handled more carefully in
        FITS and VOTable files.
        </li>
    <li>The Sky Coordinates Window now suggests names for new columns.
        </li>
    <li>The Filestore Browser now allows you to enter the position 
        in a file of the table to load (e.g. HDU index for FITS 
        or TABLE index for VOTable).
        </li>
    <li>Added Hide All &amp; Reveal All actions to the Columns window.
        </li>
    <li>When joining tables, column name comparison to determine whether
        deduplication is required is now case-insensitive.
        </li>
    <li>Fixed a problem which was causing TOPCAT to crash when attempting 
        to save an altered copy of a FITS file under the same name.
        </li>
    <li>The manual has been reorganised somewhat, and a new
        <ref id="quick" plaintextref="yes">Quick Start</ref> section added.
        </li>
    <li>There is an experimental implementation of the Aladin 
        interoperability interface.  This hasn't really been tested however,
        so may not work.  Improved Aladin interoperability is expected in 
        future releases.
        </li>
    <li>Fixed a bug in Cartesian crossmatching algorithms which failed
        to match if the required error in any dimension was zero.</li>
    </ul>
</p></dd>

<dt>Version 2.1 (7 April 2006)</dt>
<dd><p>A number of graphical and other improvements have been made
    at this release.
    <dl>

    <dt>Stacked Line Plot</dt>
    <dd><p>A new 
        <ref id="LinesWindow" plaintextref="yes">Stacked Line Plot</ref>
        visualisation window has been added.  This is especially 
        suitable for use with time series data.
        </p></dd>

    <dt>Asynchronous data reading in graphics windows</dt>
    <dd><p>All the graphics windows now read data for plotting asynchronously.
        What this means is that when you change the plot in a way which 
        requires the data to be read or re-read then the GUI will not
        lock up and you can do other things, including changing the
        plot in other ways before it has completed drawing.  
        A progress bar at the bottom of the window indicates progress.
        This is only noticeable for large (slow to read) files.
        </p></dd>

    <dt>Axis Zooming</dt>
    <dd><p>The existing Histogram, 2-D Scatter Plot and Density Map windows,
        as well as the new Stacked Line Plot, now allow you to do a 1-d zoom 
        by dragging the mouse near the axis, as well as the 2-d zoom by
        dragging on the plot surface.
        </p></dd>

    <dt>PLASTIC Tool Interoperability</dt>
    <dd><p>TOPCAT now sends and services messages using the 
        PLatform for AStronomical Tool InterConnection protocol.
        See <ref id="interop"/>.
        </p></dd>

    <dt>IPAC Data Format</dt>
    <dd><p>Data files in the <ref id="inIpac">IPAC</ref> format
        defined by the CalTech's Infrared Processing and Analysis Center
        can now be read.  This is how data from the Spitzer satellite 
        amongst others is normally provided.
        </p></dd>

    <dt>String-typed coordinate columns</dt>
    <dd><p>If suitably identified (e.g. by UCD or units), string-valued
        columns which represent data in certain well-known forms,
        currently sexagesimal angles and ISO-8601-format dates, 
        can now be treated directly as numeric values in column selector
        boxes such as the ones in the plotting windows, rather than 
        having to define a new column using a string-&gt;numeric converter.
        </p></dd>

    <dt>Memory Error Reporting</dt>
    <dd><p>When the JVM runs out of memory, it now attempts to post a 
        popup window explaining this rather than just writing 
        a terse message to the console.  This popup also gives you the
        opportunity to view a new section added to the documentation:
        <ref id="largeTables" plaintextref="yes">Tips for Large Tables</ref>.
        </p></dd>

    <dt>SOAP Service deprecated</dt>
    <dd><p>TOPCAT no longer by default runs a SOAP server for accepting tables.
        You can choose to run it by specifying the <code>-soap</code>
        flag on the command line.  This facility may be withdrawn in 
        future versions, in view of the fact that the PLASTIC service
        can provide similar functionality.
        </p></dd>

    <dt>Logo fade</dt>
    <dd><p>The Starlink logo at the top of every window is set to fade
        out gradually over the period 1-APR-2006 to 1-SEP-2006.
        </p></dd>

    <dt>Bug fixes and minor alterations</dt>
    <dd><p>
        <ul>
        <li>Export of GIF and Encapsulated PostScript images from the
            graphics windows has been improved - unwanted grey backgrounds
            round the edges are now rendered transparent in GIFs and 
            white in EPS.  A section on 
            <ref id="exportGraphics" plaintextref="yes">Exporting
            Graphics</ref> has also been added to the manual.</li>
        <li>A number of graphical anomalies such as the plot bounds being reset
            when an axis Flip button was toggled have been ironed out.</li>
        <li>The JDBC behaviour has been improved: some bugs have been fixed
            and it now no longer asks for an SQL username/password twice.</li>
        <li>Work around intermittent bug when loading small files from
            MySpace.</li>
        <li>Density maps are now exported into FITS format with better 
            WCS headers where appropriate.</li>
        <li>The SDSS JPEG cutout activation action URL has been updated 
            from DR2 to DR4.</li>
        <li>A bug which caused the first row in a table to be included
            erroneously in graphical subset selections has been fixed.</li>
        <li>Added an offset selector toggle button to the Histogram window.</li>
        </ul>
    </p></dd>
    </dl>
    </p></dd>

<dt>Version 2.1-1 (13 April 2006)</dt>
<dd><p>
    <dl>
    <dt>Sphere Zoom</dt>
    <dd><p>You can now zoom in the <ref id="SphereWindow">Spherical Plot</ref>.
        </p></dd>

    <dt>PLASTIC</dt>
    <dd><p>There are some improvements to the PLASTIC functionality and
        documentation.
        <ul>
        <li>In addition to <label>Broadcast</label> actions for the various
            PLASTIC messages transmission types, there are now corresponding
            <label>Send</label> actions which allow you to direct the message
            to only a single selected listener application.
            These actions are now enabled/disabled according to whether 
            any suitable PLASTIC listeners are registered.</li>
        <li>You can now pop up a little window from the
            <label>Control Window</label>'s <label>Interop</label> menu
            which displays the currently registered PLASTIC listeners.
            The functionality of this window may be extended in future
            releases.</li>
        <li>When TOPCAT receives a <code>showObjects</code> message, 
            it now checks if a matching subset exists rather than always 
            creating and adding a new one.  If it does, it just sets current
            the existing one.  This can cut down (a bit) on proliferation 
            of Row Subsets.</li>
        <li>The <ref id="interop">PLASTIC section</ref> of the manual has
            been improved.</li>
        <li>Some of the screenshots have been updated to include 
            PLASTIC-related features.</li>
        <li>URLs using the <code>file:</code> scheme sent by TOPCAT in 
            PLASTIC messages now correctly conform to RFC 1738.</li>
        </ul>
        </p></dd>

    <dt>MySpace</dt>
    <dd><p>A workaround has been introduced for MySpace browsing
        performance problems.
        Run with <code>-Dmyspace.cache=true</code> to speed it up at the
        expense of accuracy.
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 2.1-2 (21 April 2006)</dt>
<dd><p>This is mainly a bug fix release.
    <ul>
    <li>Added explode columns option to Data Window popup menu.</li>
    <li>Fix bug present since v2.0 which was sometimes drawing wrong numeric
        labels near zero in 2D plots.  
        A side effect is that exponential multipliers will more often be
        used on axis labels (as in versions prior to v2.0).
        Hopefully somewhat improved axis labelling will be present in
        future versions.</li>
    <li>Fixed bug which was writing unclosed LINK elements in VOTables.</li>
    <li>Fixed some NullPointerException bugs in column selection and 
        2D plot.</li>
    <li>Fixed bug in scrolling to correct column in Data Window when column
        is selected in Columns Window.</li>
    </ul>
    </p></dd>

<dt>Version 2.1-3 (11 May 2006)</dt>
<dd><p>Bug fixes and some minor enhancements.
    <ul>
    <li>Implements send and receive of PLASTIC 
        <code>ivo://votech.org/votable/highlightObject</code> message.</li>
    <li>Added new <code>csv-noheader</code> output format.</li>
    <li>Added skew and kurtosis calculations to 
        <ref id="StatsWindow">Statistics Window</ref>.</li>
    <li>Improved, though still imperfect, retention of table-wide 
        metadata in VOTables.</li>
    <li>Fixed bug in writing <code>votable-fits-href</code> and
        <code>votable-binary-href</code> format tables from the file 
        browser.</li>
    <li><code>mark.workaround</code> system property,
        see <ref id="jvmProperties"/>.</li>
    </ul>
    </p></dd>

<dt>Version 2.2 (7 July 2006)</dt>
<dd><p>
    <dl>

    <dt>Column-oriented storage</dt>
    <dd><p>New features for permitting column-oriented storage
        (<ref id="outColfits">colfits</ref> format, 
        <code>startable.storage</code> policy "<code>sideways</code>") 
        have been introduced.
        These can provide considerable efficiency improvements for
        certain tasks when working with very large (and especially wide)
        tables. 
        </p></dd>

    <dt>Bug fixes</dt>
    <dd><p>
        <ul>
        <li>Fixed bug which caused some points to be missed out in spherical
            plots.</li>
        <li>ISO-8601 strings now permit times of 24:00:00 as they should.</li>
        <li>Quoted unit values are examined to determine probable column
            data types.</li>
        </ul>
        </p></dd>

    <dt>Other items</dt>
    <dd><p>
        <ul>
        <li>Added flux conversion functions (Jansky&lt;-&gt;magnitude).</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 2.2-1 (3 August 2006)</dt>
<dd><p>
    <ul>
    <li>Added new coordinate system ICRS for sky coordinate conversions.</li>
    <li>Eliminated some unsightly but harmless stack dumps that could 
        occur during plotting.</li>
    <li>TUCDnn header cards now used in FITS files to transmit UCDs
        (non-standard mechanism).</li>
    <li>Added TST (Tab-Separated Table) format 
        <ref id="inTst">input</ref> and 
        <ref id="outTst">output</ref> handlers.</li>
    <li>Efficiency improvements for column-oriented access.</li>
    <li>Improved responsiveness when viewing table data for extremely
        large tables.</li>
    </ul>
    </p></dd>

<dt>Version 2.3 (5 October 2006)</dt>
<dd><p>
    Various modifications and improvements:
    <ul>
    <li>Removed Starlink logo from the top right corner of all TOPCAT windows,
        including screenshots in documentation.
        New logos (Starlink, Astrogrid, VOTech, Bristol) 
        are added in <strong>About</strong> window.</li>
    <li>Added new <label>Add Sample Subset</label>,
                  <label>Add Head Subset</label> and
                  <label>Add Tail Subset</label>
        utility tool buttons to the
        <ref id="SubsetWindow">Subset Window</ref>.</li>
    <li>Direct MySpace access using <code>ivo:</code> or <code>myspace:</code>
        URLs is now provided - see new <ref id="tableLocation"/>.</li>
    <li>Added time conversion functions between MJD and Decimal Year.</li>
    <li>ISO-8601 column numerical values (e.g. in plots) are now by default
        Decimal Year rather than Julian Epoch.  The numerical values are quite
        close, but Decimal Year is probably more what you'd intuitively 
        expect.</li>
    <li>Added <code>toHex</code> and <code>fromHex</code> numeric
        conversion functions.</li>
    <li>Added <code>-J</code> flag to <code>topcat</code> startup script
        for passing flags directly to Java.</li>
    <li>Added Sample (as opposed to Population) Standard Deviation/Variance
        calculation options to the Statistics Window.</li>
    <li>Improved listing for functions in <ref id="funcs"/> of user document
        (subsection for each function class).</li>
    <li>Modified presentation of HTML version of user document using CSS.</li>
    </ul>
    Bug fixes:
    <ul>
    <li>Fixed bug (introduced at v2.2-1) which made table display and adding
        columns slow, and column widths the wrong size.</li>
    <li>Fixed bug (introduced at v2.0) which prevented Exact matches using 
        non-numeric columns.  Exact match now also deals with array-valued
        columns.</li>
    <li>Fixed PLASTIC bug which was ignoring ID argument of
        <code>ivo://votech.org/votable/loadFromURL</code> message.</li>
    <li>Fixed bug in coordinate conversion that caused bad behaviour in the
        presence of malformed input coords.</li>
    <li>Fixed bug with plotting very large or very small axis labels in
        3-d plots.</li>
    <li>Fixed a couple of minor crossmatching bugs (which would not have
        affected results).</li>
    </ul>
    </p></dd>

<dt>Version 2.3-1 (Starlink Hokulei release)</dt>
<dd><p>
    <ul>
    <li>Output to MySpace can now be streamed, if running under J2SE1.5 or
        later.</li>
    <li>Intercept OutOfMemoryErrors during 3D plotting to give an explanatory
        popup.</li>
    <li>Fixed bug in axis range checking.</li>
    <li>Fixed bug in handling of single quotes in FITS file metadata.</li>
    <li>Concatenation column assignments now smarter for fully compatible
        input tables.</li>
    <li>Some optimisations for very large files.</li>
    <li>Added Vega&lt;-&gt;AB magnitude conversion constants to 
        <ref id="Fluxes">Fluxes</ref> functions.</li>
    <li>Encapsulated PostScript exported from graphics windows is improved.
        These files should now print when sent directly to a printer,
        and the image size is now guaranteed sensible for a portrait
        A4/letter page.</li>
    <li>Added hyperbolic trig functions
        (<code>sinh</code>, <code>cosh</code>, <code>tanh</code> and inverses)
        <ref id="Maths">Maths</ref> class
        (sinh, cosh, tanh and inverses).</li>
    <li>Added cosmology distance calculations in class
        <ref id="Distances">Distances</ref>.</li>
    </ul>
    </p>
    <p><strong>Graphics upgrades</strong>
    <ul>
    <li>Column selector panels in graphics windows are now in scrollers.</li>
    </ul>
    </p></dd>

<dt>Version 3.0 (5 July 2007)</dt>
<dd><p>This release includes major visualisation improvements and some changes
    to the plotting user interface:
    <dl>
    <dt>Error bars</dt>
    <dd><p>Comprehensive plotting of symmetric and asymmetric error bars 
        (and crosshairs, and boxes, and ellipses, ...) in 1, 2 and 3
        dimensional plots is now provided -- see <ref id="errorBars"/>.
        </p></dd>
    <dt>Auxiliary (colour) axes</dt>
    <dd><p>It is now possible to modify the colour of plotted points 
        according to values in one or more axes additional to the 
        spatial ones -- see <ref id="auxAxes"/>.
        </p></dd>
    <dt>Histogram Weighting</dt>
    <dd><p>The <ref id="HistogramWindow">Histogram</ref> and
        <ref id="DensityWindow">Density Map</ref> windows now have the
        option of weighting the quantity represented, so that
        the binned values are sums rather than just counts.
        </p></dd>
    <dt>Density Map Colour Scale</dt>
    <dd><p>When the density map is in indexed (non-RGB) mode you can now
        select from various colour maps to represent bin occupancy.
        This makes level differences easier to see.
        </p></dd>
    <dt>Plot window rearrangement</dt>
    <dd><p>Buttons which affect data selection are now arranged in their
        own toolbar below the plot (<ref id="PointSelector"/>).  
        The size of the plot control area can be manually resized to 
        give more room for the plot itself by using the
        <label>Split Window</label> (&IMG.SPLIT;) button, 
        which is useful on small screens.
        </p></dd>
    <dt>Expression language enhancements</dt>
    <dd><p>Table parameters can now be referenced in expressions using
        <code>&param.prefix;</code> notation (<ref id="jelParams"/>),
        and both columns and parameters can be referenced by UCD using
        <code>&ucd.prefix;</code> notation (<ref id="jelCols"/>).
        </p></dd>
    <dt>Statistics &amp; Histogram result re-use</dt>
    <dd><p>The <ref id="StatsWindow">Statistics</ref> and 
        <ref id="HistogramWindow">Histogram</ref> windows now both provide 
        <label>Save</label> and <label>Import</label> actions,
        which take the data presented in the window and allow it to be
        saved to a file or imported directly into TOPCAT as a new table.
        </p></dd>
    <dt>Cartesian 3D zoom</dt>
    <dd><p>It is now possible to zoom the 
        <ref id="Cartesian3DWindow">3D Plot</ref> towards the centre in the
        same way as the <ref id="SphereWindow">Spherical Plot</ref>.
        </p></dd>
    <dt>GAVO Millennium simulation database load dialogue</dt>
    <dd><p>You can now directly query the 
        <webref url="http://www.g-vo.org/Millennium"
                >GAVO Millennium database</webref> service 
        (<ref id="GavoTableLoadDialog"/>).  Thanks to Gerard Lemson of GAVO
        for contributing code for this.
        </p></dd>
    <dt>Row subset improvements</dt>
    <dd><p>Row Subset names can now be re-used, and when you are asked to
        select a new subset name you are allowed to choose one from the
        list of existing ones.  When a row selection is received from another 
        application via PLASTIC the subset name (the name of the sending 
        application) is re-used in this way.  This helps to keep the 
        number of subsets under control.
        </p>
        <p>Receving a row subset from PLASTIC in this way, and certain other
        actions, now cause the subset to be shown straight away 
        (and updated if necessary) on any existing plots, which makes
        this kind of PLASTIC interaction more responsive.
        </p>
        <p>The size of each subset, and also the corresponding percentage of
        the table it represents, is now calculated automatically and 
        displayed in the <ref id="SubsetWindow">Subset Window</ref>.
        The old behaviour of only calculating sizes on request can be
        reinstated using the <label>Autocount rows</label> (&IMG.RECOUNT;)
        menu item if required.
        </p></dd>
    <dt>Fix Vertical in 3D plots</dt>
    <dd><p>A <label>Stay Upright</label> (&IMG.NORTH;) button is provided
        in the <ref id="Cartesian3DWindow">Cartesian</ref> and 
        <ref id="SphereWindow">spherical</ref> 3D plots which allow 
        you to keep the Z axis/north pole vertical during rotations.
        </p></dd>
    <dt>Quantile calculation</dt>
    <dd><p>The <ref id="StatsWindow">Statistics Window</ref> can now 
        calculate quantiles (median, quartiles, .001, .01, .99 and .999)
        on request.
        </p></dd>
    <dt>Minor changes and bugfixes</dt>
    <dd><p>
    <ul>
    <li>JPEG and PNG now plot export available from all graphics windows.</li>
    <li>Dramatic performance improvement for transparent pixel plotting in 
        3D plots on some platforms.</li>
    <li>Added locale-specific <code>formatDecimalLocal()</code> functions in
        class <ref id="Formats">Formats</ref>.</li>
    <li>Added <code>fluxToLuminosity</code> and <code>luminosityToFlux</code>
        functions in class <ref id="Fluxes">Fluxes</ref>.</li>
    <li>Improved deduplication of column names when joining tables.</li>
    <li>3D plots now correctly report number of visible points.</li>
    <li>Improved error message for broken CSV files.</li>
    <li>Improved error reporting in the presence of a deficient JVM
        (such as GNU <code>gcj</code>).</li>
    <li>Worked around a Mac OSX Java bug which caused table display to
        go funny when columns were deleted.</li>
    <li>Fixed error in output of FITS table <code>TNULL</code><m>n</m> header
        cards - write them as numeric not string values.</li>
    <li>Fixed a number of bugs in responding to PLASTIC messages
        (threading, failure to respond).</li>
    <li>3D plots now plot symbols for all subsets not just one,
        as for 2D plots.</li>
    <li>Fixed bug which prevented non-string parameter values from
        being reassigned.</li>
    </ul>
    </p></dd>
    </dl>

    </p></dd>

<dt>Version 3.0-1 (Starlink Puana release)</dt>
<dd><p>
    <ul>
    <li>Added error bars capped by arrows.</li>
    <li>Fixed bug which caused error bars in legend to draw in the wrong colour
        in EPS output.</li>
    </ul>
    </p></dd>

<dt>Version 3.1 (29 August 2007)</dt>
<dd><p>
    <ul>
    <li>You can now annotate plotted points using 
        <ref id="labels" plaintextref="yes">text labels</ref> in
        2d and 3d scatter plots - use the <label>Draw Label</label>
        (&IMG.LABEL;) button to assign a column containing label text.</li>
    <li>Radial axis control in sphere plot is now not visible by default -
        you need to click the <label>Radial Coordinates</label> (&IMG.RADIAL;)
        button in the dataset toolbar to enable it.</li>
    <li>New <label>Show Legend</label> (&IMG.LEGEND;) button in plot windows
        determines whether a legend will be displayed next to the plot.</li>
    <li>New <label>Hide Legend</label> checkbox in style editor windows which 
        allows subset legend entries to be excluded from the displayed legend
        individually.</li>
    </ul>
    </p></dd>

<dt>Version 3.2 (28 January 2008)</dt>
<dd><p>
    <dl>
    <dt>Functionality enhancements</dt>
    <dd><p>
        <ul>
        <li>Considerably improved display of per-table metadata in the
            <ref id="ParameterWindow">Parameter Window</ref>.
            It is now possible to view long or multi-line parameter values.</li>
        <li>FITS header cards in table HDU are now read (but not written) 
            as table parameters.</li>
        <li>Add mouse wheel zoom for 3D plots.</li>
        <li>Add <label>Write Mode</label> selector to 
            <ref id="SQLWriteDialog">SQL Output Dialogue</ref>, to allow
            appending and optional drop prior to create of new table in 
            database.</li>
        <li>Now TOPCAT will automatically register with a PLASTIC hub any time
            one becomes available - the hub does not have to be running
            when TOPCAT starts.  As a corrollary, if you start an internal or
            external hub from the <label>Interop</label> menu, 
            you no longer need to explicitly invoke the 
            <label>Register</label> item afterwards.</li>
        <li>Add <code>-exthub</code> flag which starts a new external
            PLASTIC hub.</li>
        <li>Activation window permits selection of different image viewers
            for <label>View URL as Image</label> option.
            Note this is not currently provided for the 
            <label>Display Cutout Image</label> option - this may be
            addressed in the future.</li>
        </ul>
        </p></dd>
    <dt>Bugfixes and minor improvements</dt>
    <dd><p>
        <ul>
        <li>Added <code>-stilts</code> convenience flag so you can easily
            run STILTS from a TOPCAT installation.</li>
        <li>Fix calculation error in <code>fluxToLuminosity</code>
            function.</li>
        <li>Fix some bugs associated with text label plotting.</li>
        <li>Error bars for zero/negative values are now correctly extended
            to the axis (rather than being omitted)
            in 2D plots with logarithmic axes.</li>
        <li>Modified the size of some windows - now posts somewhat smaller 
            windows if a small screen is in use.</li>
        <li>System properties specified explicitly on command line now take
            precendence over those in <code>.starjava.properties</code>
            file.</li>
        <li>Embedded spaces in output ASCII format table column names 
            are now substituted with underscores, which prevents writing
            ASCII tables that cannot be read.</li>
        <li>Downgraded from WARNING to INFO log messages about 
            the (extremely common) VOTable syntax error of omitting 
            a FIELD/PARAM element's <code>datatype</code> attribute.</li>
        <li>Starting an external hub now works more reliably.</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 3.3 (19 August 2008)</dt>
<dd><p>
    <dl>
    <dt>Functionality enhancements:</dt>
    <dd><p>
        <ul>
        <li>Added normalisation option (&IMG.NORMALISE;)
            to <ref id="HistogramWindow">Histogram Window</ref>.</li>
        <li>In overplots using different tables, an attempt is now made
            to use the same columns/expressions for axis values as
            for the main table.  This may be convenient when 
            overplotting data from several similar tables.</li>
        <li>FITS files with columns using variable-length arrays
            ('P' or 'Q' data type descriptors) can now be read
            (in random access mode, i.e. from an uncompressed FITS file
            on disk, only).</li>
        <li>The <label>lut.files</label> system property can now 
            be used to configure custom colour maps for auxiliary axes
            and density maps - see <ref id="jvmProperties"/>.</li>
        <li>New class <ref id="Arrays">Arrays</ref>
            added to algebraic functions.</li>
        <li>Histogram <label>Offset</label> control now works for
            logarithmic X scale as well as linear.</li>
        </ul>
        </p></dd>
    <dt>Bug fixes and other changes:</dt>
    <dd><p>
        <ul>
        <li>Efficiency improvements (~25%? in both CPU time and 
            memory usage) for HEALPix-based sky crossmatching.
            Thanks to Nikolay Kouropatkine at Fermilab for a 
            new version of the 
            <webref url="http://home.fnal.gov/~kuropat/HEALPIX/PixTools.html"
                    >PixTools</webref> library
            which provided this improvement
            (this version also fixed a - minor? - HEALPix bug).</li>
        <li>Sexagesimal field identification for ASCII input files has
            become more forgiving; it now accepts minutes or seconds 
            equal to 60 without a syntax error.</li>
        <li>Fixed a pair matching performance bug (slower if tables were not 
            given in the right order) introduced at v1.4.</li>
        <li>The <code>-disk</code> flag is now honoured when loading 
            tables from JDBC, which makes it possible to input larger
            datasets from RDBMS.</li>
        <li>Fixed problem which caused the graphics system to hang or fail
            when drawing Dot-to-dot lines in 2D plot for points a very 
            long way off the screen.</li>
        <li>Fixed bug which caused incorrect plotting of cumulative
            histograms with small weights.</li>
        <li>Slight modification to spike-style bar drawing in Histogram,
            now has tidier appearance when using dashed lines.</li>
        </ul>
        </p></dd>
    <dt>Internal</dt>
    <dd><p>There has been extensive internal reorgamisation of the plotting
        classes.  There should be no user-visible effects of this, but
        please report anything which seems to be misbehaving.
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 3.4 (23 December 2008)</dt>
<dd><p>
    <dl>
    <dt>SAMP</dt>
    <dd><p>TOPCAT now uses 
        <webref url="http://www.ivoa.net/Documents/latest/SAMP.html"
                >SAMP</webref>
        as a (preferred) alternative to PLASTIC for inter-tool
        interoperability.  SAMP is now usually the default; the old behaviour
        can be recovered using the <code>-plastic</code> command-line flag.
        Although much of the messaging behaviour remains the same,
        various improvements to the GUI accompany this change:
        <ul>
        <li>New <ref id="sampPanel">SAMP Panel</ref> at the bottom of the
            Control Window summarising status</li>
        <li>New <label>SAMP Status</label> (&IMG.SAMP;) toolbar button in
            Control Window, which pops up new
            <ref id="SampWindow">SAMP Window</ref></li>
        <li>Other slight rerrangements of toolbar buttons and menu items
            in Control Window</li>
        <li><label>Broadcast Row</label> checkbox added near Activation Action
            in Control Window</li>
        </ul>
        For more discussion see <ref id="interop"/>.
        </p></dd>
    <dt>Registry Access</dt>
    <dd><p>TOPCAT's registry access has finally been updated to use 
        VOResource 1.03 and the Registry Interface 1.01
        (it was previously using very out of date protocols).
        This means that the Cone Search dialogue
        (as well as the semi-supported SIAP and Registry dialogues) 
        will now pick up a much more up to date set of services.
        Additionally, you can choose your own registry service, and
        the registry searches in those dialogues now feature keyword searches
        rather than picking up all known cone/SIAP services.
        See <ref id="ConeSearchDialog"/>.
        </p></dd>
    <dt>Other enhancements</dt>
    <dd><p>
        <ul>
        <li>Table columns and parameters can now be referenced by Utype using
            &utype.prefix; syntax in a similar way to using UCDs -
            see <ref id="jelCols"/>.</li>
        <li>When a new subset is created by whatever method, the user
            can now elect to transmit it to other applications using
            SAMP/PLASTIC as an alternative to adding a new subset
            to the table's subset list.</li>
        <li>Add items to <label>Help</label> menu for viewing help in the
            default web browser rather than TOPCAT's help browser.</li>
        <li>Add a plot output format option to write gzipped PostScript.</li>
        <li><code>-version</code> command line flag now reports subversion
            revision as well as symbolic version number.</li>
        </ul>
        </p></dd>
    <dt>Bugfixes</dt>
    <dd><p>
        <ul>
        <li>Fixed histogram bug (blank plot) for small values when using 
            logarithmic Y axis.</li>
        <li>Fix stacktrace error in 3D plots when no data is available.</li>
        <li>The SIMBAD name resolver is fixed in the cone search window
            (it was using a no-longer-supported service format).</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 3.4-1 (27 March 2009)</dt>
<dd><p>
    <ul>
    <li>Note Sybase ASE works (documentation edit only)</li>
    <li>Fixed bug which caused SIAP queries to fail every time.</li>
    <li>SIAP load dialogue now has name resolution capability.</li>
    <li>Added SSAP load dialogue.  Basic functionality only.</li>
    <li>Added documentation for previously-unadvertised
        SIAP/SSAP load dialogues.</li>
    <li>Fixed bug which caused registry queries (Cone, SIA, SSA) to fail
        for Java 1.6.</li>
    <li>Fixed bug which caused blank Contact field in registry query 
        results.</li>
    <li>Can now query registry for more registry services.</li>
    <li>Fits BINTABLE TZERO/TSCAL value reading improvements:
       <ul>
       <li>Columns with integer TZERO values now read as integers
           rather than floating point values where possible.  
           This includes unsigned longs ('K'), which were previously 
           represented as doubles with lost precision.  
           Unsigned longs which are too large however (&gt;2<sup>63</sup>) 
           are read as nulls.</li>
       <li>Byte-valued columns can now be written out by 
           <code>fits-basic</code> output 
           handler as signed byte values (TFORM=B,TZERO=-128) 
           rather than signed shorts (TFORM=I).</li>
       <li>More comprehensive testing.</li> 
       <li>Fixed bug in calculating value scaled double ('D') values.</li>
       <li>Fixed bug in typing value for scaled float ('E') arrays.</li>
       </ul></li>
    <li>Added column selector documentation <ref id="columnSelector"/>.</li>
    <li>Fix bug when decoding <code>file:</code>-type URLs
        containing <code>%xx</code> escapes.</li>
    <li>Fix error reporting bug in registry search.</li>
    <li>Report application name and version in User-Agent header of outgoing 
        HTTP requests.</li>
    <li>Provide aliases <code>-sia</code> and <code>-ssa</code> for
        <code>-siap</code> and <code>-ssap</code> command line flags.</li>
    <li>Fix SIA and SSA queries to avoid exponential notation in parameters;
        there is currently no standard concerning numeric representations,
        but this avoids problems with some servers.</li>
    <li>The fixed length Substring Array Convention for string arrays
        (<code>TFORMnn=rAw</code>)
        is now understood for FITS binary tables.</li>
    <li>Fixed <code>-noserv</code> flag.</li>
    <li>Fixed so that attempting to run services under unfavourable firewall
        conditions does not cause startup to hang.</li>
    <li>Minor SAMP bugs fixed (JSAMP upgraded to 0.3-1).</li>
    </ul>
    </p></dd>

<dt>Version 3.4-2 (17 July 2009)</dt>
<dd><p>
    <ul>
    <li>Plot windows now allow a plot title to be set from the
        <label>Configure Axes and Title</label> window
        (<ref id="axisConfig"/>).</li>
    <li>Loading message now displayed in control window table list 
        when table is being loaded from PLASTIC or SAMP, or during startup.</li>
    <li>Incoming and outgoing SAMP <code>load.table</code> messages now use 
        the <code>name</code> parameter, which gives a better chance of a
        useful human-readable name being attached to transmitted tables.</li>
    <li>Sexagesimal delimiters can now be spaces as alternative to colons
        in Cone/SSA/SIA load dialogues.</li>
    <li>GAVO load dialogue updated in line with modified database service.</li>
    <li>Work around J2SE mark/reset bug when loading table direct from URL.</li>
    <li>Produce null rather than nonsense results from sky coordinate 
        conversions with unphysical latitudes.</li>
    <li>Produce null rather than questionable results from sexagesimal
        conversions with mins/secs out of range.</li>
    <li>Startup script improved to provide some cosmetic improvements for
        Mac users: the TOPCAT icon is shown in the dock rather than the
        generic Java icon, and the menu application name is set to 
        "TOPCAT" rather than the classname.  Note these don't take effect
        if running directly using <code>java -jar</code>.</li>
    <li>STILTS run using <code>topcat -stilts</code> from standalone jar 
        can now correctly report starjava revision.</li>
    </ul>
    </p></dd>

<dt>Version 3.4-3 (31 July 2009)</dt>
<dd><p>
    <ul>
    <li>Fixed two bugs related to drag and drop: intermittent failure of drop
        (Mac only?), and application crash when making a drop that fails.</li>
    </ul>
    </p></dd>

<dt>Version 3.5 (6 November 2009)</dt>
<dd><p>There are several improvements in this version, many of them to do
    with improved functionality and usability for loading or acquiring 
    data both from local files and from various Virtual Observatory services.
    </p>
    <p> 
    <dl>
    <dt>Multiple-table load</dt>
    <dd><p>TOPCAT will now load multiple tables from a single file if
        multiple tables are present, rather than just the first one.
        This applies to multi-extension FITS files which contain more than
        one table HDU, and to VOTable documents which contain more than one
        TABLE element.  It affects the Filestore dialogue, naming files
        on the command line, and the new VizieR load dialogue.
        </p>
        <p>In previous versions, when you selected a multi-extension FITS
        file or VOTable from one of the load dialogues or on the command 
        line, only the first table contained in it would be loaded, and
        any others were silently ignored.
        Such files often only contain a single table, but not always.
        Now, if multiple tables are present in the container file, each
        one will appear as a new table in the tables list.
        Other table file formats are not currently affected, since there
        is no mechanism for storing multiple tables in, say, a CSV file.
        </p></dd>
    <dt>Multiple Cone, SIA and SSA searches</dt>
    <dd><p>In previous versions, it was possible to use the Virtual Observatory
        Cone Search, Simple Image Access and Simple Spectral Access services
        to locate catalogue records, images and spectra respectively in a
        single (cone-shaped) region of the sky, with position and radius
        entered manually.
        In this version it is possible to execute such a query for each
        row of an input table, with position and radius obtained from table
        data in appropriate columns.  This effectively gives a join between a
        local table and a remote one exposed by a cone-like searchable 
        VO interface.
        </p></dd>
    <dt>VizieR load dialogue</dt>
    <dd><p>A new <ref id="VizierTableLoadDialog">VizieR load dialogue</ref>
        has been introduced to make queries directly to CDS's VizieR service.
        Thanks to Thomas Boch for contributing code for this.
        </p></dd>
    <dt>VO menu</dt>
    <dd><p>A new menu labelled <label>VO</label> (for Virtual Observatory)
        has been added to the Control Window.
        This currently contains single and multiple Cone, SIA and SSA
        queries and the service specific load dialogues, namely the
        VizieR and Millennium ones.
        All these features are also available elsewhere in the GUI,
        but the new menu groups together VO-related functionality for
        convenience.
        </p></dd>
    <dt>Positional search dialogue enhancements</dt>
    <dd><p>A number of improvements have been made to the Cone Search,
        SIA and SSA dialogues; these applies both to the old single-region
        search dialogues and the new multi-region searches.
        <ul>
        <li>The service URL can now be entered (e.g. cut'n'pasted) directly 
            as an alternative to obtaining it from a registry search.
            This allows use of unregistered services, as well as making it
            easy to select the service URL for pasting elsewhere.</li>
        <li>The resource table returned from the registry search can now
            be sorted by column contents, by clicking on the selected
            column header.</li> 
        <li>While searching the registry, some indication of the number
            of services found so far is displayed.</li>
        <li>Searching the registry is less likely to result in an
            out of memory error.</li>
        <li>The (not very useful, and potentially confusing) registry
            <label>Update</label> button has been withdrawn; its function
            is now available only from the <label>Registry</label>
            menu instead.</li>
        <li>The metadata contained in tables returned from a successful 
            search is improved.</li>
        <li>The SIA and SSA dialogues now have a selector for choosing
            the desired image/spectrum format.</li>
        <li>The SIA and SSA dialogues now longer require explicit entry
            of a size parameter (these protocols define default behaviour
            for when no non-zero size has been specified).</li>
        <li>The SIA and SSA now automatically query the registry for all
            appropriate services when first displayed.  
            This is sensible behaviour
            at the moment, since there is at time of writing 
            a reasonable number of them.  A directed search may be given 
            instead at the user's option.</li>
        <li>The Cone Search window provides better instructions on use
            when first displayed.</li>
        </ul>
        </p>
        <p>A new section <ref id="vo"/> has been added to the manual 
        providing an introduction to the concepts of VO data access,
        and a new apendix section <ref id="vo-windows"/> describes the
        various single- and multiple-query windows.
        </p></dd>
    <dt>Storage Policy change</dt>
    <dd><p>The way that TOPCAT stores large tables has changed.
        In previous versions, table data was held in memory 
        (the default <em>Storage Policy</em> was "<code>memory</code>"))
        unless the <code>-disk</code> flag was specified 
        (to use the "<code>disk</code>" storage policy), in which case it was
        stored in temporary disk files.  If you didn't put <code>-disk</code>
        on the command line, it was common to run out of memory when working
        with large tables.
        </p>
        <p>Now, the default storage policy is "<code>adaptive</code>".
        This means that relatively small tables are held in memory,
        and larger ones are stored in temporary files.
        The effect should be that most of the time, you don't need to
        specify any special options, and you can work with small or 
        large tables without running out of memory.
        Using <code>-disk</code> is still permissible, and may help in
        unusual circumstances.
        Running out of memory is still a possibility, but should be much
        less common.
        </p>
        <p>The old behaviour can be restored by using the new
        <code>-memory</code> command-line flag.
        </p>
        <p>The only differences you notice from this change should be good
        ones, however it is slightly experimental.  Please contact the author
        if you suspect it has introduced any problems.
        </p></dd> 
    <dt>SAMP-related enhancements</dt>
    <dd><p>
        <ul>
        <li>Spectrum Display activation action now uses SAMP or PLASTIC to
            display in a suitably compliant external spectrum viewer.
            The old behaviour was to display the spectrum in an internal SPLAT
            window, but it didn't work very well.</li>
        <li>The JSAMP library has been upgraded to v1.0, giving
            some SAMP behaviour changes, enhancements and bugfixes.
            Control of things like TOPCAT server port and server endpoint
            hostname are now configurable using <code>jsamp.*</code> 
            <ref id="jvmProperties">system properties</ref>.</li>
        <li>The <code>-jsamp</code> command-line flag has been added 
            for convenience so that the TOPCAT jar file can be used 
            easily as a JSAMP toolkit.</li>
        </ul>
        </p></dd>
    <dt>VOTable-related enhancements</dt>
    <dd><p>
        <ul>
        <li>Namespacing of VOTable documents made more intelligent, and
            configurable using the <code>votable.namespacing</code> system
            property.</li>
        <li>VOTable 1.2 supported.</li>
        <li>The VOTable 1.2 <code>xtype</code> attribute is now used to 
            try to identify columns containing ISO-8601 format dates, 
            which allows them to be treated as numeric values for 
            plotting etc.</li>
        <li>As described above, when loading a VOTable document which
            contains multiple TABLE elements, all the contained TABLEs
            are now separately loaded into TOPCAT rather than just the
            first one, which is what used to happen.</li>
        </ul>
        </p></dd>
    <dt>Loading changes</dt>
    <dd><p>
        <ul>
        <li>The Load Window now has toolbar buttons as well as items in the
            <label>DataSources</label> menu for more convenient
            access to the various load dialogues.</li>
        <li>The command-line flags corresponding to load dialogues
            (<code>-tree</code>,
             <code>-file</code>,
             <code>-sql</code>,
             <code>-cone</code>,
             <code>-gavo</code>,
             <code>-registry</code>,
             <code>-sia</code>,
             <code>-ssa</code>)
            have been withdrawn from use; they were probably not widely used,
            and are of minimal usefulness with the new load window toolbar
            buttons.</li>
        <li>While a table is loading an entry is now visible in the 
            Control Window table list.  Previously it was not always
            clear whether a slow load was in progress or not.</li>
        </ul>
        </p></dd>
    <dt>Bugfixes and minor enhancements</dt>
    <dd><p>
        <ul>
        <li>There are improvements (and possibly new problems) in the loading
            dialogue framework.  One item is that a failed load less often
            closes the dialogue.</li>
        <li>HTML table output is now HTML 4.01 by default
            (includes THEAD and TBODY tags).</li>
        <li>There is a workaround for illegally truncated type declarations
            in IPAC tables.</li>
        <li>XML, including VOTable, output is handled more carefully; 
            fix VOTable output encoding to be UTF-8,
            and ensure no illegal XML characters are written.</li>
        <li>Fixed plotting bugs - caused intermittent GUI corruption 
            (e.g. missing toolbar buttons), especially on MacOS.</li>
        <li>Bug fixed in crossmatching output: entries which should have been 
            null were sometimes written as non-null (typically large negative
            numbers) in FITS and in non-TABLEDATA VOTable output.
            This affected cells in otherwise non-nullable columns
            where the entire row was absent.  The previous behaviour is not
            likely to have been mistaken for genuine results.</li>
        <li><code>parse*</code> string-&gt;numeric conversion 
            functions now cope with leading or trailing whitespace.</li>
        <li>The list of example queries in the GAVO load dialogue has
            been extended to match those in its web interface.</li>
        <li>Fixed an obscure bug which could under rare circumstances cause
            truncation of strings with leading/trailing whitespace read
            from text-format files.</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 3.5-1 (21 December 2009)</dt>
<dd><p>This version has one significant new feature:
    <ul>
    <li>Plot windows can now export to PDF as well as other formats.</li>
    </ul>
    Other than that, is is mostly performance and usability enhancements and
    bugfixes:
    <ul>
    <li>Fixed a bug which caused an error when attempting to load multiple
        files from the command line.</li>
    <li>Improve documentation of 3D windows, including zoom options.</li>
    <li>Fixed a bug which caused an error when attempting to do cone/SIA/SSA 
        search from directly supplied service URL.</li>
    <li>Improve error reporting from multi-cone (etc) window.</li>
    <li>You can now cut and paste from the linear correlation coefficient
        display in the 2-d plot style editor.</li>
    <li>Faster display of load window and VO menu options.</li>
    <li>Fixed internationalisation bug which could cause cone searches etc
        to fail in locales that use "," for a decimal point.</li>
    <li>Registry searches are now faster and less likely to run out of memory.
        Registry-search-based operations (cone search dialogues etc) now 
        run in topcat-lite configuration as well as topcat-full.</li>
    <li>Now warns about non-active resources returned from registry searches
        (which shouldn't happen).</li>
    <li>Improved helpfulness of error messages in multi-cone etc windows.</li>
    <li>Performance improvements when loading from VOTable documents 
        which contain many small tables, both 
        in general and in the special case of SIA/SSA results.
        This makes a big difference in some cases.</li>
    </ul>
    </p></dd>

<dt>Version 3.5-2 (24 March 2010)</dt>
<dd><p>
    <ul>
    <li>Add <ref id="MemoryMonitor">memory monitor</ref> 
        indicator in control window.</li>
    <li>Considerable performance and scalability improvements to the
        crossmatching algorithms.
        For several common regimes, using default settings,
        memory use has been decreased by a
        factor of about 5, and CPU time reduced by a factor of about 3.</li>
    <li>Add <ref id="matchTuning">optional tuning controls</ref>
        (<label>Tuning Parameters</label> and <label>Full Profiling</label>)
        to the crossmatching windows.
        Experimentation with these can lead to significant performance
        improvements for given matches.</li>
    <li>Fixed a crossmatch bug; it was giving a possibility of
        suboptimal "Best Match Only"
        match assignments when pair matching in crowded fields.
        Crossmatch results thus may differ between earlier versions
        and this one.  Both are reasonable, but the newer behaviour is
        more correct.  In non-crowded fields, there should be no change.</li>
    <li>Add new functions to
        <ref id="Arrays">Arrays</ref>:
        <code>array</code> functions for constructing arrays,
        and new aggregating functions <code>median</code> and
        <code>quantile</code>.</li>
    <li>Added <label>Verbosity</label> selector in multi-cone window.</li>
    <li>Improved logging of registry searches.</li>
    <li>Adjusted the way that data types are read from JDBC databases.
        Date, Time and Timestamp type columns will now be converted to Strings
        which means they can be written to most output formats
        (previously they were omitted from output tables).</li>
    <li>Match Window documentation extended and somewhat reorganised
        (they now have their own
        <ref id="match-windows">appendix subsection</ref>).</li>
    <li>MacOS icons improved: thanks to Simon Murphy (ANU)
        for this contribution.</li>
    <li>Memory management adjusted further - default (Adaptive) storage policy
        now uses direct allocation (=<code>malloc()</code>) 
        for intermediate-sized buffers
        to avoid running out of java heap space.</li>
    <li>Further performance improvement for VOTable documents with
        very many TABLEs.</li>
    <li>Fix bug in code for handling very large mapped FITS files.
        This was causing fatal read errors in some cases.</li>
    <li>Fix issue when sending some SAMP messages
        (unhelpful reuse of message tags).</li>
    <li>Fixed minor error when a directory in the file browser got deleted
        while visible.</li>
    <li>Fix minor scrolling bug in table and column windows.</li>
    <li>Fix histogram save/export bug: the exported table now has the same 
        X bounds as the currently displayed histogram.</li>
    <li>Withdraw embedded SPLAT application.
        SPLAT could previously be used in some circumstances for in-JVM
        display of spectra, but this facility didn't work well and was
        presumably little used.  You can still view spectra by configuring
        an Activation Action to talk to an external spectrum viewer
        (SPLAT or some other choice) via SAMP or PLASTIC.</li>
    <li>Withdraw SOAP server functionality.  This has been deprecated since
        v2.1.  External control is better handled using SAMP (or PLASTIC).
        If anybody misses this functionality, get in touch and I will
        consider a similar but less SOAPy alternative.</li>
    </ul>
    </p></dd>

<dt>Version 3.6 (6 August 2010)</dt>
<dd><p>This version contains some new features and usability enhancements,
    and a number of bugfixes.
    <dl>
    <dt>Load/Save Dialogue improvements:</dt>
    <dd><p>
        <ul>
        <li>There is a new <label>System Browser</label> option when loading
            and saving.  This does essentially same job as the old
            <label>Filestore Browser</label> (still available), selecting
            a file to load or save, but it uses the system-default GUI to do it.
            For Mac and Windows users, this may present a more familiar and
            functional interface to the file system (for Linux users, it is
            probably not an improvement).  Both options are available,
            so you can choose whichever you prefer.
            </li>
        <li>You can now save multiple tables at once.
            The <ref id="SaveQueryWindow">Save Window</ref> now offers
            three ways of saving: <label>Current Table</label>, 
            <label>Multiple Tables</label> and <label>Session</label>.
            Current Table saves the current Apparent Table as before.
            Multiple Table saves some or all of the loaded Apparent Tables
            to a container file
            (typically Multi-Extension FITS or multi-TABLE VOTable).
            Session saves some or all tables as well, but additionally 
            saves many aspects of the TOPCAT state, such as table subsets,
            sort order, hidden columns etc.
            </li>
        </ul>
        </p></dd>
    <dt>Other significant enhancements:</dt>
    <dd><p>
        <ul>
        <li>Finally - you can delete and rename row subsets in the 
            <ref id="SubsetWindow">Subset Window</ref>!
            Apologies to those who've been asking that this has taken
            so long to implement.</li>
        <li>There are new actions in the Control Window 
            <ref id="controlMenus">File menu</ref> to change the order of
            loaded tables in the table list (move them up and down).
            You can use ALT-up/down keys to do the same thing.
            This may be useful in conjunction with the new 
            session/multi-table save facility.</li>
        <li>Utype metadata items are now visible in the Parameter and Column
            windows.</li>
        <li>The JSAMP library has been upgraded to version 1.1.
            This means that the hub will appear in the "System Tray" where
            possible (when using java 1.6+, and when using a suitable 
            display manager).  It also recognises the SAMP_HUB environment
            variable for non-standard hub locations.</li>
        <li>There are a couple of improvements in the
            <ref id="VizierTableLoadDialog">VizieR load dialogue</ref>:
            it has options to display sub-tables within catalogues and 
            to include or exclude obsolete catalogues.</li>
        </ul>
        </p></dd>
    <dt>Minor enhancements:</dt>
    <dd><p>
        <ul>
        <li>The current table can now be discarded by hitting the
            <label>Delete</label> key in the Control Window table list.</li>
        <li>SDSS image cutout downloads updated to DR7 (was DR4).</li>
        <li>The unofficial column type "<code>long</code>" is recognised
            in IPAC format tables.</li>
        <li>An efficiency warning is now issued for large
            compressed FITS files.</li>
        <li>Format row counts are displayed with group separators
            (e.g. thousands separated by commas) in some places
            for better readability.</li>
        </ul>
        </p></dd>
    <dt>Fixes for bugs and misfeatures:</dt>
    <dd><p>
        <ul>
        <li>Table parameter values in algebraic expressions now evaluate to
            their current value, rather than the value when the expression 
            was entered.</li>
        <li>Tables in TOPCAT now have private copies of column and table
            metadata.
            This means that changing a column name or parameter in one table
            will not affect other tables.
            It should also prevent a related bug that allowed the
            column headings in the table browser to get out of step with those
            in the columns window and elsewhere.</li>
        <li>Receipt of a SAMP <code>table.highlight.row</code> message will no
            longer cause a similar message to be sent back
            (and similarly for the PLASTIC
            <code>ivo://votech.org/votable/highlightObject</code> message).
            The previous behaviour was an unwanted implementation side effect
            which could sometimes cause problems in interaction with other
            tools.</li>
        <li>Fixed bug in FITS-plus metadata output
            (table parameters were getting lost).</li>
        <li>Better behaviour (warn + failover) when attempting to read large
            files on 32-bit OS or JVM.</li>
        <li>Corrected literature references in Fluxes conversion class 
            documentation (thanks to Mattia Vaccari).</li>
        <li>Fix memory usage issues (unnecessarily large output graphics
            files, possible out of memory errors) for density plots
            with large pixel sizes.</li>
        <li>Fixed bug in CSV file parsing that could ignore header row in
            absence of non-numeric columns.</li>
        <li>Fix some minor bugs with Cancel operation during table save.</li>
        <li>Reinstate help buttons from Save Window toolbar 
            (erroneously removed since version 2.0).</li>
        <li>Make sure that failed load of table with no rows reports as such
            rather than failing silently.</li>
        <li>Loading tables by typing their name directly in the Load Window
            now loads multiple tables if present not just the first one,
            in common with most of the other load dialogue types.</li>
        <li>Upgraded PixTools HEALPix library to 2010/02/09 version.
            This fixes a bug that could theoretically cause deficient
            crossmatch results, though I haven't managed to produce
            such errors.</li>
        <li>Fixed (I hope) "Table no longer loaded" error when sending tables
            via SAMP.</li>
        </ul>
        </p></dd>
    </dl>
    </p>
    <p>Finally, from this release TOPCAT requires version 1.5 (a.k.a. 5.0)
    of the Java J2SE Runtime Environment; it will no longer run on
    version 1.4, which is now very old.  I don't expect this to cause
    compatibility issues for anyone, but I'm interested to hear if that's
    not the case.
    </p></dd>

<dt>Version 3.7 (23 December 2010)</dt>
<dd><p>This version contains some significant enhancements and a number
    of minor improvements and bugfixes.
    <dl>
    <dt>Load Dialogues:</dt>
    <dd><p>Table loading has had a major overhaul.
        Load dialogues are no longer <em>modal</em>, that is you can now
        interact with the rest of the application while they are open.
        This has a number of benefits:
        <ul>
        <li>A slow load doesn't prevent you from doing other things.</li>
        <li>You can be loading several different tables at once,
            either from the same or from different places.</li>
        <li>You can use the Help system while a load dialogue is open
            (load dialogues now have the usual Help button like other
            TOPCAT windows).</li>
        </ul>
        </p>
        <p>It has also enabled some related changes:
        <ul>
        <li>Progress is reported for each table load - you can see how many
            rows have loaded and, if known, how many there are in total</li>
        <li>Cancelling a load in progress is more straightforward and
            works more reliably than in earlier versions</li>
        </ul>
        </p>
        <p>A few related bugs and idiosyncracies have been corrected
        at the same time.
        </p></dd>
    <dt>Registry Queries:</dt>
    <dd><p>The registry search interface used in single and multiple VO
           access windows has been improved:
        <ul>
        <li>When specifying a keyword search for Cone, SIA or SSA services,
            you can select which registry record fields to match
            (ShortName, ID, Title, Publisher, Subjects etc).
            This makes it much easier to get the records you're
            interested in.</li>
        <li>The Subjects field is now displayed for retrieved records.</li>
        <li>Lists of registry records (i.e. Cone, SIA or SSA services) can
            now be sent to/received from other tools via SAMP
            (<code>voresource.loadlist</code>{,<code>.cone</code>,<code>.siap</code>,<code>.ssap</code>} MTypes).</li>
        <li>Sky coordinates can be received from other tools via SAMP and
            used to set Cone, SIA or SSA position
            (<code>coord.pointAt.sky</code> MType).</li>
        </ul>
        </p></dd>
    <dt>BaSTI Load Dialogue:</dt>
    <dd><p>A new load dialogue is available for accessing the INAF-OATS
        <webref url="http://albione.oa-teramo.inaf.it/">BaSTI</webref>
        (Bag of Stellar Tracks and Isochrones) service --
        code contributed by Marco Molinaro.
        </p></dd>
    <dt>Searchable Help:</dt>
    <dd><p>The Help browser now has a Search tab as well as the 
        Table of Contents tab, so you can do text searching on the
        extensive help document.
        </p></dd>
    <dt>Minor Enhancements:</dt>
    <dd><p>
        <ul>
        <li>Storage management improvements; removed restriction on large
            (&gt;2Gb) non-FITS datasets in some circumstances.</li>
        <li>Fix so FITS tables &gt;2Gb can be used in 32-bit mode
            (though slower than 64-bit).</li>
        <li>All windows have a new Scrollable option
            in their File menu.  It is not generally recommended to use this
            option, since in general the windows are arranged so that resizing
            them will resize sensible parts of them, but it may be useful
            if using some of the larger windows on an unusually
            small screen.</li>
        <li>FITS files now store table names in EXTNAME (and possibly EXTVAR)
            header cards.</li>
        <li>Window placement should now behave a bit more like platform norms,
            rather than sitting in the top left corner.</li>
        <li>When a table is discarded, it is now deselected from any table
            selector (for instance in a plot, match or 
            concatenation window).</li>
        <li>HTML table output now writes cell contents which look like URLs 
            in HTML &lt;A&gt; tags.</li>
        <li>Basic authorization (<code>http://user:pass@host/path</code>) on
            table URLs handled.</li>
        <li>Logs current version and whether it is up to date with latest
            release on startup.  This behaviour can be controlled by the
            [-no]checkversion flag.</li>
        <li>Belatedly added STFC logo to About window.</li>
        <li>Add recommendation to use 64-bit java in large
            table tips section.</li>
        </ul>
        </p>
        </dd>
    <dt>Bug Fixes:</dt>
    <dd><p>
        <ul>
        <li>Fix bug in registry result table which displayed resource
            identifier instead of publisher in the Publisher column.</li>
        <li>Fix SAMP table load bug which tripped over "+" characters
            in URLs.</li>
        <li>Fix regression bug from v3.6 - loading jdbc tables from
            command line or text entry now works again.</li>
        <li>Fixed file pointer <code>int</code> overflow bug in FITS
            MultiMappedFiles.</li>
        <li>Fixed a couple of bugs relating to VOTable strict mode.</li>
        <li>Possibly fixed a not-well-characterised bug in
            registry search.</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 3.8 (9 May 2011)</dt>
<dd><p>
    <dl>
    <dt>TAP</dt>
    <dd><p>A new <ref plaintextref="yes" id="TapTableLoadDialog"
                      >TAP load dialogue</ref>
        supporting data retrieval using 
        the Table Access Protocol (TAP) has been introduced.
        This provides SQL-like free-form access to any remote databases
        exposed with the TAP protocol.
        </p>
        </dd>
    <dt>SAMP changes</dt>
    <dd><p>An internal SAMP hub is now by default started when
        TOPCAT starts up if no existing hub is apparently running,
        so under normal circumstances the SAMP panel at the bottom right
        of the Control Window should be active all the time.
        This means that you don't need to do any explicit preparation to
        communicate with other SAMP-aware applications.
        If you want to return to the previous behaviour (hub only started
        by explicit user action), use the <code>-nohub</code> flag on the
        command line.
        You can connect and disconnect with the hub by clicking the connection
        logo at the right of the SAMP panel.
        </p>
        <p>The JSAMP library is upgraded to JSAMP v1.2, which fixes one or
        two bugs and supports the experimental Web Profile, though Web Profile
        support is not switched on by default.
        </p>
        </dd>
    <dt>Other enhancements</dt>
    <dd><p>
        <ul>
        <li>Random Groups HDUs are now tolerated, though not interpreted, 
            within FITS files.</li>
        <li>Add quintuple match option to multi-table match window
            (someone requested it!).</li>
        <li>You can now re-activate a row in the table viewer window by
            deselecting and then re-selecting it.</li>
        <li>Expressions in column selectors are now left (and coloured grey)
            rather than deleted in the case of a syntax error.</li>
        <li>Improve text rendering in Available Functions window.</li>
        <li>GAVO load dialogue now uses fixed-width font for SQL entry.</li>
        <li>Registry search now includes Publisher field by default.</li>
        </ul>
        </p></dd>
    <dt>Bug fixes and workarounds</dt>
    <dd><p>
        <ul>
        <li>JDBC table input handler now effectively downcasts 
            BigInteger/BigDecimal types to Long/Double.
            The PostgreSQL JDBC driver seems to use the Big* types routinely
            for numeric values (which I don't think it used to do).</li>
        <li>Add workaround for J2SE bug
            <webref
             url='http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4795134'
                   >#4795134</webref>,
            which could cause errors when reading compressed FITS files.</li>
        <li>Fix FITS character handling bug which could cause corrupted FITS
            files on output in presence of non-ASCII characters.</li>
        <li>Fix (some) JDBC connection leaks.</li>
        <li>Attempt case-sensitive matching before case-insensitive for
            column names.</li>
        </ul>
        </p>
        </dd>
    </dl>
    </p></dd>

<dt>Version 3.9 (27 October 2011)</dt>
<dd><p>
    <dl>
    <dt>Crossmatching:</dt>
    <dd><p>
        <ul>
        <li>Additional asymmetric match options have been added to
            the Pair Match window -
            as well as the old symmetric Best Match option, you can now choose
            to do a match which identifies the best match for each row of
            one or the other input table
            (see <ref id="matchRowSelect">Output Rows Selector Box</ref>).
            They correspond to finding the best match in table B for each row
            in table A, and in crowded fields often provide more intuitive
            semantics than the previous symmetric <code>best</code> option
            (in non-crowded fields there is generally no difference).
            This replicates the matching performed by some other tools,
            including Aladin.</li>
        <li>New <ref id="matchCriteria">Match Algorithms</ref>,
            <label>2-d Cartesian Ellipses</label> and
            <label>Sky Ellipses</label>,
            have been introduced to permit matching of general
            elliptical, rather than just circular, regions in both planar
            and sky coordinates.
            Another, <label>N-d Cartesian with Errors</label>,
            has been added for dealing with per-object errors
            in Cartesian coordinates (previously per-object errors
            could only be handled in sky coords).</li>
        <li>Fixed a significant bug in sky crossmatching.  
            If all points in a table were on one side of the RA=0 line, 
            but the error radius extended across that line, matches on the 
            other side could be missed.  Matches could also be missed if 
            different tables used different conventional ranges for RA 
            (e.g. -180..180 in one case and 0..360 in another).
            This fix may in some, but not most, cases result in slower matching
            than previously.</li>
        <li>Semantics of the <label>Sky With Errors</label> match
            algorithm have changed slightly.</li>
        </ul>
        </p></dd>
    <dt>Notable usability improvements:</dt>
    <dd><p>
        <ul>
        <li>You can now change the column order of a table by dragging
            the rows up and down in the 
            <ref id="ColumnInfoWindow">Columns Window</ref>.</li>
        <li>Algebraic functions involving angles are now mostly available
            using degrees as well as radians.
            The <code>Coords</code> class has been replaced by
            <ref id="CoordsDegrees"><code>CoordsDegrees</code></ref> and
            <ref id="CoordsRadians"><code>CoordsRadians</code></ref> classes
            providing sky coordinate functions,
            and a new class
            <ref id="TrigDegrees"><code>TrigDegrees</code></ref>
            provides normal degree-based trigonometric functions
            alongside the radian-based versions in
            <ref id="Maths"><code>Maths</code></ref>.
            The functions in the various activation action classes now take
            degrees and not radians.
            Some of the old function names have changed to make clear that they
            use radians and not degrees.</li>
        <li>The <label>File|Discard Table</label> action in the
            Control Window can now remove multiple tables at once if
            more than one is selected.</li>
        <li>ADQL parsing and syntax highligting has been added to the 
            TAP load dialogue,
            thanks to Gr&#x00e9;gory Mantelet's
            <webref url="http://cdsportal.u-strasbg.fr/adqltuto/"
                    >ADQL library</webref>.</li>
        <li>TAP queries are now synchronous by default
            (the <label>Synchronous</label> checkbox is now checked
            by default).</li>
        <li>The <ref id="SQLTableLoadDialog">SQL Query Dialogue</ref>
            (finally) has a multi-line entry field for SQL query text.</li>
        <li>Add <label>To Browser</label> button to Help Window - this displays
            the currently displayed help page in your normal web browser.</li>
        <li>New convenience button added to Available Functions window
            which is a shortcut to display of the expression syntax in the
            Help browser.</li>
        </ul>
        </p></dd>
    <dt>Other upgrades and enhancements:</dt>
    <dd><p>
        <ul>
        <li>JSAMP has been upgraded to version 1.3-1.
            The main change is that the Web Profile is now enabled by default
            in the SAMP hub that TOPCAT launches.
            There are also more options in the Hub menus,
            and it will overwrite any moribund <code>.samp</code> file at
            startup, which <em>should</em> eliminate annoying persistent
            "404 No handler for URL" warnings.
            </li>
        <li>Add <label>Delete On Exit</label> checkbox to 
            Running Jobs tab of TAP load dialogue.
            Jobs are now created by default with Delete On Exit
            set true (you can change the default with the Deletion menu).</li>
        <li>You can now run JyStilts from the <code>topcat-*.jar</code> 
            jar files in the same way as from <code>stilts.jar</code>.</li>
        <li>Add experimental system properties
            <code>star.basicauth.user</code> and
            <code>star.basicauth.password</code>.</li>
        <li>Added the experimental <code>topcat.exttools</code>
            <ref id="jvmProperties">system property</ref> to allow 
            custom tools to be added to the main toolbar at runtime.</li>
        <li>Improve resilience of multi-cone operation in the presence of
            unreliable or inconsistent DAL services.</li>
        <li>Added new constants to expression language
            <code>POSITIVE_INFINITY</code>, 
            <code>NEGATIVE_INFINITY</code> and 
            <code>NaN</code>.</li>
        <li>Add <code>-running</code> flag which loads tables specified on the
            command line into a existing instance of TOPCAT if one is already
            running.</li>
        <li>Add new <code>join</code> function to 
            <ref id="Arrays">Arrays</ref> class 
            to combine array elements into a string.</li>
        <li>TAP load dialogue uses modified upload ID as per most recent 
            TAPRegExt draft.  This may cause some TAP services incorrectly
            to appear not to support uploads if they have not made a
            similar update.</li>
        </ul>
        </p></dd>
    <dt>Bug fixes:</dt>
    <dd><p>
        <ul>
        <li>Improved some issues (reporting wrong row subset counts
            and membership) related to changing subset definitions.</li>
        <li>Fix cone search verbosity parameter so that VERB=3 is not
            erroneously ignored.</li>
        <li>Fix bug introduced at v3.7 related to labelling loaded files
            (improper handling and propagation of <code>LOAD_SOURCE</code>
            table parameter).</li>
        <li>A PARAMref element with no referent in a VOTable 
            no longer causes an uncaught NullPointerException.</li>
        <li>Fix a small bug related to enabledness of buttons in control
            window and hub connection.</li>
        <li>Work round an obscure java misfeature which could cause
            the wrong cell to be edited if a sort interrupts an edit.</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 4.0b (28 March 2013)</dt>
<dd><p>TOPCAT version 4 includes a complete rewrite of the plotting
    (see below for details).
    The new plotting functionality is however experimental
    and changes may be made to the GUI following user feedback.
    For this reason, the classic plot windows remain available
    from their usual toolbar buttons and the new plot windows are
    currently hidden away in the <label>Graphics</label> menu.
    The "b" designation of this version acknowledges the experimental
    nature of the visualisation changes, but other new features are
    considered stable.
    </p>
    <p>
    <dl>
    <dt>Logo:</dt>
    <dd><p>I finally bid an affectionate farewell to the Top Cat
        Hannah-Barbera cartoon graphic.
        Never having had any legal right whatsoever to use this logo
        my conscience has eventually got the better of me and TOPCAT
        now has an excellent new logo kindly drawn by my friend Phil Hall.
        It's still a yellow cat.
        </p></dd>
    <dt>Plotting:</dt>
    <dd><p>Four new "Layer plot" windows are available from the
        <label>Graphics</label> menu: Plane, Sky, Cube and Sphere layer plots.
        These feature a new more powerful (and, yes, more complicated) user
        interface, and are fully documented in <ref id="plot2"/>.
        New functionality includes:
        <dl>
        <dt>New Sky Coordinate Plot</dt>
        <dd><p>
            <ul>
            <li>Choice of projection:
                Sin (rotatable), Aitoff, Plate Carr&#xE9;e</li>
            <li>Data and view sky coordinate systems selected separately:
                options are equatorial, galactic, supergalactic, ecliptic</li>
            <li>Sky coordinate grid labelled and visible at all zooms</li>
            </ul>
            </p></dd>
        <dt>New data plot options</dt>
        <dd><p>
            <ul>
            <li>vectors</li>
            <li>ellipses (with position angle)</li>
            <li>pair, triple, ... data point lines/polygons</li>
            <li>contours</li>
            <li>variable size markers</li>
            </ul>
            </p></dd>
        <dt>Improved interactive response</dt>
        <dd><p>
            <ul>
            <li>In 2d and sky plots mouse wheel zooms
                around cursor position</li>
            <li>In 2d and sky plots you can
                drag the plot around</li>
            <li>In 3d plots right mouse button recentres cube
                on selected point</li>
            <li>In 3d plots zooming zooms data in the cube
                rather than enlarging the cube wireframe itself</li>
            <li>Many controls are sliders which update
                the plot as you slide</li>
            </ul>
            </p></dd>
        <dt>New plot colouring modes</dt>
        <dd><p>Density colour coding for all plot types,
            with density colour map based either on dataset colour or
            chosen from a fixed set.
            Flat, transparent and aux colour coding still available as before.
            </p></dd>
        <dt>Better support for large datasets</dt>
        <dd><p>Several features have been introduced to provide more meaningful
            visualisation of large datasets.  Improved density-like plots
            and contours give you better ways to understand plots containing
            many more points than there are pixels to plot them on.
            There is separately some improvement in scalability:
            up to roughly 10 million points is currently feasible depending
            on available memory etc, though it depends what you're doing.
            However, I hope to improve this limit in future.</p></dd>
        <dt>Improved axis labelling</dt>
        <dd><p>
            <ul>
            <li>Choice of font size and style</li>
            <li>Option of LaTeX input for non-ASCII characters etc</li>
            <li>Log axes labelled better</li>
            <li>Minor tick option</li>
            </ul>
            </p></dd>
        <dt>Legend options</dt>
        <dd><p>External or manually positioned internal placement.
            </p></dd>
        <dt>Analytic function plotting in 2D</dt>
        <dd><p>Plot functions of X or Y coordinate using
            TOPCAT expression language.</p></dd>
        </dl>
        <em>(Note this plot change list was missing from the v4.0 release
            and retrospectively added at v4.0-1).</em>
        </p></dd>
    <dt>Other new capabilities:</dt>
    <dd><p>
        <ul>
        <li>Use MOC footprints to speed up multi-cone searches,
            including footprint icon display in multicone window.</li>
        <li>Add IPAC output format.</li>
        <li>Add new class
            <ref id="KCorrections">KCorrections</ref>
            to the expression language,
            containing a method for calculating K-corrections
            following the method of Chilingarian and Zolotukhin.</li>
        <li>VOTable input and output are now supported for version 1.3
            of the VOTable standard.</li>
        <li>The version of the VOTable format used for VOTable output
            can now be selected,
            by using the <ref id="jvmProperties">system property</ref>
            <code>votable.version</code>.
            Output version is VOTable 1.2 by default.
            VOTable output no longer includes <code>schemaLocation</code>
            attribute.</li>
        <li>You can now reference tables in multi-extension FITS files by name
            (EXTNAME or EXTNAME-EXTVER) as an alternative to by HDU index.</li>
        </ul>
        </p></dd>
    <dt>Other enhancements:</dt>
    <dd><p>
        <ul>
        <li>ADQL parsing in the TAP window can now highlight all unknown symbols
            not just one of them.  This is possible by upgrading to the
            official v1.1 of Gr&#x00e9;gory Mantelet's ADQL library,
            which improves some other aspects of ADQL parsing as well.</li>
        <li>Add new function <code>hypot</code> (=sqrt(x*x+y*y))
            to the <code>Maths</code> class in expression language.</li>
        <li>Add new <code>split</code> functions for string splitting
            to the <code>Strings</code> class in expression language.</li>
        <li>Some changes to the <code>toString</code> function:
            it now works on non-numeric values,
            gives the right answer for <code>Long</code> integers
            and character values,
            and returns a blank value rather than the string "null" or "NaN"
            for blank inputs.</li>
        <li>Sexagesimal to numeric angle conversion functions now permit the
            seconds part of the sexagesimal string to be missing.</li>
        <li>Changes to the IPAC format definition are accommodated:
            the "long"/"l" type, which is apparently now official,
            no longer generates a warning, and headers may now use
            minus signs instead of whitespace.</li>
        <li>Fixed SAMP table loads to honour "name" parameter.</li>
        <li>PNG graphics output no longer has transparent background.</li>
        <li>Upgrade JSAMP library to version 1.3-3.</li>
        <li>Work around change in VizieR output so that VizieR catalogue
            searching works again.  This may be a temporary change.</li>
        <li>Update URLs for GAVO Millennium database service at request of
            Gerard Lemson.</li>
        <li>Add new class
            <ref id="Coverage">Coverage</ref>
            to the expression language containing MOC-related functions
            (currently, just <code>inMoc</code>).</li>
        <li>Add explanatory section to manual on
            <ref id="matchGroup">Multi-Object Matches</ref>.</li>
        <li>Add <code>-debug</code> flag to manage logging messages better.</li>
        </ul>
        </p></dd>
    <dt>Bug fixes:</dt>
    <dd><p>
        <ul>
        <li>Fix serious and long-standing bug
            (bad TZERO header, causes subsequent reads to fail)
            for FITS output of boolean array columns.</li>
        <li>Fix small but genuine sky matching bug.
            The effect was that near the poles matches near the specified
            threshold could be missed.  The bug was in the PixTools library,
            fixed at the 2012-07-28 release.</li>
        <li>Fix bug which failed when attempting to read FITS files with
            complex array columns (<code>TFORMn=rC/rM</code>).</li>
        <li>Fix failure when loading very large sequential tables.</li>
        <li>Fixed table concatenation so that column datatype array size etc
            is consistent with both input tables not just the first one.</li>
        <li>Adjust SQL writer to avoid type error for MySQL.</li>
        <li>Fix plotting bug that might have caused mysterious failures to
            update the plot.  Or it might not.</li>
        <li>Fix ADQL parsing in TAP window so that TAP_UPLOAD tables
            are treated correctly.</li>
        <li>Fix bug which could cause truncation of strings in FITS and
            possibly VOTable output when tables were hand-edited to add
            strings longer than previously-declared length.</li>
        <li>Fixed bug in multi-table matches (&gt;2 tables) which could
            result in output rows with columns from only a single table,
            i.e. not representing an inter-table match.</li>
        <li>Fix bug in HMS sexagesimal formatting: minus sign was omitted from
            negative angles.  Now the output is forced positive.</li>
        <li>Fix minor bug associated with deleting the current row subset
            (this now causes All to become current).</li>
        <li>Cope with 1-column CSV files.</li>
        <li>Fix (some, though probably not all) possible bug(s)
            related to running on Java 1.7 on Mac.</li>
        <li>Use the correct form "<code>rows</code>"/"<code>bytes</code>"
            rather than "<code>row</code>"/"<code>byte</code>"
            for TAP capability unit values.</li>
        <li>Infinite floating point values are now correctly encoded
            in VOTable output ("<code>+Inf</code>"/"<code>-Inf</code>",
            not "<code>Infinity</code>"/"<code>-Infinity</code>" as in
            previous versions).</li>
        <li>Fixed some layout problems which could lead to zero-width text
            entry fields for RA/Dec.</li>
        <li>Fixed bug when attempting to explode a hidden array column.</li>
        <li>Fix error bar rendering bug which could result in diagonal lines
            being offset near the edge of plots.</li>
        <li>Fix problem with GUI locking up when plotting
            outsize histograms.</li>
        <li>Fixed bug in stacked line plot which caused scribbly
            drawing in the presence of null X axis values.</li>
        <li>Fixed problem with row highlight messages bouncing for ever
            between applications when the Transmit Row activation
            action is in use.</li>
        <li>Improve behaviour when deleting a parameter in the
            Parameter Window.</li>
        </ul>
        </p></dd>
    </dl>
    </p>
    </dd>

<dt>Version 4.0-1 (1 July 2013)</dt>
<dd><p>
    <dl>
    <dt>New Functionality</dt>
    <dd><p>
        <ul>
        <li>Add read-only support for
            <webref url="http://cdf.gsfc.nasa.gov/">CDF</webref>
            (NASA Common Data Format) files.
            Currently, no attempt is made to present time-like values in a
            human-friendly way, but this may improve in a future release.
            The SAMP <code>table.load.cdf</code> MType is also supported
            for receiving CDF files.</li>
        <li>Improve handling of HTTP basic authorization.
            HTTP 401s now pop up a user/password dialogue window,
            unless the <code>star.basicauth.*</code> system properties
            have been set up.</li>
        <li>Add options to calculate the (scaled or unscaled)
            Median Absolute Deviation in the Statistics window.</li>
        </ul>
        </p></dd>
    <dt>Minor enhancements</dt>
    <dd><p>
        <ul>
        <li>Now subscribes to SAMP <code>voresource.loadlist.tap</code> MType,
            accepting resource list in TAP load dialogue "Select Service"
            tab.</li>
        <li>The Columns window now makes a better attempt at displaying
            non-standard per-column metadata of unusual types, in particular
            array values.</li>
        <li>Line plotting improved in layer plots
            (including better dashing, new antialias option).</li>
        <li>Implemented fixes to reduce the chance of users inadvertently
            overloading external Cone/SIA/SSA services with multicone-like
            queries.
            First, fix it so that abandoned queries are properly terminated,
            rather than continuing to hit the server until completion or JVM
            shutdown.
            Second, implement a sensible default maximum value for the
            <label>Parallelism</label> field in the multi-cone (etc) panel
            (though this may be adjusted with a system property).</li>
        <li>Source code is now managed by git and not subversion.
            The format of the "Starjava revision" string reported by the
            <code>-version</code> flag and the Help|About menu item
            has changed accordingly.</li>
        </ul>
        </p></dd>
    <dt>Bug fixes</dt>
    <dd><p>
        <ul>
        <li>Fix CSV regression bug introduced at v4.0b
            - CSV files now work again with MSDOS-style line breaks.</li>
        <li>TAP example queries now quote table and column names
            where necessary.
            This fixes a bug that was particularly evident with the VizieR TAP
            service for which nearly all table names are
            not legal ADQL identifiers.</li>
        <li>Quoting behaviour has changed when generating SQL to write to
            RDBMS tables.  This ought to reduce problems related to mixed-case
            identifiers.  However, it is possible that it could lead to
            unforseen new anomalies.</li>
        <li>Fix bug with reading session files containing 1-column tables.</li>
        <li>Fixed FITS output bug which could result in badly-formed
            string-valued header cards (no closing quote).</li>
        <li>Turn off layer plot optimisation that could result in lost
            precision for double values.</li>
        <li>Fix layer plot bug that broke the plot if both handles of a range
            slider were dragged to the same position.</li>
        <li>Fixed it so that layer plot axis range settings are reset when
            the Rescale button is used.</li>
        <li>Fixed a bug that caused an exception when a table in a layer plot
            was deleted from the application.</li>
        <li>Fixed a bug when zooming way out from a sky plot.</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 4.1 (7 March 2014)</dt>
<dd><p>In this version, the new plotting windows appear for the first
    time in the main Control Window toolbar, and are no longer considered
    experimental.  There have been many changes to their user interface
    and functionality since the last release.
    The old plotting windows are still available from the
    Control Window <label>Graphics</label> menu, but are now considered
    somewhat deprecated, and will not be developed or fixed further.
    </p>
    <p>
    <dl>
    <dt>Navigation changes to the new plotting windows:</dt>
    <dd><p>
        <ul>
        <li>In 2d plots, right-button drag (or ctrl-drag) does
            a 2-d anisotropic zoom - you can stretch or squash the plot
            in both directions.</li>
        <li>In 3d plots, right-button drag (or ctrl-drag) does
            a 2-d anisotropic zoom along the 2 axes most face-on.</li>
        <li>In 3d plots, middle-button drag (or shift-drag) slides the
            plot along the 2 axes most face-on.</li>
        <li>In 2d plots, the pan/zoom actions (wheel, pan-drag, zoom-drag)
            can be done outside the plot to affect just one axis.</li>
        <li>Most navigation mouse actions now show visual feedback on
            the screen.</li>
        <li>A new tab <label>Navigation</label> is added to the Axis controls.
            This lets you configure zoom/pan actions, for
            instance selecting zoom factor and X/Y/XY zoom options
            for when mouse wheel is used.</li>
        <li>A hints panel is added below the plot showing current
            mouse navigation actions.</li>
        <li>Removed zoom in/out buttons in the toolbar of the layer
            plot windows; there are better ways to zoom.</li>
        </ul>
        </p></dd>
    <dt>Other changes to the new plotting windows:</dt>
    <dd><p>
        <ul>
        <li>Histogram plot type added.  You can also add histograms to
            a normal plane plot if you want to.</li>
        <li>Layer plot windows now have a progress bar at the bottom
            for loading data, and optionally for other potentially slow
            operations like replotting, identifying a point,
            turning blob-selected points into a subset etc.</li>
        <li>For very large/slow plots, intermediate subsampled plots are
            optionally displayed while panning/zooming to improve
            responsiveness.</li>
        <li>Toolbar buttons rearranged; the buttons for adding and removing
            layer controls are now in the layer control panel not the
            main plot window toolbar.</li>
        <li>When a pair crossmatch completes successfully,
            you get the option to plot the results,
            which shows you exactly how the located matches
            relate to the input positions (pairs of points are plotted).</li>
        <li>Text label plotting now has crowding configuration options:
            according to configuration, text labels are only drawn if there
            aren't too many close together.</li>
        <li>New grid and label colour configuration options for plane and
            sky plots.</li>
        <li>More colour maps added.</li>
        <li>Antialiasing option added for grid line and label drawing.</li>
        <li>New auto transparency shading mode.</li>
        <li>Add some padding around auto-ranged plot limits.</li>
        <li>Changing table in a plot now tries to retain the coordinate values
            if they still make sense.</li>
        <li>Axis tick labelling improved, including avoiding overlapping
            tick labels.</li>
        <li>Sky plot re-ranging improved: new data set now re-ranges unless
            lock button is set.</li>
        <li>Clip selector added for density and aux colour maps,
            which means you can now use just part of a colour map, giving
            you much more control over colouring.</li>
        <li>Sky plot position formatting now honours sexagesimal setting.</li>
        <li>Some minor threading/performance improvements.</li>
        <li>Experimental time plot type added.
            This plot type is considered experimental and appears in the
            Graphics menu but not currently on the main toolbar.
            It can plot time series and spectrograms.  May be improved in
            future versions.</li>
        <li>The control for plotting pairs of points works differently
            (now has its own layer control not just a Form).
            The triple-point form (which didn't work properly) is withdrawn
            for now.
            </li>
        </ul>
        </p></dd>
    <dt>Other enhancements:</dt>
    <dd><p>
        <ul>
        <li>A new experimental SAMP message <code>table.get.stil</code>
            is supported, allowing SAMP clients to retrieve tables from
            TOPCAT.</li>
        <li>URL selector fields in Activation Action window are now
            editable.</li>
        <li>Add cuboid match algorithm to match windows.</li>
        <li>The Exact matcher now considers scalar numeric values equal if
            they have the same numeric value; they are no longer required
            to have the same type.</li>
        <li>Array-valued per-column metadata items are now displayed
            properly.</li>
        <li>The <code>toString</code> function now works for byte and
            boolean values as well as other data types.</li>
        <li>Replace the (slightly dangerous, also undocumented)
            Apply Subset option in the table viewer window with a new
            Highlight Subset option.
            Also add a new Highlight Subset option in the Subsets window.</li>
        <li>In the old-style histogram plot, exporting it now provides
            cumulative counts if the visible histogram is currently
            in cumulative mode.</li>
        <li>Keyboard focus is more helpfully positioned by default in
            some dialogue windows (it starts off in the first text field).</li>
        </ul>
        </p></dd>
    <dt>Bugfixes etc:</dt>
    <dd><p>
        <ul>
        <li>Fix a registry access bug related to namespaces.
            It is now finally possible to query the STSci/NVO/VAO registry,
            as well as the AstroGrid and Euro-VO registries, from the
            Cone/SIA/SSA/TAP VO windows.  Queries to the STSci registry
            have not been working since mid-2010 as a consequence of bugs
            in (mostly) the TOPCAT client and (partially) the STSci
            registry service.</li>
        <li>Work around bug in MacOS text rendering in plots that painted
            text in the wrong direction when not horizontal (e.g. letters
            going backwards when running vertically).
            The workaround involves defaulting to antialiased text when
            drawing axis grids for MacOS.
            As well as getting the text the right way round this does
            look a bit nicer, but it is also perceptibly slower.
            If speed is more important than correctness you can turn it off
            using the <label>Antialias</label> checkbox
            in the <label>Axes</label>-<label>Grid</label> tabs
            of the various plot windows.</li>
        <li>Withdraw <label>Labels</label> tab in the Sphere plot,
            since it didn't do anything.</li>
        <li>Rename the <label>File</label> menu in most windows to
            <label>Window</label>, which is much more appropriate.</li>
        <li>Fix bug when concatenating tables whose data cells
            may have been edited by hand.</li>
        <li>Fix service selection bug (NullPointerException)
            in multi-SIA/SSA windows.</li>
        <li>Fix bug which prevented access to long integer array elements
            from expression language.</li>
        <li>Fix bug in Statistics window so that Boolean columns correctly
            report mean values (true/true+false proportion).</li>
        <li>Fix TST input handler so TST files with fewer than 3 columns
            can be read.</li>
        <li>Upgrade JSAMP to version 1.3-4
            (hub now supports web clients with <code>https</code> URLs).</li>
        <li>Moved text documenting <code>table.load.cdf</code> and 
            <code>table.load.stil</code> SAMP MTypes from the transmit
            section (wrong) to the receive section (right)
            of this document.</li>
        <li>Minor improvements to CDF support.</li>
        <li>Fix some plot threading issues.</li>
        <li>The reported point count is improved in plots.</li>
        <li>Better handling of OutOfMemoryErrors during plotting.</li>
        <li>Better handling of LaTeX errors in axis labelling.</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 4.2 (4 July 2014)</dt>
<dd><p>
    <dl>
    <dt>Significant new functionality and changes:</dt>
    <dd><p>
        <ul>
        <li>Add the new
            <ref id="CdsUploadMatchWindow">CDS X-Match Upload Window</ref>.
            In most cases (matching with a table that can be found in VizieR)
            this window can and should be used instead of the old
            Multi-Cone window - it is <em>much</em> faster.
            The button for this window replaces the
            MultiCone button in the main Control Window toolbar.
            MultiCone is still available from the VO and Joins menus,
            but is now for most purposes deprecated.</li>
        <li>Windows with a <ref id="RegistryPanel">Registry Query Panel</ref>
            can now talk to the registry using either RI1.0
            (the only option in previous versions) or RegTAP.
            RegTAP is generally much better
            (faster, less bandwidth, more reliable),
            and is the default choice, but a selector allows you
            to revert to RI1.0 if preferred.</li>
        <li>The "frame"-style zooming that was used in old-style plots
            is now available in the new-style plots - drag the mouse
            using the middle button or shift key.</li>
        <li>The <ref id="TapTableLoadDialog">TAP Window</ref> button
            replaces the Concatenate window button on the toolbar.
            The Concatenate window is still available from the
            Joins menu.  This is not new functionality, but the UI change
            reflects the growing usefulness of TAP services.</li>
        </ul>
        </p></dd>
    <dt>Minor improvements:</dt>
    <dd><p>
        <ul>
        <li>Form configuration options are now preserved, rather than reset,
            when a new table is selected in one of the plot windows.</li>
        <li>Registry search panels now display resource count at the bottom of
            the resource list.</li>
        <li>Update the endpoint for the NVO/VAO RI1.0 registry
            (now deprecated in favour of RegTAP), on advice from
            Theresa Dower.</li>
        <li>Fixed TAP load dialogue so that by default it stays open after a
            table is loaded (the <label>Stay Open</label> option is set true
            by default).</li>
        <li>Improve TAP window Running Jobs display.  The Job URL is now always
            shown even when the other job details scroll off screen,
            and the details scroll to the top not the bottom when a job is
            selected or refreshed.</li>
        <li>Upgraded Gregory Mantelet's ADQL library to version 1.2.
            Better ADQL parsing.</li>
        <li>Modify the way antialiasing is controlled in plot windows.
            The Grid antialiasing
            option, where present, now just covers the actual grid lines.
            Text antialiasing is now selected with a new "Antialias" option
            in the (now possibly misnamed) "Text Syntax" item
            in Font configuration.  This now affects the Aux axis and Legend
            labelling as well as the grid labelling.</li>
        <li>Added new graphics output format <code>png-transp</code>
            to generate PNG files with transparent backgrounds.</li>
        </ul>
        </p></dd>
    <dt>Bug fixes:</dt>
    <dd><p>
        <ul>
        <li>Set antialiasing on by default for OSX -
            get it right this time.</li>
        <li>Fixed some bugs related to TAP table uploads.</li>
        <li>Fix out-by-one error in reporting of Row of min/max values
            in Statistics window.</li>
        <li>Add missing geometric reserved words to ADQL reserved word list.
            Has a slight effect on ADQL validation in TAP window.</li>
        <li>No longer disable "View URL As ..." options in Activation window
            when no suitable columns are present.</li>
        <li>Fixed bug in which cube plot navigation help button gave you
            sphere plot help and vice versa.</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Version 4.2-1 (13 November 2014)</dt>
<dd><p>
    <dl>
    <dt>New functionality:</dt>
    <dd><p>
        <ul>
        <li>Add (experimental) read-only support for Gaia/DPAC 
            <ref id="inGbin">GBIN format</ref>.</li>
        <li>Add special variables <code>$ncol</code> and <code>$nrow</code> to
            the <ref id="jelParams">expression language</ref>
            to refer to the column and row counts in the underlying table.
            The special variable <code>index</code> is also deprecated in favour
            of <code>$index</code> or <code>$0</code>.</li>
        <li>Support viewing tables up to 2<sup>31</sup>
            (2 billion) rows in the table viewer window.
            The previous limit was 2<sup>27</sup> (134 million) rows.
            This does not necessarily mean that using TOPCAT on Gigarow tables
            is a good idea!</li>
        </ul>
        </p></dd>
    <dt>Minor improvements and bugfixes:</dt>
    <dd><p>
        <ul>
        <li>Change the default RegTAP registry endpoint to
            <code>http://reg.g-vo.org/tap</code>,
            which should have good reliability,
            since it can point to different RegTAP services as required.</li>
        <li>Add some more colour maps for aux/density shading.</li>
        <li>Fix regression bug (introduced at v4.2) which caused authentication
            to fail when using the SQL Query load dialogue.</li>
        <li>Attempting to write FITS tables with &gt;999 columns now fails
            with a more helpful error message.</li>
        <li>Somewhat improved Unicode handling in VOTables.
            If you load a VOTable with columns marked
            <code>datatype="unicodeChar"</code>
            and save it again, the columns now remain <code>unicodeChar</code>
            instead of getting squashed to type <code>char</code>.
            Some lurking Unicode-related issues remain.</li>
        <li>Fix time plot to work for ISO-8601 times.
            This change also breaks use of ISO-8601 times in non-time plots,
            but that didn't work particularly well before.
            Please complain if this change of functionality
            causes a problem.</li>
        <li>Fix problem with activation action image viewer selection box.</li>
        <li>Update JSAMP to v1.3.5.</li>
        </ul>
        </p></dd>
    </dl>
    </p></dd>

<dt>Next version</dt>
<dd><p>
    <ul>
    <li>Fix some problems to do with zooming to very large/small
        plot axis ranges.</li>
    <li>Hide error bars (etc) that would extend to negative values
        on logarithmic axes; previously they were being drawn in anomalous
        places.</li>
    <li>Histogram normalisation option adjusted so that total area under bars,
        rather than total height of bars, is fixed.</li>
    <li>New <ref id="form-linearfit">Linear Fitting</ref> form for
        Plane plot.
        This reinstates behaviour available from old plot windows,
        but it provides some more options, like point weighting.</li>
    <li>New Save/Import options in
        <ref id="HistogramPlotWindow">Histogram window</ref>
        allow you to export histogram bin data as a new table
        (this reinstates behaviour available from old plot windows).</li>
    <li>Fixed error in fits-var output
        (PCOUNT header card did not include block alignment gap).</li>
    <li>New <label>Size</label> tab is provided in plot window Axes
        control to allow explicit setting of output plot dimensions and
        alignment in pixels - useful for exporting plots.</li>
    </ul>
    </p></dd>

</dl>
</p>

</subsect>

</sect>

</appendices>

</docbody>

</sun>