STILTS-PLOT2SKY(1)

📦
version 3.5.4 · 5 versions
, in ubuntu stonking

🦋 NAME 🦋

stilts-plot2sky — she draws a sky plot. That's the whole job description, and she does it gorgeously. (It's part of the Stilts commands, and it lives in section 1, for anyone checking receipts. 💅)

✨ SYNOPSIS ✨

okay so the whole invocation looks like this, and yes it's giving long, but that's just because she has options:

stilts plot2sky [xpix=<int-value>] [ypix=<int-value>]
                [insets=<top>,<left>,<bottom>,<right>]
                [omode=swing|out|cgi|discard|auto]
                [storage=simple|memory|disk|policy|cache|basic-cache|persistent|parallel]
                [seq=<suffix>[,...]]
                [legend=true|false|null] [legborder=true|false]
                [legopaque=true|false] [legseq=<suffix>[,...]]
                [legpos=<xfrac,yfrac>] [title=<value>] [auxmap=<map-name>|<color>-<color>[-<color>...]]
                [auxclip=<lo>,<hi>]
                [auxflip=true|false] [auxquant=<number>]
                [auxfunc=log|linear|histogram|...] [auxmin=<number>]
                [auxmax=<number>] [auxlabel=<text>] [auxcrowd=<factor>]
                [auxwidth=<pixels>] [auxvisible=true|false|null]
                [forcebitmap=true|false] [compositor=0..1]
                [animate=<table>] [afmt=<in-format>]
                [astream=true|false] [acmd=<cmds>] [parallel=<int-value>]
                [projection=sin|aitoff|aitoff0|car|car0]
                [viewsys=equatorial|galactic|supergalactic|ecliptic]
                [reflectlon=true|false] [grid=true|false]
                [scalebar=true|false]
                [labelpos=Auto|External|Internal|...] [sex=true|false]
                [crowd=<number>] [gridcolor=<rrggbb>|red|blue|...]
                [gridtrans=0..1] [labelcolor=<rrggbb>|red|blue|...]
                [gridaa=true|false] [texttype=plain|antialias|latex]
                [fontsize=<int-value>] [fontstyle=standard|serif|mono]
                [fontweight=plain|bold|italic|bold_italic]
                [clon=<degrees>] [clat=<degrees>] [radius=<degrees>]
                [zoomfactor=<number>] [leglabelN=<text>] [layerN=<layer-type> <layerN-specific-params>]
                [datasysN=equatorial|galactic|supergalactic|ecliptic]

💖 DESCRIPTION 💖

So plot2sky draws plots on the celestial sphere. The way that sphere shows up on your screen is controlled by the projection parameter. By default you get a view of a rotatable sphere seen from the outside — which, for small regions of sky, approximates a tangent projection — but no cap, Hammer-Aitoff and Plate Carée projections are also available. She also ships with a bunch of options for drawing and labelling the coordinate grid, so your sky plot can actually tell you where you are. 🎀

Positional coordinates are given as lon,lat pairs — longitude and latitude in decimal degrees. By default those get represented in the output in the same coordinate system, unlabelled. That's the chill default. But babe, she can also transform between different coordinate systems if you specify the per-plot view system with the viewsys parameter and the per-layer data system with the datasysN parameter, like:

plot2sky viewsys=galactic layer1=mark in1=cat.fits lon1=RA2000 lat1=DEC2000 datasys1=equatorial

Content gets added to the plot by specifying one or more plot layers with the layerN parameter. The N part is a suffix applied to every parameter affecting that layer, and literally any suffix is fair game (including the empty string, iconic behaviour honestly). The available layers for this plot type are:

mark, size, sizexy, skyvector, skyellipse, skycorr, link2, mark2, poly4, mark4, polygon, area, central, label, arealabel, contour, skydensity, healpix, skygrid.

