torchbp.ops.cfbp module

torchbp.ops.cfbp.backprojection_cart_2d_tx_power_cfbp(wa, g, g_extent, grid, r_res, pos, att, stages, divisions=2, normalization=None, azimuth_resolution=True, downsample_x=4.0, downsample_y=4.0, min_nsweeps=64, min_nx=32, min_ny=32, margin=4, beam_theta_samples=32.0)[source]

Fast factorized (CFBP style) version of backprojection_cart_2d_tx_power().

Splits the track recursively into subapertures like cfbp(), computes coarse per-subaperture accumulator maps over the ground region each illuminates, and merges them pairwise with bilinear interpolation. Like the polar backprojection_polar_2d_tx_power_ffbp() the accumulated fields are smooth and phase-free, so the subaperture maps can be sampled much more coarsely than the output grid (downsample_x, downsample_y) and the azimuth resolution moments merge exactly (Chan’s parallel variance formula). Unlike the polar version everything is in absolute Cartesian coordinates: no origin shift and no carrier phase.

Output matches backprojection_cart_2d_tx_power() up to interpolation error, except near illumination edges where pixels with very few contributing pulses can differ. Ground-plane grid only (z = 0, per-sweep pos z altitude).

Parameters:

  • wa (Tensor) – Amplitude weighting of each pulse, shape [nsweeps].

  • g (Tensor) – Square-root of two-way antenna gain, shape [elevation, azimuth].

  • g_extent (list) – Antenna pattern extent [g_el0, g_az0, g_el1, g_az1] in radians.

  • grid (CartesianGrid or dict) – Cartesian grid {"x": (x0, x1), "y": (y0, y1), "nx": nx, "ny": ny}. x is range, y is along-track / azimuth.

  • r_res (float) – Range bin resolution. Unused, kept for signature parity with backprojection_cart_2d_tx_power().

  • pos (Tensor) – Platform position at each pulse, shape [nsweeps, 3].

  • att (Tensor) – Euler angles [roll, pitch, yaw] at each pulse, shape [nsweeps, 3]. Pitch rotates the antenna pattern about its boresight (the along-track attitude angle for a side-looking antenna).

  • stages (int) – Number of recursions.

  • divisions (int) – Subaperture divisions per stage. Default 2.

  • normalization (str or None) – “sigma”, “gamma”, “beta”/None or “point”; see backprojection_cart_2d_tx_power().

  • azimuth_resolution (bool) – If True (default), also normalize for the varying azimuth resolution.

  • downsample_x (float) – Subaperture map step relative to the output grid step in x (range) and y (azimuth). The fields are smooth, so values well above 1 are usually fine. Default 4.

  • downsample_y (float) – Subaperture map step relative to the output grid step in x (range) and y (azimuth). The fields are smooth, so values well above 1 are usually fine. Default 4.

  • min_nsweeps (int) – Do not recurse into subapertures with fewer pulses than this.

  • min_nx (int) – Minimum subaperture map size. Avoids large edge interpolation errors.

  • min_ny (int) – Minimum subaperture map size. Avoids large edge interpolation errors.

  • margin (int) – Extra margin in subaperture map cells around the computed extents.

  • beam_theta_samples (float) – Minimum number of subaperture map samples across the antenna half amplitude azimuth beamwidth (and a quarter of that across the elevation beamwidth in range). Caps downsample_y/downsample_x so a beam thin compared to the output grid step stays resolved.

Returns:

tx_power – Cartesian image of square root of power returned from each pixel assuming constant reflectivity, shape [nx, ny].

Return type:

Tensor

torchbp.ops.cfbp.cart_tx_power_merge2(acc0, acc1, grid0, grid1, grid_new)[source]

Merge two Cartesian tx_power accumulator maps onto a new Cartesian grid.

Bilinearly interpolates the 4-channel accumulator maps (S, W, P1, M2, see torchbp.ops.backproj._backprojection_cart_2d_tx_power_accum()) from each input grid onto the output grid and combines them. All grids are in absolute world coordinates, so an output pixel maps straight into each input’s local index; no origin shift is needed. The psi moments are combined with Chan’s parallel variance formula so the merge is exact up to interpolation. acc1 = None interpolates only acc0 (single-input regrid). Used internally by backprojection_cart_2d_tx_power_cfbp().

Parameters:
Return type:

Tensor

torchbp.ops.cfbp.cfbp(data, grid, fc, r_res, pos, stages, divisions=2, d0=0.0, oversample_y=1.4, guard_y=0.05, beamwidth=3.141592653589793, data_fmod=0, interp_method=('knab', 8, 1.4))[source]

