Projections API Reference

@project data quantity... [keyword=value...]

Project several quantities and bind each map to a variable of that name.

projection returns one object whose maps is a dictionary, so pulling several quantities out of it is a line of lookups:

pj = projection(gas, [:sd, :T], myargs=args)
sd = pj.maps[:sd]; T = pj.maps[:T]

This does the same in one line, and asks for the quantities together, which is also the form that lets the projection use its threads (see Performance):

@project gas sd T myargs=args
# sd and T are now the maps, and proj is the full projection object

Keywords pass straight through, so off-axis works the same way:

@project gas sd inclination=60 azimuth=30 binning=:exact

The full object is bound as proj, so the extent, units and everything else stay reachable:

heatmap(proj.extent[1:2], proj.extent[3:4], sd)

Like @loadall, this binds names in your scope. Inside a function or a package, prefer the explicit form above.

See also: projection, @loadall.

periodic_recenter(m; center=[0., 0., 0.], direction=:z, range_unit=:standard, verbose=verbose_mode)

Roll a projection so that center sits in the middle of the map.

On a periodic run a structure on a box face appears split across opposite edges of a projection. This shifts the map around the periodic boundary so it appears whole, and relabels extent and cextent so both are measured from center, which is then at (0, 0).

The shift is by whole pixels, so no value is altered and no interpolation happens: the sum over the map, and hence any total it represents, is unchanged. Only the frame moves.

center follows the usual convention: box fractions with range_unit=:standard (the default), or a physical length with range_unit=:kpc and friends. [:bc] means the box centre. A shift is only meaningful on an axis that actually wraps; if getinfo determined the run is not periodic, this warns rather than refusing, since the map may have come from somewhere else.

Pass the same direction you gave projection. A projection does not record which axis it looked along, so this cannot be inferred: with direction=:z the map spans x and y, with :x it spans y and z, with :y it spans x and z. Giving the wrong one rolls along the wrong axes.

Off-axis projections are not supported and are refused. Rolling only works because a whole-pixel shift of an axis-aligned map is the same thing as translating the box by a lattice vector. An off-axis camera plane is tilted with respect to the box, so no shift of its pixels corresponds to a periodic translation, and the result would be wrong rather than merely approximate.

p = projection(gas, :sd, :Msol_pc2)
q = periodic_recenter(p, center=[0., 0., 0.])   # the blast at the origin, made whole
heatmap(q.extent[1:2], q.extent[3:4], q.maps[:sd])

See also: projection.

gridoverlay(dataobject; level=:max, direction=:z, center=[:boxcenter], range_unit=:standard,
            xrange=[missing,missing], yrange=[missing,missing], zrange=[missing,missing],
            unit=:standard) -> (segments, extent, level)

Cell-boundary line segments of the AMR cells at one refinement level, viewed along direction (:x/:y/:z), for overlaying the AMR structure on a map. level is :max (default, the finest), :min, or an integer. The cell edges are de-duplicated.

The result is the 2-D footprint of that level's cells (collapsed along direction), so it suits both a projection and a slice:

• slice — pass a thin zrange (the slice plane) → the exact in-plane cell grid there;
• projection — use the full column → where that level's cells project to along the line of sight.

(The two coincide when the refined region is a column-aligned box, and differ for irregular refinement.)

Off-axis views work too: pass the same view keywords as projection — los/up, inclination/azimuth (or theta/phi, position_angle), axis=:angmom, or direction=:faceon/:edgeon. Each cell centre is projected through the camera basis and drawn as a cell-sized square (an approximate indicator; the true tilted-cube silhouette is a hexagon). Off-axis overlays are not edge-de-duplicated, so on dense AMR pick a coarser level or a sub-region to keep the segment count manageable.

Returns a NamedTuple: segments (a Vector{NTuple{4,Float64}} of (x1,y1,x2,y2) in the plane coordinates and unit), extent [xmin,xmax,ymin,ymax], and the level used. Plot with linesegments! — or, after using Makie, the convenience gridoverlay!(ax, go).

p  = projection(gas, :sd)
go = gridoverlay(gas; level=:max)         # the finest-cell grid, where it exists
# overlay go.segments on the heatmap of p.maps[:sd]

gridoverlay!(ax, go; color=(:white,0.3), linewidth=0.4)

Draw a gridoverlay result go onto a Makie axis ax (the AMR cell boundaries). Available after using Makie/CairoMakie.

benchmark_projection_hydro(gas_data, thread_counts::Vector{Int}, n_runs::Int=10, output_file::String="") → Dict

Execute comprehensive AMR hydro projection benchmark with robust statistical analysis.

This function serves as the main coordinator for hydro projection performance testing. It performs AMR structure analysis, data quality validation, executes both single-variable and multi-variable projection benchmarks across specified thread counts, and exports results in multiple formats with comprehensive statistical analysis.

Benchmark Methodology

