solver

Documentation

Overview

Package solver provides a Go client for the Astrometry.net plate-solving service via Docker containers (dm90/astrometry or ghcr.io/diarmuidkelly/astrometry-dockerised-solver).

Package solver provides a Go client for the Astrometry.net plate-solving service via Docker containers (diarmuidk/astrometry-dockerised-solver or dm90/astrometry).

Plate-solving identifies the celestial coordinates and orientation of astronomical images by matching star patterns against index files. This package wraps the astrometry.net solver in a convenient Go API.

Basic Usage

config := &solver.ClientConfig{
	IndexPath: "/path/to/index/files",
}

client, err := solver.NewClient(config)
if err != nil {
	log.Fatal(err)
}

opts := solver.DefaultSolveOptions()
opts.ScaleLow = 300
opts.ScaleHigh = 500
opts.ScaleUnits = "arcminwidth"

result, err := client.Solve(context.Background(), "image.jpg", opts)
if err != nil {
	log.Fatal(err)
}

if result.Solved {
	fmt.Printf("RA: %.6f, Dec: %.6f\n", result.RA, result.Dec)
}

Docker Execution Modes

The client supports two Docker execution modes:

1. Docker Run Mode (default): Spawns a new container for each solve operation. Simpler but slower for multiple solves.

2. Docker Exec Mode: Uses an existing long-running container via docker exec. Faster for multiple solves, requires a running container.

config := &solver.ClientConfig{
	IndexPath:     "/path/to/indexes",
	UseDockerExec: true,
	ContainerName: "astrometry-solver",
}

Index

• Constants
• Variables
• type Client
  • func NewClient(config *ClientConfig) (*Client, error)
  • func (c *Client) Solve(ctx context.Context, imagePath string, opts *SolveOptions) (*Result, error)
  • func (c *Client) SolveBytes(ctx context.Context, data []byte, format string, opts *SolveOptions) (*Result, error)
• type ClientConfig
  • func DefaultClientConfig() *ClientConfig
• type Result
  • func ParseWCSFile(wcsPath string) (*Result, error)
• type SolveOptions
  • func DefaultSolveOptions() *SolveOptions

Constants

const (
	// DefaultDockerImage is the default Docker image used for plate-solving
	// Compatible images: "dm90/astrometry", "diarmuidk/astrometry-dockerised-solver", "ghcr.io/diarmuidkelly/astrometry-dockerised-solver"
	DefaultDockerImage = "diarmuidk/astrometry-dockerised-solver"
)

Variables

