STILTS-PIXSAMPLE(1)

📦

version 3.5.4 · 5 versions

3.5.4 · ubuntu stonking (latest)
3.4.3 · ubuntu jammy
3.4.9 · ubuntu noble
3.4.7 · debian bookworm
3.5.2 · debian trixie, ubuntu questing, ubuntu resolute

✨ NAME ✨

stilts-pixsample — samples from a HEALPix pixel data file 🫶

okay so bestie, this is the Stilts command that reaches into an all-sky HEALPix map and pulls out a value for every single sky position you throw at it. no cap. 💖

🌈 SYNOPSIS 🌈

stilts pixsample [in=<table>] [ifmt=<in-format>] [icmd=<cmds>]
                 [pixdata=<pix-table>] [pfmt=<in-format>] [pcmd=<cmds>]
                 [ocmd=<cmds>]
                 [omode=out|meta|stats|count|checksum|cgi|discard|topcat|samp|tosql|gui]
                 [out=<out-table>] [ofmt=<out-format>]
                 [pixorder=nested|ring|(auto)] [stat=point|mean]
                 [lon=<expr>] [lat=<expr>]
                 [insys=icrs|fk5|fk4|galactic|supergalactic|ecliptic]
                 [pixsys=icrs|fk5|fk4|galactic|supergalactic|ecliptic]
                 [radius=<expr>]

🦋 DESCRIPTION 🦋

So pixsample samples data at the sky position that each row of your table represents, pulling from an all-sky map that lives in a HEALPix-format pixel data file. and here's the tea: those files are actually tables (usually in FITS format) where the row number is the HEALPix pixel index and the pixel values are the cell contents. one or more columns can be hanging out in there, holding values for one or more all-sky maps. what this command does is add a column to your input table with the pixel data at the position of each input row, for each of the data columns in the HEALPix table. slay. 💅

⚠️ important — this command does not attempt to convert between coordinate systems except as instructed. so it's genuinely important to know what coordinate system the HEALPix file is in, and to make sure the coordinates you're supplying from the input table match it. you may need to go read the documentation or the headers of the HEALPix file in question to figure that out. the Examples section has some examples for you. 👀

there's a choice of how the sampling is done ✨ the simplest way is just to use the value of the pixel covering the indicated position. an alternative is to average over a disc of a given radius (which can be a function of the input row, no big deal). other options (e.g. max/min) could easily be added. (not yet tho.)

so like — HEALPix isn't a common format for storing image data in general, but it is used for storing a bunch of important all-sky data sets, like the WMAP results and Schlegel dust maps. the NASA LAMBDA (Legacy Archive for Microwave Background Data Analysis) archive has a number of maps in a suitable format, including foreground data like predicted reddening as well as CMB maps. iconic behaviour honestly. 🌌

note: at present this command only supports all-sky, not partial, HEALPix maps. partial map support may be added at some point in the future if there is demand. so like, speak up if you want it ig 🙈

🎀 OPTIONS 🎀

in=<table> — where your input table lives. it can 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. cute 💖

ifmt=<in-format> — specifies the format of the input table as specified by parameter in. the known formats are listed in SUN/256. use this flag if you already know what format your table is in. if it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. this cannot always be done correctly tho — in which case the program will exit with an error explaining which formats were attempted. this parameter is ignored for scheme-specified tables.
icmd=<cmds> — specifies processing to be performed on the input table as specified by parameter in, before any other processing has taken place. the value here 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 this way defines the processing pipeline which is 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 the 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 '\fR' at the end of a line joins it with the following line.

pixdata=<pix-table> — where the table containing the pixel data lives. the data must be in the form of a HEALPix table, with one pixel per row in HEALPix order. these files are typically, but not necessarily, FITS tables. a filename or URL may be used, but a local file will be more efficient. 🏃‍♀️💨

some HEALPix format FITS tables seem to have rows which contain 1024-element arrays of pixels instead of single pixel values. this (rather perverse?) format is not currently supported here, but if there is demand support could be added.

pfmt=<in-format> — file format for the HEALPix pixel data table. this is usually, but not necessarily, FITS.
pcmd=<cmds> — specifies processing to be performed on the pixel data table as specified by parameter pixdata, before any 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 alternatively 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. a backslash character '\fR' at the end of a line joins it with the following line.

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. 💅

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 the result gets written as a new table to disk or wherever, as determined by the out and ofmt parameters. but bestie, there are other possibilities, and they correspond to all the uses a table can be put to other than outputting it — like 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's 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, so you can be lazy, we love that). 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".