• Single-Variable Test: Surface density projection (:sd → Msun/pc²)
• Multi-Variable Test: 10 simultaneous variable projections: vars = [:v, :σ, :σx, :σy, :σz, :vrcylinder, :vϕcylinder, :σrcylinder, :σϕcylinder, :cs]
• Statistical Robustness: several repetitions per configuration with coefficient of variation
• Quality Control: Success rate monitoring (>80% threshold for reliable data)
• Memory Profiling: Peak memory usage and garbage collection analysis

Threading Analysis

Evaluates performance across thread counts with derived metrics:

• Speedup: Performance improvement vs single-threaded execution
• Efficiency: Speedup per thread (percentage of ideal scaling)
• Memory Scaling: Memory usage patterns across thread configurations

Output Files Generated

• {output_file}.csv: Structured data for spreadsheet analysis and plotting
• {output_file}.json: Machine-readable structured data for programmatic access
• {output_file}_summary.txt: Human-readable performance report with insights

Arguments

• gas_data: HydroDataType object from loaddata() or gethydrodata()
• thread_counts::Vector{Int}: Thread counts to benchmark [1, 2, 4, 8, 16, ...]
• n_runs::Int=10: Statistical repetitions per configuration (10 for robust analysis)
• output_file::String="": Output filename base (auto-generated timestamp if empty)

Returns

Dictionary containing complete benchmark results with keys:

• n_threads, test_type, mean_time, std_time, speedup, efficiency
• mean_memory, success_rate, min_time, max_time, n_runs

Example Usage

# Load RAMSES hydro data
gas_data = loaddata(300, "/path/to/ramses/output/", :hydro)

# Run comprehensive benchmark (single + multi-variable)
results = benchmark_projection_hydro(gas_data, [1, 2, 4, 8, 16], 10, "performance_test")

# Results saved as:
# - performance_test.csv (for plotting with plot_results.jl)
# - performance_test.json (for programmatic analysis)  
# - performance_test_summary.txt (human-readable report)

Performance Insights

The benchmark automatically analyzes threading efficiency and provides guidance:

• Identifies optimal thread counts for your system and data size
• Detects threading bottlenecks and memory constraints
• Quantifies single vs multi-variable projection performance differences
• Provides statistical confidence intervals for all measurements

Integration Workflow

1. Data Loading: Use Mera's loaddata() for your RAMSES simulation
2. Benchmarking: Execute this function with desired thread counts
3. Visualization: Use plot_results.jl to create performance dashboards
4. Analysis: Review summary.txt for optimization recommendations

show_threading_info()

Display information about Julia threading configuration and recommendations.

projection()

Display an overview of variable symbols accepted by the projection interface for hydro and particle data as well as derived quantities. This zero-argument form is a helper to discover valid field names before calling one of the many method overloads such as:

projection(hydro::HydroDataType, :rho; direction=:z, res=256)
projection(particles::PartDataType, [:mass, :vz]; weighting=:mass)

Actual data projections are implemented in specialized method definitions located in projection_hydro.jl and projection_particles.jl (and gravity combo variants). Those methods accept keywords like direction, res, xrange, yrange, zrange, center, weighting, show_progress, and unit selection arguments. This summary call prints the canonical / alias variable names and returns nothing.

AMR Hydro Projection Functions

This module provides high-performance functionality for projecting AMR (Adaptive Mesh Refinement) hydrodynamic simulation data onto regular 2D grids. The projection engine handles multi-level AMR data with proper coordinate transformations, geometric mapping, and optimized parallel processing.

Architecture Overview

The projection system uses variable-based parallelization where each thread processes one variable across all AMR levels. This approach eliminates the costly combining phase that traditional chunked parallelization requires, resulting in significant performance improvements.

Key Design Principles:

• Thread Safety: No shared mutable state between threads
• Memory Efficiency: Direct allocation without memory pools
• Performance: Variable-based parallelization eliminates combining overhead
• Conservation: Mass-preserving cell-to-pixel mapping
• Flexibility: Support for multiple projection directions and coordinate systems

Core Functionality

Data Projection Features:

• Multi-resolution mapping: Projects AMR cells from different refinement levels onto uniform grids
• Variable projection: Supports density, surface density, velocity, pressure, temperature and derived quantities
• Flexible grid sizing: Custom resolution, pixel size, or automatic sizing based on AMR levels
• Spatial filtering: Range-based data selection in x, y, z dimensions with thin slice support
• Weighting schemes: Mass weighting (default), volume weighting, or custom weighting functions
• Direction control: Project along x, y, or z directions with proper coordinate remapping

AMR-Specific Features:

• Conservative mapping: Mass-conserving cell-to-pixel mapping with geometric overlap calculations
• Level-specific processing: Individual handling of each AMR refinement level for accuracy
• Boundary handling: Robust treatment of cell boundaries and partial overlaps
• Coordinate transformations: Automatic handling of different AMR coordinate systems