👑 OPTIONS 👑

  • xpix=<int-value> — Size of the output image in the X direction, in pixels. This includes space for any axis labels, padding, and other decoration outside the plot area itself. See also insets. ✨
  • ypix=<int-value> — Size of the output image in the Y direction, in pixels. Same deal: this includes space for axis labels, padding, and other decoration outside the actual plot area. See also insets.
  • insets=<top>,<left>,<bottom>,<right> — Defines how much space, in pixels, goes around the actual plotting area. That space is for axis labels and other decorations, and whatever's left over becomes an empty border.

The size and position of the actual plotting area is determined by this parameter together with xpix and ypix.

The value is 4 comma-separated integers: <top>,<left>,<bottom>,<right>. Any or all of these values can be left blank, and then the corresponding margin gets calculated automatically based on how much space is required. 🫶

  • omode=swing|out|cgi|discard|auto — Determines how the drawn plot gets output. See SUN/256.
    • swing: The plot is displayed in a window on the screen. This plot is "live" — it can be resized and (except for old-style plots) navigated around with mouse actions the same way you'd do it with plots in TOPCAT. 🔥
    • out: The plot is written to a file given by out, using the graphics format given by ofmt.
    • cgi: The plot is written in a way suitable for CGI use straight from a web server. The output is in the graphics format given by ofmt, preceded by a suitable "Content-type" declaration.
    • discard: The plot is drawn, but discarded. There is no output. (Not me drawing a whole plot and then throwing it away 💀)
    • auto: Behaves as swing or out mode depending on the presence of the out parameter.
  • storage=simple|memory|disk|policy|cache|basic-cache|persistent|parallel — Determines the way data is accessed when the plot is being constructed. There are two main vibes here: cached or not cached.

If no caching is used, rows are read sequentially from the specified input table(s) every single time they're required. That generally means a small resource footprint (though that can depend on how the table is specified), and it makes sense if the data only needs to be scanned once — or maybe if the table is, like, very large. If caching is used, the required data is read once from the specified input table(s), then prepared and cached before any plotting happens, and the plots are done using that cached data. Fair warning: this can eat a significant amount of storage for large tables, but it's usually more sensible (read: faster) if the data will need to be scanned multiple times. There are various options for cache storage.

The options are:

  • simple: no caching, data read directly from the input table
  • memory: cached to memory; OutOfMemoryError possible for very large plots 😭
  • disk: cached to disk
  • policy: cached using the application-wide default storage policy, which is usually adaptive (a memory/disk hybrid)
  • persistent: cached to persistent files on disk, in the system temporary directory (defined by the system property java.io.tmpdir). If this is used, plot data is stored on disk in a way that means it can be re-used between STILTS invocations, so data preparation can be avoided on subsequent runs. Note however that it can leave potentially large files in your temporary directory. 🙈
  • cache: synonym for memory (backward compatibility)
  • basic-cache: a dumber version of memory (no optimisation for constant-valued columns)
  • parallel: experimental version of the memory-based cache that reads into the cache in parallel for large files. This makes the plot faster to prepare, but interaction is a bit slower and sequence-dependent attributes of the plot may not come out right. This experimental option may be withdrawn or modified in future releases.

The default value is memory if a live plot is being generated (omode=swing), since in that case the plot needs to be redrawn every time the user does plot navigation actions or resizes the window, or if animations are being produced. Otherwise (e.g. output to a graphics file) the default is simple.

  • seq=<suffix>[,...] — Contains a comma-separated list of layer suffixes that determines the order in which layers are drawn on the plot. This can affect which symbols get plotted on top of — and therefore potentially obscure — which other ones. 💅

When specifying a plot, multiple layers may be specified, each introduced by a parameter layer<N>, where <N> is a different (arbitrary) suffix labelling the layer, and it gets appended to all the parameters specific to defining that layer.

