CLI reference¶
This page is generated recursively from the installed torchsky argument parser.
torchsky¶
usage: torchsky [-h] [--version] {map,sky,viz} ...
Torch-native celestial geometry, sphere, and mapmaking workflows.
positional arguments:
{map,sky,viz}
map High-SNR sky map: coadd (SWarp/drizzle-like) or continuous
field render
sky Sky background estimation and multi-exposure matching.
viz Start the torchsky web visualization server.
options:
-h, --help show this help message and exit
--version show program's version number and exit
Examples:
torchsky --version
torchsky map --help
torchsky sky estimate --help
torchsky map¶
usage: torchsky map [-h] [--dry-run] [--plan-json PATH] [--from-plan PATH]
[--scratch-dir SCRATCH_DIR]
[--output-planes {SCI,WHT,IVAR,CTX,MASK,NEXP,NCORR,DQ} [{SCI,WHT,IVAR,CTX,MASK,NEXP,NCORR,DQ} ...]]
[--method {coadd,field}]
[--workflow {native,drizzle,swarp,montage}] [--hdu HDU]
[--weights [WEIGHTS ...]]
[--photometric-scales [PHOTOMETRIC_SCALES ...]]
[--background-offsets [BACKGROUND_OFFSETS ...]]
[--background-mode {none,per-exposure,overlap}]
[--sky-method {mesh,polynomial}]
[--sky-statistic {median,huber,tukey}]
[--sky-block-size SKY_BLOCK_SIZE]
[--sky-mesh-filter {median,gaussian,none}]
[--sky-mesh-filter-size SKY_MESH_FILTER_SIZE]
[--sky-interpolate {bilinear,bicubic}]
[--sky-order SKY_ORDER] [--weight-maps [WEIGHT_MAPS ...]]
[--weight-map-hdu WEIGHT_MAP_HDU]
[--mask-maps [MASK_MAPS ...]]
[--mask-map-hdu MASK_MAP_HDU] [--dq-maps [DQ_MAPS ...]]
[--dq-hdu HDU] [--good-bits MASK]
[--primary-beam-maps [PRIMARY_BEAM_MAPS ...]]
[--primary-beam-hdu PRIMARY_BEAM_HDU]
[--reference REFERENCE] [--reference-hdu REFERENCE_HDU]
[--plan-reference PLAN_REFERENCE]
[--stack {weighted_mean,mean,median,sigma_clipped}]
[--clip-sigma CLIP_SIGMA]
[--clip-iterations CLIP_ITERATIONS]
[--kernel {nearest,bilinear,bicubic,lanczos3,lanczos5,mitchell_netravali,catmull_rom,fft_shift,fft_diagonal_affine,periodic_linear_affine,fft_linear_affine,drizzle_point,drizzle_square,conservative_polygon}]
[--drizzle-pixfrac DRIZZLE_PIXFRAC]
[--value-semantics {surface_brightness,flux}]
[--auto-tile | --no-auto-tile] [--tile-pixels TILE_PIXELS]
[--tile-above-megapixels TILE_ABOVE_MEGAPIXELS]
[--field-preset {fast,balanced,spectral,operator_constrained}]
[--field-amp {none,float16,bfloat16}]
[--field-model MODEL] [--artifact ARTIFACT]
[--resume RESUME] [--field-band BAND]
[--field-spectral-source {svo,builtin,file,gaussian}]
[--svo-facility SVO_FACILITY]
[--svo-instrument SVO_INSTRUMENT] [--svo-filter-id ID]
[--svo-prefer {classic,2025,any}]
[--svo-cache-dir SVO_CACHE_DIR] [--no-svo-cache]
[--field-transmission PATH] [--field-transmission-dir DIR]
[--field-transmission-unit {angstrom,nm}]
[--field-gaussian-lambda-eff ANGSTROM]
[--field-gaussian-lambda-min ANGSTROM]
[--field-gaussian-lambda-max ANGSTROM]
[--field-gaussian-sigma ANGSTROM] [--field-quiet-svo]
[--field-steps N] [--field-lr RATE]
[--field-patch-size PIXELS] [--field-patches-per-obs N]
[--field-obs-per-step N] [--field-spectral-samples N]
[--field-spatial-sampling {center,gauss_legendre_2x2}]
[--field-render-tile PIXELS] [--field-max-pixels N]
[--per-filter] [--union-footprint | --no-union-footprint]
[--footprint-padding FOOTPRINT_PADDING]
[--footprint-tolerance-px FOOTPRINT_TOLERANCE_PX]
[--footprint-max-depth FOOTPRINT_MAX_DEPTH]
[--max-footprint-pixels MAX_FOOTPRINT_PIXELS]
[--overwrite | --no-overwrite] [--device DEVICE]
output [inputs ...]
Build a pixelized coadd or fit and render a continuous sky field from FITS observations. Select the workflow with --method coadd or --method field.
positional arguments:
output Output FITS path (or directory with --per-filter)
inputs Input FITS images (paths or globs); omit with --from-
plan
options:
-h, --help show this help message and exit
--dry-run Validate inputs and print planned output shape without
writing a map
--plan-json PATH Atomically write the resolved map plan before compute
--from-plan PATH Replay a validated schema-v2 plan; only output/scratch
may change
--scratch-dir SCRATCH_DIR
Scratch location for spillable reducers and large
products
--output-planes {SCI,WHT,IVAR,CTX,MASK,NEXP,NCORR,DQ} [{SCI,WHT,IVAR,CTX,MASK,NEXP,NCORR,DQ} ...]
Requested output planes, recorded in plan-v2 (default:
SCI WHT IVAR MASK NEXP; CTX and DQ are opt-in)
--method {coadd,field}
coadd: resample+stack; field: fit continuous field
then render to grid
--workflow {native,drizzle,swarp,montage}
Calibrated map workflow preset; explicit controls
override it
--hdu HDU Input image HDU index
--weights [WEIGHTS ...]
Per-input scalar inverse-variance weights; when
omitted, unit relative coadd weights do not produce
IVAR
--photometric-scales [PHOTOMETRIC_SCALES ...]
Per-input coadd calibration scale applied as scale *
(image - background)
--background-offsets [BACKGROUND_OFFSETS ...]
Per-input background offsets; coadd subtracts them,
fields model them in rendering
--background-mode {none,per-exposure,overlap}
Background policy; default is selected by --workflow
--sky-method {mesh,polynomial}
Sky model type (default: mesh)
--sky-statistic {median,huber,tukey}
Sky per-cell statistic (default: huber)
--sky-block-size SKY_BLOCK_SIZE
Mesh block size in pixels (mesh method, default: 128)
--sky-mesh-filter {median,gaussian,none}
Mesh post-filter (mesh method, default: median)
--sky-mesh-filter-size SKY_MESH_FILTER_SIZE
Mesh post-filter kernel size (mesh method, default: 3)
--sky-interpolate {bilinear,bicubic}
Mesh-to-image interpolation (mesh method, default:
bicubic)
--sky-order SKY_ORDER
Polynomial degree (polynomial method, default: 3)
--weight-maps [WEIGHT_MAPS ...]
Per-input FITS weight maps; multiplied by --weights
when set
--weight-map-hdu WEIGHT_MAP_HDU
HDU index for all --weight-maps
--mask-maps [MASK_MAPS ...]
Per-input FITS mask maps; nonzero pixels contribute
--mask-map-hdu MASK_MAP_HDU
HDU index for all --mask-maps
--dq-maps [DQ_MAPS ...]
Per-input DQ bitmask maps; rejected bits follow --dq-
policy
--dq-hdu HDU HDU name or index for all --dq-maps (default: DQ)
--good-bits MASK Bits that must be zero for a pixel to contribute when
a mask map is read as a bitmask (instead of a
boolean/weight mask)
--primary-beam-maps [PRIMARY_BEAM_MAPS ...]
Per-input primary-beam maps for coadd weighting
--primary-beam-hdu PRIMARY_BEAM_HDU
HDU index for all --primary-beam-maps; default follows
torchsky image read
--reference REFERENCE
FITS whose WCS+shape define the output grid
--reference-hdu REFERENCE_HDU
Zero-based image HDU index in --reference (default: 0)
--plan-reference PLAN_REFERENCE
Which input (0-based) defines grid when --reference
omitted (coadd/field)
--stack {weighted_mean,mean,median,sigma_clipped}
Stacking after resampling (coadd)
--clip-sigma CLIP_SIGMA
Robust sigma threshold for --stack=sigma_clipped
(default: 4)
--clip-iterations CLIP_ITERATIONS
Maximum iterations for --stack=sigma_clipped (default:
3)
--kernel {nearest,bilinear,bicubic,lanczos3,lanczos5,mitchell_netravali,catmull_rom,fft_shift,fft_diagonal_affine,periodic_linear_affine,fft_linear_affine,drizzle_point,drizzle_square,conservative_polygon}
Resampling kernel (coadd); drizzle_* uses native
forward-drizzle when available
--drizzle-pixfrac DRIZZLE_PIXFRAC
Drizzle pixfrac when using drizzle_* kernels (coadd)
--value-semantics {surface_brightness,flux}
Input pixel value meaning used for area scaling
(default: surface_brightness)
--auto-tile, --no-auto-tile
Tile large outputs into spatial chunks (coadd); use
--no-auto-tile to disable
--tile-pixels TILE_PIXELS
Force tile height=width in pixels (coadd); implies
tiling
--tile-above-megapixels TILE_ABOVE_MEGAPIXELS
With --auto-tile, tile when H×W exceeds this many
megapixels (coadd)
--field-preset {fast,balanced,spectral,operator_constrained}
Supported field recipe (default: balanced)
--field-amp {none,float16,bfloat16}
Opt-in CUDA autocast precision with local gradient
scaling
--field-model MODEL Experimental raw field model kind; overrides --field-
preset
--artifact ARTIFACT Save a safe resumable field artifact directory
--resume RESUME Resume model, optimizer, and RNG state from a field
artifact
--field-band BAND Filter name for the field bandpass, e.g. F277W
--field-spectral-source {svo,builtin,file,gaussian}
How to set FieldObservation spectral metadata:
svo=astroquery SVO FPS (default; needs pip install
astroquery), builtin=small JWST table in torchsky,
file=two-column wavelength transmission table,
gaussian=effective wavelength + min/max (Gaussian
sigma from width or --field-gaussian-sigma)
--svo-facility SVO_FACILITY
SVO get_filter_list facility (--field-spectral-
source=svo)
--svo-instrument SVO_INSTRUMENT
SVO get_filter_list instrument (--field-spectral-
source=svo)
--svo-filter-id ID Exact SVO filterID (e.g. JWST/NIRCam.F277W); if set,
transmission is downloaded for this ID (--field-band
still labels band_name)
--svo-prefer {classic,2025,any}
When multiple SVO rows match a band token, prefer
classic vs NIRCam2025
--svo-cache-dir SVO_CACHE_DIR
Directory to cache downloaded SVO filter curves
(defaults to $TORCHSKY_SVO_CACHE or
~/.cache/torchsky/svo)
--no-svo-cache Disable reading or writing persistent local disk cache
for SVO filter profiles
--field-transmission PATH
Two-column wavelength, transmission file (--field-
spectral-source=file)
--field-transmission-dir DIR
Directory with {BAND}.txt|dat|csv per filter (--per-
filter + file source)
--field-transmission-unit {angstrom,nm}
Wavelength unit in --field-transmission file columns
--field-gaussian-lambda-eff ANGSTROM
Effective wavelength (Å) for gaussian spectral source
--field-gaussian-lambda-min ANGSTROM
Bandpass lower edge (Å) for gaussian spectral source
--field-gaussian-lambda-max ANGSTROM
Bandpass upper edge (Å) for gaussian spectral source
--field-gaussian-sigma ANGSTROM
Gaussian transmission sigma (Å); default from
lambda_max-lambda_min FWHM
--field-quiet-svo Do not log resolved SVO filterID to stderr
--field-steps N Number of field-optimization steps (default: 80)
--field-lr RATE Field optimizer learning rate (default: 0.005)
--field-patch-size PIXELS
Training crop size in pixels; 0 = full frame each step
--field-patches-per-obs N
Training patches sampled from each observation per
step (default: 2)
--field-obs-per-step N
Observations sampled for each field-optimization step
(default: 2)
--field-spectral-samples N
Quadrature samples across each observation passband
(default: 9)
--field-spatial-sampling {center,gauss_legendre_2x2}
Detector-pixel sampling for field rendering: center
(fast) or gauss_legendre_2x2 (anti-aliased pixel
average)
--field-render-tile PIXELS
spatial_tile_hw for render when the field map is
larger than this
--field-max-pixels N Refuse field rendering if output grid exceeds this
many pixels
--per-filter Group inputs by FITS FILTER and write one product per
filter (coadd and field). Without it, inputs from
different filters are rejected.
--union-footprint, --no-union-footprint
Auto-compute output WCS from union bounding box of all
input footprints (like SWarp). Use --no-union-
footprint to use the first input as reference.
--footprint-padding FOOTPRINT_PADDING
Whole-pixel padding factor for the union footprint
(default: 1.0 = exact)
--footprint-tolerance-px FOOTPRINT_TOLERANCE_PX
Maximum curved-WCS boundary chord error in target
pixels
--footprint-max-depth FOOTPRINT_MAX_DEPTH
Maximum adaptive boundary subdivision depth; failure
is closed
--max-footprint-pixels MAX_FOOTPRINT_PIXELS
Refuse targets exceeding this many pixels (memory
guard, coadd/field)
--overwrite, --no-overwrite
Overwrite an existing output file (use --no-overwrite
to fail instead)
--device DEVICE Tensor device for FITS I/O and map math (e.g. cuda,
cuda:1, cpu). Default: CUDA when available else CPU;
also settable via TORCHSKY_DEVICE.
Examples:
torchsky map coadd.fits exposure1.fits exposure2.fits
torchsky map field.fits exposure*.fits --method field --field-model sine --field-steps 200 --device cuda
torchsky sky¶
usage: torchsky sky [-h] {estimate,match} ...
Estimate detector backgrounds or solve additive offsets across aligned exposures.
positional arguments:
{estimate,match}
estimate Estimate 2D sky background for an image.
match Compute additive sky offsets across overlapping exposures.
options:
-h, --help show this help message and exit
Examples:
torchsky sky estimate --help
torchsky sky match --help
torchsky sky estimate¶
usage: torchsky sky estimate [-h] [--hdu HDU] [--mask MASK]
[--mask-hdu MASK_HDU]
[--method {mesh,polynomial}]
[--statistic {median,huber,tukey}]
[--block-size BLOCK_SIZE]
[--mesh-filter {median,gaussian,none}]
[--mesh-filter-size MESH_FILTER_SIZE]
[--interpolate {bilinear,bicubic}]
[--order ORDER] [--device DEVICE]
image output
Estimate a mesh or polynomial background model from one FITS image.
positional arguments:
image Input FITS image path.
output Output FITS path for sky model.
options:
-h, --help show this help message and exit
--hdu HDU Image HDU index.
--mask MASK Optional mask FITS (True = exclude).
--mask-hdu MASK_HDU Mask HDU index.
--method {mesh,polynomial}
Sky model type (default: mesh).
--statistic {median,huber,tukey}
Per-cell/per-pixel robust statistic (default: huber).
--block-size BLOCK_SIZE
Mesh block size in pixels (mesh method, default: 128).
--mesh-filter {median,gaussian,none}
Mesh post-filter (mesh method, default: median).
--mesh-filter-size MESH_FILTER_SIZE
Mesh post-filter kernel size (mesh method, default:
3).
--interpolate {bilinear,bicubic}
Mesh-to-image interpolation (mesh method, default:
bicubic).
--order ORDER Polynomial degree (polynomial method, default: 3).
--device DEVICE Compute device (e.g. cuda, cpu).
Examples:
torchsky sky estimate input.fits sky.fits
torchsky sky estimate input.fits sky.fits --method mesh --block-size 64 --device cuda
torchsky sky match¶
usage: torchsky sky match [-h] [--hdu HDU] [--masks [MASKS ...]]
[--mask-hdu MASK_HDU] [--output OUTPUT]
[--method {mesh,polynomial}]
[--statistic {median,huber,tukey}]
[--block-size BLOCK_SIZE] [--order ORDER]
[--device DEVICE]
[--mesh-filter {median,gaussian,none}]
[--mesh-filter-size MESH_FILTER_SIZE]
[--interpolate {bilinear,bicubic}]
images [images ...]
Estimate and optionally apply additive background offsets to aligned FITS images.
positional arguments:
images Input FITS images (same pixel grid).
options:
-h, --help show this help message and exit
--hdu HDU Image HDU index.
--masks [MASKS ...] Optional per-image masks.
--mask-hdu MASK_HDU Mask HDU index.
--output OUTPUT Output pattern with {i} (e.g. sky_{i}.fits).
--method {mesh,polynomial}
Sky model type for per-image estimation.
--statistic {median,huber,tukey}
Robust statistic; median is mesh-only (default:
huber).
--block-size BLOCK_SIZE
Mesh block size for per-image sky (default: 128).
--order ORDER Polynomial degree (polynomial method, default: 3).
--device DEVICE Compute device (e.g. cuda, cpu).
--mesh-filter {median,gaussian,none}
Mesh post-filter (mesh method, default: median).
--mesh-filter-size MESH_FILTER_SIZE
Mesh post-filter kernel size (mesh method, default:
3).
--interpolate {bilinear,bicubic}
Mesh-to-image interpolation (mesh method, default:
bicubic).
Examples:
torchsky sky match exposure1.fits exposure2.fits
torchsky sky match exposure*.fits --output corrected_{i}.fits --method polynomial --order 2
torchsky viz¶
usage: torchsky viz [-h] [--root DIR] [--port PORT] [--host HOST]
[--no-browser] [--cache-mb MB]
[--log-level {critical,error,warning,info,debug}]
[--max-registered-surveys N] [--max-validation-pairs N]
[--max-image-pixels N] [--expose-health-root]
[--cors-origin URL] [--cors-credentials]
Browser-based FITS / sky / validation viewer. Works on localhost and remote clusters (CANFAR, JupyterHub) via HTTPS.
Security: there is no authentication. Only expose --host 0.0.0.0 on trusted networks or behind a reverse proxy. The server can read any file under --root and loads full images into memory for HiPS/validation (see --max-image-pixels and registration caps).
options:
-h, --help show this help message and exit
--root DIR Directory to browse (default: current directory).
--port PORT HTTP port to listen on (default: 8822).
--host HOST Bind address (default: 127.0.0.1). Use 0.0.0.0 for
remote access.
--no-browser Do not open a browser window automatically.
--cache-mb MB PNG tile LRU cache size in MiB (default: 512).
--log-level {critical,error,warning,info,debug}
uvicorn log level (default: warning).
--max-registered-surveys N
Max HiPS surveys kept in memory; oldest dropped when
exceeded (default: 64).
--max-validation-pairs N
Max validation registrations; oldest dropped when
exceeded (default: 32).
--max-image-pixels N Reject HiPS/validation images with H*W above this
(default: 512*1024*1024).
--expose-health-root Include absolute --root path in /api/health JSON (off
by default).
--cors-origin URL Allowed CORS origin (repeatable). Default: no cross-
origin requests.
--cors-credentials Allow credentialed CORS (only with explicit --cors-
origin list).
Examples:
torchsky viz
torchsky viz --root /data/products --host 0.0.0.0 --no-browser