ruststartracker 0.2.1__tar.gz

ruststartracker-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Nicolas Tobler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ruststartracker-0.2.1/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.3
+Name: ruststartracker
+Version: 0.2.1
+Summary: Lightweight Python Star Tracker With Rust Backend
+License: MIT
+Author: Nicolas Tobler
+Author-email: nitobler@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: numpy (>=1.26.0,<2.0.0)
+Requires-Dist: opencv-python-headless (>=4.9.0,<5.0.0)
+Description-Content-Type: text/markdown
+
+# Lightweight Python Star Tracker With Rust Backend
+
+Based on the methodology used in https://github.com/nasa/COTS-Star-Tracker, with following improvements:
+- Reduced dependencies to opencv and numpy for lightweight usage in a Raspberry Pi.
+- Reimplemented computationally expensive parts in rust. This includes most parts that are not image processing related.
+- Added quadratic inter star angle index look up polynomial for faster triangle search.
+- Added spatial index to look up neighboring stars.
+
+Features:
+- Attitude estimation from image and camera calibration parameters.
+- Attitude estimation from list of star observation coordinates.
+- Star catalog creation with temporal corrections.
+
+## Example
+
+```python
+import ruststartracker
+
+# Get catalog positions
+catalog = ruststartracker.StarCatalog()
+star_catalog_vecs = catalog.normalized_positions()
+
+# Define opencv camera parameters, see https://docs.opencv.org/4.x/dc/dbb/tutorial_py_calibration.html
+camera_params = ruststartracker.CameraParameters(
+    camera_matrix=...,
+    cam_resolution=...,
+    dist_coefs=...,
+)
+
+# Create StarTracker instance (reuse this)
+st = ruststartracker.StarTracker(
+    star_catalog_vecs,
+    camera_params,
+    max_inter_star_angle=...,
+    inter_star_angle_tolerance=...,
+    n_minimum_matches=...,
+)
+
+# Obtain numpy array image
+img = ...
+
+# Find attitude from given image
+result = st.process_image(img)
+
+print(result)
+# StarTrackerResult(quat=[-0.43977802991867065, -0.439766526222229, -0.4398997128009796, 0.6478340029716492], match_ids=[1435, 1272, 1140, 2035, 1070, 1438, 1338, 903, 260, 2141, 1771, 1727, 385, 1717, 2204, 2062, 1989, 1634, 708, 1357], n_matches=20, duration_s=0.0003700880042742938)
+```
+
+## Installation
+
+- Make sure rust tool chain (`cargo`) is installed and in the `PATH` environment variable.
+- Install with `pip install git+https://github.com/ntobler/ruststartracker.git`.
+
+## TODOs
+
+- Improve error messages.
+- Return more diagnostic data.
+

ruststartracker-0.2.1/README.md

@@ -0,0 +1,57 @@
+# Lightweight Python Star Tracker With Rust Backend
+
+Based on the methodology used in https://github.com/nasa/COTS-Star-Tracker, with following improvements:
+- Reduced dependencies to opencv and numpy for lightweight usage in a Raspberry Pi.
+- Reimplemented computationally expensive parts in rust. This includes most parts that are not image processing related.
+- Added quadratic inter star angle index look up polynomial for faster triangle search.
+- Added spatial index to look up neighboring stars.
+
+Features:
+- Attitude estimation from image and camera calibration parameters.
+- Attitude estimation from list of star observation coordinates.
+- Star catalog creation with temporal corrections.
+
+## Example
+
+```python
+import ruststartracker
+
+# Get catalog positions
+catalog = ruststartracker.StarCatalog()
+star_catalog_vecs = catalog.normalized_positions()
+
+# Define opencv camera parameters, see https://docs.opencv.org/4.x/dc/dbb/tutorial_py_calibration.html
+camera_params = ruststartracker.CameraParameters(
+    camera_matrix=...,
+    cam_resolution=...,
+    dist_coefs=...,
+)
+
+# Create StarTracker instance (reuse this)
+st = ruststartracker.StarTracker(
+    star_catalog_vecs,
+    camera_params,
+    max_inter_star_angle=...,
+    inter_star_angle_tolerance=...,
+    n_minimum_matches=...,
+)
+
+# Obtain numpy array image
+img = ...
+
+# Find attitude from given image
+result = st.process_image(img)
+
+print(result)
+# StarTrackerResult(quat=[-0.43977802991867065, -0.439766526222229, -0.4398997128009796, 0.6478340029716492], match_ids=[1435, 1272, 1140, 2035, 1070, 1438, 1338, 903, 260, 2141, 1771, 1727, 385, 1717, 2204, 2062, 1989, 1634, 708, 1357], n_matches=20, duration_s=0.0003700880042742938)
+```
+
+## Installation
+
+- Make sure rust tool chain (`cargo`) is installed and in the `PATH` environment variable.
+- Install with `pip install git+https://github.com/ntobler/ruststartracker.git`.
+
+## TODOs
+
+- Improve error messages.
+- Return more diagnostic data.