Cartesian factorized backprojection. [1]

Factorized backprojection directly on a Cartesian grid. The aperture is recursively split into subapertures which are backprojected with backprojection_cart_2d() onto the full output grid extent, coarsely sampled in the cross-range (y) dimension. Subaperture images are demodulated with the carrier referenced to the subaperture center, which makes them bandlimited so that merging only needs upsampling along y and a phase re-reference, done in a single fused kernel (see interp_method). The output matches backprojection_cart_2d(data, grid, ...) up to interpolation error.

Antenna pattern normalization is not implemented.

Gradient can be calculated with respect to data. Gradient with respect to pos flows only through the base-level backprojections; the merge phase references are treated as constants (same as ffbp()).

Parameters:

  • data (Tensor) – Range compressed input data. Shape should be [nsweeps, samples].

  • grid (CartesianGrid or dict) –

    Cartesian grid definition. Can be:

    • CartesianGrid object: CartesianGrid(x_range=(-50, 50), y_range=(-50, 50), nx=200, ny=200)

    • dict: {"x": (x0, x1), "y": (y0, y1), "nx": nx, "ny": ny}

    The grid should be oversampled for good interpolation accuracy.

  • fc (float) – RF center frequency in Hz.

  • r_res (float) – Range bin resolution in data (meters). For FMCW radar: c/(2*bw*oversample), where c is speed of light, bw is sweep bandwidth, and oversample is FFT oversampling factor.

  • pos (Tensor) – Position of the platform at each data point. Shape should be [nsweeps, 3].

  • stages (int) – Number of recursions.

  • divisions (int) – Number of subaperture divisions per stage. Default is 2.

  • d0 (float) – Zero range correction.

  • oversample_y (float) – Internally oversample y by this amount to avoid aliasing. The x dimension needs no internal oversampling since subaperture images are never resampled in x.

  • guard_y (float) – Internal guard band on each side of the y extent as a fraction of ny, cropped from the output. Absorbs the y edge effects of the merge interpolation (periodic wrap-around for the fft method, window truncation for knab).

  • beamwidth (float) – Beamwidth of the antenna in radians. Passed to backprojection_cart_2d().

  • data_fmod (float) – Range modulation frequency applied to input data.

  • interp_method (tuple or str) – Merge interpolation method. ("knab", order, oversample) uses the compiled merge kernel with an exactly evaluated Knab windowed-sinc interpolator of order taps designed for signals occupying 1/oversample of the sampling rate; oversample should not exceed oversample_y. "fft" uses exact FFT resampling in pure torch, which is slower but has no interpolation error and supports gradient calculation through the merge. The knab method falls back to the fft path when the merged images require gradient.

Returns:

img – Cartesian format radar image. Shape is [1, nx, ny].

Return type:

Tensor

Notes

The subaperture images are sampled in y at oversample_y * ny / divisions**stage points. This covers the azimuth bandwidth, which shrinks with the subaperture length, but the demodulated images also contain the range envelope bandwidth projected onto y, approximately sin(theta_max) * B, where theta_max is the largest angle of the scene from boresight and B = 1/(os * r_res) with os the range FFT oversampling factor of the data. This term does not shrink when the aperture is split, so scenes with large angular extent combined with small range oversampling need a larger oversample_y or fewer stages to avoid aliasing in the base images. Polar ffbp() does not have this limitation and is a better choice for very wide-angle imaging.

References

[1]

  1. Dong, G. -C. Sun, Z. Yang, L. Guo and M. Xing, “Cartesian

Factorized Backprojection Algorithm for High-Resolution Spotlight SAR Imaging,” in IEEE Sensors Journal, vol. 18, no. 3, pp. 1160-1168, 1 Feb.1, 2018.

torchbp.ops.cfbp.cfbp_adaptive(data, grid, fc, r_res, pos, stages, divisions=2, d0=0.0, oversample_y=1.4, guard_y=0.05, beamwidth=3.141592653589793, data_fmod=0, data_oversample=2.0, merge_cost=8.0, interp_method=('knab', 8, 1.4))[source]

Cartesian factorized backprojection with range-adaptive y-density.

