PANOPTES Utilities

PANOPTES Logo

Utility functions for use within the Project PANOPTES ecosystem and for general astronomical processing.

This library defines a number of modules that contain useful functions as well as a few services.

Install

To install type:

pip install panoptes-utils

Full options for install:

pip install "panoptes-utils[config,docs,images,telemetry]"

See the full documentation at: https://panoptes.github.io/panoptes-utils/

Dependencies

There are a few system dependencies depending on what functionality you will be using.

In particular, the plate solving requires astrometry.net and the appropriate index files.

Use the following on a debian-based system (e.g. Ubuntu) to easily install all dependencies:

apt-get update && apt-get install --no-install-recommends --yes \
  libffi-dev libssl-dev \
  astrometry.net astrometry-data-tycho2 \
  dcraw exiftool libcfitsio-dev libcfitsio-bin \
  libfreetype6-dev libpng-dev libjpeg-dev libffi-dev

Command Line

The panoptes-utils command provides subcommands for image processing, configuration management, and telemetry. Use panoptes-utils --help or panoptes-utils <subcommand> --help for full option details.

`image` — Image processing

Convert and plate-solve astronomical images:

# Watch a directory and auto-process new files
panoptes-utils image watch <path>

# Convert a CR2 to FITS
panoptes-utils image cr2 to-fits <file.cr2>

# Plate-solve a FITS file
panoptes-utils image fits solve <file.fits>

`config` — Configuration store

Read and write configuration values from the YAML config file. No server process required.

# Initialise the config file from the built-in template
panoptes-utils config init

# Read a value (returns entire config if no key given)
panoptes-utils config get location.elevation

# Update a value
panoptes-utils config set name "My Observatory"

Variable	Description	Default
`PANOPTES_CONFIG_FILE`	Path to the YAML config file	`~/.panoptes/config.yaml`

Deprecated: panoptes-utils config run / config stop (HTTP server) are deprecated. Use $PANOPTES_CONFIG_FILE and the store directly instead.

`telemetry` — Telemetry server

Requires the telemetry extra (pip install "panoptes-utils[telemetry]").

Start a telemetry server for recording and querying observatory events:

# Start the server
panoptes-utils telemetry run

# Display current readings (add --follow for live updates)
panoptes-utils telemetry current --follow

# Stop the server
panoptes-utils telemetry stop

Variable	Description	Default
`PANOPTES_TELEMETRY_HOST`	Telemetry server host address	`localhost`
`PANOPTES_TELEMETRY_PORT`	Telemetry server port	`6562`
`PANOPTES_TELEMETRY_SITE_DIR`	Directory for rotated NDJSON site logs	`telemetry`

The public telemetry model is intentionally simple: there is one telemetry feed, and start_run() optionally activates a run context. When a run is active, subsequent events are automatically associated with that run and stamped with meta["run_id"].

Example local workflow with Python:

from panoptes.utils.telemetry import TelemetryClient

client = TelemetryClient()

print(client.ready())

# Before start_run(), events are recorded without any active run context.
client.post_event("weather", {"sky": "clear", "wind_mps": 2.1}, meta={"source": "demo"})

# start_run() activates the run context for subsequent events.
client.start_run(run_id="001")
event = client.post_event("status", {"state": "running"})
print(event.meta["run_id"])
client.stop_run()

# Or let the server create the next run automatically.
next_run = client.start_run()
print(next_run["run_id"], next_run["run_dir"])

print(client.current())   # dict[str, TelemetryEvent]

client.stop_run()
client.shutdown()

For server internals and HTTP API examples, see the Telemetry Server documentation.

Development with UV

This project uses UV for fast Python package and environment management with modern PEP 735 dependency groups.

Prerequisites:

Python 3.12+
UV: https://docs.astral.sh/uv/ (install via curl -LsSf https://astral.sh/uv/install.sh | sh or pipx install uv).

Basic workflow:

Create and sync a dev environment with all dependencies:

# Install all optional extras and dev dependencies (recommended for development)
uv sync --all-extras --group dev

# Or install only base dependencies
uv sync

# Activate the virtual environment
source .venv/bin/activate
# or run commands without activating using `uv run ...`

Install specific dependency groups as needed:

# Install testing dependencies
uv sync --group testing

# Install linting tools
uv sync --group lint

# Install all dev dependencies (includes testing + lint)
uv sync --group dev

Install specific optional extras as needed (choose any):

# Examples: config, images, docs, examples
uv sync --extra config --extra images --extra docs

# Or install all extras
uv sync --all-extras

Run tests:

# All tests with coverage, using pytest options from pyproject.toml
uv run pytest

# Single test file
uv run pytest tests/test_utils.py

Lint / style checks:

# Lint with Ruff
uv run ruff check .

# Auto-fix linting issues
uv run ruff check --fix .

# Format code with Ruff
uv run ruff format .

# Check formatting without making changes
uv run ruff format --check .

Build the package (wheel and sdist):
```
uv build
```
Run the CLI locally (Typer app):
```
uv run panoptes-utils --help
```
Versioning: Version is derived from git tags via setuptools-scm. To produce a new version, create and push a tag (e.g., v0.1.0).

[Testing]

To test the software, prefer running via UV so the right environment and options are used:

uv run pytest

By default all tests will be run. If you want to run one specific test, give the specific filename as an argument to pytest:

uv run pytest tests/test_mount.py

Metadata

Release files for panoptes-utils 0.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for panoptes-utils 0.5.3
File	Size	Uploaded
panoptes_utils-0.5.3.tar.gz	1.8 MB	Jul 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for panoptes-utils 0.5.3
File	Interpreter	ABI	Platform	Reset
panoptes_utils-0.5.3-py3-none-any.whl 105.7 kB Jul 21, 2026	Python 3	none	any	Details

Total release size: 1.9 MB

Release files / panoptes_utils-0.5.3.tar.gz

Download URL	panoptes_utils-0.5.3.tar.gz
Size	1.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`ffbeb6d9c37c249b173c17425f2eeaacd8bde3871f001af955f3fb6a1cc3602d`
BLAKE2b-256 checksum How to use checksums	`5808fef522fe131717c671b698bb826adf0a2d8e2073fe4636f92d6b42fef3f4`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`

Release files / panoptes_utils-0.5.3-py3-none-any.whl

Download URL	panoptes_utils-0.5.3-py3-none-any.whl
Size	105.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4dd05fee103509813fdbc8308496f030f18cffaf272b3f5587f40de08d41162f`
BLAKE2b-256 checksum How to use checksums	`12220912b1e26eaeef142fa8ec2b77b3762b06f748aaea91bc578fa82f3861f2`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`