By default the layers are drawn on the plot in the order the layer* parameters appear on the command line. But if this parameter is specified, each comma-separated element is interpreted as a layer suffix, giving the ordered list of layers to plot. Every element of the list must be a suffix with a corresponding layer parameter, but missing or repeated elements are allowed. Slay.

  • legend=true|false|null — Whether to draw a legend or not. If no value is supplied, the decision is made automatically: a legend is drawn only if it would have more than one entry.
  • legborder=true|false — If true, a line border is drawn around the legend.
  • legopaque=true|false — If true, the background of the legend is opaque, and the legend obscures any plot components behind it. Otherwise, it's transparent.
  • legseq=<suffix>[,...] — Determines which layers are represented in the legend (if present) and in which order they appear. The legend has a line for each layer label (as determined by the leglabelN parameter). If multiple layers have the same label, they contribute to the same entry in the legend, with style icons plotted over each other. The value of this parameter is a comma-separated sequence of layer suffixes, which determines the order in which the legend entries appear. Layers whose suffixes are missing from this list do not show up in the legend at all. 👀

If no value is supplied (the default), the sequence is the same as the layer plotting sequence (see seq).

  • legpos=<xfrac,yfrac> — Determines the internal position of the legend on the plot. The value is a comma-separated pair giving the X and Y positions of the legend within the plotting bounds — so for instance "0.5,0.5" will put the legend right in the middle of the plot. If no value is supplied, the legend will appear outside the plot boundary. 🎀
  • title=<value> — the text that gets slapped at the top of your plot 💖. If it's null (which is the default, bestie), no title shows up at all and you get more room for the graphics. Extra pixels, zero regrets ✨
  • auxmap=<map-name>|<color>-<color>[-<color>...] — the colour map used for Aux axis shading 🎨

SUN/256 has a whole mixed bag of colour ramps, and they're all listed right here: inferno, magma, plasma, viridis, cividis, cubehelix, sron, rainbow, rainbow2, rainbow3, pastel, cosmic, ember, gothic, rainforest, voltage, bubblegum, gem, chroma, sunset, neon, tropical, accent, gnuplot, gnuplot2, specxby, set1, paired, hotcold, guppy, iceburn, redshift, pride, rdbu, piyg, brbg, cyan-magenta, red-blue, brg, heat, cold, light, greyscale, colour, standard, bugn, bupu, orrd, pubu, purd, painbow, huecl, infinity, hue, intensity, rgb_red, rgb_green, rgb_blue, hsv_h, hsv_s, hsv_v, yuv_y, yuv_u, yuv_v, scale_hsv_s, scale_hsv_v, scale_yuv_y, mask, blacker, whiter, transparency.

ngl, a LOT of these — including the rainbow-ish ones — get side-eye from the visualisation community 💀 be warned, bestie.

You can also build your own custom colour map by handing over a sequence of colour names separated by minus sign (-) characters 🎀 In that case the ramp is a linear interpolation between each pair of colours you named, using the same syntax as when you specify a colour value. So for example "yellow-hotpink-#0000ff" would shade from yellow via hot pink to blue. Obsessed with that actually.

  • auxclip=<lo>,<hi> — defines a subrange of the colour ramp for Aux shading ✂️ You give it a (low,high) comma-separated pair of two numbers between 0 and 1.

If you use the full range 0,1 the whole range of colours specified by the selected shader gets used. But if you hand it something like 0,0.5, only those colours at the left hand end of the ramp show up.

If you pick the null (default) value, a default clip is used 💅 It generally covers most or all of the range 0-1, but for colour maps that fade to white, a small proportion of the lower end may be excluded, so that all the colours are visually distinguishable from a white background. This default is usually a good idea if the colour map is being used with something like a scatter plot, where markers are plotted against a white background 🫶 But for something like a density map, where the whole plotting area is tiled with colours from the map, it may be better to supply the whole range 0,1 explicitly, fr fr.

  • auxflip=true|false — if true, the colour map on the Aux axis gets reversed 🔄 mirror moment.
  • auxquant=<number> — lets the colour map used for the Aux axis be quantised ✨ If you pick an integer value N, the colour map gets viewed as N discrete evenly-spaced levels, so only N different colours show up in the plot. This can generate a contour-like effect and may make it easier to trace the boundaries of regions of interest by eye 👀

