Raw Rust extension

astroapers._rust is the expert API for the least Python overhead.

Facts:

Import it as import astroapers._rust as aapr.
It expects raw, contiguous NumPy arrays with the exact dtype required by the function name.
It does not accept mask=, validate=, return_npix=, keyword geometry arguments, scalar/list coordinate normalization, or Python BoundingBox objects.
It returns raw extension values, usually Python lists or tuples of lists.
Function docstrings are currently not generated by the Rust extension, so the examples below are the API guide.

For more raw-call patterns, inspect astroapers.kernels; it is the Python layer that calls _rust internally.

Basic aperture sums

import numpy as np
import astroapers as aap
import astroapers._rust as aapr

data = np.ascontiguousarray(np.ones((32, 32)), dtype=np.float64)
x = np.ascontiguousarray([16.0], dtype=np.float64)
y = np.ascontiguousarray([16.0], dtype=np.float64)

apsum = aapr.apsum_circ_exact_sum(data, x, y, 5.0)
apsum_with_npix = aapr.apsum_circ_exact(data, x, y, 5.0)

apsum, apsum_with_npix

([78.53981633974482], ([78.53981633974482], [78.53981633974483]))

Naming rules

Raw aperture-sum functions follow these patterns:

pattern	meaning
`apsum_<shape>_<mode>`	return `(apsum, npix)` for many centers
`apsum_<shape>_<mode>_sum`	return only `apsum` for many centers
`apsum_<shape>_<mode>_one`	scalar-center variant where available
`weights_<shape>_<mode>`	return raw bbox-tight weight arrays and bbox bounds
`weights_<shape>_<mode>_one`	one bbox-local weight image
`bboxes_<shape>`	return raw bbox bound arrays
`npix_<shape>_<mode>`	return effective in-frame pixel counts

Image dtype suffixes are explicit:

suffix	image dtype
no suffix	`float64`
`_f32`	`float32`
`_i32`	`int32`
`_i16`	`int16`

Example:

data_f32 = np.ascontiguousarray(data, dtype=np.float32)
aapr.apsum_circ_exact_sum_f32(data_f32, x, y, 5.0)

[78.53981633974482]

Raw weights

Raw weight functions return flattened bbox-tight weights plus bbox bounds:

weights, ixmins, ixmaxs, iymins, iymaxs = aapr.weights_circ_exact(x, y, 5.0)

shape0 = (iymaxs[0] - iymins[0], ixmaxs[0] - ixmins[0])
weights0 = np.asarray(weights[0], dtype=np.float64).reshape(shape0)

shape0, weights0.sum()

((11, 11), np.float64(78.53981633974485))

Construct a Python BoundingBox only when you want its convenience methods:

bbox0 = aap.BoundingBox(ixmins[0], ixmaxs[0], iymins[0], iymaxs[0])
sum0, npix0 = bbox0.apsum(weights0, data)

sum0, npix0

(78.53981633974485, 78.53981633974485)

Available groups

Use dir(aapr) to inspect the exact functions in the installed build:

names = [name for name in dir(aapr) if not name.startswith("__")]
names[:12], len(names)

(['_farthest_mask_pixel',
  '_selected_pixel_distances',
  'apsum_circ_ann_exact',
  'apsum_circ_ann_exact_f32',
  'apsum_circ_ann_exact_i16',
  'apsum_circ_ann_exact_i32',
  'apsum_circ_ann_exact_one',
  'apsum_circ_ann_exact_one_f32',
  'apsum_circ_ann_exact_one_i16',
  'apsum_circ_ann_exact_one_i32',
  'apsum_circ_ann_exact_sum',
  'apsum_circ_ann_exact_sum_f32'],
 117)

The main groups are:

circular, elliptical, and rectangular raw apsum_* functions;
circular-annulus exact raw apsum_* functions;
raw npix_* functions for simple circle/ellipse/rectangle exact and center modes;
raw weights_* functions for circle, ellipse, rectangle, pill, wedge, path, and their annuli;
raw bboxes_* functions for supported geometries;
parallel-threshold utilities.

For shapes without a fused raw apsum_* function, use raw weights_* or bboxes_*, or use the Python convenience layer when readability and mask handling matter more than minimum overhead.