astroapers 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. astroapers-0.1.1/Cargo.lock +281 -0
  2. astroapers-0.1.1/Cargo.toml +38 -0
  3. astroapers-0.1.1/LICENSE +12 -0
  4. astroapers-0.1.1/PKG-INFO +194 -0
  5. astroapers-0.1.1/README.md +154 -0
  6. astroapers-0.1.1/pyproject.toml +70 -0
  7. astroapers-0.1.1/python/astroapers/__init__.py +130 -0
  8. astroapers-0.1.1/python/astroapers/_aperture_kernel_ops.py +176 -0
  9. astroapers-0.1.1/python/astroapers/_apertures.py +1052 -0
  10. astroapers-0.1.1/python/astroapers/_calibration.py +149 -0
  11. astroapers-0.1.1/python/astroapers/_cli.py +70 -0
  12. astroapers-0.1.1/python/astroapers/_containers.py +452 -0
  13. astroapers-0.1.1/python/astroapers/_kernel_dispatch.py +250 -0
  14. astroapers-0.1.1/python/astroapers/_kernel_docs.py +575 -0
  15. astroapers-0.1.1/python/astroapers/_kernel_validation.py +137 -0
  16. astroapers-0.1.1/python/astroapers/_path.py +290 -0
  17. astroapers-0.1.1/python/astroapers/_path_encoding.py +88 -0
  18. astroapers-0.1.1/python/astroapers/_pill.py +307 -0
  19. astroapers-0.1.1/python/astroapers/_utils.py +185 -0
  20. astroapers-0.1.1/python/astroapers/_wedge.py +216 -0
  21. astroapers-0.1.1/python/astroapers/kernels.py +2005 -0
  22. astroapers-0.1.1/python/astroapers/plotting.py +92 -0
  23. astroapers-0.1.1/src/aperture.rs +167 -0
  24. astroapers-0.1.1/src/geometry.rs +1874 -0
  25. astroapers-0.1.1/src/lib.rs +21 -0
  26. astroapers-0.1.1/src/pyapi/apsum.rs +1055 -0
  27. astroapers-0.1.1/src/pyapi/bbox.rs +271 -0
  28. astroapers-0.1.1/src/pyapi/mask.rs +122 -0
  29. astroapers-0.1.1/src/pyapi/npix.rs +141 -0
  30. astroapers-0.1.1/src/pyapi/parallel_api.rs +22 -0
  31. astroapers-0.1.1/src/pyapi/path.rs +186 -0
  32. astroapers-0.1.1/src/pyapi/raster.rs +792 -0
  33. astroapers-0.1.1/src/pyapi/summation.rs +1218 -0
  34. astroapers-0.1.1/src/pyapi/support.rs +404 -0
  35. astroapers-0.1.1/src/pyapi/weights.rs +1510 -0
  36. astroapers-0.1.1/src/pyapi.rs +54 -0
  37. astroapers-0.1.1/tests/rust_api.rs +53 -0
