ruststartracker 0.2.2__tar.gz → 0.2.3__tar.gz

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ruststartracker
-Version: 0.2.2
+Version: 0.2.3
 Summary: Lightweight Python Star Tracker With Rust Backend
 License: MIT
 Author: Nicolas Tobler
@@ -34,6 +34,35 @@ Features:
 
 ## Example
 
+### Rust
+
+See [examples/basic.rs](examples/basic.rs)
+
+```rust
+// Get catalog positions
+let catalog: StarCatalog = StarCatalog::from_gaia(max_magnitude: ...).unwrap();
+let stars_xyz: Vec<[f32; 3]> = catalog.normalized_positions(epoch: ..., observer_position: ...);
+let stars_mag: Vec<f32> = catalog.magnitudes();
+
+// Create StarTracker instance (reuse this)
+let star_matcher = StarMatcher::new(
+    stars_xyz,
+    stars_mag,
+    max_lookup_magnitude: ...
+    max_inter_star_angle: ...,
+    inter_star_angle_tolerance: ...,
+    min_matches: ...,
+    timeout: ...
+);
+
+// Normalized observation in the camera frame
+let obs_xyz_camera: Vec<[f32; 3]> = ...
+
+let result = star_matcher.find(&obs_xyz_camera);
+println!("Result: {:?}", result);
+```
+
+### Python
 ```python
 import ruststartracker
 
@@ -72,11 +101,6 @@ print(result)
 
 - Install with `pip install ruststartracker` (Currently only ARM/x86 Linux wheels available).
 
-## TODOs
-
-- Improve error messages.
-- Return more diagnostic data.
-
 ## Attributions
 
 ### Gaia Data

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/README.md

@@ -13,6 +13,35 @@ Features:
 
 ## Example
 
+### Rust
+
+See [examples/basic.rs](examples/basic.rs)
+
+```rust
+// Get catalog positions
+let catalog: StarCatalog = StarCatalog::from_gaia(max_magnitude: ...).unwrap();
+let stars_xyz: Vec<[f32; 3]> = catalog.normalized_positions(epoch: ..., observer_position: ...);
+let stars_mag: Vec<f32> = catalog.magnitudes();
+
+// Create StarTracker instance (reuse this)
+let star_matcher = StarMatcher::new(
+    stars_xyz,
+    stars_mag,
+    max_lookup_magnitude: ...
+    max_inter_star_angle: ...,
+    inter_star_angle_tolerance: ...,
+    min_matches: ...,
+    timeout: ...
+);
+
+// Normalized observation in the camera frame
+let obs_xyz_camera: Vec<[f32; 3]> = ...
+
+let result = star_matcher.find(&obs_xyz_camera);
+println!("Result: {:?}", result);
+```
+
+### Python
 ```python
 import ruststartracker
 
@@ -51,11 +80,6 @@ print(result)
 
 - Install with `pip install ruststartracker` (Currently only ARM/x86 Linux wheels available).
 
-## TODOs
-
-- Improve error messages.
-- Return more diagnostic data.
-
 ## Attributions
 
 ### Gaia Data

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/build_script.py

@@ -50,7 +50,12 @@ def build_script() -> None:
     if not gaia_file.exists():
         download_gaia_data(gaia_file)
 
-    subprocess.check_call(["cargo", "build", "--release"], cwd=cwd)  # noqa: S603, S607
+    subprocess.check_call(  # noqa: S603
+        ["cargo", "build", "--release", "--features", "improc,gaia"],  # noqa: S607
+        cwd=cwd,
+        stdout=None,
+        stderr=None,
+    )
     shutil.copy(
         cwd / "target/release/libruststartracker.so", cwd / "ruststartracker/libruststartracker.so"
     )

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ruststartracker"
-version = "0.2.2"
+version = "0.2.3"
 description = "Lightweight Python Star Tracker With Rust Backend"
 authors = ["Nicolas Tobler <nitobler@gmail.com>"]
 readme = "README.md"
