STILTS-PLOT2CUBE(1)

📦
version 3.5.4 · 5 versions
, in ubuntu stonking

💖 stilts-plot2cube(1) 💖

Stilts commands — okay so this is the manual page for stilts-plot2cube, and bestie, it is A LOT. We're doing part 1 of 5, so hydrate, get comfy, and let's go 🫶

✨ NAME ✨

stilts-plot2cube — Draws a cube plot 🧊✨

🎀 SYNOPSIS 🎀

       stilts plot2cube [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>] [xscale=linear|log|asinh(<a>)|symlog(<t>,<s>)]
                        [yscale=linear|log|asinh(<a>)|symlog(<t>,<s>)]
                        [zscale=linear|log|asinh(<a>)|symlog(<t>,<s>)]
                        [xlog=true|false] [ylog=true|false] [zlog=true|false]
                        [xflip=true|false] [yflip=true|false]
                        [zflip=true|false] [isometric=true|false]
                        [xlabel=<text>] [ylabel=<text>] [zlabel=<text>]
                        [xcrowd=<number>] [ycrowd=<number>] [zcrowd=<number>]
                        [labelangle=horizontal|angled|adaptive]
                        [frame=true|false] [minor=true|false]
                        [gridaa=true|false] [texttype=plain|antialias|latex]
                        [fontsize=<int-value>] [fontstyle=standard|serif|mono]
                        [fontweight=plain|bold|italic|bold_italic]
                        [xmin=<number>] [xmax=<number>] [xsub=<lo>,<hi>]
                        [ymin=<number>] [ymax=<number>] [ysub=<lo>,<hi>]
                        [zmin=<number>] [zmax=<number>] [zsub=<lo>,<hi>]
                        [phi=<degrees>] [theta=<degrees>] [psi=<degrees>]
                        [zoom=<factor>] [xoff=<pixels>] [yoff=<pixels>]
                        [zoomaxes=[[x][y][z]]] [zoomfactor=<number>]
                        [leglabelN=<text>] [layerN=<layer-type> <layerN-
                        specific-params>] [geomN=components|vector|polar]

🦋 DESCRIPTION 🦋

Okay so plot2cube draws plots in a Cartesian 3-dimensional space. The plotting volume is a cube, viewed from the outside, and it's usually bounded by an annotated wire frame. It's giving aquarium but for your data 💅

Positional coordinates are, by default, specified as x, y, z triples, like:

plot2cube layer1=mark in1=sim.fits x1=XPOS y1=YPOS z1=ZPOS

But you can pick other coordinate specifications with the per-layer geomN parameter, like:

plot2cube layer1=mark in=sim.fits geom1=vector xyz1=POS3D

or

plot2cube layer1=mark in1=sphere.fits geom1=polar lon1=RA lat1=DEC r1=RADIUS

Content gets added to the plot by specifying one or more plot layers using the layerN parameter. The N part is a suffix that applies to all the parameters affecting a given layer — any suffix (yes, even the empty string) is allowed, no gatekeeping here ✨

The available layers for this plot type are: mark, size, sizexy, xyzvector, xyzerror, link2, mark2, poly4, mark4, polygon, label, line3d, contour, spheregrid. That's fourteen icons, all in their own lane 😌

✨ OPTIONS ✨

🩷 General plotting 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: it includes space for axis labels, padding and other decoration hanging around outside the plot area itself. See also insets. 📐
  • insets=<top>,<left>,<bottom>,<right> — Defines how much space in pixels sits around the actual plotting area. That space is used for axis labels and other decorations, and whatever's left over just becomes an empty border.

The size and position of the actual plotting area is determined by this parameter along with xpix and ypix, so these three are besties fr.

The value of this parameter is 4 comma separated integers: <top>,<left>,<bottom>,<right>. Any or all of these values may be left blank, and in that case the corresponding margin gets calculated automatically based on how much space is actually required. Lowkey magic but it's just math 🧮

  • omode=swing|out|cgi|discard|auto — Determines how the drawn plot will be output, see SUN/256. The choices:
    • swing: The plot will be 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 in the same way as plots in TOPCAT. Main character energy honestly 👑
    • out: The plot will be written to a file given by out, using the graphics format given by ofmt.
    • cgi: The plot will be written in a way suitable for CGI use direct 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 spending effort to throw 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 that data is accessed when constructing the plot. There are two main flavours here: cached or not cached.

