astronomyengine (version 0.1.0)

astro_search_hour_angle: Search for when a body reaches a specified hour angle

Description

Searches for the time when the center of a body reaches a specified hour angle as seen by an observer on the Earth. The hour angle is 0 when the body reaches its highest point (culmination) above the horizon in a given day.

Usage

astro_search_hour_angle(
  body,
  time,
  latitude,
  longitude,
  height = 0,
  hour_angle = 0,
  direction = 1L
)

Value

A list with elements:

time

POSIXct time of the event.

azimuth

Azimuth angle in degrees (0° = North, 90° = East).

altitude

Altitude angle in degrees above the horizon.

Arguments

body

Integer body code (see astro_body).

time

A POSIXct date/time in UTC to start the search from.

latitude

Observer's geographic latitude in degrees.

longitude

Observer's geographic longitude in degrees.

height

Observer's height above sea level in metres. Default 0.

hour_angle

An hour angle value in the range [0, 24) indicating the number of sidereal hours after the body's most recent culmination. Default 0 (culmination).

direction

1L to search forward in time, -1L to search backward. Default 1L (forward).

Details

To find when a body culminates (reaches maximum altitude), use hour_angle = 0. To find when a body reaches its minimum altitude, use hour_angle = 12.

Examples

t <- as.POSIXct("2025-06-21", tz = "UTC")
# Find when the Sun culminates (hour_angle = 0)
astro_search_hour_angle(astro_body[["SUN"]], t,
                        latitude = -33.8688, longitude = 151.2093)