STILTS-PIXFOOT(1)

📦
version 3.5.4 · 5 versions
, in ubuntu stonking

💖 NAME 💖

hiii bestie, welcome to stilts-pixfoot — it's a page from the Stilts commands collection and its whole entire job is: Generates Multi-Order Coverage maps. that's it. that's the girl. she takes a bunch of sky positions and makes you a map. iconic behavior. 🗺️✨

🦋 SYNOPSIS 🦋

stilts pixfoot [ifmt=<in-format>] [istream=true|false] [in=<table>]
               [icmd=<cmds>] [order=0..29] [ra=<expr>] [dec=<expr>]
               [radius=<expr>] [mocfmt=fits|json|ascii] [out=<out-file>]

🌸 DESCRIPTION 🌸

okay so here's the tea ☕: pixfoot grabs a list of sky positions from an input table and generates a pixel map that describes a sky region which includes them all — every single one of them, no stragglers left behind. 💅

right now the output goes to a format called a Multi-Order Coverage map (MOC for short, iykyk). it's a HEALPix-based format, meaning it's literally just a big list of HEALPix pixels of different sizes, and the way it stacks those different-sized pixels together means it can describe reeeeally complex regions super efficiently. it's giving organized chaos, and I'm obsessed. 🫶 Other output formats may be introduced in the future, so like, watch this space.

now, bestie, there's a similar girl in town: the mocshape command does a comparable job, but — and this is the key difference — it can also work with input columns representing shapes that are not just points or circles. it also offers different MOC generation implementations that may be more efficient when you're working with very large input tables. so if you're hauling around a massive table, maybe go say hi to her instead. 👑

See also the Coverage class for MOC-related functions. 🌈

✨ OPTIONS ✨

  • ifmt=<in-format> — tells the program what the format of the input table is, as specified by parameter in. the known formats are all listed in SUN/256. use this flag when you already know what format your table is in, because if it's set to the special value (auto) — which is the default — the program will try to detect the format for you automatically. and bestie, that auto-detection cannot always be done correctly — in that case the program will exit with an error explaining which formats it attempted. 🙈 also: this parameter is ignored for scheme-specified tables.
  • istream=true|false — set this to true and the input table specified by the in parameter gets read as a stream. heads up: you have to give the ifmt parameter in this case. depending on the required operations and processing mode, this may cause the read to fail (sometimes it's necessary to read the table more than once). it's not normally necessary to set this flag — in most cases the data will be streamed automatically if that's the best thing to do. however, it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable), which is lowkey a win. this parameter is ignored for scheme-specified tables.
  • in=<table> — the location of the input table. it may take one of these forms:
    • a filename. 📄
    • a URL. 🔗
    • the special value "-", meaning standard input. in this case the input format must be given explicitly using the ifmt parameter. note that not all formats can be streamed in this way.
    • a scheme specification of the form :<scheme-name>:<scheme-args>.
    • a system command line with either a "<" character at the start, or a "|" character at the end (<syscmd or syscmd|). this executes the given pipeline and reads from its standard output. this will probably only work on unix-like systems.

in any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. 🧚

  • icmd=<cmds> — specifies processing to be performed on the input table specified by parameter in, before any other processing has taken place. the value is one or more of the filter commands described in SUN/256. if you're giving more than one, they must be separated by semicolon characters (";"). you can repeat this parameter multiple times on the same command line to build up a list of processing steps — and the sequence of commands you give in this way defines the processing pipeline that gets performed on the table. 💫

commands may alternatively be supplied in an external file by using the indirection character '@'. so a value of "@filename" causes the file filename to be 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 which are blank or which start with a '#' character are ignored. a backslash character \ at the end of a line joins it with the following line. 🌟

  • order=0..29 — the maximum HEALPix order for the MOC. this defines the maximum resolution of the output coverage map. the angular resolution corresponding to order k is approximately 180/sqrt(3.Pi)/2^k degrees (3520*2^-k arcmin). permitted values are 0..29 inclusive. the default value is 13, which corresponds to about 26 arcsec. 🎀
  • ra=<expr> — right ascension in degrees for the position of each row of the input table. this may simply be a column name, or it may be an algebraic expression calculated from columns as explained in SUN/256. if left blank, an attempt is made to guess from UCDs, column names and unit annotations what expression to use. 🔭
  • dec=<expr> — declination in degrees for the position of each row of the input table. this may simply be a column name, or it may be an algebraic expression calculated from columns as explained in SUN/256. if left blank, an attempt is made to guess from UCDs, column names and unit annotations what expression to use. 🔭
  • radius=<expr> — an expression which evaluates to the radius in degrees of the cone at each row of the input table. the default is "0", which treats each position as a point rather than a cone — but you can use a constant or an expression as described in SUN/256 instead. 🍓
  • mocfmt=fits|json|ascii — determines the output format for the MOC file. pick your fighter. 💅
  • out=<out-file> — the location of the output file. this is usually a filename to write to. if it's equal to the special value "-" the output will be written to standard output. 🫶

🔥 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 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)

and that's the whole page, bestie!! 🎀 version 3.5.4-debian, dated Mar 2017, and you've officially survived STILTS-PIXFOOT(1). go forth and map the sky, you absolute main character. 💅✨🌸🦋🍓

📦 where this page comes from