STILTS-VOTCOPY(1)

📦
version 3.5.4 · 5 versions
, in ubuntu stonking

💖 STILTS-VOTCOPY(1) 💖

okay bestie, settle in, because this is stilts-votcopy from the stilts commands set, and it's literally here to transform between VOTable encodings. no cap. 🦋

✨ NAME ✨

stilts-votcopy — Transforms between VOTable encodings

🌸 SYNOPSIS 🌸

stilts votcopy [in=<location>] [out=<location>]
               [format=TABLEDATA|BINARY|BINARY2|FITS]
               [version=1.0|1.1|1.2|1.3|1.4|1.5] [charset=<xml-
               encoding>] [cache=true|false] [href=true|false]
               [nomagic=true|false] [base=<location>]

🎀 DESCRIPTION 🎀

so the VOTable standard is out here providing three basic encodings of the actual data inside each table: TABLEDATA, BINARY and FITS. and like, they are so different in energy.

TABLEDATA is a pure-XML encoding, which is relatively easy for humans to read and write. it's giving "i can open this in a text editor and understand my life" energy. however, it is verbose and not very efficient for transmission and processing, which is literally why the more compact BINARY format has been defined. 💅

FITS format shares the advantages of BINARY, but is more likely to be used where a VOTable is providing metadata 'decoration' for an existing FITS table. cute.

and there's more: the BINARY and FITS encodings may carry their data either inline (as the base64-encoded text content of a STREAM element) or externally (referenced by a STREAM element's href attribute). two vibes, one format, iykyk.

these different formats have their different advantages and disadvantages, as one does. since, to some extent, programmers are humans too (😭 fr), much existing VOTable software deals in TABLEDATA format even though it may not be the most efficient way to proceed. conversely, you might wish to examine the contents of a BINARY-encoded table without use of any software more specialised than a text editor. so there are times when it is desirable to convert from one of these encodings to another. that's the whole point bestie.

votcopy is a tool which translates between these encodings while making a minimum of other changes to the VOTable document. the processing may result in some changes to lexical details such as whitespace in start tags, but the element structure is not modified. iconic behaviour honestly.

unlike tpipe it does not impose STIL's model of what constitutes a table on the data between reading it in and writing it out, so subtleties dependent on the exact structure of the VOTable document will not be mangled. we respect the original document's main character energy. the only important changes should be the contents of DATA elements in the document. periodt. ✨

💅 OPTIONS 💅

  • in=<location> — Location of the input VOTable. it can be a URL, a filename, or - to indicate standard input. the input table may be compressed using one of the known compression formats (Unix compress, gzip or bzip2). 🧚
  • out=<location> — Location of the output VOTable. may be a filename or - to indicate standard output.
  • format=TABLEDATA|BINARY|BINARY2|FITS — Determines the encoding format of the table data in the output document. if null is selected, then the tables will be data-less (will contain no DATA element), leaving only the document structure. and yes bestie, data-less tables are legal VOTable elements. 🫶
heads up: the BINARY2 format is only available for version=1.3
  • version=1.0|1.1|1.2|1.3|1.4|1.5 — Determines the version of the VOTable standard to which the output will conform. If null (the default), the output table will have the same version as the input table. matching energy, love that.
  • charset=<xml-encoding> — Selects the Unicode encoding used for the output XML. the available options are dependent on your JVM (not us, blame the JVM 💀), so use help=charset for a full listing. setting the value null will use the JVM's system default.
  • cache=true|false — Determines whether the input tables are read into a cache prior to being written out. the default is selected automatically depending on the input table, so you should normally leave this flag alone. hands off, bestie.
  • href=true|false — In the case of BINARY or FITS encoding, this determines whether the STREAM elements output will contain their data inline or externally. if set false, the output document will be self-contained, with STREAM data inline as base64-encoded characters. if true, then for each TABLE in the document the binary data will be written to a separate file and referenced by an href attribute on the corresponding STREAM element. the name of these files is usually determined by the name of the main output file; but see also the base flag. 👑
  • nomagic=true|false — Eliminate the null attributes of VALUES elements where they are no longer required. in VOTable versions <=1.2, the only way to specify null values for integer-type scalar columns was to use the null attribute of the VALUES element to indicate an in-band magic value representing null. from VOTable v1.3, null values can be represented using empty <TD> elements or flagged specially in BINARY2 streams. in these cases, it is recommended (though not required) not to use the VALUES/null mechanism.

If this parameter is set true, then any VALUES/null attributes will be removed in VOTable 1.3 BINARY2 or TABLEDATA output. if this results in an empty VALUES element, it too will be removed. bye girl 🎀

this parameter is ignored if the output VOTable version is lower than 1.3 or if format=BINARY/FITS.
  • base=<location> — Determines the name of external output files written when the href flag is true. normally these are given names based on the name of the output file. but if this flag is given, the names will be based on the <location> string. this flag is compulsory if href is true and out=- (output is to standard out), since in this case there is no default base name to use. you must have it, no cap.

🌈 SEE ALSO 🌈

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.5.4-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)

okay bestie that's the whole page, you ate it 💖 and for the cute little sign-off: this lil drop of wisdom is from Mar 2017, and it's the STILTS version 3.5.4-debian era of STILTS-VOTCOPY(1). go convert some encodings, you main character 🌸🦋✨

📦 where this page comes from