If no caching is used, rows are read sequentially from the specified input table(s) every time they are required. This generally requires a small resource footprint (though that can depend on how the table is specified 👀) and makes sense if the data only needs to be scanned once, or maybe if the table is 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 is performed, and plots are done using this cached data. This may use a significant amount of storage for large tables, but it's usually more sensible (faster) if the data will need to be scanned multiple times.

The options are:

  • simple: no caching, data read directly from input table
  • memory: cached to memory; OutOfMemoryError possible for very large plots 😭
  • disk: cached to disk
  • policy: cached using application-wide default storage policy, which is usually adaptive (a memory/disk hybrid situation)
  • persistent: cached to persistent files on disk, in the system temporary directory (defined by system property java.io.tmpdir). If this is used, plot data will be 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 it can leave potentially large files in your temporary directory 🫣
  • cache: synonym for memory (backward compatibility, we respect the elders)
  • basic-cache: 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 will make 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 🚧
Heads up on the default, because it's conditional bestie: 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 performs 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>[,...] — A comma-separated list of layer suffixes that determines the order in which layers are drawn on the plot. This can affect which symbols are plotted on top of, and so potentially obscure, which other ones. Stacking order is real 🥞

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 is appended to all the parameters specific to defining that layer.

By default, layers are drawn on the plot in the order in which 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 — no cap 🧢

  • 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. Solo layers, no legend for you 💅
  • legborder=true|false — If true, a line border is drawn around the legend. Frame it like a polaroid 🖼️
  • 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, so everything behind it is still visible.
  • 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 all 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 with suffixes missing from this list do not show up in the legend at all — ghosted, gone, blocked 🚫

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 of values 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. Center-stage confirmed 🎯

okay we're not done yet — part 2 is coming and there's still so much more to get into 💜

  • title=<value> — the text of a title to show at the top of the plot. If it's null (the default), no title is shown and there's more space for the graphics. ✨
  • auxmap=<map-name>|<color>-<color>[-<color>...] — the colour map used for Aux axis shading. A mixed bag of colour ramps is available as listed in SUN/256: 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. Note: many of these, including rainbow-like ones, are frowned upon by the visualisation community. 😬 You can also construct your own custom colour map by giving a sequence of colour names separated by minus sign ("-") characters. In this case the ramp is a linear interpolation between each pair of colours named, using the same syntax as when specifying a colour value. So for instance "yellow-hotpink-#0000ff" would shade from yellow via hot pink to blue. 🎨
  • auxclip=<lo>,<hi> — defines a subrange of the colour ramp to be used for Aux shading. The value is specified as a (low,high) comma-separated pair of two numbers between 0 and 1. If the full range 0,1 is used, the whole range of colours specified by the selected shader will be used. But if for instance a value of 0,0.5 is given, only those colours at the left hand end of the ramp will be seen. If the null (default) value is chosen, a default clip will be used. This generally covers most or all of the range 0-1 but for colour maps which fade to white, a small proportion of the lower end may be excluded, to ensure 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. However, for something like a density map when the whole plotting area is tiled with colours from the map, it may be better to supply the whole range 0,1 explicitly. 🤍
  • auxflip=true|false — if true, the colour map on the Aux axis will be reversed. 🔄
  • auxquant=<number> — allows the colour map used for the Aux axis to be quantised. If an integer value N is chosen then the colour map will be viewed as N discrete evenly-spaced levels, so that only N different colours will appear in the plot. This can be used to generate a contour-like effect, and may make it easier to trace the boundaries of regions of interest by eye. If left 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 that values in the Aux range are 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. Note that 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 on the other hand use a scaling function that corresponds to the actual distribution of the data, so that there are about the same number of points (or pixels, or whatever is being scaled) of each colour. The histogram options are somewhat more expensive, but can be a good choice if you are exploring data whose distribution is unknown or not well-behaved over its min-max range. The Histogram and HistoLog options both assign the colours in the same way, but they display the colour ramp with linear or logarithmic annotation respectively; the HistoLog option 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 not supplied, 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 not supplied, the value is determined from the plotted data. ⬆️
  • auxlabel=<text> — sets the label used to annotate the aux axis, if it is 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 result in more ticks, and 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. 🔢
  • 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. 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. 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 are 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 proportion 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. 🌈
  • animate=<table> — if not null, this parameter causes the command to 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. 🎬 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. 🔍
  • astream=true|false — set this to true and the animation control table you named with animate gets read as a stream. 💧 Heads up tho: if you do that, you have to hand over the afmt parameter too. Depending on what ops you're running and your processing mode, the read might just fail (sometimes it needs to read that table more than once, dramatic much 😭). You don't normally need to bother with this flag — bestie, in most cases the data streams automatically when that's the right move. But lowkey it can mean less resource usage when you're chewing through huge files in certain formats (VOTable, looking at you). And psst: this parameter is ignored for scheme-specified tables. ✋
  • acmd=<cmds> — says what processing should happen to the animation control table (the one from animate) before anything else runs. The value is one or more of the filter commands from SUN/256. Give more than one? Separate them with semicolon characters (";"). And you can repeat this parameter multiple times on the same command line to build up a whole lil stack of processing steps — that sequence of commands is literally the processing pipeline that gets performed on the table. 🛠️

