convolve-rs 2.0.0

Rust port of beamcon from RACS-tools: smooth FITS images and cubes to a common beam via UV-plane (FFT) convolution
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405

import builtins
import typing
__all__ = [
    "Beam",
    "common_beam",
    "gauss_factor",
    "smooth",
]

class Beam:
    r"""
    A 2D elliptical Gaussian beam (PSF).
    
    Args:
        major_deg: FWHM major axis in degrees (FITS BMAJ).
        minor_deg: FWHM minor axis in degrees (FITS BMIN), at most ``major_deg``.
        pa_deg: Position angle in degrees East of North (FITS BPA).
    
    Raises:
        ValueError: If ``minor_deg > major_deg``, an axis is negative, or a
            value is not finite.
    
    Examples:
        >>> from convolve_rs import Beam
        >>> beam = Beam(0.005, 0.004, 30.0)
        >>> beam.major_deg
        0.005
        >>> round(beam.major_arcsec, 6)
        18.0
        >>> Beam(0.004, 0.005, 0.0)
        Traceback (most recent call last):
        ...
        ValueError: invalid beam: minor axis (0.005) > major axis (0.004)
    """
    @property
    def major_deg(self) -> builtins.float:
        r"""
        FWHM major axis in degrees (FITS BMAJ).
        """
    @property
    def minor_deg(self) -> builtins.float:
        r"""
        FWHM minor axis in degrees (FITS BMIN).
        """
    @property
    def pa_deg(self) -> builtins.float:
        r"""
        Position angle in degrees East of North (FITS BPA).
        """
    @property
    def major_arcsec(self) -> builtins.float:
        r"""
        FWHM major axis in arcseconds.
        """
    @property
    def minor_arcsec(self) -> builtins.float:
        r"""
        FWHM minor axis in arcseconds.
        """
    def __new__(cls, major_deg: builtins.float, minor_deg: builtins.float, pa_deg: builtins.float) -> Beam: ...
    @classmethod
    def from_arcsec(cls, major_arcsec: builtins.float, minor_arcsec: builtins.float, pa_deg: builtins.float) -> Beam:
        r"""
        A beam from FWHM axes in arcseconds and a PA in degrees.
        
        Examples:
            >>> from convolve_rs import Beam
            >>> Beam.from_arcsec(18.0, 14.4, 30.0).major_deg
            0.005
        """
    def area_sr(self) -> builtins.float:
        r"""
        Solid angle in steradians, ``pi / (4 ln 2) * major_rad * minor_rad``.
        """
    def deconvolve(self, other: Beam) -> Beam:
        r"""
        The beam that, convolved with ``other``, gives this one.
        
        Raises:
            ValueError: If ``other`` does not fit inside this beam.
        
        Examples:
            >>> from convolve_rs import Beam
            >>> a = Beam.from_arcsec(3.0, 3.0, 0.0)
            >>> b = Beam.from_arcsec(4.0, 4.0, 0.0)
            >>> c = a.convolve(b)
            >>> round(c.deconvolve(a).major_arcsec, 6)
            4.0
            >>> b.deconvolve(c)
            Traceback (most recent call last):
            ...
            ValueError: beam could not be deconvolved: source beam is smaller than the PSF
        """
    def convolve(self, other: Beam) -> Beam:
        r"""
        This beam convolved with ``other``.
        
        Examples:
            >>> from convolve_rs import Beam
            >>> a = Beam.from_arcsec(3.0, 3.0, 0.0)
            >>> b = Beam.from_arcsec(4.0, 4.0, 0.0)
            >>> round(a.convolve(b).major_arcsec, 6)
            5.0
        """
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...