ruststartracker-0.2.1/pyproject.toml

@@ -0,0 +1,138 @@
+[tool.poetry]
+name = "ruststartracker"
+version = "0.2.1"
+description = "Lightweight Python Star Tracker With Rust Backend"
+authors = ["Nicolas Tobler <nitobler@gmail.com>"]
+readme = "README.md"
+license = "MIT"
+include = [
+    { path = "ruststartracker/star_catalog.tsv", format = ["sdist", "wheel"] },
+    { path = "ruststartracker/libruststartracker.so", format = ["wheel"] },
+]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+numpy = "^1.26.0"
+opencv-python-headless = "^4.9.0"
+
+[tool.poetry.group.dev.dependencies]
+matplotlib = "^3.9.2"
+scipy = "^1.14.1"
+viztracer = "^0.16.3"
+pytest = "^8.3.3"
+pytest-cov = "^6.0.0"
+pre-commit = "^3.8.0"
+astropy = "^6.1.4"
+mypy = "^1.13.0"
+scipy-stubs = "^1.14.1.5"
+ruff = "^0.9.3"
+bump-my-version = "^1.2.0"
+
+[tool.poetry.build]
+script = "rust_build.py"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.bumpversion]
+current_version = "0.2.1"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+commit_message = "ci: bump version to {new_version}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "Cargo.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    # Pyflakes
+    "F",
+    # pycodestyle error
+    "E",
+    # pycodestyle warning
+    "W",
+    # pydocstring
+    "D",
+    # mccabe
+    "C90",
+    # isort
+    "I",
+    # Pep8 naming
+    "N",
+    # pyupgrade
+    "UP",
+    # flake8-2020
+    "YTT",
+    # flake8-annotations
+    "ANN",
+    # flake8-bandit
+    "S",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # boolean trap
+    "FBT001",
+    # Built in shadowing
+    "A",
+    # flake8-comprehensions
+    "C4",
+    "NPY",
+    "DTZ",
+    "T10",
+    "EXE",
+    "ISC",
+    "ICN",
+    "LOG",
+    "PIE",
+    "Q",
+    "RET",
+    "SLF",
+    "TID",
+    "TCH",
+    "ARG",
+    "PTH",
+    # Perflint
+    "PERF",
+    # Ruff-specific rules
+    "RUF"
+]
+ignore = [
+    "ISC001" # conflict with formatter
+]
+pydocstyle.convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"test*" = ["D100", "D103", "SLF001", "ANN", "S101"]
+
+[tool.mypy]
+packages = ["ruststartracker"]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=ruststartracker --cov-report xml --cov-report term --cov-fail-under=95"
+
+[tool.codespell]
+ignore-words-list = "crate"
+
+[tool.coverage.report]
+exclude_lines = [
+    'if __name__ == "__main__":',
+    'if plot:',
+    'if debug:',
+    'if verbose:',
+]

ruststartracker-0.2.1/rust_build.py

@@ -0,0 +1,21 @@
+"""Build rust backend.
+
+This script is automatically run when the pyproject is installed.
+"""
+
+import pathlib
+import shutil
+import subprocess
+
+
+def rust_build() -> None:
+    """Build rust backend and move shared library to correct folder."""
+    cwd = pathlib.Path(__file__).parent.expanduser().absolute()
+    subprocess.check_call(["cargo", "build", "--release"], cwd=cwd)  # noqa: S603, S607
+    shutil.copy(
+        cwd / "target/release/libruststartracker.so", cwd / "ruststartracker/libruststartracker.so"
+    )
+
+
+if __name__ == "__main__":
+    rust_build()