You can also put the commands in 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. Commands inside the file can be separated by newline characters and/or semicolons, and blank lines or lines starting with a '#' character are just ignored, no drama. And a backslash character \ at the end of a line joins it with the following line. 🫶

  • parallel=<int-value> — how many threads run at the same time when animation output is being produced. Only used if you supplied the animate parameter. Default is however many processors the JVM can apparently see. 👑
  • xscale=linear|log|asinh(<a>)|symlog(<t>,<s>) — the mapping of your data onto graphical coordinates on the X axis. Your options are:
    • linear: linear scale, periodt.
    • log: logarithmic scale.
    • asinh: scaling based on the inverse hyperbolic sin function. It's approximately linear near the origin and approximately logarithmic far away from it. It takes one parameter — the "linear width" a — which controls how far the linear-like region stretches, and it must be strictly positive. The function is x->asinh(x/a).
    • symlog: symmetric logarithmic scale. Linear near the origin, and positive/negative logarithmic for larger values. Two parameters: t (a.k.a. linthresh) and s (a.k.a. linscale). Both must be strictly positive. The linear region is in the range -t<x<+t, and the graphical extent from the origin to t is the same as s decades in the logarithmic region.

For the options with parameters, the values go after the name in brackets, like "symlog(10,0.5)". If the parameters are missing (like just "symlog") some default values get used. ✨

linear and log should be self-explanatory, bestie. symlog and asinh let you plot over a wide dynamic range like log, but unlike log they can handle negative and positive values. In both cases the scaling near the origin is more or less linear (like x), and far from the origin it's more or less logarithmic (like log(x) or -log(-x)). symlog just switches between the two regimes at a given threshold, while asinh transitions smoothly between them. These options were copied from the equivalent functionality in matplotlib. iykyk. 💅

  • yscale=linear|log|asinh(<a>)|symlog(<t>,<s>) — same deal but for the Y axis 💜. Options:
    • linear: linear scale.
    • log: logarithmic scale.
    • asinh: scaling based on the inverse hyperbolic sin function. Approximately linear near the origin, approximately logarithmic far from it. One parameter — the "linear width" a — controlling the extent of the linear-like region, and it must be strictly positive. The function is x->asinh(x/a).
    • symlog: symmetric logarithmic scale. Linear near the origin, positive/negative logarithmic for larger values. Two parameters: t (a.k.a. linthresh) and s (a.k.a. linscale), both strictly positive. Linear region is -t<x<+t, and the graphical extent from the origin to t matches s decades in the logarithmic region.

Parameters go in brackets after the name, e.g. "symlog(10,0.5)". Missing parameters (e.g. "symlog") means defaults get used.

