Provided by: stilts_3.4.3-1_all bug

NAME

       stilts-cone - Executes a Cone Search-like query

SYNOPSIS

       stilts cone [serviceurl=<url-value>] [lon=<degrees>] [lat=<degrees>] [radius=<degrees>]
                   [skysys=icrs|fk5|fk4|galactic|supergalactic|ecliptic]
                   [servicetype=cone|ssa|sia1|sia2|sia] [verb=1|2|3] [compress=true|false]
                   [dataformat=<value>] [ocmd=<cmds>]
                   [omode=out|meta|stats|count|checksum|cgi|discard|topcat|samp|tosql|gui]
                   [out=<out-table>] [ofmt=<out-format>]

DESCRIPTION

       cone is a utility to execute one of the "Simple" positional  DAL  query  operations  on  a
       remote  server:  Simple  Cone  Search, Simple Image Access (SIA) or Simple Spectral Access
       (SSA). The job it does is not very complicated: given a base URL for a service of  one  of
       these  types  and  values  for  the central position and radius required, it assembles the
       query URL in the form required for the relevant protocol,  retrieves  the  result  of  the
       query,  and  turns it into a table which can be operated on with the usual STILTS pipeline
       operations.

OPTIONS

       serviceurl=<url-value>
              The base part of a URL which defines the query to be  made.  Additional  parameters
              will  be  appended  to  this  using  CGI  syntax  ("name=value",  separated  by '&'
              characters). If this value does not end in either a '?' or a '&', one will be added
              as appropriate.

       lon=<degrees>
              Central longitude position for cone search. By default this is the Right Ascension,
              but depending on the value of the skysys parameter it may be  in  a  different  sky
              system.

       lat=<degrees>
              Central  latitude position for cone search. By default this is the Declination, but
              depending on the value of the skysys parameter it may be in a different sky system.

       radius=<degrees>
              Search radius in degrees.

       skysys=icrs|fk5|fk4|galactic|supergalactic|ecliptic
              Sky coordinate system used to interpret the lon and lat parameters. If the value is
              ICRS  (the  default)  the  provided  values  are  assumed to be Right Ascension and
              Declination and are sent unchanged; for other values they will  be  converted  from
              the named system into RA and Dec first.

       servicetype=cone|ssa|sia1|sia2|sia
              Selects  the type of data access service to contact. Most commonly this will be the
              Cone Search service itself, but there are one or two other possibilities:

                * cone: Cone Search protocol -  returns  a  table  of  objects  found  near  each
                  location. See Cone Search standard.

                * ssa:  Simple  Spectral  Access  protocol - returns a table of spectra near each
                  location. See SSA standard.

                * sia1: Simple Image Access protocol version 1 - returns a table of  images  near
                  each location. See SIA 1.0 standard.

                * sia2:  Simple  Image Access protocol version 2 - returns a table of images near
                  each location. See SIA 2.0 standard.

                * sia: alias for sia1

       verb=1|2|3
              Verbosity level of the tables returned by the query service. A value of 1 indicates
              the bare minimum and 3 indicates all available information.

       compress=true|false
              If  true,  the  service  is  requested  to  provide  HTTP-level compression for the
              response stream (Accept-Encoding header is set to "gzip", see RFC 2616). This  does
              not  guarantee that compression will happen but if the service honours this request
              it may result in a smaller amount  of  network  traffic  at  the  expense  of  more
              processing on the server and client.

       dataformat=<value>
              Indicates  the  format of data objects described in the returned table. The meaning
              of this is dependent on the value of the servicetype parameter:

                * servicetype=cone: not used

                * servicetype=ssa: gives the MIME type of spectra referenced in the output table,
                  also  special  values  "votable",  "fits",  "compliant",  "graphic", "all", and
                  others (value of the SSA FORMAT parameter).

                * servicetype=sia1: gives the MIME type required for images/resources  referenced
                  in  the  output  table,  corresponding to the SIA FORMAT parameter. The special
                  values "GRAPHIC" (all graphics formats) and "ALL" (no restriction)  as  defined
                  by  SIAv1  are  also  permissible.  For  SIA  version  1  only,  this  defaults
                  to"image/fits".

                * servicetype=sia2: gives the MIME type required for images/resources  referenced
                  in  the  output  table,  corresponding to the SIA FORMAT parameter. The special
                  values "GRAPHIC" (all graphics formats) and "ALL" (no restriction)  as  defined
                  by SIAv1 are also permissible.

                * servicetype=sia:  gives  the MIME type required for images/resources referenced
                  in the output table, corresponding to the SIA  FORMAT  parameter.  The  special
                  values  "GRAPHIC"  (all graphics formats) and "ALL" (no restriction) as defined
                  by  SIAv1  are  also  permissible.  For  SIA  version  1  only,  this  defaults
                  to"image/fits".

       ocmd=<cmds>
              Specifies  processing  to  be  performed  on  the  output  table,  after  all other
              processing has taken place. The value of this parameter  is  one  or  more  of  the
              filter  commands  described  in  SUN/256.  If  more than one is given, they must be
              separated by semicolon characters (";"). This parameter can  be  repeated  multiple
              times on the same command line to build up a list of processing steps. The sequence
              of commands given in this way defines the processing pipeline which is performed on
              the table.

              Commands may alteratively be supplied in an external file, by using the indirection
              character '@'. Thus a value of "@filename" causes the file filename to be read  for
              a  list of filter commands to execute. The commands in the file may be separated by
              newline characters and/or semicolons, and lines which are blank or which start with
              a '#' character are ignored.

       omode=out|meta|stats|count|checksum|cgi|discard|topcat|samp|tosql|gui
              The  mode  in which the result table will be output. The default mode is out, which
              means that the result will be written as a new  table  to  disk  or  elsewhere,  as
              determined  by the out and ofmt parameters. However, there are other possibilities,
              which correspond to uses to which a table can be put other than outputting it, such
              as  displaying  metadata,  calculating  statistics, or populating a table in an SQL
              database. For some values of this parameter,  additional  parameters  (<mode-args>)
              are required to determine the exact behaviour.

              Possible values are

                * out

                * meta

                * stats

                * count

                * checksum

                * cgi

                * discard

                * topcat

                * samp

                * tosql

                * gui
               Use the help=omode flag or see SUN/256 for more information.

       out=<out-table>
              The  location of the output table. This is usually a filename to write to. If it is
              equal to the special value "-" (the default) the output table will  be  written  to
              standard output.

              This parameter must only be given if omode has its default value of "out".

       ofmt=<out-format>
              Specifies  the format in which the output table will be written (one of the ones in
              SUN/256 - matching is case-insensitive and you can use just the first few letters).
              If  it  has the special value "(auto)" (the default), then the output filename will
              be examined to try to guess what sort of file is required usually by looking at the
              extension. If it's not obvious from the filename what output format is intended, an
              error will result.

              This parameter must only be given if omode has its default value of "out".

SEE ALSO

       stilts(1)

       If the package stilts-doc is installed, the full documentation  SUN/256  is  available  in
       HTML format:
       file:///usr/share/doc/stilts/sun256/index.html

VERSION

       STILTS version 3.4.3-debian

       This  is  the  Debian  version  of Stilts, which lack the support of some file formats and
       network protocols. For differences see
       file:///usr/share/doc/stilts/README.Debian

AUTHOR

       Mark Taylor (Bristol University)

                                             Mar 2017                              STILTS-CONE(1)