convolve_rs/lib.rs
1//! Rust port of `beamcon_2D`/`beamcon_3D` from
2//! [RACS-tools](https://github.com/AlecThomson/RACS-tools): smooth radio
3//! astronomy FITS images and cubes to a common resolution via UV-plane (FFT)
4//! convolution.
5//!
6//! Also available as a [Python package](https://pypi.org/project/convolve-rs/)
7//! and a CLI tool (`convolvers`).
8//!
9//! # Overview
10//!
11//! - [`Beam`]: a 2D elliptical Gaussian beam (PSF) with convolution /
12//! deconvolution algebra ([`beam`]).
13//! - [`common_beam`](fn@common_beam): smallest beam that a set of beams can be
14//! convolved to ([`common_beam`](mod@common_beam) module).
15//! - [`convolve_uv`](fn@convolve_uv): FFT-based UV-plane convolution of an
16//! image between two beams ([`convolve_uv`](mod@convolve_uv) module).
17//! - [`smooth`](fn@smooth): high-level convolve-plus-flux-scaling for Jy/beam
18//! or Kelvin images ([`smooth`](mod@smooth) module).
19//! - [`fits_io`] / [`cube_io`]: FITS image and cube I/O.
20//!
21//! # Example
22//!
23//! Smooth an image from a 10″ to a 20″ circular beam:
24//!
25//! ```
26//! use convolve_rs::{Beam, BrightnessUnit, smooth};
27//! use ndarray::Array2;
28//!
29//! let old_beam = Beam::from_arcsec(10.0, 10.0, 0.0)?;
30//! let new_beam = Beam::from_arcsec(20.0, 20.0, 0.0)?;
31//! let image = Array2::<f32>::from_elem((64, 64), 1.0);
32//! let pixel_size_deg = 2.5 / 3600.0;
33//!
34//! let smoothed = smooth(
35//! &image,
36//! &old_beam,
37//! &new_beam,
38//! pixel_size_deg,
39//! pixel_size_deg,
40//! None,
41//! BrightnessUnit::JyPerBeam,
42//! )?;
43//! assert_eq!(smoothed.dim(), image.dim());
44//! # Ok::<(), Box<dyn std::error::Error>>(())
45//! ```
46pub mod beam;
47pub mod common_beam;
48pub mod convolve_uv;
49pub mod cube_io;
50pub mod fits_io;
51pub mod smooth;
52
53pub use beam::{Beam, BeamError, gauss_factor};
54pub use common_beam::{CommonBeamError, common_beam, find_commonbeam_between};
55pub use convolve_uv::{ConvolutionResult, ConvolveError, convolve_uv, fftfreq, gaussft};
56pub use fits_io::{FitsError, FitsImageData, output_path, read_fits, write_fits};
57pub use smooth::{BrightnessUnit, SmoothError, smooth};
58
59#[cfg(feature = "python")]
60mod python;
61#[cfg(feature = "python")]
62pub use python::_convolve_rs;