AstronomicalWidget

​

Overview

​

Class Definition

from TerraLab.widgets.sky_widget import AstronomicalWidget

​

Key Components

​

Helper Classes

​

ClickableLabel

• clicked: pyqtSignal() - Emitted when the label is clicked

• mousePressEvent(event) - Handles mouse press events and emits the clicked signal

​

AstroEngine

• DEG_TO_RAD: float - π/180.0
• RAD_TO_DEG: float - 180.0/π
• AU_IN_KM: float - 149597870.7
• EARTH_RADIUS_KM: float - 6378.14

@staticmethod
get_julian_century(dt_utc: datetime) -> Tuple[float, float]

• dt_utc (datetime) - UTC datetime object

• Tuple of (T: Julian century from J2000.0, jd: Julian Day)

@staticmethod
normalize(angle: float) -> float

• angle (float) - Angle in degrees

• float - Normalized angle (0-360°)

@staticmethod
get_moon_position_elp(T: float) -> Tuple[float, float, float]

• T (float) - Julian centuries from J2000.0

• Tuple of (longitude: geocentric ecliptic longitude in degrees, latitude: ecliptic latitude in degrees, distance: Earth-Moon distance in km)

@staticmethod
get_sun_position_vsop(T: float) -> Tuple[float, float, float]

• T (float) - Julian centuries from J2000.0

• Tuple of (true_longitude: ecliptic longitude in degrees, 0.0: ecliptic latitude (always 0 for Sun), distance: Earth-Sun distance in km)

@staticmethod
ecliptic_to_equatorial(lon: float, lat: float, T: float) -> Tuple[float, float]

• lon (float) - Ecliptic longitude in degrees
• lat (float) - Ecliptic latitude in degrees
• T (float) - Julian centuries from J2000.0

• Tuple of (ra: right ascension in degrees, dec: declination in degrees)

@staticmethod
get_topocentric_position(
    ra_geo: float,
    dec_geo: float,
    dist_km: float,
    obs_lat: float,
    obs_lon: float,
    jd: float
) -> Tuple[float, float, float]

• ra_geo (float) - Geocentric right ascension in degrees
• dec_geo (float) - Geocentric declination in degrees
• dist_km (float) - Distance from Earth center in km
• obs_lat (float) - Observer latitude in degrees
• obs_lon (float) - Observer longitude in degrees
• jd (float) - Julian Day

• Tuple of (ra_topo: topocentric RA in degrees, dec_topo: topocentric Dec in degrees, lst: local sidereal time in degrees)

@staticmethod
get_planet_heliocentric(name: str, T: float) -> Tuple[float, float, float]

• name (str) - Planet name: ‘mercury’, ‘venus’, ‘mars’, ‘jupiter’, ‘saturn’
• T (float) - Julian centuries from J2000.0

• Tuple of (L_hel: heliocentric longitude in degrees, B_hel: heliocentric latitude in degrees, R_hel: radius vector in AU)

@staticmethod
get_planet_geocentric(
    p_L: float,
    p_B: float,
    p_R: float,
    earth_L: float,
    earth_B: float,
    earth_R: float
) -> Tuple[float, float, float]

• p_L (float) - Planet heliocentric longitude in degrees
• p_B (float) - Planet heliocentric latitude in degrees
• p_R (float) - Planet radius vector in AU
• earth_L (float) - Earth heliocentric longitude in degrees
• earth_B (float) - Earth heliocentric latitude in degrees
• earth_R (float) - Earth radius vector in AU

• Tuple of (longitude: geocentric ecliptic longitude in degrees, latitude: geocentric ecliptic latitude in degrees, delta: Earth-planet distance in AU)

@staticmethod
calculate_satellite_magnitude(
    sat_range_km: float,
    phase_angle_rad: float,
    std_mag: float = -1.8
) -> float

• sat_range_km (float) - Distance to satellite in km
• phase_angle_rad (float) - Phase angle in radians (0 = full, π = new)
• std_mag (float) - Standard magnitude at 1000km, default -1.8

• float - Calculated visual magnitude

​

RusticTimeBar

• valueChanged: pyqtSignal(float) - Emitted when time value changes, passes hour value (0-24)

RusticTimeBar(parent=None)

• current_hour: float - Current hour value (0-24)
• lat: float - Observer latitude in degrees
• lon: float - Observer longitude in degrees
• day_of_year: int - Day of year (1-365)

set_time(hour: float) -> None

• hour (float) - Hour value (0-24), automatically normalized to 0-24 range

update_params(lat: float, lon: float, day_of_year: int) -> None

• lat (float) - Latitude in degrees
• lon (float) - Longitude in degrees
• day_of_year (int) - Day of year (1-365)