linear and log = self-explanatory. symlog and asinh cover a wide dynamic range like log, but they can also take negative as well as positive values. Near the origin the scaling is more or less linear (like x), far from it more or less logarithmic (like log(x) or -log(-x)). symlog switches at a given threshold, asinh transitions smoothly. Copied from the equivalent functionality in matplotlib. 🌈

  • zscale=linear|log|asinh(<a>)|symlog(<t>,<s>) — you guessed it, but for the Z axis 🦋. Options:
    • linear: linear scale.
    • log: logarithmic scale.
    • asinh: scaling based on the inverse hyperbolic sin function. Approximately linear near the origin and approximately logarithmic far from it. One parameter, the "linear width" a, controlling the extent of the linear-like region, strictly positive. Function is x->asinh(x/a).
    • symlog: symmetric logarithmic scale. Linear near the origin, positive/negative logarithmic for larger values. Two parameters, t (a.k.a. linthresh) and s (a.k.a. linscale), both strictly positive. Linear region spans -t<x<+t, and the graphical extent from origin to t equals s decades in the logarithmic region.

Same bracket situation: "symlog(10,0.5)", and missing parameters like "symlog" fall back to defaults.

linear and log speak for themselves. symlog and asinh both do the wide-dynamic-range thing like log, but they're the ones who can hang with negative values too. Near origin ≈ linear (like x), far from origin ≈ logarithmic (like log(x) or -log(-x)). symlog switches regimes at a threshold; asinh glides smoothly. Copied from matplotlib's equivalent functionality. 💫

  • xlog=true|false — false (the default) means the scale on the X axis is linear; true means it's logarithmic.
⚠️ Heads up: this option is deprecated in favour of the xscale option, which has way more flexible axis scaling options. She's old, she's tired, let her rest. 😴
  • ylog=true|false — false (the default) = linear scale on the Y axis; true = logarithmic.
⚠️ Also deprecated! Use yscale instead, it's way more flexible. 🙈
  • zlog=true|false — false (the default) = linear scale on the Z axis; true = logarithmic.
⚠️ Yep, deprecated too. zscale is the moment, it has more flexible axis scaling options. 💀
  • xflip=true|false — if true, the scale on the X axis increases in the opposite sense from usual (so right to left instead of left to right). 🔄
  • yflip=true|false — if true, the scale on the Y axis increases in the opposite sense from usual (e.g. right to left rather than left to right). 🔄
  • zflip=true|false — if true, the scale on the Z axis increases in the opposite sense from usual (e.g. right to left rather than left to right). 🔄
  • isometric=true|false — set it true and the scaling is the same on the X, Y and Z axes, so positions keep their natural position in 3-d Cartesian space. 🧊 Set it false and the three axes get scaled independently, so positions may end up squashed in some directions (not the vibe). This option is ignored if there's a mix of linear and logarithmic axes. 🚫
  • xlabel=<text> — the label used for annotating axis X. If you don't supply a value, a default one based on the plotted data gets used. 🏷️
  • ylabel=<text> — the label used for annotating axis Y. No value supplied? A default based on the plotted data steps in. 🏷️
  • zlabel=<text> — the label used for annotating axis Z. Same energy: no value = default based on the plotted data. 🏷️
  • xcrowd=<number> — controls how closely the tick marks are spaced on the X axis. Default is 1, which is normal crowding. Bigger values = more ticks, smaller values = fewer ticks. But bestie, the tick marks will never get so close that the labels overlap each other, so if you want seriously densely spaced marks you might need to shrink the font size too. 🎯
  • ycrowd=<number> — how closely the tick marks are spaced on the Y axis. Default 1 = normal crowding. Larger values give more ticks, smaller values give fewer. Same caveat tho: the marks won't be spaced so closely that the labels overlap each other, so for very closely spaced marks you may need to reduce the font size as well. 💅
  • zcrowd=<number> — how tightly the tick marks get squished together on the Z axis. Default is 1, aka normal crowding. Bigger value = more ticks, smaller value = fewer ticks, bestie. BUT 💀 they will not crowd so close that the labels start overlapping each other, so if you want those super tight marks you're gonna have to shrink the font size too. It's giving teamwork.
  • labelangle=horizontal|angled|adaptive — controls which way the numeric labels on the axes are facing. By default they're written parallel to the axes as long as they fit, but if they get too crowded they can get angled so they don't overlap. This option is literally just the parallel-or-angled controller. ✨