def common_beam(beams: typing.Sequence[Beam], tolerance: builtins.float = 0.0001, nsamps: builtins.int = 200, epsilon: builtins.float = 0.0005) -> Beam:
    r"""
    The smallest beam every beam in ``beams`` can be convolved to.
    
    Uses the CASA formula for two beams and otherwise the minimum-volume
    ellipse fit of ``radio_beam.Beams.common_beam(method='pts')``, with the
    same ``tolerance``, ``nsamps`` and ``epsilon``.
    
    Returns:
        Beam: The common beam, of the same class as ``beams[0]``.
    
    Raises:
        ValueError: If ``beams`` is empty or no common beam is found.
    
    Examples:
        >>> from convolve_rs import Beam, common_beam
        >>> b1 = Beam.from_arcsec(10.0, 8.0, 30.0)
        >>> b2 = Beam.from_arcsec(12.0, 6.0, 60.0)
        >>> cb = common_beam([b1, b2])
        >>> cb.major_arcsec >= 12.0
        True
    """

def gauss_factor(conv_beam: Beam, orig_beam: Beam, dx_arcsec: builtins.float, dy_arcsec: builtins.float) -> tuple[builtins.float, builtins.float, builtins.float, builtins.float, builtins.float]:
    r"""
    The factor that keeps a Jy/beam image in Jy/beam after convolving it from
    ``orig_beam`` with the kernel ``conv_beam``. Pixel sizes are in arcsec.
    
    Returns:
        tuple: ``(fac, amp, bmaj, bmin, bpa)``: the pixel factor, the kernel
        amplitude, and the resulting beam (arcsec, arcsec, degrees).
    
    Examples:
        >>> from convolve_rs import Beam, gauss_factor
        >>> conv = Beam.from_arcsec(5.0, 5.0, 0.0)
        >>> orig = Beam.from_arcsec(10.0, 10.0, 0.0)
        >>> fac, amp, bmaj, bmin, bpa = gauss_factor(conv, orig, 2.5, 2.5)
        >>> round(bmaj, 5)
        11.18034
    """

def smooth(image: typing.Any, old_beam: Beam, new_beam: Beam, dx_deg: builtins.float, dy_deg: builtins.float, cutoff_arcsec: typing.Optional[builtins.float] = None, bunit: typing.Optional[builtins.str] = None) -> typing.Any:
    r"""
    Smooth an image from ``old_beam`` to ``new_beam``.
    
    Jy/beam images are scaled by the beam-area ratio so they stay in Jy/beam;
    Kelvin images are not scaled. The GIL is released while the image is
    convolved, so calls from several threads run in parallel.
    
    Args:
        image (numpy.ndarray): 2D ``float32`` or ``float64`` array, in either
            byte order. The output has the same dtype in native byte order.
        old_beam (Beam): Current beam.
        new_beam (Beam): Target beam; ``old_beam`` convolved with some
            Gaussian must give it.
        dx_deg (float): Pixel size along x in degrees (CDELT1; sign ignored).
        dy_deg (float): Pixel size along y in degrees (CDELT2; sign ignored).
        cutoff_arcsec (float, optional): Raise ``ValueError`` if the BMAJ of
            ``old_beam`` exceeds this.
        bunit (str, optional): FITS ``BUNIT``. ``"K"`` means no flux scaling;
            an unrecognised value warns and is treated as Jy/beam (the default).
    
    Returns:
        numpy.ndarray: The smoothed image. An all-NaN image is returned as is.
    
    Raises:
        ValueError: If ``new_beam`` cannot be reached from ``old_beam``,
            ``old_beam`` has zero size, its BMAJ exceeds ``cutoff_arcsec``, or
            ``image`` is not a 2D float array.
    
    Examples:
        >>> import numpy as np
        >>> from convolve_rs import Beam, smooth
        >>> image = np.ones((64, 64), dtype=np.float32)
        >>> old = Beam.from_arcsec(10.0, 10.0, 0.0)
        >>> new = Beam.from_arcsec(20.0, 20.0, 0.0)
        >>> dx = 2.5 / 3600.0
        >>> round(float(smooth(image, old, new, dx, dx)[32, 32]), 3)
        4.0
        >>> round(float(smooth(image, old, new, dx, dx, bunit="K")[32, 32]), 3)
        1.0
    """