Plain cfbp() on a subsampled output grid fails when the aperture is long compared to the closest scene range: the demodulated subaperture images then have more y-bandwidth than the proportionally decimated grids can hold at near range, at every level of the recursion. Because the Cartesian scheme never resamples x, the scene can be split into ground range blocks with zero seam error and each block run at its own internal y-density: block rows at ground range x get an integer density multiplier k(x) and stage count s(x) (see cfbp_adaptive_blocks()), the cfbp tree runs on a grid with k * ny y-samples, and the output is decimated by taking every k-th sample, which lands exactly on the requested grid positions. The result therefore matches backprojection_cart_2d on the output grid to normal cfbp accuracy at all ranges, while far ranges keep the full factorization speedup (deeper recursion is chosen there, shallower near-in where the angular extent saturates). stages is the maximum recursion depth.

Near range blocks saturate geometrically (the angular extent of a subaperture seen from a pixel is bounded), so k stays finite for scenes starting near zero ground range as long as the platform altitude is nonzero.

Parameters are as in cfbp(), plus:

Parameters:

  • data_oversample (float) – Range FFT oversampling factor of the range compressed data, i.e. the fraction 1/data_oversample of the sample bandwidth occupied by the data spectrum. Used to size the projected range envelope bandwidth term of the internal grids. Default is 2.

  • merge_cost (float) – Assumed cost of one level of merging relative to one backprojection operation, used when selecting the per-block stage count. See cfbp_adaptive_blocks().

  • data (Tensor)

  • grid (CartesianGrid | dict)

  • fc (float)

  • r_res (float)

  • pos (Tensor)

  • stages (int)

  • divisions (int)

  • d0 (float)

  • oversample_y (float)

  • guard_y (float)

  • beamwidth (float)

  • data_fmod (float)

  • interp_method (tuple | str)

Returns:

img – Cartesian format radar image. Shape is [1, nx, ny].

Return type:

Tensor

torchbp.ops.cfbp.cfbp_adaptive_blocks(grid, pos, fc, r_res, stages, divisions=2, oversample_y=1.4, data_oversample=2.0, merge_cost=8.0)[source]

Compute the range-adaptive y-density blocks used by cfbp_adaptive().

For every output row (ground range x) the demodulated subaperture image y-bandwidth is estimated at each recursion level as:

B(l, rho) = (2*fc/c) * l / sqrt((l/2)**2 + rho**2) + sin_max / (data_oversample * r_res)

where l is the subaperture length at that level, rho = sqrt(x**2 + h**2) is the closest slant distance from the row to the track line, and sin_max is the largest angle of arrival at the row. The first term is the subaperture angular extent seen from the pixel (saturates for long subapertures at close range), the second is the range envelope bandwidth projected onto y. For a given stage count s, the required integer density multiplier k(s) is the smallest one for which every level of the recursion satisfies its Nyquist limit, rounded up to the 2**m / 3*2**m bucket grid.

The stage count is also chosen per row, by minimizing the estimated cost per output sample k(s) * (nsweeps / divisions**s + merge_cost * s) (base backprojection plus merge passes): deep recursion pays off at far range where the angular term is small, while near range rows saturate and prefer shallow recursion. stages is the maximum allowed. merge_cost is the assumed cost of one level of merging relative to one backprojection operation. Consecutive rows with equal (k, s) are grouped into blocks.

Returns:

blocks – Half-open output row ranges with their density multiplier and stage count, in ascending row order covering the full grid.

Return type:

list of (row_start, row_end, k, s)

Parameters:

  • grid (CartesianGrid | dict)

  • pos (Tensor)

  • fc (float)

  • r_res (float)

  • stages (int)

  • divisions (int)

  • oversample_y (float)

  • data_oversample (float)

  • merge_cost (float)

torchbp.ops.cfbp.cfbp_merge2(img0, img1, w0, idx0, w1, idx1, dx, dy, ox0, oy0, z0, ox1, oy1, z1, oxp, oyp, zp, ref_phase)[source]

Merge two demodulated cfbp subaperture images into their parent image.

Both children and the output share the same x and y extents; the y interpolation from child sampling to output sampling uses the precomputed per-output-row weight tables (see _merge_weight_table()). ox*, oy* are the output grid start coordinates relative to each subaperture center (child 0, child 1, parent) and z* the corresponding center heights. Each interpolated child is re-referenced from its own demodulation carrier to the parent carrier with phase pi * ref_phase * (d_child - d_parent) and the two are summed.

Parameters:

  • img0 (Tensor)

  • img1 (Tensor)

  • w0 (Tensor)

  • idx0 (Tensor)

  • w1 (Tensor)

  • idx1 (Tensor)

  • dx (float)

  • dy (float)

  • ox0 (float)

  • oy0 (float)

  • z0 (float)

  • ox1 (float)

  • oy1 (float)

  • z1 (float)

  • oxp (float)

  • oyp (float)

  • zp (float)

  • ref_phase (float)

Return type:

Tensor