ruststartracker-0.2.1/ruststartracker/__init__.py

@@ -0,0 +1,12 @@
+"""Star tracker implementation with backend in rust."""
+
+from ruststartracker.catalog import StarCatalog
+from ruststartracker.star import CameraParameters, StarTracker, StarTrackerError, StarTrackerResult
+
+__all__ = [
+    "CameraParameters",
+    "StarCatalog",
+    "StarTracker",
+    "StarTrackerError",
+    "StarTrackerResult",
+]

ruststartracker-0.2.1/ruststartracker/catalog.py

@@ -0,0 +1,151 @@
+"""Create star catalog."""
+
+import csv
+import datetime
+import math
+import pathlib
+
+import numpy as np
+import numpy.typing as npt
+
+AU: float = 149597870.693
+"""Astronomical unit."""
+
+INTERNAL_CATALOG_FILE = pathlib.Path(__file__).parent.expanduser().absolute() / "star_catalog.tsv"
+"""Location of the internal star catalog file."""
+
+
+def time_to_epoch(t: datetime.datetime) -> float:
+    """Convert a date time object to the Epoch in Julian years."""
+    # Get time stamp at the Julian year J2000
+    delta_t_j2000 = 64  # Delta T at J2000 https://en.wikipedia.org/wiki/%CE%94T_(timekeeping)
+    j2000 = datetime.datetime.fromisoformat("2000-01-01T12:00:00").timestamp() - delta_t_j2000
+    # Calculate difference from given datetime to j2000 and convert to Julian years
+    seconds_in_j_year = 365.25 * 86400
+    return (t.timestamp() - j2000) / seconds_in_j_year + 2000.0
+
+
+class StarCatalog:
+    """Star catalog from Hipparcos data."""
+
+    _data: npt.NDArray[np.float32]
+    """Underlying data array."""
+    ra: npt.NDArray[np.float32]
+    """Right ascension at epoch in rads."""
+    de: npt.NDArray[np.float32]
+    """Declination at epoch in rads."""
+    parallax: npt.NDArray[np.float32]
+    """Parallax in rads."""
+    proper_motion_ra: npt.NDArray[np.float32]
+    """Proper motion of the right ascension in mad."""
+    proper_motion_de: npt.NDArray[np.float32]
+    """Proper motion of the declination in mad."""
+    magnitude: npt.NDArray[np.float32]
+    """Magnitude values."""
+    epoch: float = 1992.25
+    """Epoch of the catalog in years."""
+
+    def __init__(
+        self, filename: pathlib.Path | str | None = None, max_magnitude: float = 6.0
+    ) -> None:
+        """Read catalog from file.
+
+        Args:
+            filename: Star catalog filename.
+            max_magnitude: Maximum magnitude to include.
+        """
+        # Use locally included star catalog is no file is given
+        filename = INTERNAL_CATALOG_FILE if filename is None else pathlib.Path(filename)
+
+        keep_columns = ("RArad", "DErad", "Plx", "pmRA", "pmDE", "Hpmag")
+
+        with filename.open("r") as f:
+            it = csv.reader(f, delimiter="\t", strict=True)
+
+            # skip head
+            [next(it) for _ in range(52)]
+
+            # Get columns
+            columns = next(it)
+
+            keep_columns_indices = tuple(columns.index(x) for x in keep_columns)
+            min_length = len(keep_columns_indices)
+
+            mag_column_index = columns.index("Hpmag")
+
+            # Skip unit and horizontal bar
+            [next(it) for _ in range(2)]
+
+            rows = [
+                [float(line[j]) for j in keep_columns_indices]
+                for line in it
+                if len(line) >= min_length and float(line[mag_column_index]) <= max_magnitude
+            ]
+        self._data = np.array(rows, dtype=np.float32)
+
+        self.ra = self._data[:, keep_columns.index("RArad")]
+        self.de = self._data[:, keep_columns.index("DErad")]
+        self.parallax = self._data[:, keep_columns.index("Plx")]
+        self.proper_motion_ra = self._data[:, keep_columns.index("pmRA")]
+        self.proper_motion_de = self._data[:, keep_columns.index("pmDE")]
+        self.magnitude = self._data[:, keep_columns.index("Hpmag")]
+
+        deg2rad = math.pi / 180
+        arcsec2deg = 1 / 3600
+        mas2arcsec = 1 / 1000
+        mas2rad = mas2arcsec * arcsec2deg * deg2rad
+
+        # Convert data to rad
+        self.ra *= deg2rad
+        self.de *= deg2rad
+        self.proper_motion_ra *= mas2rad
+        self.proper_motion_de *= mas2rad
+        self.parallax *= mas2rad
+
+    def normalized_positions(
+        self, *, epoch: float | None = None, observer_position: np.ndarray | None = None
+    ) -> npt.NDArray[np.float32]:
+        """Get star positions as normalized (x, y, z) vector.
+
+        Args:
+            epoch: The Julian epoch at which the positions should be calculated in Julian
+                years. E.g. 2024.3. If None, the current local time us used.
+            observer_position: The position of the observer in the Equatorial coordinate
+                system relative to the sun. If None, position is not corrected.
+
+        Returns:
+            Normalized (x, y, z) vector of star positions, shape=[n, 3]
+        """
+        if epoch is None:
+            epoch = time_to_epoch(datetime.datetime.now(tz=datetime.timezone.utc))
+
+        delta_epoch = epoch - self.epoch
+
+        # Precalculate sin and cos
+        cos_ra: npt.NDArray[np.float32] = np.cos(self.ra)
+        sin_ra: npt.NDArray[np.float32] = np.sin(self.ra)
+        sin_de: npt.NDArray[np.float32] = np.sin(self.de)
+        cos_de: npt.NDArray[np.float32] = np.cos(self.de)
+        zeros = np.zeros_like(self.de)
+
+        # Get star positions as normalized vector (x, y, z)
+        vectors: npt.NDArray[np.float32] = np.stack(
+            [cos_de * cos_ra, cos_de * sin_ra, sin_de], axis=-1
+        )
+
+        # Correct proper motion
+        p_hat = np.stack([-sin_ra, cos_ra, zeros], axis=-1)
+        q_hat = np.stack([-sin_de * cos_ra, -sin_de * sin_ra, cos_de], axis=-1)
+        pm = delta_epoch * (
+            self.proper_motion_ra[..., np.newaxis] * p_hat
+            + self.proper_motion_de[..., np.newaxis] * q_hat
+        )
+        vectors += pm
+
+        if observer_position is not None:
+            plx = self.parallax[:, np.newaxis] * (observer_position / AU)[np.newaxis, :]
+            vectors -= plx
+
+        # normalize star positions
+        vectors /= np.linalg.norm(vectors, axis=-1, keepdims=True)
+        return vectors

