STILTS-CONE(1)

✨ STILTS-CONE(1) ✨

welcome to a page from the Stilts commands manual, bestie 💖 strap in, it's giving "positional astronomy but make it cute".

---

🎀 NAME 🎀

stilts-cone — runs a Cone Search-ish query, no cap.

🦋 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 💜

so cone is this little utility whose whole personality is running one of the "Simple" positional DAL query operations on a remote server. like: Simple Cone Search, Simple Image Access (SIA), or Simple Spectral Access (SSA). 🛰️

and honestly? the job is not that deep. you hand it a base URL for a service of one of those types, plus values for the central position and radius it needs, and it:

• assembles the query URL in the exact form the relevant protocol demands,
• goes and fetches the result of the query,
• and turns that into a table you can then poke at with all the usual STILTS pipeline operations. 💅

main character energy: small job, done flawlessly.

---

🌟 OPTIONS 🌟

• serviceurl=<url-value> — the base part of a URL that defines the query to be made. extra parameters get appended to it using CGI syntax ("name=value", separated by & characters). and if this value doesn't end in either a ? or a &, one gets added for you as appropriate. 🫶
• lon=<degrees> — the central longitude position for the cone search. by default that's the Right Ascension, but depending on what skysys is set to, it might be in a whole different sky system. 👀
• lat=<degrees> — the central latitude position for the cone search. by default that's the Declination, but again, depending on what skysys is set to, it may be living in a different sky system.
• radius=<degrees> — search radius, in degrees. that's it, that's the tweet. ⭕
• skysys=icrs|fk5|fk4|galactic|supergalactic|ecliptic — the sky coordinate system used to interpret the lon and lat parameters. if the value is ICRS (the default) then the values you provide are assumed to be Right Ascension and Declination and get sent unchanged. for any other value, they get converted from that named system into RA and Dec first. ✨
• servicetype=cone|ssa|sia1|sia2|sia — picks which type of data access service to contact. most of the time this is just 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 sia
• verb=1|2|3 — verbosity level of the tables the query service returns. 1 means the bare minimum, 3 means all the available information. 🗣️
• compress=true|false — if true, the service is asked to provide HTTP-level compression for the response stream (the Accept-Encoding header is set to "gzip", see RFC 2616). > heads up: this does not guarantee compression will happen — but if the service honours the request it may mean less network traffic, at the cost of more processing on both the server and the client. 💀
• dataformat=<value> — tells you the format of the data objects described in the returned table. what it actually means depends on what servicetype is:
  • servicetype=cone: not used
  • servicetype=ssa: gives the MIME type of spectra referenced in the output table, plus special values "votable", "fits", "compliant", "graphic", "all", and others (it's the 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> — says what processing should happen on the output table, after all the other processing has already happened. the value is one or more of the filter commands described in SUN/256. if you give more than one, they must be separated by semicolon characters (";"). this parameter can be repeated multiple times on the same command line so you can build up a whole list of processing steps. the sequence of commands you give in this way defines the processing pipeline that gets performed on the table. 🧚

you can also supply commands in an external file using the indirection character '@'. so a value of "@filename" makes the file filename get read for a list of filter commands to execute. the commands in that file may be separated by newline characters and/or semicolons, and lines that are blank or that start with a '#' character are ignored. a backslash character '\fR' at the end of a line joins it with the following line. 📎

• omode=out|meta|stats|count|checksum|cgi|discard|topcat|samp|tosql|gui — the mode the result table gets output in. default is out, which means the result is written as a new table to disk or elsewhere, as determined by the out and ofmt parameters. but there are other possibilities too, corresponding to all the other uses a table can be put to besides outputting it — like displaying metadata, calculating statistics, or populating a table in an SQL database. for some values of this parameter, extra parameters (<mode-args>) are required to decide the exact behaviour.

possible values are

• out
• meta
• stats
• count
• checksum
• cgi
• discard
• topcat
• samp
• tosql
• gui

use the help=omode flag, or check SUN/256, for more info. 🔍

• out=<out-table> — where the output table goes. usually a filename to write to. if it equals the special value "-" (which is the default) the output table gets written to standard output. 📤

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

• ofmt=<out-format> — the format the output table gets written in (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 gets examined to try and 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, you get an error. 😭

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 at: file:///usr/share/doc/stilts/sun256/index.html 📚

💖 VERSION 💖

STILTS version 3.5.4-debian

this is the Debian version of Stilts, which lacks the support of some file formats and network protocols. for differences see: file:///usr/share/doc/stilts/README.Debian 🐧

🫶 AUTHOR 🫶

Mark Taylor (Bristol University) 💫

---

that's the whole page, bestie, every last flag accounted for 🧚✨ this was the STILTS-CONE(1) page from Stilts commands, STILTS version 3.5.4-debian, dated Mar 2017 — mwah, slay, go query something 💋👑