Main Projection Function

Create high-performance 2D projections of AMR hydro data with full control over resolution, spatial ranges, and processing options. This function automatically selects between sequential and variable-based parallel processing based on data characteristics.

Function Signature

projection(dataobject::HydroDataType, vars::Array{Symbol,1};
           units::Array{Symbol,1}=[:standard],
           lmax::Real=dataobject.lmax,
           res::Union{Real, Missing}=missing,
           pxsize::Array{<:Any,1}=[missing, missing],
           mask::Union{Vector{Bool}, MaskType}=[false],
           direction::Symbol=:z,
           weighting::Array{<:Any,1}=[:mass, missing],
           mode::Symbol=:standard,
           xrange::Array{<:Any,1}=[missing, missing],
           yrange::Array{<:Any,1}=[missing, missing],
           zrange::Array{<:Any,1}=[missing, missing],
           center::CenterType=[0., 0., 0.],
           range_unit::Symbol=:standard,
           data_center::CenterType=[missing, missing, missing],
           data_center_unit::Symbol=:standard,
           verbose::Bool=true,
           show_progress::Bool=true,
           verbose_threads::Bool=false,
           myargs::ArgumentsType=ArgumentsType())

return AMRMapsType

Arguments

Required Parameters:

• dataobject::HydroDataType: AMR hydro simulation data loaded by Mera.jl
  • Must contain spatial coordinates and hydro variables
  • Supports RAMSES, ENZO, and other AMR formats
• vars::Array{Symbol,1}: Variables to project (e.g., [:rho, :vx, :vy] or [:sd])
  • Multiple variables trigger automatic variable-based parallelization
  • Single variables use optimized sequential processing

Grid Resolution Control:

• res::Union{Real, Missing}: pixel count per dimension across the whole box, so the pixel size is boxlen/res and a windowed projection returns only the pixels the window covers (a ±5 kpc window in a 100 kpc box at res=64 gives an 8×8 map, not 64×64). This is why res pairs with lmax (res = 2^lmax). Use pxsize=[size, unit] to set the pixel size directly and get a window-sized map.
  • Higher values increase precision but require more memory
  • Recommended: 256-1024 for most applications
• lmax::Real: Use 2^lmax pixels when res not specified (default: dataobject.lmax)
  • Automatically matches finest AMR level resolution