@@ -0,0 +1,281 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 4
4
+
5
+ [[package]]
6
+ name = "astroapers"
7
+ version = "0.1.1"
8
+ dependencies = [
9
+ "numpy",
10
+ "pyo3",
11
+ "rayon",
12
+ ]
13
+
14
+ [[package]]
15
+ name = "autocfg"
16
+ version = "1.5.0"
17
+ source = "registry+https://github.com/rust-lang/crates.io-index"
18
+ checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
19
+
20
+ [[package]]
21
+ name = "crossbeam-deque"
22
+ version = "0.8.6"
23
+ source = "registry+https://github.com/rust-lang/crates.io-index"
24
+ checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
25
+ dependencies = [
26
+ "crossbeam-epoch",
27
+ "crossbeam-utils",
28
+ ]
29
+
30
+ [[package]]
31
+ name = "crossbeam-epoch"
32
+ version = "0.9.18"
33
+ source = "registry+https://github.com/rust-lang/crates.io-index"
34
+ checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
35
+ dependencies = [
36
+ "crossbeam-utils",
37
+ ]
38
+
39
+ [[package]]
40
+ name = "crossbeam-utils"
41
+ version = "0.8.21"
42
+ source = "registry+https://github.com/rust-lang/crates.io-index"
43
+ checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
44
+
45
+ [[package]]
46
+ name = "either"
47
+ version = "1.15.0"
48
+ source = "registry+https://github.com/rust-lang/crates.io-index"
49
+ checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
50
+
51
+ [[package]]
52
+ name = "heck"
53
+ version = "0.5.0"
54
+ source = "registry+https://github.com/rust-lang/crates.io-index"
55
+ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
56
+
57
+ [[package]]
58
+ name = "libc"
59
+ version = "0.2.186"
60
+ source = "registry+https://github.com/rust-lang/crates.io-index"
61
+ checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
62
+
63
+ [[package]]
64
+ name = "matrixmultiply"
65
+ version = "0.3.10"
66
+ source = "registry+https://github.com/rust-lang/crates.io-index"
67
+ checksum = "a06de3016e9fae57a36fd14dba131fccf49f74b40b7fbdb472f96e361ec71a08"
68
+ dependencies = [
69
+ "autocfg",
70
+ "rawpointer",
71
+ ]
72
+
73
+ [[package]]
74
+ name = "ndarray"
75
+ version = "0.17.2"
76
+ source = "registry+https://github.com/rust-lang/crates.io-index"
77
+ checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
78
+ dependencies = [
79
+ "matrixmultiply",
80
+ "num-complex",
81
+ "num-integer",
82
+ "num-traits",
83
+ "portable-atomic",
84
+ "portable-atomic-util",
85
+ "rawpointer",
86
+ ]
87
+
88
+ [[package]]
89
+ name = "num-complex"
90
+ version = "0.4.6"
91
+ source = "registry+https://github.com/rust-lang/crates.io-index"
92
+ checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
93
+ dependencies = [
94
+ "num-traits",
95
+ ]
96
+
97
+ [[package]]
98
+ name = "num-integer"
99
+ version = "0.1.46"
100
+ source = "registry+https://github.com/rust-lang/crates.io-index"
101
+ checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
102
+ dependencies = [
103
+ "num-traits",
104
+ ]
105
+
106
+ [[package]]
107
+ name = "num-traits"
108
+ version = "0.2.19"
109
+ source = "registry+https://github.com/rust-lang/crates.io-index"
110
+ checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
111
+ dependencies = [
112
+ "autocfg",
113
+ ]
114
+
115
+ [[package]]
116
+ name = "numpy"
117
+ version = "0.28.0"
118
+ source = "registry+https://github.com/rust-lang/crates.io-index"
119
+ checksum = "778da78c64ddc928ebf5ad9df5edf0789410ff3bdbf3619aed51cd789a6af1e2"
120
+ dependencies = [
121
+ "libc",
122
+ "ndarray",
123
+ "num-complex",
124
+ "num-integer",
125
+ "num-traits",
126
+ "pyo3",
127
+ "pyo3-build-config",
128
+ "rustc-hash",
129
+ ]
130
+
131
+ [[package]]
132
+ name = "once_cell"
133
+ version = "1.21.4"
134
+ source = "registry+https://github.com/rust-lang/crates.io-index"
135
+ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
136
+
137
+ [[package]]
138
+ name = "portable-atomic"
139
+ version = "1.13.1"
140
+ source = "registry+https://github.com/rust-lang/crates.io-index"
141
+ checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
142
+
143
+ [[package]]
144
+ name = "portable-atomic-util"
145
+ version = "0.2.7"
146
+ source = "registry+https://github.com/rust-lang/crates.io-index"
147
+ checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
148
+ dependencies = [
149
+ "portable-atomic",
150
+ ]
151
+
152
+ [[package]]
153
+ name = "proc-macro2"
154
+ version = "1.0.106"
155
+ source = "registry+https://github.com/rust-lang/crates.io-index"
156
+ checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
157
+ dependencies = [
158
+ "unicode-ident",
159
+ ]
160
+
161
+ [[package]]
162
+ name = "pyo3"
163
+ version = "0.28.3"
164
+ source = "registry+https://github.com/rust-lang/crates.io-index"
165
+ checksum = "91fd8e38a3b50ed1167fb981cd6fd60147e091784c427b8f7183a7ee32c31c12"
166
+ dependencies = [
167
+ "libc",
168
+ "once_cell",
169
+ "portable-atomic",
170
+ "pyo3-build-config",
171
+ "pyo3-ffi",
172
+ "pyo3-macros",
173
+ ]
174
+
175
+ [[package]]
176
+ name = "pyo3-build-config"
177
+ version = "0.28.3"
178
+ source = "registry+https://github.com/rust-lang/crates.io-index"
179
+ checksum = "e368e7ddfdeb98c9bca7f8383be1648fd84ab466bf2bc015e94008db6d35611e"
180
+ dependencies = [
181
+ "target-lexicon",
182
+ ]
183
+
184
+ [[package]]
185
+ name = "pyo3-ffi"
186
+ version = "0.28.3"
187
+ source = "registry+https://github.com/rust-lang/crates.io-index"
188
+ checksum = "7f29e10af80b1f7ccaf7f69eace800a03ecd13e883acfacc1e5d0988605f651e"
189
+ dependencies = [
190
+ "libc",
191
+ "pyo3-build-config",
192
+ ]
193
+
194
+ [[package]]
195
+ name = "pyo3-macros"
196
+ version = "0.28.3"
197
+ source = "registry+https://github.com/rust-lang/crates.io-index"
198
+ checksum = "df6e520eff47c45997d2fc7dd8214b25dd1310918bbb2642156ef66a67f29813"
199
+ dependencies = [
200
+ "proc-macro2",
201
+ "pyo3-macros-backend",
202
+ "quote",
203
+ "syn",
204
+ ]
205
+
206
+ [[package]]
207
+ name = "pyo3-macros-backend"
208
+ version = "0.28.3"
209
+ source = "registry+https://github.com/rust-lang/crates.io-index"
210
+ checksum = "c4cdc218d835738f81c2338f822078af45b4afdf8b2e33cbb5916f108b813acb"
211
+ dependencies = [
212
+ "heck",
213
+ "proc-macro2",
214
+ "pyo3-build-config",
215
+ "quote",
216
+ "syn",
217
+ ]
218
+
219
+ [[package]]
220
+ name = "quote"
221
+ version = "1.0.45"
222
+ source = "registry+https://github.com/rust-lang/crates.io-index"
223
+ checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
224
+ dependencies = [
225
+ "proc-macro2",
226
+ ]
227
+
228
+ [[package]]
229
+ name = "rawpointer"
230
+ version = "0.2.1"
231
+ source = "registry+https://github.com/rust-lang/crates.io-index"
232
+ checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
233
+
234
+ [[package]]
235
+ name = "rayon"
236
+ version = "1.12.0"
237
+ source = "registry+https://github.com/rust-lang/crates.io-index"
238
+ checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
239
+ dependencies = [
240
+ "either",
241
+ "rayon-core",
242
+ ]
243
+
244
+ [[package]]
245
+ name = "rayon-core"
246
+ version = "1.13.0"
247
+ source = "registry+https://github.com/rust-lang/crates.io-index"
248
+ checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
249
+ dependencies = [
250
+ "crossbeam-deque",
251
+ "crossbeam-utils",
252
+ ]
253
+
254
+ [[package]]
255
+ name = "rustc-hash"
256
+ version = "2.1.2"
257
+ source = "registry+https://github.com/rust-lang/crates.io-index"
258
+ checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
259
+
260
+ [[package]]
261
+ name = "syn"
262
+ version = "2.0.117"
263
+ source = "registry+https://github.com/rust-lang/crates.io-index"
264
+ checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
265
+ dependencies = [
266
+ "proc-macro2",
267
+ "quote",
268
+ "unicode-ident",
269
+ ]
270
+
271
+ [[package]]
272
+ name = "target-lexicon"
273
+ version = "0.13.5"
274
+ source = "registry+https://github.com/rust-lang/crates.io-index"
275
+ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
276
+
277
+ [[package]]
278
+ name = "unicode-ident"
279
+ version = "1.0.24"
280
+ source = "registry+https://github.com/rust-lang/crates.io-index"
281
+ checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
@@ -0,0 +1,38 @@
1
+ [package]
2
+ name = "astroapers"
3
+ version = "0.1.1"
4
+ edition = "2021"
5
+ description = "Rust-backed aperture overlap and summation utilities"
6
+ license = "BSD-3-Clause"
7
+ readme = "README.md"
8
+ repository = "https://github.com/ysbach/astroapers"
9
+ homepage = "https://ysbach.github.io/astroapers/"
10
+ documentation = "https://docs.rs/astroapers"
11
+ keywords = ["astronomy", "aperture", "photometry", "numpy", "pyo3"]
12
+ categories = ["science", "algorithms"]
13
+ include = [
14
+ "/Cargo.toml",
15
+ "/Cargo.lock",
16
+ "/LICENSE",
17
+ "/README.md",
18
+ "/src/**/*.rs",
19
+ "/tests/**/*.rs",
20
+ ]
21
+
22
+ [lib]
23
+ name = "astroapers"
24
+ crate-type = ["cdylib", "rlib"]
25
+
26
+ [features]
27
+ default = []
28
+ python = ["dep:pyo3", "dep:numpy"]
29
+ extension-module = ["python", "pyo3/extension-module"]
30
+
31
+ [dependencies]
32
+ numpy = { version = "0.28", optional = true }
33
+ pyo3 = { version = "0.28", optional = true }
34
+ rayon = "1.10"
35
+
36
+ [profile.release]
37
+ codegen-units = 1
38
+ lto = "thin"
@@ -0,0 +1,12 @@
1
+ Copyright 2026 @ysBach
2
+
3
+ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
4
+
5
+ 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
6
+
7
+ 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
8
+
9
+ 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
10
+
11
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
12
+
@@ -0,0 +1,194 @@
1
+ Metadata-Version: 2.4
2
+ Name: astroapers
3
+ Version: 0.1.1
4
+ Classifier: Development Status :: 3 - Alpha
5
+ Classifier: Intended Audience :: Science/Research
6
+ Classifier: License :: OSI Approved :: BSD License
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Programming Language :: Rust
9
+ Classifier: Topic :: Scientific/Engineering :: Astronomy
10
+ Requires-Dist: numpy
11
+ Requires-Dist: reducers>=0.2
12
+ Requires-Dist: jupyter ; extra == 'dev'
13
+ Requires-Dist: matplotlib ; extra == 'dev'
14
+ Requires-Dist: pandas ; extra == 'dev'
15
+ Requires-Dist: photutils ; extra == 'dev'
16
+ Requires-Dist: scipy ; extra == 'dev'
17
+ Requires-Dist: sep ; extra == 'dev'
18
+ Requires-Dist: ruff ; extra == 'dev'
19
+ Requires-Dist: pytest ; extra == 'dev'
20
+ Requires-Dist: jupyter ; extra == 'docs'
21
+ Requires-Dist: matplotlib ; extra == 'docs'
22
+ Requires-Dist: pandas ; extra == 'docs'
23
+ Requires-Dist: photutils ; extra == 'docs'
24
+ Requires-Dist: scipy ; extra == 'docs'
25
+ Requires-Dist: sep ; extra == 'docs'
26
+ Requires-Dist: quartodoc ; extra == 'docs'
27
+ Requires-Dist: griffe<1 ; extra == 'docs'
28
+ Provides-Extra: dev
29
+ Provides-Extra: docs
30
+ License-File: LICENSE
31
+ Summary: Rust-backed aperture overlap and summation utilities
32
+ Home-Page: https://ysbach.github.io/astroapers/
33
+ Requires-Python: >=3.10
34
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
35
+ Project-URL: Documentation, https://ysbach.github.io/astroapers/
36
+ Project-URL: Homepage, https://github.com/ysbach/astroapers
37
+ Project-URL: Issues, https://github.com/ysbach/astroapers/issues
38
+ Project-URL: Repository, https://github.com/ysbach/astroapers
39
+
40
+ # astroapers
41
+
42
+ (Astronomy + Apertures + Rust(rs) = astroapers)
43
+
44
+ <p align="center">
45
+ <img src="logo.png" alt="astroapers aperture logo" width="170"><br>
46
+ </p>
47
+
48
+
49
+
50
+ `astroapers` is a Rust-backed Python package for exact pixel-aperture overlap,
51
+ bbox-tight aperture weights, and aperture summation in pixel coordinates.
52
+ Although it was developed for astronomical image analysis, the core algorithms
53
+ operate on generic two-dimensional image arrays. They can also be useful for
54
+ other scientific and technical images, including microscopy, photography, and
55
+ any workflow that needs reproducible measurements over pixel-defined apertures
56
+ or regions.
57
+
58
+ The package exposes three public layers:
59
+
60
+ - `PixelAp` objects such as `CircAp`, `EllipAp`, `RectAp`, `PillAp`, and
61
+ `WedgeAp` for readable workflows, plotting, weights, and one-shot aperture
62
+ sums.
63
+ - `bboxes()`, `weights_exact()`, and `BoundingBox` methods for reusing bbox-tight
64
+ aperture weights.
65
+ - `import astroapers._rust as aapr` for expert users who need the raw extension functions and
66
+ are willing to supply contiguous arrays and handle raw return values. (For how-tos for `aapr`, inspect `astroapers.kernels`; it is the Python layer that calls `_rust` internally).
67
+
68
+ Project links:
69
+
70
+ - Documentation: <https://ysbach.github.io/astroapers/>
71
+ - Rust API reference: <https://docs.rs/astroapers>
72
+ - GitHub: <https://github.com/ysbach/astroapers>
73
+
74
+ ## Install
75
+
76
+ `astroapers` builds a native Rust extension with `maturin`, so source installs
77
+ require a working Rust/Cargo toolchain.
78
+
79
+
80
+ ```bash
81
+ # You may activate your Python environment before this, e.g.,
82
+ # source ~/.venvs/your_env/bin/activate
83
+
84
+ # General install:
85
+ uv pip install -e .
86
+
87
+ # development install:
88
+ uv pip install -e ".[dev]"
89
+ ```
90
+
91
+ Then try tests:
92
+ ```bash
93
+ uv run pytest -q
94
+ ```
95
+
96
+ For Rust crate use:
97
+
98
+ ```toml
99
+ [dependencies]
100
+ astroapers = "0.1"
101
+ ```
102
+
103
+ ## Quickstart
104
+
105
+ ```python
106
+ import astroapers as aap
107
+
108
+ ap = aap.CircAp((42.3, 17.2), r=3.0)
109
+ apsum, npix = ap.apsum_exact(data, mask=bad_pixels) # return_npix=True by default
110
+ weights = ap.weights_exact()[0]
111
+ center_weights = ap.weights_center()[0]
112
+ bbox = ap.bboxes()[0]
113
+ center_samples = ap.sampled_values(data)[0]
114
+ weighted_values = ap.weighted_values(data)[0]
115
+ fits_section = bbox.to_fits_section(data.shape)
116
+
117
+ wedge = aap.WedgeAp((42.3, 17.2), r_in=5.0, r_out=50.0, theta_in=0.0, dtheta_in=0.2)
118
+ wedge_sum, wedge_npix = wedge.apsum_exact(data)
119
+ ```
120
+
121
+ For maximum-performance:
122
+
123
+ ```python
124
+ import astroapers._rust as aapr
125
+
126
+ x = np.ascontiguousarray(x, dtype=np.float64)
127
+ y = np.ascontiguousarray(y, dtype=np.float64)
128
+ data = np.ascontiguousarray(data, dtype=np.float64)
129
+
130
+ apsum = aapr.apsum_circ_exact_sum(data, x, y, 3.0)
131
+ ```
132
+
133
+ ## Dtype caveats
134
+
135
+ `astroapers` performs geometry and public aperture-sum outputs in `float64`.
136
+ The raw `_rust` functions do not provide validation, mask handling, dtype
137
+ conversion, or return shaping. Use contiguous arrays with the dtype-specific raw
138
+ function (`*_f32`, `*_i32`, `*_i16`) when not using `float64`. Coordinate inputs
139
+ and scalar geometry parameters are expected to be `float64`-compatible.
140
+
141
+ Bbox-tight weights from `PixelAp.weights_exact()` are `float64`. When user-supplied
142
+ weights are passed to `BoundingBox` methods, only `float32` and `float64` arrays
143
+ are preserved. Other numeric or boolean weight arrays, including extended
144
+ precision dtypes such as `float128`/`longdouble` where NumPy provides them, are
145
+ converted to `float64`. `BoundingBox.to_image()`, `weighted_cutout()`, and
146
+ `weighted_values()` preserve `float32` when both data and weights are `float32`,
147
+ but `BoundingBox.apsum()` and `BoundingBox.npix()` always accumulate in
148
+ `float64`. Bad-pixel masks passed as `mask=` are converted to boolean, where
149
+ `True` means excluded.
150
+
151
+ `weights_center()` and `sampled_values(data)` are related but not synonyms:
152
+ `weights_center()` returns bbox-tight binary weights, while
153
+ `sampled_values(data)` returns the raw image values selected by the positive
154
+ center weights.
155
+
156
+ ## Documentation
157
+
158
+ The documentation is hosted at <https://ysbach.github.io/astroapers/> and built
159
+ from the Quarto site in `docs/quarto`. The hosted docs contain:
160
+
161
+ - autogenerated API reference pages from Python docstrings;
162
+ - generated Rust API reference from `rustdoc`;
163
+ - tutorial `.qmd` files for common aperture-sum, mask, background, vector, and
164
+ raw-Rust performance workflows.
165
+
166
+ Local docs build:
167
+
168
+ ```bash
169
+ uv pip install -e ".[docs]"
170
+ make docs-build
171
+ ```
172
+
173
+ ## Release Checks
174
+
175
+ Before publishing both distributions, verify the Python package and Rust crate
176
+ from the same source tree:
177
+
178
+ ```bash
179
+ cargo test --no-default-features
180
+ cargo check --features extension-module
181
+ cargo package --allow-dirty
182
+ uv run pytest -q
183
+ uv build
184
+ ```
185
+
186
+ Publish the Cargo crate with `cargo publish`, then publish the Python artifacts
187
+ from `dist/` with `uv publish` after confirming the versions match in
188
+ `Cargo.toml` and `pyproject.toml`.
189
+
190
+ ## Conventions
191
+
192
+ Coordinates follow the SEP/Photutils pixel convention: pixel `(x, y)` is
193
+ centered at integer coordinates and covers `[x - 0.5, x + 0.5]`.
194
+
@@ -0,0 +1,154 @@
1
+ # astroapers
2
+
3
+ (Astronomy + Apertures + Rust(rs) = astroapers)
4
+
5
+ <p align="center">
6
+ <img src="logo.png" alt="astroapers aperture logo" width="170"><br>
7
+ </p>
8
+
9
+
10
+
11
+ `astroapers` is a Rust-backed Python package for exact pixel-aperture overlap,
12
+ bbox-tight aperture weights, and aperture summation in pixel coordinates.
13
+ Although it was developed for astronomical image analysis, the core algorithms
14
+ operate on generic two-dimensional image arrays. They can also be useful for
15
+ other scientific and technical images, including microscopy, photography, and
16
+ any workflow that needs reproducible measurements over pixel-defined apertures
17
+ or regions.
18
+
19
+ The package exposes three public layers:
20
+
21
+ - `PixelAp` objects such as `CircAp`, `EllipAp`, `RectAp`, `PillAp`, and
22
+ `WedgeAp` for readable workflows, plotting, weights, and one-shot aperture
23
+ sums.
24
+ - `bboxes()`, `weights_exact()`, and `BoundingBox` methods for reusing bbox-tight
25
+ aperture weights.
26
+ - `import astroapers._rust as aapr` for expert users who need the raw extension functions and
27
+ are willing to supply contiguous arrays and handle raw return values. (For how-tos for `aapr`, inspect `astroapers.kernels`; it is the Python layer that calls `_rust` internally).
28
+
29
+ Project links:
30
+
31
+ - Documentation: <https://ysbach.github.io/astroapers/>
32
+ - Rust API reference: <https://docs.rs/astroapers>
33
+ - GitHub: <https://github.com/ysbach/astroapers>
34
+
35
+ ## Install
36
+
37
+ `astroapers` builds a native Rust extension with `maturin`, so source installs
38
+ require a working Rust/Cargo toolchain.
39
+
40
+
41
+ ```bash
42
+ # You may activate your Python environment before this, e.g.,
43
+ # source ~/.venvs/your_env/bin/activate
44
+
45
+ # General install:
46
+ uv pip install -e .
47
+
48
+ # development install:
49
+ uv pip install -e ".[dev]"
50
+ ```
51
+
52
+ Then try tests:
53
+ ```bash
54
+ uv run pytest -q
55
+ ```
56
+
57
+ For Rust crate use:
58
+
59
+ ```toml
60
+ [dependencies]
61
+ astroapers = "0.1"
62
+ ```
63
+
64
+ ## Quickstart
65
+
66
+ ```python
67
+ import astroapers as aap
68
+
69
+ ap = aap.CircAp((42.3, 17.2), r=3.0)
70
+ apsum, npix = ap.apsum_exact(data, mask=bad_pixels) # return_npix=True by default
71
+ weights = ap.weights_exact()[0]
72
+ center_weights = ap.weights_center()[0]
73
+ bbox = ap.bboxes()[0]
74
+ center_samples = ap.sampled_values(data)[0]
75
+ weighted_values = ap.weighted_values(data)[0]
76
+ fits_section = bbox.to_fits_section(data.shape)
77
+
78
+ wedge = aap.WedgeAp((42.3, 17.2), r_in=5.0, r_out=50.0, theta_in=0.0, dtheta_in=0.2)
79
+ wedge_sum, wedge_npix = wedge.apsum_exact(data)
80
+ ```
81
+
82
+ For maximum-performance:
83
+
84
+ ```python
85
+ import astroapers._rust as aapr
86
+
87
+ x = np.ascontiguousarray(x, dtype=np.float64)
88
+ y = np.ascontiguousarray(y, dtype=np.float64)
89
+ data = np.ascontiguousarray(data, dtype=np.float64)
90
+
91
+ apsum = aapr.apsum_circ_exact_sum(data, x, y, 3.0)
92
+ ```
93
+
94
+ ## Dtype caveats
95
+
96
+ `astroapers` performs geometry and public aperture-sum outputs in `float64`.
97
+ The raw `_rust` functions do not provide validation, mask handling, dtype
98
+ conversion, or return shaping. Use contiguous arrays with the dtype-specific raw
99
+ function (`*_f32`, `*_i32`, `*_i16`) when not using `float64`. Coordinate inputs
100
+ and scalar geometry parameters are expected to be `float64`-compatible.
101
+
102
+ Bbox-tight weights from `PixelAp.weights_exact()` are `float64`. When user-supplied
103
+ weights are passed to `BoundingBox` methods, only `float32` and `float64` arrays
104
+ are preserved. Other numeric or boolean weight arrays, including extended
105
+ precision dtypes such as `float128`/`longdouble` where NumPy provides them, are
106
+ converted to `float64`. `BoundingBox.to_image()`, `weighted_cutout()`, and
107
+ `weighted_values()` preserve `float32` when both data and weights are `float32`,
108
+ but `BoundingBox.apsum()` and `BoundingBox.npix()` always accumulate in
109
+ `float64`. Bad-pixel masks passed as `mask=` are converted to boolean, where
110
+ `True` means excluded.
111
+
112
+ `weights_center()` and `sampled_values(data)` are related but not synonyms:
113
+ `weights_center()` returns bbox-tight binary weights, while
114
+ `sampled_values(data)` returns the raw image values selected by the positive
115
+ center weights.
116
+
117
+ ## Documentation
118
+
119
+ The documentation is hosted at <https://ysbach.github.io/astroapers/> and built
120
+ from the Quarto site in `docs/quarto`. The hosted docs contain:
121
+
122
+ - autogenerated API reference pages from Python docstrings;
123
+ - generated Rust API reference from `rustdoc`;
124
+ - tutorial `.qmd` files for common aperture-sum, mask, background, vector, and
125
+ raw-Rust performance workflows.
126
+
127
+ Local docs build:
128
+
129
+ ```bash
130
+ uv pip install -e ".[docs]"
131
+ make docs-build
132
+ ```
133
+
134
+ ## Release Checks
135
+
136
+ Before publishing both distributions, verify the Python package and Rust crate
137
+ from the same source tree:
138
+
139
+ ```bash
140
+ cargo test --no-default-features
141
+ cargo check --features extension-module
142
+ cargo package --allow-dirty
143
+ uv run pytest -q
144
+ uv build
145
+ ```
146
+
147
+ Publish the Cargo crate with `cargo publish`, then publish the Python artifacts
148
+ from `dist/` with `uv publish` after confirming the versions match in
149
+ `Cargo.toml` and `pyproject.toml`.
150
+
151
+ ## Conventions
152
+
153
+ Coordinates follow the SEP/Photutils pixel convention: pixel `(x, y)` is
154
+ centered at integer coordinates and covers `[x - 0.5, x + 0.5]`.