# CLI usage
`convolvers 2d` and `convolvers 3d` do the jobs of `beamcon_2D` and
`beamcon_3D`. Install with:
```sh
cargo install convolve-rs
```
```{note}
The help text on this page is generated by running the binary when the docs
are built.
```
```{command-output} cargo run -q --bin convolvers -- --help
:cwd: ..
```
## Common workflows
Smooth a set of images to their common beam:
```sh
convolvers 2d *.fits
```
Smooth to an explicit target beam (all three of `--bmaj`, `--bmin`, `--bpa`
required):
```sh
convolvers 2d --bmaj 20 --bmin 20 --bpa 0 image.fits
```
Report the common beam without writing anything:
```sh
convolvers 2d --dryrun *.fits
```
Smooth cubes channel-by-channel (`natural`, the default) or to one beam across
all channels and cubes (`total`):
```sh
convolvers 3d --mode total cube1.fits cube2.fits
```
## `convolvers 2d`
```{command-output} cargo run -q --bin convolvers -- 2d --help
:cwd: ..
```
## `convolvers 3d`
```{command-output} cargo run -q --bin convolvers -- 3d -h
:cwd: ..
```
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)
## Beam handling
- A computed common beam is rounded up to 0.1″ axes and 0.01° position angle,
as in racs_tools. An explicit `--bmaj/--bmin/--bpa` target is used as given.
`--circularise` applies to either.
- Images or channels whose BMAJ exceeds `--cutoff`, or whose beam has zero
size, are written as NaN and left out when finding or checking the target.
- Only the first plane of a 4D image is smoothed; the output has
`NAXIS3 = NAXIS4 = 1`. `BITPIX = -64` images are smoothed and written in
double precision; integer images are smoothed in single precision and
written as `BITPIX = -32`.