Off-axis cheatsheet

Everything an off-axis projection can do, on one page. The Off-axis tutorial shows each item working, chapter by chapter.

Works the same on hydro and on particles unless a row says otherwise.

A word used everywhere below: los, the line of sight. It names the line through the object that the camera looks along. The vector points from the object toward the camera: the camera sits on the +los side and looks along -los, so los=[0,0,1] looks down from +z, like direction=:z. A projection adds up everything along that line, so each pixel is the total (or average) of one straight column through the data. "Off-axis" means the line of sight is not one of the box axes x, y or z.

Am I off-axis at all?

Some variables exist only on one path, so a call that silently took the other one gives a confusing error. Check m.los: if it is empty, the camera was never built.

Pointing the camera

Give exactly one line-of-sight specifier. If you give two, Mera raises an error.

And these modify whichever you chose:

axis= takes

:x, :y, :z, a 3-vector [ax,ay,az], or :angmom (alias :L) for the data's own angular momentum. Combining axis= with direction=:faceon/:edgeon is an error, because those presets already use L.

How los becomes an image

Mera builds a right-handed orthonormal basis from los:

with cam_right × up = los, so los points out of the image toward you.

Without up=, the camera uses world +z as its up hint, falling back to +y when the line of sight is within 3 degrees of the z axis. Along the six box directions this gives:

"The same orientation" means the image axes agree. The pixel grids still differ slightly, because the two paths place pixel edges differently, so do not subtract one map from the other.

Pass up= yourself whenever the default is not what you want. position_angle then rolls the result about the line of sight without changing m.los.

One rule, every spelling. The same up rule is the reference for inclination/azimuth and for face_on/edge_on, so these are identical views, not merely the same line of sight:

face_on and edge_on use the same camera rule, so their frames match the presets when the angular momentum matches. They measure it about the centre of mass of the whole object unless you give center or aperture, while the presets measure it about center, inside fov and after mask. Pass a frame on as los=fr.los, up=fr.up.

Near the pole the up rule uses +y inside a 3 degree cone, so a face-on galaxy whose spin axis wobbles by a hundredth of a degree keeps its roll. A spin axis that crosses the edge of the cone between two snapshots still makes the image jump, so for a time series pass one fixed axis=L or up=.

Framing

Without fov, an off-axis frame auto-fits the data it was given, so an object appears to zoom as you rotate. fov is what stops that: the frame is then fixed by fov, symmetric about center and the same at every angle, whether the data fills it or not. That holds for sparse data too, such as a star disc, a masked selection or a thin depth slab. With :circle, a grid frame is one coarse cell wider than fov, so a gas map and a star map share a pixel grid only with aperture=:square.

fov is silently capped at 0.49·boxlen for :circle and 0.49/√2·boxlen for :square.

Cutting along the line of sight

zrange is world space and does not follow the camera; depth does. On an axis-aligned call the line of sight is a box axis, so zrange already cuts this slab and depth is refused.

fov gives an uneven depth on its own: the sphere it selects is deepest on axis and reaches zero at the frame boundary. depth is what makes the column the same length everywhere.

Whole cells or partial ones

Use split=true when the edge matters: a small aperture, a thin slab, or any time you stack slabs and expect them to re-sum. With whole cells, a cell on a cut is counted by both pieces. On a regular grid a tilted line of sight can put many cell centres exactly on a cut, so the pieces add up to more than the whole.

split=true re-sums exactly: the pieces add up, and the map holds the mass of the split region. How wrong whole cells are depends entirely on your data. Both checks below come out at 0.0 percent with split=true. Without it:

The two differ by three orders of magnitude. The coarse test grid puts many cell centres exactly on a face. The refined snapshot puts almost none there. And a 5 kpc aperture is a handful of coarse cells across, but hundreds of fine ones. Do not carry either number to your own run: measure it, as Chapter 5 of the tutorial does.

Getting the mass right, and getting the edge sharp

These are two different jobs and they need two different keywords.

split alone gives the right number with a staircase edge, because a half-in cell still deposits its (reduced) mass over its whole footprint. refine cuts that cell into children so the mass sits where it belongs. Both conserve: the total is unchanged by refining, it just moves.

projection(gas, :sd; center=[:bc], fov=5, fov_unit=:kpc, split=true, refine=2, los=[1,2,3])