If you leave it blank, the colour map is nominally continuous (though in practice it may be quantised to a medium-sized number like 256).

  • auxfunc=log|linear|histogram|... — defines the way values in the Aux range get mapped to the selected colour ramp 🧚

The available options are:

  • log: Logarithmic scaling, positive values only
  • linear: Linear scaling
  • histogram: Scaling follows data distribution, with linear axis
  • histolog: Scaling follows data distribution, with logarithmic axis, positive values only
  • asinh: Asinh scaling, wide dynamic range for both positive and negative values
  • sqrt: Square root scaling
  • square: Square scaling
  • acos: Inverse cosine Scaling
  • cos: Cosine Scaling

For all these options the full range of valid data values is used, and displayed on the colour bar if applicable 👑 Heads up though: the logarithmic-based options Log and HistoLog will ignore non-positive values. The Linear, Log, Square and Sqrt options just apply the named function to the full data range. The histogram options are different — they use a scaling function that corresponds to the actual distribution of the data, so there are about the same number of points (or pixels, or whatever's being scaled) of each colour 🌈 The histogram options are somewhat more expensive, but they can be a good choice if you're exploring data whose distribution is unknown or not well-behaved over its min-max range. Histogram and HistoLog both assign the colours in the same way, but they display the colour ramp with linear or logarithmic annotation respectively; HistoLog also ignores non-positive values 💜

  • auxmin=<number> — minimum value of the data coordinate on the Aux axis 📉 This sets the value before any subranging is applied. If you don't supply it, the value is determined from the plotted data.
  • auxmax=<number> — maximum value of the data coordinate on the Aux axis 📈 This sets the value before any subranging is applied. If you don't supply it, the value is determined from the plotted data.
  • auxlabel=<text> — sets the label used to annotate the aux axis, if it's visible 🏷️
  • auxcrowd=<factor> — determines how closely the tick marks are spaced on the Aux axis, if visible 🎯 The default value is 1, meaning normal crowding. Larger values = more ticks, smaller values = fewer ticks. Tick marks will not however be spaced so closely that the labels overlap each other, so to get very closely spaced marks you may need to reduce the font size as well. iykyk.
  • auxwidth=<pixels> — determines the lateral size of the aux colour ramp, if visible, in pixels 📏
  • auxvisible=true|false|null — determines whether the aux axis colour ramp is displayed alongside the plot 👁️

If not supplied (the default), the aux axis will be visible when aux shading is used in any of the plotted layers.

  • forcebitmap=true|false — affects whether rendering of the data contents of a plot (though not axis labels etc) is always done to an intermediate bitmap rather than, where possible, being painted using graphics primitives 🖼️ This is a rather arcane setting that may nevertheless have noticeable effects on the appearance and size of an output graphics file, as well as plotting time. For some types of plot (e.g. shadingN=auto or shadingN=density) it will have no effect, since this kind of rendering happens in any case. Not me warning you it's arcane 💀

When writing to vector graphics formats (PDF and PostScript), setting it true will force the data contents to be bitmapped 😭 This may make the output less beautiful (round markers will no longer be perfectly round), but it may result in a much smaller file if there are very many data points. Trade-offs, bestie.

When writing to bitmapped output formats (PNG, GIF, JPEG, ...), it fixes shapes to be the same as seen on the screen rather than be rendered at the mercy of the graphics system, which sometimes introduces small distortions 👑

  • compositor=0..1 — defines how multiple overplotted partially transparent pixels get combined to form a resulting colour 🌸 The way this is used depends on the details of the specified plot.

Currently this parameter takes a "boost" value in the range 0..1. If the value is zero, saturation semantics are used: RGB colours are added in proporition to their associated alpha value until the total alpha is saturated (reaches 1), after which additional pixels have no further effect. For larger boost values, the effect is similar, but any non-zero alpha in the output is boosted to the given minimum value ✨ The effect of this is that even very slightly populated pixels can be visually distinguished from unpopulated ones, which may not be the case for saturation composition. Main character pixels only 💅

  • animate=<table> — if not null, this parameter makes the command create a sequence of plots instead of just one 🎬 The parameter value is a table with one row for each frame to be produced. Columns in the table are interpreted as parameters which may take different values for each frame; the column name is the parameter name, and the value for a given frame is its value from that row. Animating like this is considerably more efficient than invoking the STILTS command in a loop. Slay.

The location of the animation control table. This may take one of the following forms:

  • A filename.
  • A URL.
  • The special value -, meaning standard input. In this case the input format must be given explicitly using the afmt 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 🦋

  • afmt=<in-format> — specifies the format of the animation control table as specified by parameter animate 📋 The known formats are listed in SUN/256. This flag can be used if you 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 however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. Periodt.
  • astream=true|false — ok so if you set this true, that animation control table you named with animate gets read as a stream 🌀. Heads up though: you must also hand over the afmt parameter in that case, no exceptions. Depending on what operations you're running and which processing mode you're in, this can make the read fail — sometimes the table genuinely has to be read more than once and streaming just won't allow it. 💀 Normally you do not need to set this flag, because in most cases the data gets streamed automatically the moment that's the best move. But every now and then it means less resource usage when you're crunching big files in certain formats (VOTable, looking at you 👀). Also — this parameter is completely ignored for scheme-specified tables. Periodt.
  • acmd=<cmds> — this one tells stilts what processing to do on the animation control table named by animate, and it happens before anything else gets processed. The value is one or more of those filter commands described in SUN/256 ✨. Give it more than one? Separate them with semicolon characters (";"). And you can repeat this parameter as many times as you want on the same command line to stack up a whole list of processing steps — the sequence you build that way is the processing pipeline that runs on the table, no cap.

You can also drop your commands into an external file instead, using the indirection character '@'. So a value of "@filename" makes the file filename get read for a list of filter commands to execute 🎀. Inside that file, commands can be separated by newline characters and/or semicolons, and any 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 — like a lil glue stick for your syntax 💅.

  • parallel=<int-value> — decides how many threads run in parallel when animation output is being produced 🧵. Only used if you actually supplied the animate parameter — otherwise it's just vibing. The default value is the number of processors apparently available to the JVM.
  • projection=sin|aitoff|aitoff0|car|car0 — the sky projection used to display the plot 🌈.

The available options are:

  • sin: rotatable sphere
  • aitoff: Hammer-Aitoff projection with lon=0 at center
  • aitoff0: Hammer-Aitoff projection with lon=180 at center
  • car: Plate Carree projection (lon/lat on Cartesian axes) with lon=0 at center
  • car0: Plate Carree Projection (lon/lat on Cartesian axes) with lon=180 at center
Real talk, for historical reasons the projections named "aitoff" actually denote the equal-area Hammer-Aitoff projection and not the Aitoff projection itself. So don't come for me. 🙈

The Hammer-Aitoff projection is defined as:

  • x = [2sqrt(2)/sqrt(1+cos(lat)cos(lon/2))]cos(lat)sin(lon/2)
  • y = [sqrt(2)/sqrt(1+cos(lat)cos(lon/2))]sin(lat)
  • viewsys=equatorial|galactic|supergalactic|ecliptic — the sky coordinate system used for the generated plot 🌌.

Choosing this value goes hand in hand with the data coordinate system you might specify for plot layers. If you leave it unspecified, a generic longitude/latitude system is used, and all the lon/lat coordinates in your plotted data layers are assumed to be in that same system. But if you do supply a value here, then a sky system must be supplied for each data layer with the datasys parameter, and the coordinates get converted from data to view system before being plotted. ✨

The available options are:

  • equatorial: J2000 equatorial system
  • galactic: IAU 1958 galactic system
  • supergalactic: De Vaucouleurs supergalactic system
  • ecliptic: ecliptic system based on conversion at 2000.0
  • reflectlon=true|false — whether to invert the celestial sphere by displaying the longitude axis increasing right-to-left instead of left-to-right 🪞. Displaying the celestial sphere this way is conventional because that's literally what it looks like from the earth 🌍, so the default is true. Set it false if you wanna see the sphere from the outside, looking in. Main character energy either way.
  • grid=true|false — if true, sky coordinate grid lines get drawn on the plot 📐. If false, they're simply not there. Gone. Absent. 💅
  • scalebar=true|false — if true, a small bar is drawn near the bottom left of the plot, annotated with a distance in degrees, arc minutes or arc seconds, so you can eyeball the size of features on the plot 👀. It's giving helpful little ruler.
  • labelpos=Auto|External|Internal|... — controls whether and where the numeric annotations of the lon/lat axes show up 🏷️. The default option Auto usually does the sensible thing, but the other options exist so you can force labelling internally or externally to the plot region, or yeet the numeric labels entirely.

The available options are:

  • Auto: Uses External or Internal policy according to whether the sky fills the plot bounds or not
  • External: Labels are drawn outside the plot bounds
  • Internal: Labels are drawn inside the plot bounds
  • Basic: Labels are drawn somewhere near the grid line
  • Hybrid: Grid lines are labelled outside the plot bounds where possible, but inside if they would otherwise be invisible
  • None: Axes are not labelled
  • ExternalSys: Like External, but the axes are also labelled with coordinate system axis names
  • InternalSys: Like Internal, but the axes are also labelled with coordinate system axis names
The ExternalSys and InternalSys options use axis descriptions appropriate to the View coordinate system for the current plot; these options may not work well for plots which are all-sky or show a substantial proportion of the sky. So like, careful bestie 🫶
  • sex=true|false — if true, grid line labels are written in sexagesimal notation ⏱️; if false, in decimal degrees. That's it, that's the whole thing.
  • crowd=<number> — determines how closely sky grid lines are spaced 📏. The default value is 1, meaning normal crowding. Bigger values = more grid lines. Smaller values = fewer grid lines. Pick your density, diva ✨.
  • gridcolor=<rrggbb>|red|blue|... — the color of the plot grid 🎨, given by name or as a hexadecimal RGB value.

The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names are also understood — too many to list here, lowkey. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. 🌈

Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities — e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. 💜

  • gridtrans=0..1 — transparency of grid lines that may be drawn over the plot 👻. The range is 0 (opaque) to 1 (invisible). This value is 1-alpha. So yeah, invisible grid lines are a vibe, I guess ✨.
  • labelcolor=<rrggbb>|red|blue|... — the color of axis labels and other plot annotations 🏷️, given by name or as a hexadecimal RGB value.

The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names are also understood — too many to list here tbh. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. 🌸

Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities — e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. 💅

  • gridaa=true|false — if true, grid lines are drawn with antialiasing ✨. Antialiased lines look smoother, but may take perceptibly longer to draw. Only has any effect for bitmapped output formats. Trade-off city, bestie.
  • texttype=plain|antialias|latex — determines how to turn label text into characters on the plot 📝. Plain and Antialias both take the text at face value, but Antialias smooths the characters. LaTeX interprets the text as LaTeX source code and typesets it accordingly — full math-mode diva behavior 👑

When you're not using LaTeX, antialiased text usually looks nicer, but can be perceptibly slower to plot. At time of writing, on MacOS antialiased text seems to be required to stop the writing coming out upside-down for non-horizontal text (MacOS java bug). Not us fighting a java bug in the year of our lord 😭

  • fontsize=<int-value> — size of the text font in points 🔤.
  • fontstyle=standard|serif|mono — font style for text, the main character selection screen 💅.

The available options are:

  • standard
  • serif
  • mono
  • fontweight=plain|bold|italic|bold_italic — font weight for text 🫶.

The available options are:

  • plain
  • bold
  • italic
  • bold_italic
  • clon=<degrees> — longitude of the central position of the plot in decimal degrees 🌐. Use it with clat and radius. If the center is not specified, the field of view gets determined from the data. So like, it'll figure itself out.
  • clat=<degrees> — latitude of the central position of the plot in decimal degrees 🌐. Use it with clon and radius. If the center is not specified, the field of view gets determined from the data. Same deal, bestie.
  • radius=<degrees> — approximate radius of the plot field of view in degrees 📐. Only used if clon and clat are also specified. It's a package deal, no solo runs.
  • zoomfactor=<number> — sets the amount by which the plot view zooms in or out for each unit of mouse wheel movement 🖱️. A value of 1 means mouse wheel zooming has no effect. A higher value means the mouse wheel zooms faster, and a value nearer 1 means it zooms slower. Values below 1 are not permitted. That's the law 🚫
  • leglabelN=<text> — sets the presentation label for the layer with a given suffix 🏷️. This is the text displayed in the legend, if there is one. Multiple layers may use the same label — in which case they get combined to form a single legend entry. Slay, unified branding ✨

If no value is supplied (which is the default), the suffix itself is used as the label. Convenient 💅

💅 layerN=<layer-type> <layerN-specific-params>

okay bestie listen up, this one is literally the whole point of the command ✨ It picks which kind of plot type you want for layer N. So a plot is made of a plotting surface (that's set up with all those unsuffixed parameters of the plotting command) plus zero or more plot layers. Every layer gets introduced by a parameter named layer<N>, where that "<N>" suffix is a little label that IDs the layer, and it gets tacked onto all the parameter names that configure that layer. And the suffix? Can be ANY string. Even the empty string. Yes, truly, the audacity 💀

This parameter takes one of these values, and there's more detail in SUN/256 if you want the deep lore:

  • mark
  • size
  • sizexy
  • skyvector
  • skyellipse
  • skycorr
  • link2
  • mark2
  • poly4
  • mark4
  • polygon
  • area
  • central
  • label
  • arealabel
  • contour
  • skydensity
  • healpix
  • skygrid

And every single one of these layer types brings its own list of type-specific parameters to define the deets of that layer, covering some or all of these groups:

  • input table parameters (like inN, icmdN)
  • coordinate params that refer to input table columns (like xN, yN)
  • layer style parameters (like shadingN, colorN)

Here's the cute part 🌸 Every parameter notionally carries that same suffix N — but if the suffix isn't there, the application will go look for a parameter with the same name and no suffix instead. So if a bunch of your layers share a value for some parameter (input table, say), you can just supply it once with an unsuffixed parameter and save yourself from typing the same thing over and over with different suffixes. Living smart, not hard. Periodt 💅

🪐 datasysN=equatorial|galactic|supergalactic|ecliptic

This sets the sky system used to interpret the data longitude and latitude coordinate values you hand in, for one specific plot layer.

Choosing this value goes hand in hand with viewsys, which sets the view sky system for the entire plot, mmkay. So: if you don't specify either the view system or the data system, plotting happens in a generic sky system that's assumed to be the same for the data and the view. But — and this is important, bestie, don't skip it 😭 — if ANY layer has a supplied data sky system, then there must be an explicitly or implicitly supplied view sky system, because your data input coordinates are getting transformed into it. And if you don't supply it explicitly, the data system just defaults to the same value as the view system. Easy.

The options on the menu are:

  • equatorial: J2000 equatorial system 👑
  • galactic: IAU 1958 galactic system 🌌
  • supergalactic: De Vaucouleurs supergalactic system ✨
  • ecliptic: ecliptic system based on conversion at 2000.0 🌞

🫶 SEE ALSO

  • stilts(1) — the main character, go read it

If you've got the stilts-doc package installed, the full documentation SUN/256 is sitting right there in HTML format, no cap:

file:///usr/share/doc/stilts/sun256/index.html

🌈 VERSION

STILTS version 3.5.4-debian

Heads up babes: this is the Debian version of Stilts, and it's lowkey missing support for some file formats and network protocols 🙈 For the differences, go look at:

file:///usr/share/doc/stilts/README.Debian

👑 AUTHOR

Mark Taylor (Bristol University) — an absolute legend, fr fr 💖

and that's the whole page, bestie 🎀 this one's from Mar 2017, from the STILTS 3.5.4-debian era, so go forth and plot those skies. slay ✨💅

📦 where this page comes from