get_sun_alt_fast(hour: float, lat: float, lon: float, day: int) -> float

• hour (float) - Local hour (0-24)
• lat (float) - Latitude in degrees
• lon (float) - Longitude in degrees
• day (int) - Day of year

• float - Sun altitude in degrees

​

Background Workers

​

CatalogLoaderWorker

• catalog_ready: pyqtSignal(list, object, object, object, object, object, object) - Emitted when catalog is loaded. Parameters: (celestial_objects, np_ra, np_dec, np_mag, np_r, np_g, np_b)

@pyqtSlot(str)
load(json_path: str) -> None

• json_path (str) - Path to JSON catalog file

​

SkyfieldLoaderWorker

• skyfield_ready: pyqtSignal(object, object) - Emitted when Skyfield is initialized. Parameters: (ts: timescale, eph: ephemeris)

@pyqtSlot()
load() -> None

​

StarRenderWorker

• result_ready: pyqtSignal(QImage, list) - Emitted when star rendering completes. Parameters: (image: QImage, visible_stars: list of (x, y, object) tuples)
• trails_ready: pyqtSignal(QImage) - Emitted when star trail rendering completes. Parameters: (image: QImage)

@pyqtSlot(dict)
render(params: dict) -> None

• params (dict) - Rendering parameters including:
  • width (int) - Image width in pixels
  • height (int) - Image height in pixels
  • zoom_level (float) - Zoom factor
  • vertical_ratio (float) - Vertical offset ratio
  • elevation_angle (float) - Camera elevation in degrees
  • azimuth_offset (float) - Camera azimuth in degrees
  • ra, dec, mag, r, g, b (np.ndarray) - Star data arrays
  • lst (float) - Local sidereal time in degrees
  • lat_rad (float) - Observer latitude in radians
  • mag_limit (float) - Magnitude limit for visibility
  • star_scale (float) - Star size scaling factor
  • bortle (int) - Bortle scale value (1-9)
  • is_auto (bool) - Auto mode flag
  • extinction_coeff (float) - Atmospheric extinction coefficient
  • horizon_profile (object) - Horizon profile with light_domes data
  • pure_colors (bool) - Use legacy pure color rendering (no bloom)
  • spike_threshold (float) - Magnitude threshold for diffraction spikes
  • cel_objs_ref (list) - Reference to celestial objects list

@pyqtSlot(dict)
render_trails(params: dict) -> None

• params (dict) - Trail rendering parameters including all render() params plus:
  • start_hour (float) - Trail start hour
  • end_hour (float) - Trail end hour
  • day_of_year (int) - Day of year
  • longitude (float) - Observer longitude
  • is_moving (bool) - Quality mode flag

​

Usage Example

from PyQt5.QtCore import QThread
from TerraLab.widgets.sky_widget import (
    AstroEngine,
    RusticTimeBar,
    CatalogLoaderWorker,
    StarRenderWorker
)
from datetime import datetime, timezone

# Calculate Moon position
dt = datetime.now(timezone.utc)
T, jd = AstroEngine.get_julian_century(dt)
lon, lat, dist = AstroEngine.get_moon_position_elp(T)
print(f"Moon: Lon={lon:.2f}° Lat={lat:.2f}° Dist={dist:.0f}km")

# Convert to equatorial coordinates
ra, dec = AstroEngine.ecliptic_to_equatorial(lon, lat, T)
print(f"Moon RA={ra:.2f}° Dec={dec:.2f}°")

# Create time bar widget
time_bar = RusticTimeBar()
time_bar.update_params(lat=40.0, lon=-3.0, day_of_year=100)
time_bar.set_time(12.5)  # 12:30 PM
time_bar.valueChanged.connect(lambda hour: print(f"Time: {hour:.2f}h"))

# Load star catalog in background
loader_worker = CatalogLoaderWorker()
loader_thread = QThread()
loader_worker.moveToThread(loader_thread)
loader_worker.catalog_ready.connect(
    lambda objs, ra, dec, mag, r, g, b: print(f"Loaded {len(objs)} stars")
)
loader_thread.started.connect(lambda: loader_worker.load("/path/to/catalog.json"))
loader_thread.start()

​

Notes

• The AstroEngine uses high-precision algorithms suitable for professional astronomical applications
• Star rendering is performed in background threads to maintain UI responsiveness
• NumPy is required for vectorized star rendering operations
• Atmospheric effects include extinction (airmass), refraction, and local light pollution
• Diffraction spikes are rendered for bright stars (magnitude < spike_threshold)
• Binary cache files (.npy) are automatically generated to speed up subsequent catalog loads