refine needs fov and split=true, because it subdivides the cells the sphere crosses; it raises otherwise. It does not apply to the depth slab, which is not a region.

Cost grows with the boundary area, at most 8^N per boundary cell, so refine=2 is usually plenty and refine_to is the safer knob when the AMR level varies across the boundary.

The same two keywords exist on subregion for a region you select yourself, and that :fraction column flows into off-axis maps too:

subregion(gas, sphere(10; center=[:bc], range_unit=:kpc); split=true, refine=2)

Choosing the axis from the data

What the presets measure. direction=:faceon, :edgeon and axis=:angmom compute the axis from the data that gets drawn, about center:

• These narrow the sum: mask, parttypes, the fov sphere (radius fov, or √2·fov for aperture=:square) and angmom_radius.
• These do not: xrange/yrange/zrange and depth. depth cannot, because it is measured along the axis being computed.
• Without fov or angmom_radius the sum runs over every cell or particle in the object. The outer material has the longest lever arm and can tilt a "face-on galaxy" by the halo. On particles that includes the dark matter, which usually dominates: pass parttypes=[:stars] or a mask to orient on the stars.

To orient on something other than what you draw, such as all components together, a selection you do not want in the picture, or a fixed axis for a time series, compute the vector yourself and pass it in. projection then uses it as given:

L = angmom([gas, stars, dm]; center=[:bc], range_unit=:kpc, radius=[15, :kpc])
projection(gas, :sd; axis=L, inclination=0, center=[:bc], range_unit=:kpc, mask=cold)

The vector is per object. Gas and stars each have their own, so :faceon on one is a different camera from :faceon on the other. To compare them, compute one vector and pass it to both:

L = angmom([gas, stars]; center=[:bc], range_unit=:kpc, radius=[15, :kpc])
projection(gas,   :sd; axis=L, inclination=0, center=[:bc], range_unit=:kpc)
projection(stars, :sd; axis=L, inclination=0, center=[:bc], range_unit=:kpc)

The orientation is measured in the box velocity frame. For an object streaming through the box, measuring about its own centre of mass largely cancels that, and angmom(...; vcenter=:auto) removes the bulk motion outright.

How a cell lands on the pixels

Each kernel hands out the whole of every cell: the shares it gives to the pixels add up to one. So all four keep the map total equal to the object's total, to rounding error. In tests the difference is a few units of the last digit (eps), and at most about one part in 10¹² for :exact with pixels much finer than the cells. The kernels differ in where the mass goes, not in how much there is. This holds for extensive maps, the ones that add up: :mass and :sd on cells, :ekin, :etherm and :volume with mode=:sum, :sd times the pixel area on particles, and any particle quantity with mode=:sum. A mean such as :T does not sum to anything.

On particles the default is :cic, not :overlap. Points have no footprint, so :overlap and :exact fall back to :cic and say so once. nmax does not exist there.

Variables

Available on any path

Almost everything getvar can produce: :sd, :mass, :rho, :T, :vx, the velocity dispersions, and so on. The three exceptions are listed under Axis-aligned only below.

Off-axis only

Asked for on an axis-aligned call, these raise. The velocity ones name the box-frame equivalent.

Axis-aligned only

:r_cylinder, :r_sphere, :ϕ. These describe the pixel's own geometry, and an off-axis pixel is a slanted column with no single radius.

σ against σLOS, v against vLOS

This distinction is the reason there are two sets.

Both work off-axis. :σz on a face-on view is still the simulation z, which is almost never what a face-on view is asking about. The line-of-sight pair is the observable one: :σlos is the width of the line a spectrograph would record. Edge-on, much of that width is rotation. projection has no vcenter; to take the rotation out first, use rotation_frame and restframe (see How Quantities Are Computed).

The full box-frame set is :σx :σy :σz :σ :σr_cylinder :σϕ_cylinder :σr_sphere :σθ_sphere :σϕ_sphere, each built from its own v and v².

The camera triple and the box triple describe one tensor in two frames, so σcamx² + σcamy² + σlos² = σx² + σy² + σz², pixel by pixel.

Counting what fed a pixel

:ncell and :npart ride along with any other variable and are filled by the same deposit. What the number means depends on the kernel:

Use it to find the pixels you cannot quote: a pixel holding one object has a dispersion of exactly zero, and a mean that is just that one object.

Weighting and totals

:sd and :mass on hydro are always summed; mode changes the other variables.

On particles projection(part, :mass) is the mass-weighted mean particle mass, because a particle has no volume. For the mass in each pixel use mode=:sum, or :sd times the pixel area.

Dispersions are always built from weighted means, whatever mode says: a width is not a sum. With mode=:sum the velocity components themselves (:vx and so on) are still sums.

Masking

mask= takes one boolean per row of the object you pass.

cold = getvar(gas, :T, :K) .< 1e4
projection(gas, :sd; los=[1,2,3], mask=cold, center=[:bc], fov=16, fov_unit=:kpc)

It composes with fov everywhere, with depth and split on grid data, and with parttypes on particles. It also sets the camera for :faceon, :edgeon and axis=:angmom: mask=cold orients on the cold gas, and parttypes=[:dm], direction=:faceon on the dark matter alone. Pass axis=L if the axis should come from other data.

For value-space selection, filterdata and getmask build masks from any getvar quantity.

Slices

A slice is not a projection. It is a nearest-cell painter on a plane: cells tile space, one owns each pixel, and nothing is integrated or conserved.

sl = slice(gas, :rho, :g_cm3; los=[1,2,3], center=[:bc], pxsize=[0.5,:kpc])

Slices work on cell data only (not particles), one variable at a time. offset/offset_unit moves the plane along the view, and xrange/yrange set the window in the camera plane. There is no fov and no binning. There is no cell count, because it would read 1 everywhere. cellsize against pixsize is the useful diagnostic: where the cell is larger than the pixel, the extra pixels carry no extra information.

What comes back

Empty off-axis pixels are 0.0, not NaN: filter on > 0 before taking a logarithm or a minimum.

Off-axis, getextent is measured from the frame centre. On the axis-aligned path it is absolute box coordinates.

Reproducing a map

A map carries what you need to make it again. provenance(m) records the snapshot and the Mera build (path, output, time, levels, version and commit). The camera is on the map itself: m.los, m.up, m.cam_right, m.center, m.pixsize and m.extent. savemap stores both, so a map reloaded with loadmap still says where it came from and how it was made.

The one input that is not on the map is the data behind a :faceon, :edgeon or axis=:angmom view. That axis depends on what you loaded, center, the mask, parttypes, fov and angmom_radius. To repeat a view exactly, reuse the recorded vectors instead of the preset:

projection(gas2, :sd; los=m.los, up=m.up, center=[:bc], range_unit=:kpc, fov=16, fov_unit=:kpc)

For a time series, compute the axis once with angmom and pass it to every snapshot. See also Reproducibility.

Movies, other data and periodic boxes

• An orbit movie: rotation_sequence sweeps :azimuth, :inclination or :position_angle. It defaults to axis=:angmom and, without fov, fits the frame to the radius that holds 99 % of the mass.
• Gravity: projection(hydro, gravity, var). Radiative transfer has no velocities, so :faceon, :edgeon and axis=:angmom fail on it: pass axis=angmom(gas; center=[:bc]).
• Periodic boxes: an off-axis map cannot be rolled across the box, and periodic_recenter refuses it. Keep the object away from a box face (see Periodic Boxes).

Things that will surprise you

• A mask changes the picture size. Without fov, the frame is fitted around the data that is left after the mask. Two maps with different masks then have different pixel grids. Give fov to fix the frame.
• fov alone does not give equal depth. fov selects a sphere, so a ray through the centre of the frame is long and a ray near the edge is short. Add depth if every pixel should look through the same thickness.
• :σz is always the simulation's z direction, also in a face-on view. The spread you would measure with a telescope is :σlos.
• :σ is not the total spread. It is the spread of the speed. For the total, take √(σx² + σy² + σz²).
• Thin slabs with whole cells do not add up to the thick slab they were cut from, because a cell on a boundary is counted in both. Use split=true.
• Gas and stars give different :faceon views, because each rotates about its own axis. Compute one axis with angmom and pass it to both.
• direction=:x, :y and :z are not off-axis. The camera-only variables such as :vlos are refused there. Use los=[0,0,1] to get the camera path along a box axis.