starfinder

Crates.iostarfinder
lib.rsstarfinder
version1.3.2
created_at2024-09-10 01:18:26.26192+00
updated_at2025-07-09 17:36:00.833679+00
descriptionstarfinder is a Rust & Python package that provides functionality to read, process, and render star data from the Tycho-2 catalog. It's built with Rust for performance and exposes a Python API for ease of use.
homepagehttps://github.com/djmango/starfinder
repositoryhttps://github.com/djmango/starfinder
max_upload_size
id1369946
size142,366
Sulaiman Ghori (djmango)

documentation

README

starfinder

starfinder is a Rust & Python package that provides functionality to read, process, and render star data from the Tycho-2 catalog. It's built with Rust for performance and exposes a Python API for ease of use.

Starfinder output

Pictured above: Example Starfinder output

Here is a real result of successful analysis of an image generated by the renderer, submitted to nova.astrometry.net. The location that the engine calculated was accurate to ~1/10th of a second. This is likely attributable to rendering techniques that can be improved moving forward (there are already ideas in the pipeline).

Setup

  1. Download the Tycho-2 catalog:

  2. Ensure your project structure looks like this:

.
├── Cargo.lock
├── Cargo.toml
├── README.md
├── data
│   └── tycho2
│       ├── catalog.dat
│       ├── index.dat
│       ├── suppl_1.dat
│       └── suppl_2.dat
├── poetry.lock
├── pyproject.toml
└── src

Running the Renderer

Using Cargo (Rust)

Running the renderer

To run the renderer with default settings:

cargo run --release

To run with custom arguments:

cargo run --release -- --roll 0.0 --fov-w 75.0 --fov-h 50.0

Command-line Arguments

Flag Description Default Notes
--center-ra FOV center point right ascension 180.0 In degrees
--center-dec FOV center point declination 0.0 In degrees
--fov-w Width of FOV 60.0 In degrees
--fov-h Height of FOV 45.0 In degrees
--roll Camera sensor roll 0.0 In degrees
--fov_max Maximum FOV 60.0 In degrees
--max-magnitude Maximum visual magnitude 12.0 Lower is brighter
--lambda-nm Targeted wavelength 540.0 In nanometers
--pixel-size-m Simulated sensor pixel size 3e-6 In meters
--width Output image width 800 In pixels
--height Output image height 800 In pixels
--output, -o Output filename renders/star_map.png

Python Installation and Usage

Installation

Ensure you have Python 3.8 or later, then:

pip install starfinder

Or if you want to install the package in development mode:

pipx install maturin
maturin develop

Basic Usage

from starfinder import StarCatalogArgs, process_star_catalog_py

args = StarCatalogArgs(
    source="data/optimized.dat",
    center_ra=180.0,
    center_dec=0.0,
    fov_w=60.0,
    fov_h=45.0,
    roll=0.0,
    max_magnitude=6.0,
    lambda_nm=540.0,
    pixel_size_m=3e-6,
    width=800,
    height=600,
    output="renders/star_map.png"
)

process_star_catalog_py(args)

API Reference

StarCatalogArgs

Parameters:

  • source (str): Path to the Tycho-2 catalog file
  • center_ra (float): Right Ascension of FOV center (degrees)
  • center_dec (float): Declination of FOV center (degrees)
  • fov_w (float): FOV width (degrees)
  • fov_h (float): FOV height (degrees)
  • roll (float): Camera roll (degrees)
  • max_magnitude (float): Maximum visual magnitude
  • lambda_nm (float): Targeted wavelength (nanometers)
  • pixel_size_m (float): Sensor pixel size (meters)
  • width (int): Output image width (pixels)
  • height (int): Output image height (pixels)
  • output (str): Output image filename

process_star_catalog_py(args: StarCatalogArgs) -> None

Processes the star catalog based on the provided arguments.

Contributing

Contributions to starfinder are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPLv3 License - see the LICENSE file for details.

Commit count: 82

cargo fmt