ruststartracker-0.2.1/ruststartracker/libruststartracker.pyi

@@ -0,0 +1,58 @@
+from collections.abc import Iterator
+
+import numpy as np
+import numpy.typing as npt
+
+class StarMatcher:
+    def __init__(
+        self,
+        stars_xyz: npt.NDArray[np.float32],
+        max_inter_star_angle: float,
+        inter_star_angle_tolerance: float,
+        n_minimum_matches: int,
+        timeout_secs: float,
+    ) -> None: ...
+    def find(
+        self, obs_xyz: npt.NDArray[np.float32]
+    ) -> tuple[
+        npt.NDArray[np.float32],
+        npt.NDArray[np.uint32],
+        npt.NDArray[np.uint32],
+        int,
+        list[list[float]],
+        float,
+    ]: ...
+
+class TriangleFinder:
+    def __init__(
+        self,
+        ab: npt.NDArray[np.float32],
+        ac: npt.NDArray[np.float32],
+        bc: npt.NDArray[np.float32],
+    ) -> None: ...
+    def get(self) -> list[int]: ...
+
+class IterTriangleFinder:
+    def __init__(
+        self,
+        ab: npt.NDArray[np.float32],
+        ac: npt.NDArray[np.float32],
+        bc: npt.NDArray[np.float32],
+    ) -> None: ...
+    def __iter__(self) -> Iterator[list[int]]: ...
+
+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
+    ) -> tuple[list[list[int]], list[float], list[float]]: ...
+    def look_up_close_angles(
+        self, vectors: npt.NDArray[np.float32], max_angle_rad: float
+    ) -> list[tuple[list[float], float]]: ...
+    def look_up_close_angles_naive(
+        self, vectors: npt.NDArray[np.float32], max_angle_rad: float
+    ) -> list[tuple[list[float], float]]: ...