Your choices, queen:

  • horizontal: axis labels are horizontal
  • angled: axis labels are angled
  • adaptive: axis labels are horizontal if possible, but angled if necessary to fit more in
  • frame=true|false — if true, a cube wire frame with labelled axes gets drawn so you can see the limits of the plotted 3D region. If false, no wire frame, no axes, nada. 🫥
  • minor=true|false — if true, minor tick marks are painted along the axes right alongside the major tick marks. Minor tick marks do not have associated grid lines, just so you know. 🎀
  • gridaa=true|false — if true, grid lines are drawn with antialiasing. Antialiased lines look smoother (gorgeous, honestly) but may take perceptibly longer to draw. Only has any effect for bitmapped output formats. 🦋
  • texttype=plain|antialias|latex — determines how label text gets turned into actual 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. 💅

When you're not using LaTeX, antialiased text usually looks nicer, but it 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 — that's a MacOS java bug, not you, you're doing amazing. 😭

  • fontsize=<int-value> — size of the text font, in points. ⭐
  • fontstyle=standard|serif|mono — font style for text. The options:
    • standard
    • serif
    • mono
  • fontweight=plain|bold|italic|bold_italic — font weight for text. The options:
    • plain
    • bold
    • italic
    • bold_italic
  • xmin=<number> — minimum value of the data coordinate on the X axis. This sets the value before any subranging is applied. If you don't supply it, the value gets determined from the plotted data. 🙈
  • xmax=<number> — maximum value of the data coordinate on the X axis. Again, this sets the value before any subranging is applied. If you don't supply it, it's determined from the plotted data.
  • xsub=<lo>,<hi> — defines a normalised adjustment to the data range of the X axis. You give it a comma-separated pair of two numbers: the lower and upper bounds of the range of interest, respectively. This sub-range gets applied to the data range that would otherwise be used — either automatically calculated or explicitly supplied. Zero corresponds to the lower bound and one to the upper.

The default value 0,1 therefore has no effect. You could restrict the range to its lower half with the value 0,0.5. Slay. 🔥

  • ymin=<number> — minimum value of the data coordinate on the Y axis. Set before any subranging is applied. If not supplied, it's determined from the plotted data.
  • ymax=<number> — maximum value of the data coordinate on the Y axis. Set before any subranging is applied. If not supplied, it's determined from the plotted data.
  • ysub=<lo>,<hi> — normalised adjustment to the data range of the Y axis. Comma-separated pair of two numbers: lower and upper bounds of the range of interest. Applied to the data range that would otherwise be used, either automatically calculated or explicitly supplied; zero = lower bound, one = upper.

The default 0,1 has no effect, and you can restrict to the lower half with 0,0.5. Same energy as xsub, bestie.

  • zmin=<number> — minimum value of the data coordinate on the Z axis. Set before any subranging is applied. If not supplied, determined from the plotted data.
  • zmax=<number> — maximum value of the data coordinate on the Z axis. Set before any subranging is applied. If not supplied, determined from the plotted data.
  • zsub=<lo>,<hi> — normalised adjustment to the data range of the Z axis. Two comma-separated numbers, lower and upper bounds of the range of interest. Applied to the data range that would otherwise be used, either automatically calculated or explicitly supplied; zero = lower bound, one = upper.