@@ -42,7 +42,7 @@ requires = ["poetry-core", "astroquery>=0.4.10"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.bumpversion]
-current_version = "0.2.2"
+current_version = "0.2.3"
 commit = true
 tag = true
 tag_name = "v{new_version}"

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/ruststartracker/libruststartracker.pyi

@@ -2,12 +2,15 @@ from collections.abc import Iterator
 
 import numpy as np
 import numpy.typing as npt
+from typing_extensions import Self
 
 class StarMatcher:
     def __init__(
         self,
         stars_xyz: npt.NDArray[np.float32],
+        stars_mag: npt.NDArray[np.float32],
         max_inter_star_angle: float,
+        max_lookup_magnitude: float,
         inter_star_angle_tolerance: float,
         n_minimum_matches: int,
         timeout_secs: float,
@@ -19,7 +22,7 @@ class StarMatcher:
         npt.NDArray[np.uint32],
         npt.NDArray[np.uint32],
         int,
-        list[list[float]],
+        npt.NDArray[np.float32],
         float,
     ]: ...
 
@@ -44,15 +47,43 @@ class IterTriangleFinder:
 class UnitVectorLookup:
     def __init__(self, vec: npt.NDArray[np.float32]) -> None: ...
     def lookup_nearest(self, key: npt.NDArray[np.float32]) -> int: ...
-    def get_inter_star_index_numpy(
-        self, vec: npt.NDArray[np.float32], angle_threshold: float
-    ) -> tuple[list[list[int]], list[float], list[float]]: ...
     def get_inter_star_index(
-        self, vec: npt.NDArray[np.float32], angle_threshold: float
+        self,
+        stars: npt.NDArray[np.float32],
+        magnitudes: npt.NDArray[np.float32],
+        max_angle_rad: float,
+        max_magnitude: float,
     ) -> tuple[list[list[int]], list[float], list[float]]: ...
     def look_up_close_angles(
-        self, vectors: npt.NDArray[np.float32], max_angle_rad: float
+        self,
+        vectors: npt.NDArray[np.float32],
+        magnitudes: npt.NDArray[np.float32],
+        max_angle_rad: float,
+        max_magnitude: float,
     ) -> list[tuple[list[float], float]]: ...
     def look_up_close_angles_naive(
-        self, vectors: npt.NDArray[np.float32], max_angle_rad: float
+        self,
+        vectors: npt.NDArray[np.float32],
+        magnitudes: npt.NDArray[np.float32],
+        max_angle_rad: float,
+        max_magnitude: float,
     ) -> list[tuple[list[float], float]]: ...
+
+def get_threshold_from_histogram(
+    img: npt.NDArray[np.uint8],
+    *,
+    fraction: float,
+) -> int: ...
+def extract_observations(
+    img: npt.NDArray[np.uint8],
+    threshold: int,
+    min_star_area: int,
+    max_star_area: int,
+) -> tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]: ...
+
+class StarCatalog:
+    @classmethod
+    def from_gaia(cls, *, max_magnitude: float | None) -> Self: ...
+    def normalized_positions(
+        self, *, epoch: float | None, observer_position: np.ndarray | None
+    ) -> npt.NDArray[np.float32]: ...

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/ruststartracker/star.py

@@ -87,8 +87,10 @@ class StarTracker:
     def __init__(
         self,
         stars_xyz: npt.NDArray[np.float32],
+        stars_mag: npt.NDArray[np.float32],
         camera_params: CameraParameters,
         *,
+        max_lookup_magnitude: float | None = None,
         max_inter_star_angle: float | None = None,
         inter_star_angle_tolerance: float = 0.0008,
         n_minimum_matches: int = 10,
@@ -98,11 +100,15 @@ class StarTracker:
 
         Args:
             stars_xyz: Positions of catalog stars
+            stars_mag: Magnitudes of catalog stars
             camera_params: Calibrated camera parameters
+            max_lookup_magnitude: Maximum magnitude of stars used in the triangulation. Reducing
+                this number means only bright stars are used for triangulation. This results in
+                faster lookup performance.
             max_inter_star_angle: Maximum angle between stars that should be indexed.
                 Calculating large inter star angles is expensive. If None, the angle is
                 calculated from the camera field of view.
-            inter_star_angle_tolerance: Tolerance for inter star angle matching.
+            inter_star_angle_tolerance: Tolerance for inter star angle matching in rad.
             n_minimum_matches: Minimum amount of required matches for a successful
                 attitude estimation
             timeout_secs: Maximum allowed search time in seconds. A StarTrackerError is raised
@@ -127,8 +133,13 @@ class StarTracker:
             dot_products = (corner_coords_xyz * np.array([0, 0, 1], dtype=np.float32)).sum(axis=-1)
             max_inter_star_angle = float(np.arccos(dot_products.max())) * 2
 
+        if max_lookup_magnitude is None:
+            max_lookup_magnitude = 100.0  # A very faint star. Almost infinity
+
         self._star_matcher = ruststartracker.libruststartracker.StarMatcher(
             np.ascontiguousarray(stars_xyz, dtype=np.float32),
+            np.ascontiguousarray(stars_mag, dtype=np.float32),
+            float(max_lookup_magnitude),
             float(max_inter_star_angle),
             float(inter_star_angle_tolerance),
             int(n_minimum_matches),
@@ -178,6 +189,20 @@ class StarTracker:
             max_star_area=max_star_area,
         )
 
+        if threshold is None:
+            threshold = ruststartracker.libruststartracker.get_threshold_from_histogram(
+                img, fraction=0.99
+            )
+
+        centroids, intensities = ruststartracker.libruststartracker.extract_observations(
+            img,
+            threshold,
+            min_star_area,
+            max_star_area,
+        )
+        centroids = np.array(centroids, dtype=np.float32)
+        intensities = np.array(intensities, dtype=np.float32)
+
         # At least 3 observations are required (one triangle)
         if len(centroids) < 3:
             raise StarTrackerError("Found too few star candidates (< 3) to continue.")
@@ -238,12 +263,12 @@ class StarTracker:
         quat, match_ids, obs_indices, n_matches, matched_obs, duration_s = result
 
         return StarTrackerResult(
-            quat=np.asarray(quat, dtype=np.float32),
-            match_ids=np.asarray(match_ids, dtype=np.uint32),
+            quat=quat,
+            match_ids=match_ids,
             n_matches=n_matches,
             duration_s=duration_s,
-            mached_obs_x=np.asarray(matched_obs, dtype=np.float32),
-            obs_indices=np.asarray(obs_indices, dtype=np.uint32),
+            mached_obs_x=matched_obs,
+            obs_indices=obs_indices,
         )
 
 

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/ruststartracker/test_backend.py

@@ -54,9 +54,12 @@ def test_unit_vector_lookup():
     close_indices_gt = np.concatenate(results, axis=-1).T[args]
     angles_gt = angles[args]
 
-    close_indices, angles, poly = uvl.get_inter_star_index_numpy(vec, angle_threshold)
-
-    close_indices, angles, poly = uvl.get_inter_star_index(vec[:, :3], angle_threshold)
+    close_indices, angles, poly = uvl.get_inter_star_index(
+        np.array(vec[:, :3], dtype=np.float32),
+        np.ones(len(vec), dtype=np.float32),
+        angle_threshold,
+        10,
+    )
     close_indices = np.array(close_indices)
     angles = np.array(angles)
     poly = np.array(poly)
@@ -101,6 +104,8 @@ def test_star_matcher():
     vec = rng.normal(size=[n_cat_stars, 3]).astype(np.float32)
     vec /= np.linalg.norm(vec, axis=-1, keepdims=True)
 
+    magnitudes = rng.uniform(0, 10, size=vec.shape[:1]).astype(np.float32)
+
     key = rng.normal(size=[3]).astype(np.float32)
     key /= np.linalg.norm(key, axis=-1, keepdims=True)
 
@@ -113,10 +118,16 @@ def test_star_matcher():
 
     rot = scipy.spatial.transform.Rotation.from_rotvec([1, 1, 1])
 
-    obs_rotated = rot.apply(obs)
+    obs_rotated = rot.apply(obs).astype(np.float32)
 
     index = libruststartracker.StarMatcher(
-        vec, np.radians(10).item(), np.radians(0.1).item(), 4, 999.0
+        vec,
+        magnitudes,
+        10,
+        np.radians(10).item(),
+        np.radians(0.1).item(),
+        4,
+        999.0,
     )
 
     res = index.find(obs_rotated)
@@ -124,7 +135,7 @@ def test_star_matcher():
     assert res is not None
 
     quat, match_ids, obs_indices, n_matches, matched_obs, time_s = res
-    np.testing.assert_allclose(quat, rot.inv().as_quat())
+    np.testing.assert_allclose(quat, rot.inv().as_quat(), rtol=1e-6)
     assert n_matches >= 4
     assert len(obs_index) == len(match_ids)
 

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/ruststartracker/test_catalog.py

@@ -1,10 +1,12 @@
 import datetime
+import time
 
 import astropy.time  # type: ignore[import]
 import numpy as np
 import pytest
 
 import ruststartracker.catalog
+import ruststartracker.libruststartracker
 
 
 def test_time_to_epoch():
@@ -43,5 +45,17 @@ def test_extract_observations():
     np.testing.assert_allclose(np.linalg.norm(positions, axis=-1), 1.0, rtol=1e-5)
 
 
+def test_python_rust():
+    t0 = time.monotonic()
+    positions = ruststartracker.catalog.StarCatalog().normalized_positions(epoch=2025.0)
+    print(f"Python catalog took {time.monotonic() - t0:.3f} seconds")
+    t0 = time.monotonic()
+    positions2 = ruststartracker.libruststartracker.StarCatalog.from_gaia(
+        max_magnitude=6.0
+    ).normalized_positions(epoch=2025.0, observer_position=None)
+    print(f"Rust catalog took {time.monotonic() - t0:.3f} seconds")
+    np.testing.assert_allclose(positions, positions2, rtol=1e-5, atol=1e-5)
+
+
 if __name__ == "__main__":
     pytest.main([__file__])

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/ruststartracker/test_integration.py

@@ -26,6 +26,7 @@ def prepare() -> tuple[ruststartracker.StarTracker, np.ndarray]:
 
     catalog = ruststartracker.StarCatalog()
     star_catalog_vecs = catalog.normalized_positions(epoch=2024)
+    star_catalog_magnitudes = catalog.magnitude
 
     camera_params = ruststartracker.CameraParameters(
         camera_matrix=camera_matrix,
@@ -35,6 +36,7 @@ def prepare() -> tuple[ruststartracker.StarTracker, np.ndarray]:
 
     st = ruststartracker.StarTracker(
         star_catalog_vecs,
+        star_catalog_magnitudes,
         camera_params,
         inter_star_angle_tolerance=np.radians(0.05).item(),
         n_minimum_matches=5,

{ruststartracker-0.2.2 → ruststartracker-0.2.3}/ruststartracker/test_star.py

@@ -5,16 +5,31 @@ import pytest
 import scipy.spatial
 
 import ruststartracker
+import ruststartracker.libruststartracker
 import ruststartracker.star
 
 
-def test_extract_observations():
-    size_x, size_y = (40, 50)
+@pytest.mark.parametrize("impl", ["python", "rust"])
+def test_extract_observations(impl: str):
+    size_x, size_y = (960, 480)
     img = np.zeros((size_y, size_x), np.uint8)
-    points = np.array([(3, 5), (23, 13)])
+    points = np.array([(3, 5), (23, 13), (30, 50), (230, 130)])
     for x, y in points:
         img[y - 1 : y + 3, x - 1 : x + 3] = 50
-    centers, intensities = ruststartracker.star._extract_observations(img, threshold=30)
+
+    t0 = time.monotonic()
+    if impl == "python":
+        centers, intensities = ruststartracker.star._extract_observations(img, threshold=30)
+    elif impl == "rust":
+        centers, intensities = ruststartracker.libruststartracker.extract_observations(
+            img, 30, 3, 300
+        )
+    else:
+        raise AssertionError
+    print(f"Extracting observations took {time.monotonic() - t0:.5f} seconds")
+
+    assert isinstance(centers, np.ndarray)
+    assert isinstance(intensities, np.ndarray)
     np.testing.assert_almost_equal(centers, points + 0.5)
     np.testing.assert_almost_equal(intensities, 50 * 16)
 
@@ -28,6 +43,8 @@ def setup():
     vec = rng.normal(size=[n_cat_stars, 3]).astype(np.float32)
     vec /= np.linalg.norm(vec, axis=-1, keepdims=True)
 
+    mag = rng.uniform(0, 10, size=vec.shape[:1]).astype(np.float32)
+
     angle_threshold = np.radians(10)
     dotp = np.sum([0, 0, 1] * vec, axis=-1)
     threshold = np.cos(angle_threshold).item()
@@ -55,17 +72,18 @@ def setup():
         image_patch = img[y - 1 : y + 2, x - 1 : x + 2]
         image_patch[:] = 50
 
-    return img, vec, camera_params
+    return img, vec, mag, pixel_in_frame, camera_params
 
 
 def test_star_matcher_success(setup):
-    img, vec, camera_params = setup
+    img, vec, mag, _, camera_params = setup
 
     rot = scipy.spatial.transform.Rotation.from_rotvec([1, 1, 1])
     vec = rot.inv().apply(vec)
 
     st = ruststartracker.StarTracker(
         vec,
+        mag,
         camera_params,
         inter_star_angle_tolerance=np.radians(0.1).item(),
         n_minimum_matches=6,
@@ -78,34 +96,51 @@ def test_star_matcher_success(setup):
 
 
 def test_star_matcher_exhaust(setup):
-    img, vec, camera_params = setup
+    img, vec, mag, _, camera_params = setup
     st = ruststartracker.StarTracker(
         vec,
+        mag,
         camera_params,
         inter_star_angle_tolerance=np.radians(0.001).item(),
         n_minimum_matches=500,
         timeout_secs=999.0,
     )
-    with pytest.raises(ruststartracker.StarTrackerError, match="exhaust"):
+    with pytest.raises(ruststartracker.StarTrackerError, match="SearchExhausted"):
         st.process_image(img)
 
 
 def test_star_matcher_timout(setup):
-    img, vec, camera_params = setup
-    timeout = 0.2
+    img, vec, mag, _, camera_params = setup
+    timeout = 0.0002
     st = ruststartracker.StarTracker(
         vec,
+        mag,
         camera_params,
         inter_star_angle_tolerance=np.radians(0.1).item(),
         n_minimum_matches=500,
         timeout_secs=timeout,
     )
     t = time.monotonic()
-    with pytest.raises(ruststartracker.StarTrackerError, match="Timeout reached"):
+    with pytest.raises(ruststartracker.StarTrackerError, match="Timeout"):
         st.process_image(img)
     passed_time = time.monotonic() - t
     assert passed_time > timeout
 
 
+def test_star_matcher_not_enough_stars(setup):
+    _, vec, mag, pixel_in_frame, camera_params = setup
+    timeout = 0.2
+    st = ruststartracker.StarTracker(
+        vec,
+        mag,
+        camera_params,
+        inter_star_angle_tolerance=np.radians(0.1).item(),
+        n_minimum_matches=500,
+        timeout_secs=timeout,
+    )
+    with pytest.raises(ruststartracker.StarTrackerError, match="NotEnoughStars"):
+        st.process_image_coordiantes(pixel_in_frame[:2])
+
+
 if __name__ == "__main__":
-    pytest.main([__file__])
+    pytest.main([__file__, "--capture=no"])