pixorder=nested|ring|(auto) — selects the pixel ordering scheme used by the pixel data file. there are two different ways of ordering pixels in a HEALPix file, "ring" and "nested", and the sampler needs to know which one is in use. if you know which is in use, choose the appropriate value for this parameter; if (auto) is used it will attempt to work it out from headers in the file (the ORDERING header). if no reliable ordering scheme can be determined, the command will fail with an error. 🚨
stat=point|mean — determines how the pixel values will be sampled to generate an output value. the options are:
point — just grabs the value at the pixel that covers the position you handed it. Real simple, real direct. Heads up though: when you pick this one, the radius parameter is not used at all, so don't even worry about it 💅
- mean — averages the values across every pixel inside the radius you gave it in the radius parameter. And bestie, listen: this averaging is somewhat approximate — all pixels that are mostly within the radius get averaged together with equal weights. So it's giving "vibes-based mean", not a precision situation, okay? 🫶
lon=<expr> — an expression that evaluates to the longitude coordinate, in degrees, in the input table — the spot where you wanna sample from the pixel data table. Usually this is just the name or ID of a column in the input table, or some expression involving one. 🎀 If that coordinate doesn't match the coordinate system the pixel data table is using, then you gotta set both coordinate systems with the insys and pixsys parameters. Both. Not one. Both. 😤
lat=<expr> — exactly the same energy as lon, but for the latitude coordinate, in degrees, in the input table, again for sampling from the pixel data table. Again: usually a column name or ID, or an expression involving one. And again, if it doesn't match the pixel data table's coordinate system, set both with insys and pixsys. ✨
insys=icrs|fk5|fk4|galactic|supergalactic|ecliptic — tells everyone which sky coordinate system your sample positions from lon/lat are living in. And here's the lil shortcut: if your sample positions are already in the same coordinate system as the pixel data table, you can set both insys and pixsys to null and call it a day. Slay. 💖

The coordinate systems on the menu:

icrs: ICRS (Right Ascension, Declination) ⭐
fk5: FK5 J2000.0 (Right Ascension, Declination) ⭐
fk4: FK4 B1950.0 (Right Ascension, Declination) ⭐
galactic: IAU 1958 Galactic (Longitude, Latitude) 🌌
supergalactic: de Vaucouleurs Supergalactic (Longitude, Latitude) 🌌
ecliptic: Ecliptic (Longitude, Latitude) 🌞

pixsys=icrs|fk5|fk4|galactic|supergalactic|ecliptic — same deal as insys, except this one declares the sky coordinate system used for the HEALPix data sitting in the pixdata file. And yep, same lil shortcut: if your sample positions are given in the same coordinate system as the pixel data table, you can set both insys and pixsys to null. Two-for-one, we love to see it 😌

The coordinate systems on the menu (yes it's the same list, no I'm not skipping it, details matter bestie):

icrs: ICRS (Right Ascension, Declination) ⭐
fk5: FK5 J2000.0 (Right Ascension, Declination) ⭐
fk4: FK4 B1950.0 (Right Ascension, Declination) ⭐
galactic: IAU 1958 Galactic (Longitude, Latitude) 🌌
supergalactic: de Vaucouleurs Supergalactic (Longitude, Latitude) 🌌
ecliptic: Ecliptic (Longitude, Latitude) 🌞

radius=<expr> — sets the radius, in degrees, over which pixels get sampled to generate the output statistic — what exactly it does depends on what you set stat to. Most of the time you'll just toss in a constant value, but it's allowed to be an algebraic expression based on columns from the input table, so go off 🌈

🚨 Not used if stat=point. Periodt. Don't @ me.

🌟 SEE ALSO 🌟

stilts(1)

If the package stilts-doc is installed, the full documentation SUN/256 is available in HTML format, right here:

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

Ngl, "which lack the support" is exactly what the doc says. I'm not fixing it. It's iconic. 🙈

👑 AUTHOR 👑

Mark Taylor (Bristol University)

okay that's the whole page bestie, you're officially fluent in stilts-pixsample 💖 this one's STILTS version 3.5.4-debian, stamped Mar 2017, and it's page STILTS-PIXSAMPLE(1) of the manual. go sample some pixels, you absolute main character ✨🦋

📦 where this page comes from

ubuntu stonking: stilts 3.5.4-1 · LGPL-2.1-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms