CitraScope

Documentation | Citra.space | PyPI | CitraScope-Pi

Photograph satellites from your backyard telescope.

CitraScope turns your astrophotography rig into an autonomous satellite observation station. It connects to Citra.space, picks up tasks for specific satellites, slews your telescope, captures images, and processes everything on the edge — plate solving, source extraction, photometry, and satellite matching — before delivering calibrated results back to the platform.

Use Citra.space to search for satellites, schedule observation windows, and task your telescope — CitraScope handles the rest. If you already have a mount, a camera, and software like N.I.N.A. or KStars/Ekos, CitraScope plugs right in. Install it, select your hardware adapter, and you're one click away from photographing the ISS.

Supported Hardware

Quick Start

Requires Python 3.10+. We recommend uv for installation.

# Install and run
uv tool install citrascope
citrascope

Or with pip:

pip install citrascope
citrascope

Open http://localhost:24872 in your browser to configure your hardware adapter, connect to Citra.space, and start accepting tasks.

Raspberry Pi? Check out citrascope-pi for a ready-to-flash SD card image with CitraScope pre-installed.

Optional Extras

uv tool install citrascope --with citrascope[indi]        # INDI protocol support
uv tool install citrascope --with citrascope[kstars]      # KStars/Ekos via D-Bus
uv tool install citrascope --with citrascope[usb-camera]  # USB cameras via OpenCV
uv tool install citrascope --with citrascope[rpi]         # Raspberry Pi Camera Module
uv tool install citrascope --with citrascope[all]         # INDI + KStars

pip install citrascope[indi]
pip install citrascope[kstars]
pip install citrascope[usb-camera]
pip install citrascope[rpi]
pip install citrascope[all]

CLI Options

citrascope --help
citrascope --web-port 8080    # Custom web UI port (default: 24872)

Documentation

Full documentation is available at docs.citra.space/citrascope. Documentation source is maintained in the citra-space/docs repository.

Developer Setup

uv sync --extra dev
uv run pre-commit install

Dev Container (INDI on macOS/Windows)

If you need to work with the INDI adapter on a non-Linux host, the project includes a VS Code Dev Container that provides a Linux environment with pyindi-client and its system dependencies pre-installed. Open the project in VS Code and choose Reopen in Container.

Running Tests

uv run pytest                          # Unit tests (fast, skips slow tests)
uv run pytest -m "not integration"     # Same as above, explicit
uv run pytest --override-ini="addopts=" -m "not integration"  # Include slow tests locally

Tests use pytest markers to separate fast unit tests from expensive ones:

Pre-commit Hooks

The project uses pre-commit with Ruff (linting + import sorting), Black (formatting), and Pyright (type checking).

uv run pre-commit run --all-files    # Run all checks manually

VS Code Launch Configs

The .vscode/launch.json includes pre-configured debug configurations:

• Python: citrascope — Runs the daemon with default settings
• Python: citrascope (custom port) — Runs with web interface on port 8080

Releasing

bump-my-version bump patch    # 0.1.3 → 0.1.4
bump-my-version bump minor    # 0.1.3 → 0.2.0
bump-my-version bump major    # 0.1.3 → 1.0.0
git push && git push --tags

Tagging triggers create-release.yml which creates a GitHub release, which in turn triggers pypi-publish.yml.

License

MIT