Default 0,1 = no effect. Restrict to the lower half with 0,0.5. 💜

  • phi=<degrees> — first of the Euler angles, in the ZXZ sequence, defining the rotation of the plotted 3d space. Units are degrees. This is the rotation around the initial Z axis applied before the plot is viewed.
  • theta=<degrees> — second of the Euler angles, in the ZXZ sequence, defining the rotation of the plotted 3d space. Units are degrees. This one is the rotation towards the viewer. 👀
  • psi=<degrees> — second of the Euler angles, in the ZXZ sequence, defining the rotation of the plotted 3d space. Units are degrees.
  • zoom=<factor> — sets the magnification factor at which the plotted 3D region itself is viewed, without affecting its contents. Default is 1, which means the cube fits into the plotting space however it's rotated. Much higher zoom factors will result in parts of the plotting region and axes being drawn outside of the plotting region — so, invisible. 💀
  • xoff=<pixels> — shifts the whole plot within the plotting region by the given number of pixels in the horizontal direction.
  • yoff=<pixels> — shifts the whole plot within the plotting region by the given number of pixels in the vertical direction.
  • zoomaxes=[[x][y][z]] — picks which axes the zoom navigation actions actually affect. 🎯

If no value is supplied (that's the default), the mouse wheel zooms around the center of the cube, and right-button (or CTRL-) drag zooms in the two dimensions most closely aligned with the plane of the screen, with the reference position set by the initial position of the mouse.

If this value is set (legal values are x, y, z, xy, yz, xz and xyz) then all zoom operations are around the cube center and affect the axes named.

  • zoomfactor=<number> — how much 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 wheel zooms faster; a value nearer 1 means it zooms slower. Values below 1 are not permitted. Periodt.
  • 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 into a single legend entry. 🫶

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

  • layerN=<layer-type> <layerN-specific-params> — selects one of the available plot types for layerN. A plot consists of a plotting surface, set up using the various unsuffixed parameters of the plotting command, plus zero or more plot layers. Each layer gets introduced by a parameter named layer<N>, where the suffix <N> is a label identifying the layer, and that suffix gets appended to all the parameter names that configure that layer. Suffixes may be any string — including the empty string, bestie.

This parameter may take one of the following values, described in more detail in SUN/256:

  • mark
  • size
  • sizexy
  • xyzvector
  • xyzerror
  • link2
  • mark2
  • poly4
  • mark4
  • polygon
  • label
  • line3d
  • contour
  • spheregrid

Each of these layer types comes with a list of type-specific parameters defining the details of that layer, including some or all of the following groups:

  • input table parameters (e.g. inN, icmdN)
  • coordinate params referring to input table columns (e.g. xN, yN)
  • layer style parameters (e.g. shadingN, colorN)

Every parameter notionally carries the same suffix N. But if the suffix isn't present, the application will try looking for a parameter with the same name with no suffix instead. That way, if several layers share the same value for a given parameter (input table, say), you can supply it with one unsuffixed parameter instead of repeating yourself with several same-value-different-suffix parameters. Efficiency icon. 👑

  • geomN=components|vector|polar — selects the geometry for coordinates of data in layer N. This determines what parameters you must supply to specify coordinate data for that layer.

The options, with the (suffixed) coordinate parameters they require:

  • components: xN (X coordinate), yN (Y coordinate), zN (Z coordinate)
  • vector: xyzN (3-element Cartesian component array)
  • polar: lonN (Longitude in decimal degrees), latN (Latitude in decimal degrees), rN (Radial distance)

💖 SEE ALSO 💖

  • stilts(1) — yeah bestie the main character herself, go read it 🫶

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

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

Like literally just open it in a browser and vibe. It's giving complete reference manual energy ✨

🌈 VERSION 🌈

STILTS version 3.5.4-debian

Ok so real talk: this is the Debian version of Stilts, and it lowkey does not have support for some file formats and network protocols 😭 like she's a lil stripped down, she's on a diet, she's ✨minimalist✨.

Wanna know exactly what's different? The receipts are here:

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

Go check it before you come for her, iykyk 💅

👑 AUTHOR 👑

Mark Taylor (Bristol University) — the icon, the legend, the moment. Periodt. 🎀

That's a wrap on STILTS-PLOT2CUBE(1) bestie!! This page came from the STILTS manual and it's dated Mar 2017 (yes she's vintage, she's an heirloom, she still eats 🍓). Go plot some cubes, drink some water, and stan a good coordinate system. Byeee 💖✨🦋🌸

📦 where this page comes from