• pxsize::Array: Physical pixel size [value, unit] (overrides res/lmax)
  • Direct control over spatial resolution
  • The effective pixel is boxlen/ceil(boxlen/pxsize) — exactly the requested size only when it divides the box length (both the axis-aligned and off-axis paths share this)
  • Pixel COUNTS still differ between paths at the same pxsize: axis-aligned maps frame the requested window (or the object's stored ranges) on the box-anchored lattice, while off-axis maps auto-fit the rotated data's bounding box plus an AMR-aware border (one pixel + half the coarsest selected cell per side) — pin the frame explicitly if you need comparable map dimensions

Spatial Range Control:

• xrange/yrange/zrange::Array: Spatial bounds [min, max] relative to center
  • Define the physical region to project (e.g., [-10, 10] for ±10 units)
  • Units controlled by range_unit parameter
• center::Array: Projection center coordinates (use [:bc] for box center)
  • Can be physical coordinates or special values like [:bc], [:com]
• range_unit::Symbol: Units for ranges/center (:kpc, :Mpc, :pc, :standard, etc.)
  • Ensures consistent spatial scaling across different simulations
• direction::Symbol: Axis-aligned projection direction (:x, :y, :z)
  • Determines which spatial dimension is integrated over
  • Also accepts the disk presets :faceon / :edgeon (off-axis, see below)

Off-axis projection (arbitrary line of sight):

Give any of the following to project along an arbitrary line of sight instead of an axis. When none are given, the axis-aligned path above runs unchanged. Angles are in degrees by default (angle_unit=:rad to switch). There are five ways to say where the camera looks, and they are alternatives: give exactly one. Which to reach for:

• an object you want face-on or inclined → inclination/azimuth with axis=:angmom

• a box-aligned view → direction=:x/:y/:z

• a direction you already hold as a vector, e.g. one frozen from an earlier snapshot so a time series keeps a fixed orientation → los=

• spherical angles in the box frame, the usual physics convention → theta/phi. This is the same family as los=; theta/phi name the direction with two angles instead of three components, and unlike inclination/azimuth it is measured from the box axes rather than from a reference axis you choose.

• inclination, azimuth (user-oriented; azimuth alias position_angle): tilt the view away from a reference axis by inclination (0°⇒down the axis, 90°⇒⟂ to it) and rotate around it by azimuth.

• axis: reference axis for inclination/azimuth. Default :z (box vertical — assumes nothing about the contents, good for clouds/filaments/cosmic web). :angmom measures from the object's own angular momentum L (then 0°=face-on, 90°=edge-on); or give :x/:y/a 3-vector. NOTE: :angmom (and :faceon/:edgeon) are only a meaningful "disk normal" for a rotating disk, and L is computed about center — so center on the object (its centre of mass) for L to be the true spin; off-centre it is contaminated by bulk motion.

• direction=:faceon/:edgeon: shortcuts for inclination=0/90 with axis=:angmom.

• los::Vector: explicit line-of-sight (viewing) direction, e.g. los=[1,1,1] (need not be normalized)

• theta, phi: spherical angles about the box axes; los=[sinθcosφ, sinθsinφ, cosθ].

• up::Vector: optional camera up-vector (default: auto; the reference axis kept upright)

• angle_unit::Symbol: :deg (default) or :rad

• binning::Symbol: how rotated cells are deposited onto the camera plane —

  • :overlap (default) — per-cell footprint supersampling (ns = ceil(cellsize/pixel) sub-points per cube axis, capped at nmax); AMR-aligned (no moiré, no interior holes), converges to :exact, and is usually faster than :exact. Cells coarser than the nmax cap (ns would exceed nmax) deposit each sub-cell as a footprint-sized top-hat so they still tile the camera plane without gaps — fine cells keep the sharp ±1px deposit.
  • :exact — analytic box-spline footprint: integrates the line-of-sight column (chord length through the cube) over each pixel exactly; no supersampling cap, the reference for fidelity.
  • :cic — fast preview, bilinear deposit of cell centres; speckles/moiré on coarse AMR cells
  • :ngp — fast preview, nearest-pixel deposit (sharp)

• nmax::Int: :overlap supersampling cap (default 64) — max sub-points per cube axis. Raise for fewer artifacts on very coarse cells (slower, ∝ nmax³), lower for speed.

  All are mass-conserving. Off-axis currently supports the standard hydro/RT fields and :sd/:mass; map-only variables (:r_cylinder, :ϕ, velocity dispersions) require an axis direction.

Data Processing Options:

• weighting::Array: Variable for weighting [quantity, unit] (default: [:mass])
  • Controls how cell values are averaged: mass-weighted, volume-weighted, etc.
  • e.g. [:volume] for a volume-weighted average, or [:mass] (default)
• mode::Symbol: Processing mode (:standard or :sum)
  • :standard → weighted averages (typical for intensive quantities)
  • :sum → accumulative totals (for extensive quantities like mass)
• mask::Union{Vector{Bool}, MaskType}: Boolean mask to exclude cells
  • Filter out unwanted regions or apply custom selection criteria
• units::Array{Symbol,1}: Output units for projected variables
  • Convert results to desired physical units automatically

Advanced Options:

• data_center/data_center_unit: Alternative center for data calculations
  • When different from projection center (useful for coordinate transformations)
• verbose::Bool: Print diagnostic information during processing (default: true)
  • Shows progress, memory usage, and basic threading information
• show_progress::Bool: Display progress bar for level-by-level processing (default: true)
  • Visual feedback for long-running projections
• verbose_threads::Bool: Show detailed multithreading diagnostics (default: false)
  • Enable for debugging parallel performance or thread behavior
• myargs::ArgumentsType: Struct to pass multiple arguments simultaneously
  • Convenient for passing common parameter sets

Method Variants

The projection function supports multiple calling patterns for convenience:

# Single variable projection
projection(dataobject, :rho)                    # Density with default settings
projection(dataobject, :rho, unit=:g_cm3)      # Density in specific units

# Multiple variables with same units  
projection(dataobject, [:v, :vx, :vy], :km_s) # Multiple vars, single unit

# Multiple variables with different units
projection(dataobject, [:rho, :sd], [:g_cm3, :Msol_pc2]) # Different units per variable

# Surface density projection (special handling)
projection(dataobject, :sd, :Msol_pc2)         # Surface density in solar masses per pc²

Usage Examples

Basic Density Projection

# Simple density map of full simulation box (sequential processing)
density_map = projection(gas, :rho, unit=:g_cm3, res=512)

# High resolution central region with optimal settings
density_map = projection(gas, :rho, unit=:g_cm3, 
                        xrange=[-10, 10], yrange=[-10, 10], 
                        center=[:bc], range_unit=:kpc, res=1024)

Multi-Variable Analysis (Parallel Processing)

# Velocity field analysis (automatic variable-based parallelization)
velocity_maps = projection(gas, [:vx, :vy, :vz], unit=:km_s,
                          direction=:z, res=512)
# Output: 🧵 Using parallel processing with 3 threads (one per variable)

# Combined density and velocity (optimal parallel performance)
hydro_maps = projection(gas, [:rho, :vx, :vy], [:g_cm3, :km_s, :km_s],
                       xrange=[-5, 5], yrange=[-5, 5], 
                       center=[:bc], range_unit=:kpc)
# Output: ✅ Parallel projection completed successfully

Advanced AMR Projections

# High-precision thin slice (demonstrates AMR coordinate handling)
thin_slice = projection(gas, :sd, :Msol_pc2,
                       zrange=[0.49, 0.51], center=[:bc],
                       range_unit=:standard, direction=:z, res=1024)

# Volume-weighted projection for physical accuracy
volume_proj = projection(gas, :rho, 
                        weighting=[:volume, :cm3],
                        mode=:sum, res=512)

# Large multi-variable projection (optimal parallel performance)
comprehensive = projection(gas, [:rho, :vx, :vy, :vz, :cs], 
                          [:g_cm3, :km_s, :km_s, :km_s, :km_s],
                          res=2048, verbose_threads=true)
# Shows detailed threading diagnostics for performance analysis

Direction-Specific Projections

# X-direction projection (YZ plane) - parallel processing for multiple variables
x_proj = projection(gas, [:rho, :vx], [:g_cm3, :km_s],
                   direction=:x, yrange=[-10, 10], zrange=[-5, 5],
                   center=[:bc], range_unit=:kpc)

# Y-direction projection (XZ plane) - sequential processing for single variable
y_proj = projection(gas, :sd, :Msol_pc2,
                   direction=:y, xrange=[-20, 20], zrange=[-10, 10],
                   center=[:bc], range_unit=:kpc)

Threading Control and Performance Monitoring

# Basic thread information (always shown with verbose=true)
density_map = projection(gas, :rho, :g_cm3, res=512)
# Output: Available threads: 8
#         Requested max_threads: 8
#         Processing mode: Sequential (single variable)

# Detailed threading diagnostics for performance analysis
multi_var = projection(gas, [:rho, :vx, :vy, :vz], res=1024, 
                      verbose_threads=true)
# Output: Available threads: 8
#         Requested max_threads: 8
#         Processing mode: Variable-based parallel (4 threads)
#         🧵 Thread allocation: rho→T1, vx→T2, vy→T3, vz→T4
#         ✅ Parallel projection completed successfully
#         Performance: 2.1M cells/sec, Efficiency: 91.7%
#
# Note: verbose_threads=true shows detailed per-thread performance metrics

Hide all output with verbose=false

densitymap = projection(gas, :rho, :gcm3, res=512, verbose=false) # No threading output at all

#### Physical Pixel Size Control (pxsize)

julia

High-resolution projection with 10 pc pixels

highres = projection(gas, :rho, :gcm3, pxsize=[10., :pc], xrange=[-1, 1], yrange=[-1, 1], center=[:bc], range_unit=:kpc)

Ultra-high resolution with 1 pc pixels for detailed structure

ultrahigh = projection(gas, :sd, :Msolpc2, pxsize=[1., :pc], xrange=[-500, 500], yrange=[-500, 500], center=[:bc], range_unit=:pc)

Large-scale map with 100 pc pixels for overview

overview = projection(gas, [:rho, :temperature], [:gcm3, :K], pxsize=[100., :pc], xrange=[-10, 10], yrange=[-10, 10], center=[:bc], rangeunit=:kpc)

Custom units: 0.1 kpc (100 pc) pixels

customscale = projection(gas, :vx, :kms, pxsize=[0.1, :kpc], xrange=[-5, 5], yrange=[-5, 5], center=[:bc], range_unit=:kpc)

Very fine scale: sub-parsec resolution

finedetail = projection(gas, :density, :gcm3, pxsize=[0.1, :pc], xrange=[-10, 10], yrange=[-10, 10], center=[:bc], range_unit=:pc)

### Return Value

Returns `AMRMapsType` (alias: `HydroMapsType`) containing:
- **`.maps`**: Dictionary of projected variable maps (2D arrays)
- **`.extent`**: extent `[xmin, xmax, ymin, ymax]` in **code length** units. The map *values* may be
  physical (e.g. `:Msol_pc2`); the axes are NOT — multiply by `proj.scale.kpc`/`.pc`/… for a physical
  plotting extent, or use [`getextent`](@ref)`(proj, :kpc)`. `.cextent` is the same, centred on `.center`.
- **`.pixsize`**: pixel size in **code length** units (× `proj.scale.<unit>` for physical)
- **`.lmax_projected`**: Maximum AMR level included in projection
- **`.ranges`**: normalized `[0,1]` coordinate ranges (this is the fractional field, unlike `.extent`)
- **`.center`**: projection centre, in **code length** units

### Radiative transfer (RT) projections

The same `projection` function accepts an `RtDataType` object (`rt = getrt(info)`)
and shares the AMR engine above. Two RT-specific behaviours apply:

- **Default weighting is `:volume`** (not `:mass`): RT fields carry no cell mass, so
  a mass weight is meaningless. Passing `weighting=[:mass]` is silently promoted to
  `[:volume]`. Override explicitly with e.g. `weighting=[:Np1]` to flux-weight by the
  photon density.
- **`mode=:standard`** (default) gives the **volume-weighted average** of the field
  along the line of sight (per pixel). **`mode=:sum`** gives the volume-weighted
  **sum** per pixel — i.e. Σ q·V_cell over the column, so for `:Np1` (a number
  density) it is proportional to the **total photon count** projected onto each
  pixel (the whole map sums to the box photon number), not the column density
  ∫q dz. For a mass-style **column density** use a `HydroDataType` with `:sd`
  (which divides by the pixel area); RT fields have no `:sd` analogue.

Typical RT maps:

julia rt = getrt(info) gas = gethydro(info)

Photon-count map of group 1 (volume-weighted sum per pixel)

npsum = projection(rt, :Np1, mode=:sum, center=[:bc], rangeunit=:kpc)

Reduced-flux map (beam vs. isotropic), volume-weighted average

fmap = projection(rt, :reducedflux1, center=[:bc])

Mock recombination-line emission map (∝ ∫ n_HII² dz) — a HYDRO quantity

em = projection(gas, :emrecomb, mode=:sum, center=[:bc], rangeunit=:kpc)

Ionization map xHII (hydro passive scalar located via the RT descriptor)

xmap = projection(gas, :xHII, center=[:bc])

RT photon fields and the hydro ionization state live on **separate** objects; project
each on its own object (analogous to gravity vs. hydro). Use `getvar(rt, …)` /
`getvar(gas, …)` for the per-cell quantities documented under `getvar`.

Off-axis projections:

!!! note "`xrange`/`yrange`/`zrange` are WORLD-space; `fov` is camera-space"
    The ranges select a **box in simulation coordinates**, and the off-axis frame is the bounding
    box of that region *after rotation*. Two consequences that surprise people:

    * omit `zrange` and the **full box depth** folds into the image height as you tilt — a
      ±22 kpc window came out ±45 kpc at i=30° and ±55 kpc at i=60° on a 100 kpc box;
    * the window's own **faces are visible** as straight edges across the map, because a sight
      line just outside the box clips only a corner of it.

    Neither is an error — it is what a world-space selection looks like from an angle — but if
    you want a *fixed camera-plane frame*, use `fov` instead:

    ```julia
    # world-space box: frame grows with tilt, window faces visible
    projection(gas, :sd; inclination=60, xrange=[-22,22], yrange=[-22,22], range_unit=:kpc)

    # camera-plane frame: identical at every angle (rotation-invariant sphere selection)
    projection(gas, :sd; inclination=60, fov=22, fov_unit=:kpc, aperture=:square)
    ```

    `aperture=:circle` (default) frames a sphere of radius `fov`, so the frame's corners are
    empty; `aperture=:square` selects radius `√2·fov` and crops to the ±`fov` square, giving a
    full rectangular frame that is **pixel-identical at every viewing angle** — what a gallery or
    an orbit sequence needs. Mera points this out once per session when it sees an off-axis view
    with a windowed `xrange`/`yrange` and no `zrange`.

    !!! note "`fov` integrates a chord, not a slab"
        Because the selection is a sphere of radius `R` (`fov`, or `√2·fov` for `:square`), a ray
        at in-plane distance `d` from the centre integrates `depth(d) = 2√(R² − d²)`. The column
        is deepest on axis and falls to **zero at the frame boundary** — for `:square` that is the
        four corners, which sit exactly on the sphere. On a 100 kpc box, `fov=15, :square` gives
        42.4 kpc of depth at the centre, 30.0 kpc at the middle of an edge and 0 at the corners.
        Harmless for an object centred in frame, but make `fov` comfortably larger than any
        diffuse column, profile or scale height you intend to measure.

`binning` chooses how a rotated cell is shared among pixels. **The default `:overlap` is already
the accurate one** — reach for `:cic`/`:ngp` only when you want a fast preview. All four conserve
the total; they differ in *where* they put it:

| `binning` | | |
|---|---|---|
| `:overlap` | **default** | footprint supersampling — AMR-aligned, no moiré, converges to `:exact` |
| `:exact` | reference | analytic box-spline footprint; the fidelity yardstick |
| `:cic` | preview | bilinear deposit of the cell centre; speckles/moiré on coarse cells |
| `:ngp` | fastest | nearest-pixel deposit of the cell centre |

julia gas = gethydro(info)

Look along an arbitrary line of sight (accurate :overlap deposit, by default)

m = projection(gas, :sd, :Msolpc2, los=[1,1,1], center=[:bc], rangeunit=:kpc)

Explicitly ask for a fast preview instead

m = projection(gas, :sd, :Msol_pc2, los=[1,1,1], binning=:cic, center=[:bc])

Spherical angles instead of a vector (degrees)

m = projection(gas, :sd, theta=60, phi=30, angle_unit=:deg, center=[:bc])

Disk seen face-on / edge-on (line of sight from the gas angular momentum)

fo = projection(gas, :sd, direction=:faceon, center=[:bc], rangeunit=:kpc) eo = projection(gas, :sd, direction=:edgeon, center=[:bc], rangeunit=:kpc) ```

The off-axis camera basis is stored on the returned map (m.los, m.up, m.cam_right, m.center; m.direction == :offaxis). The cell→pixel deposit uses the standard nearest-grid-point / cloud-in-cell assignment scheme (Hockney & Eastwood 1988, Computer Simulation Using Particles); :overlap extends CIC with per-cell footprint supersampling. All deposits conserve the projected total to machine precision.

Project variables or derived quantities from the particle-dataset:

• projection to a grid related to a given level

• overview the list of predefined quantities with: projection()

• select variable(s) and their unit(s)

• limit to a maximum range

• give the spatial center (with units) of the data within the box (relevant e.g. for radius dependency)

• relate the coordinates to a direction (x,y,z) — or project along an arbitrary off-axis line of sight via los=[..], spherical angles theta/phi (angle_unit=:rad/:deg), or the disk presets direction=:faceon/:edgeon (line of sight from the particle angular momentum). The off-axis camera basis is stored on the returned map (.los, .up, .cam_right, .center; .direction==:offaxis).

• thickness / thickness_unit, offset / offset_unit: project a slab rather than the full depth. A cutting plane through point particles is empty by construction (a particle has no extent), so the useful analogue of a slice is a projection of finite depth along the line of sight: thickness sets that depth and offset moves the slab, the same way offset moves the plane in offaxis_slice. Both default to range_unit. A non-positive thickness is refused rather than silently returning an empty map.

  Point particles have no footprint, so binning=:cic (default) / :ngp apply (:overlap and :exact fall back to :cic). See the hydro projection docstring for details.

• select between mass (default), volume, SPH-kernel, or Voronoi (nearest-generator) weighting

• pass a mask to exclude elements (cells/particles/...) from the calculation

• toggle verbose mode

• toggle progress bar

• pass a struct with arguments (myargs)

projection(   dataobject::PartDataType, vars::Array{Symbol,1};
                units::Array{Symbol,1}=[:standard],
                lmax::Real=dataobject.lmax,
                res::Union{Real, Missing}=missing,
                pxsize::Array{<:Any,1}=[missing, missing],
                mask=[false],
                direction::Symbol=:z,
                weighting::Symbol=:mass,
                xrange::Array{<:Any,1}=[missing, missing],
                yrange::Array{<:Any,1}=[missing, missing],
                zrange::Array{<:Any,1}=[missing, missing],
                center::CenterType=[0., 0., 0.],
                range_unit::Symbol=:standard,
                data_center::CenterType=[missing, missing, missing],
                data_center_unit::Symbol=:standard,
                ref_time::Real=dataobject.info.time,
                verbose::Bool=true,
                show_progress::Bool=true,
                myargs::ArgumentsType=ArgumentsType()  )

return PartMapsType

Arguments

Required:

• dataobject: needs to be of type: "PartDataType"
• var(s): select a variable from the database or a predefined quantity (see field: info, function projection(), dataobject.data)

Predefined/Optional Keywords:

• unit(s): return the variable in given units
• pxsize`: creates maps with the given pixel size in physical/code units (dominates over: res, lmax) : pxsize=[physical size (Number), physical unit (Symbol)]
• res: pixel count per dimension across the whole box (so the pixel size is boxlen/res); if not given, lmax selects it as 2^lmax. A windowed projection therefore returns only the pixels the window covers — use pxsize=[size, unit] for a window-sized map.
• lmax: create maps with 2^lmax pixels for each dimension
• xrange: the range between [xmin, xmax] in units given by argument range_unit and relative to the given center; zero length for xmin=xmax=0. is converted to maximum possible length
• yrange: the range between [ymin, ymax] in units given by argument range_unit and relative to the given center; zero length for ymin=ymax=0. is converted to maximum possible length
• zrange: the range between [zmin, zmax] in units given by argument range_unit and relative to the given center; zero length for zmin=zmax=0. is converted to maximum possible length
• range_unit: the units of the given ranges: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• center: in units given by argument range_unit; by default [0., 0., 0.]; the box-center can be selected by e.g. [:bc], [:boxcenter], [value, :bc, :bc], etc..
• weighting: select between :mass weighting (default), :volume weighting, or :sph (smear each cell over an M4 kernel sized from its :volume; mass-conserving; needs a :volume column), or :voronoi (nearest-generator: sample each LOS through the nearest cell — sharp, genuinely moving-mesh; intensive maps exact, surface density approximate)
• nlos: number of samples along each line of sight, :voronoi only. By default Mera steps at the scale of the cells — min(pixsize, ½·median(V)^⅓), capped at 4096 — because stepping at pixel scale walks over whole cells whenever cells are smaller than a pixel. Set it only to trade accuracy for speed, or to check convergence; verbose=true reports the value used.
• :sph totals depend on how tightly the frame crops the data. Each cell is smeared over an M4 kernel and only the part landing on in-frame pixels is deposited — the wings that fall outside are dropped, which is physical, not a bug. So the same data in a tighter frame keeps less mass: on one test field ∫Σ dA / M was 1.000000 at half-widths 0.50/0.40/0.33 of the box, 0.9934 at 0.31 and 0.9604 at 0.30, as the frame started clipping the kernel. This is also why an axis-aligned and an off-axis :sph map of the same data can differ by ~1 %: the two routes frame differently (the off-axis extent is derived from the rotated data, not from your window). Compare them with los=[0,0,1], up=[0,1,0], which makes the off-axis camera reproduce the axis-aligned geometry — the disagreement then drops to ~0.01 %, and :mass agrees exactly. Leave margin around the data if you want the total to be frame-independent.
• :voronoi on a cutout does not lose mass, even though ∫Σ dA looks short of msum. The two count different things: msum adds the whole mass of every cell whose generator lies in the region, including the part of that cell sticking out through the boundary, while the map integrates only what is actually inside. The shortfall is therefore a surface-to-volume effect and falls off as 1/L — measured on an AREPO zoom at 4.2 %, 3.4 %, 1.8 %, 1.0 % for half-widths of 200, 400, 800, 1600 ckpc/h. Refining nlos does not remove it (it converges to the same value), because it is not a sampling error. :mass does not show it only because point deposition dumps each cell's entire mass at its generator. To integrate a sub-volume exactly, select a region larger than the one you measure.
• data_center: to calculate the data relative to the datacenter; in units given by argument `datacenterunit`; by default the argument datacenter = center ;
• data_center_unit: :standard (code units), :Mpc, :kpc, :pc, :mpc, :ly, :au , :km, :cm (of typye Symbol) ..etc. ; see for defined length-scales viewfields(info.scale)
• direction: axis-aligned :x, :y, :z, or the disk presets :faceon/:edgeon
• off-axis view (any line of sight): inclination/azimuth (+ axis=:z/:angmom/vector), los=[lx,ly,lz], or theta/phi; position_angle rolls the image; angle_unit=:deg (default) or :rad. See the hydro projection docstring for the full description; for point particles binning=:overlap falls back to :cic.
• fov / fov_unit / aperture: camera-plane framing, identical to the hydro path — fov is the frame half-width and selects a sphere about center (radius fov, or √2·fov for aperture=:square, which crops to a full rectangle that is pixel-identical at every viewing angle). Use it instead of xrange/yrange whenever frames must be comparable across angles or snapshots, and give fov_unit explicitly — it defaults to :standard, a box fraction. Note the sphere means a summed quantity integrates a chord that shrinks to zero at the frame boundary; see the hydro projection docstring.
• mask: needs to be of type MaskType which is a supertype of Array{Bool,1} or BitArray{1} with the length of the database (rows)
• ref_time: the age quantity relative to a given time (code_units); default relative to the loaded snapshot time
• show_progress: print progress bar on screen
• myargs: pass a struct of ArgumentsType to pass several arguments at once and to overwrite default values of lmax, xrange, yrange, zrange, center, rangeunit, verbose, showprogress

Defined Methods - function defined for different arguments

• projection( dataobject::PartDataType, var::Symbol; ...) # one given variable
• projection( dataobject::PartDataType, var::Symbol, unit::Symbol; ...) # one given variable with its unit
• projection( dataobject::PartDataType, vars::Array{Symbol,1}; ...) # several given variables -> array needed
• projection( dataobject::PartDataType, vars::Array{Symbol,1}, units::Array{Symbol,1}; ...) # several given variables and their corresponding units -> both arrays
• projection( dataobject::PartDataType, vars::Array{Symbol,1}, unit::Symbol; ...) # several given variables that have the same unit -> array for the variables and a single Symbol for the unit

Examples

...

project(data, var [, unit]; res=auto, kwargs...)                      # already-loaded hydro/particles
project(info::InfoType, var [, unit]; vars=auto, lmax=…, kwargs...)   # load hydro, then project
project(path::AbstractString, output::Integer, var [, unit]; kwargs...)  # getinfo + load + project

One-call projection. A high-level convenience that loads the data (when given an InfoType or a path+output) and projects in a single call — the ergonomic equivalent of yt.ProjectionPlot(ds, "z", field).

• Smart resolution — if res is not given it defaults to 2^lmax capped at 1024, so a deep AMR run doesn't silently allocate an enormous map (pass res= to override; a note is printed when capped).
• Loading — reads the full hydro state by default (fast); restrict with vars=[:rho] if you know exactly what the projection (and its weighting / view) needs.
• All other keywords (direction, los, center, range_unit, weight, mode, pxsize, …) are forwarded to projection; the return value is the same map object.