CLI usage

The convolvers binary is the command-line interface, a port of beamcon_2D and beamcon_3D from RACS-tools. Install it with:

cargo install convolve-rs

Note

The help text on this page is generated by running the binary at docs build time, so it always matches the documented version.

$ cargo run -q --bin convolvers -- --help
Convolve FITS images/cubes to a common beam

Usage: convolvers <COMMAND>

Commands:
  2d    Smooth 2D FITS images to a common beam resolution
  3d    Smooth 3D/4D FITS spectral cubes to a common beam
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Common workflows

Smooth a set of images to their common beam:

convolvers 2d *.fits

Smooth to an explicit target beam (all three of --bmaj, --bmin, --bpa required):

convolvers 2d --bmaj 20 --bmin 20 --bpa 0 image.fits

Report the common beam without writing anything:

convolvers 2d --dryrun *.fits

Smooth cubes channel-by-channel (natural, the default) or to one beam across all channels and cubes (total):

convolvers 3d --mode total cube1.fits cube2.fits

convolvers 2d

$ cargo run -q --bin convolvers -- 2d --help
Smooth 2D FITS images to a common beam resolution

Usage: convolvers 2d [OPTIONS] <INFILE>...

Arguments:
  <INFILE>...  Input FITS image(s)

Options:
      --listfile               Treat a single infile as a text file listing one path per line
  -s, --suffix <SUFFIX>        Output filename suffix [default: sm]
  -p, --prefix <PREFIX>        Output filename prefix
  -o, --outdir <OUTDIR>        Output directory [default: same as input]
      --bmaj <BMAJ>            Target BMAJ in arcsec (must also specify --bmin and --bpa)
      --bmin <BMIN>            Target BMIN in arcsec
      --bpa <BPA>              Target BPA in degrees
      --circularise            Circularise the final beam (BMIN = BMAJ, BPA = 0)
  -c, --cutoff <CUTOFF>        Beam size cutoff in arcsec — blank images/channels with BMAJ larger than this
  -d, --dryrun                 Compute common beam and report without writing output files
      --tolerance <TOLERANCE>  Tolerance for MVE common-beam algorithm [default: 0.0001]
      --nsamps <NSAMPS>        Number of ellipse edge samples per beam for MVE [default: 200]
      --epsilon <EPSILON>      Epsilon (edge inflation) for MVE [default: 0.0005]
  -v, --verbose...             Verbose output (-v, -vv)
      --log <LOG>              Path to write a beamlog
  -h, --help                   Print help

convolvers 3d

$ cargo run -q --bin convolvers -- 3d -h
Smooth 3D/4D FITS spectral cubes to a common beam

Usage: convolvers 3d [OPTIONS] <INFILE>...

Arguments:
  <INFILE>...  Input FITS spectral cube(s)

Options:
      --listfile               Treat a single infile as a text file listing one path per line
  -s, --suffix <SUFFIX>        Output filename suffix [default: sm]
  -p, --prefix <PREFIX>        Output filename prefix
  -o, --outdir <OUTDIR>        Output directory [default: same as input]
      --bmaj <BMAJ>            Target BMAJ in arcsec (must also specify --bmin and --bpa)
      --bmin <BMIN>            Target BMIN in arcsec
      --bpa <BPA>              Target BPA in degrees
      --circularise            Circularise the final beam (BMIN = BMAJ, BPA = 0)
  -c, --cutoff <CUTOFF>        Beam size cutoff in arcsec — blank images/channels with BMAJ larger than this
  -d, --dryrun                 Compute common beam and report without writing output files
      --tolerance <TOLERANCE>  Tolerance for MVE common-beam algorithm [default: 0.0001]
      --nsamps <NSAMPS>        Number of ellipse edge samples per beam for MVE [default: 200]
      --epsilon <EPSILON>      Epsilon (edge inflation) for MVE [default: 0.0005]
  -v, --verbose...             Verbose output (-v, -vv)
      --mode <MODE>            Common-beam mode [default: natural] [possible values: natural, total]
  -h, --help                   Print help (see more with '--help')

Per-channel beams are read from, in priority order:

1. CASA BEAMS binary-table extension (CASAMBM=T in the header)

2. A co-located beamlog text file: {dir}/beamlog.{stem}.txt

3. Single BMAJ/BMIN/BPA from the primary header (broadcast to all channels)