var (
	// ErrNoSolution indicates that astrometry.net could not solve the image.
	ErrNoSolution = errors.New("no solution found")

	// ErrTimeout indicates that the solve operation exceeded the timeout.
	ErrTimeout = errors.New("solve operation timed out")

	// ErrDockerFailed indicates that the Docker command failed.
	ErrDockerFailed = errors.New("docker command failed")

	// ErrInvalidInput indicates invalid input parameters.
	ErrInvalidInput = errors.New("invalid input parameters")

	// ErrWCSParseFailed indicates failure to parse WCS output.
	ErrWCSParseFailed = errors.New("failed to parse WCS output")
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the main interface for astrometry.net plate solving.

func NewClient

func NewClient(config *ClientConfig) (*Client, error)

NewClient creates a new astrometry Client with the given configuration.

func (*Client) Solve

func (c *Client) Solve(ctx context.Context, imagePath string, opts *SolveOptions) (*Result, error)

Solve performs plate-solving on the given image file.

func (*Client) SolveBytes

func (c *Client) SolveBytes(ctx context.Context, data []byte, format string, opts *SolveOptions) (*Result, error)

SolveBytes performs plate-solving on image data provided as bytes. The data is written to a temporary file, solved, and cleaned up.

type ClientConfig

type ClientConfig struct {
	// DockerImage specifies the Docker image to use for solving.
	// Compatible with dm90/astrometry, diarmuidk/astrometry-dockerised-solver, or ghcr.io/diarmuidkelly/astrometry-dockerised-solver
	// Default: "diarmuidk/astrometry-dockerised-solver"
	DockerImage string

	// IndexPath is the host path to the astrometry index files.
	// This directory will be mounted into the Docker container.
	// Required.
	IndexPath string

	// TempDir is the working directory for images and output files.
	// If empty, the system temporary directory will be used.
	TempDir string

	// Timeout is the maximum duration for the solve operation.
	// Default: 5 minutes
	Timeout time.Duration

	// UseDockerExec enables using docker exec on an existing container
	// instead of spawning new containers with docker run.
	// When true, ContainerName must be specified.
	// Default: false
	UseDockerExec bool

	// ContainerName is the name of the running container to exec commands in.
	// Only used when UseDockerExec is true.
	ContainerName string

	// LocalExec runs the solve-field binary directly on PATH instead of via
	// Docker. Intended for running inside an image built FROM the solver, where
	// the astrometry binaries and index configuration are already present.
	// Takes precedence over UseDockerExec when both are set.
	// Default: false
	LocalExec bool
}

ClientConfig holds configuration for the Astrometry client.

func DefaultClientConfig

func DefaultClientConfig() *ClientConfig

DefaultClientConfig returns a ClientConfig with sensible defaults.

type Result

type Result struct {
	// Solved indicates whether the image was successfully plate-solved.
	Solved bool

	// RA is the right ascension of the image center in degrees (J2000).
	RA float64

	// Dec is the declination of the image center in degrees (J2000).
	Dec float64

	// PixelScale is the image scale in arcseconds per pixel.
	PixelScale float64

	// Rotation is the field rotation in degrees.
	Rotation float64

	// FieldWidth is the field of view width in degrees.
	FieldWidth float64

	// FieldHeight is the field of view height in degrees.
	FieldHeight float64

	// WCSHeader contains the raw parsed WCS header fields.
	WCSHeader map[string]string

	// OutputFiles contains paths to generated output files (.wcs, .corr, etc.).
	OutputFiles []string

	// AnnotatedImage contains the bytes of the annotated overlay (<base>-ngc.png),
	// in the same orientation as the input image. Populated only when the Annotate
	// option is set and the solve succeeded. Read before temp-file cleanup so it
	// survives even when KeepTempFiles is false.
	AnnotatedImage []byte

	// AnnotatedFormat is the image format of AnnotatedImage (e.g. "png").
	// Empty when no annotated image was produced.
	AnnotatedFormat string

	// SolveTime is the duration of the solve operation.
	SolveTime float64 // seconds

	// RawOutput contains the raw stdout/stderr from solve-field.
	// Only populated when Verbose option is enabled.
	RawOutput string
}

Result holds the plate-solving results.

func ParseWCSFile

func ParseWCSFile(wcsPath string) (*Result, error)

ParseWCSFile parses a FITS WCS header file and returns a Result. The WCS file uses FITS header format with fixed 80-character records.

type SolveOptions

type SolveOptions struct {
	// ScaleLow is the lower bound of the image scale in the specified units.
	ScaleLow float64

	// ScaleHigh is the upper bound of the image scale in the specified units.
	ScaleHigh float64

	// ScaleUnits specifies the units for ScaleLow and ScaleHigh.
	// Valid values: "degwidth", "arcminwidth", "arcsecperpix"
	// Default: "arcminwidth"
	ScaleUnits string

	// DownsampleFactor reduces the image resolution by this factor.
	// Higher values speed up solving but reduce accuracy.
	// Default: 2
	DownsampleFactor int

	// DepthLow is the minimum number of quads to try.
	// DepthHigh is the maximum number of quads to try.
	// Default: [10, 20]
	DepthLow  int
	DepthHigh int

	// NoPlots disables generation of plot files (RedGreen, etc.).
	// Default: true (no plots)
	NoPlots bool

	// RA, Dec, and Radius provide a search hint for the solver.
	// RA and Dec are in degrees (J2000).
	// Radius is the search radius in degrees.
	// If RA is 0, no search hint is used.
	RA     float64
	Dec    float64
	Radius float64

	// OverwriteExisting allows overwriting existing output files.
	// Default: false
	OverwriteExisting bool

	// Verbose enables verbose output from solve-field.
	// Default: false
	Verbose bool

	// KeepTempFiles preserves temporary files for debugging.
	// When true, temp directory and all solve output files are not deleted.
	// Default: false
	KeepTempFiles bool

	// Annotate requests an annotated overlay of the solved field. When true,
	// solve-field's plotting is enabled (the --no-plots flag is omitted) and,
	// on a successful solve, the resulting <base>-ngc.png is read back into
	// Result.AnnotatedImage. Overrides NoPlots.
	// Default: false
	Annotate bool
}

SolveOptions holds parameters for a plate-solving operation.

func DefaultSolveOptions

func DefaultSolveOptions() *SolveOptions

DefaultSolveOptions returns SolveOptions with sensible defaults.