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.

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:

   • Visit https://archive.eso.org/ASTROM/TYC-2/data/
   • Download catalog.dat and place it in data/tycho2/

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.