unreal.CelestialMaths

class unreal.CelestialMaths(outer: Object | None = None, name: Name | str = 'None')

Bases: BlueprintFunctionLibrary

Units Conventions
Distances:

Distances are expressed in Astronomical units - Specified by the “AU” mention in the function name

Time:

Local/UTC Time: All function parameters contains either the “Local” or “UTC” prefix in their name to specify if they expect a Local or UTC Time.

Most Celestial functions are expecting an absolute time expressed using a Julian Date. When the name “JulianDay” is used, it means the Julian Date when t=0 (midnight, beginning of the day) By definition, a Julian Date is finishing by 0.5 at Midnight.

Angles:

GMST and GAST angle are expressed in Degrees Some Celestial data involve ArcSeconds (1 Degree = 3600 Arcseconds) - Conversion functions are provided

C++ Source:

  • Plugin: CelestialVault

  • Module: CelestialVault

  • File: CelestialMaths.h

classmethod arcseconds_to_degrees(arcseconds) → double

Convert Arcseconds to Degrees

1 Degree = 3600 Arcseconds

Parameters:

arcseconds (double)

Return type:

double

classmethod arcseconds_to_radians(arcseconds) → double

Convert Arcseconds to Radians

2 PI Rad = 360 Degrees = 360 * 3600 Arcseconds

Parameters:

arcseconds (double)

Return type:

double

classmethod astronomical_units_to_meters(au) → double

Convert Astronomical Unit (UA) to meters

1 AU = 149 597 870 700 m

Parameters:

au (double)

Return type:

double

classmethod astronomical_units_to_parsec(au) → double

Convert Astronomical Unit (UA) to Parsecs

1 Parsec = 206 264.806 AU

Parameters:

au (double)

Return type:

double

classmethod b_vto_linear_color(bv) → LinearColor

Returns the RGB normalized components [0..1] from the Color Index (B-V) Value *

Parameters:

bv (float)

Return type:

LinearColor

classmethod compute_aberration(topocentric_target_location_au, earth_velocity) → Vector
Compute the Aberration of an object located far from the Earth.

In astronomy, Aberration is an apparent shift in the observed position of a celestial object caused by the finite speed of light combined with the motion of the observer. It is not an optical distortion — it’s a relativistic effect due to the fact that light takes time to reach you while you are moving.

Parameters:

  • topocentric_target_location_au (Vector)

  • earth_velocity (Vector)

Return type:

Vector

classmethod conv_celestial_body_to_string(celestial_body) → str

Celestial Body String Builder

Parameters:

celestial_body (CelestialBody)

Return type:

str

classmethod conv_declination_to_string(dec_degrees) → str

Declination String Builder

Parameters:

dec_degrees (double)

Return type:

str

classmethod conv_degrees_to_dms_string(degrees) → str

DMS String Builder

Parameters:

degrees (double)

Return type:

str

classmethod conv_degrees_to_hms_string(degrees) → str

HMS String Builder

Parameters:

degrees (double)

Return type:

str

classmethod conv_dms_to_string(sign, degrees, minutes, seconds) → str

DMS String Builder

Parameters:

  • sign (bool)

  • degrees (int32)

  • minutes (int32)

  • seconds (double)

Return type:

str

classmethod conv_hms_to_string(hours, minutes, seconds) → str

HMS String Builder

Parameters:

  • hours (int32)

  • minutes (int32)

  • seconds (double)

Return type:

str

classmethod conv_planetary_body_to_string(planetary_body) → str

Planetary Body String Builder

Parameters:

planetary_body (PlanetaryBody)

Return type:

str

classmethod conv_right_ascension_to_string(right_ascension_hours) → str

Right Ascension String Builder

Parameters:

right_ascension_hours (double)

Return type:

str

classmethod conv_stellar_body_to_string(stellar_body) → str

Stellar Body ToString String Builder

Parameters:

stellar_body (StellarBody)

Return type:

str

classmethod date_time_to_greenwich_mean_sidereal_time(utc_date_time) → double

Return the Greenwich Mean Sidereal Time (GMST) for a specific DateTime, in Degrees

By definition, the provided DateTime has to be the DateTime at the Greenwitch Meridian, so it’s a UTC DateTime

Parameters:

utc_date_time (DateTime)

Return type:

double

classmethod date_time_to_greenwich_mean_sidereal_time_unwrapped(utc_date_time) → double

Return the Greenwich Mean Sidereal Time (GMST) for a specific DateTime, in Degrees, without doing any ModPositive, so unwrapped

By definition, the provided DateTime has to be the DateTime at the Greenwitch Meridian, so it’s a UTC DateTime

Parameters:

utc_date_time (DateTime)

Return type:

double

classmethod days_to_seconds(days) → double

Converts decimal Days to Seconds

Parameters:

days (double)

Return type:

double

classmethod degrees_to_arcseconds(degrees) → double

Convert Degrees to Arcseconds

1 Degree = 3600 Arcseconds

Parameters:

degrees (double)

Return type:

double

classmethod degrees_to_dms(decimal_degrees) -> (sign=bool, degrees=int32, minutes=int32, seconds=double)

Convert decimal degrees to Degrees, Minutes, Seconds, with the appropriate Sign (True if Positive) *

Parameters:

decimal_degrees (double)

Returns:

sign (bool):

degrees (int32):

minutes (int32):

seconds (double):

Return type:

tuple

classmethod degrees_to_hms(decimal_degrees) -> (hours=int32, minutes=int32, seconds=double)

Convert Decimal degrees to Hours, Minutes, Seconds ( One Hour equals 15 degrees)

Parameters:

decimal_degrees (double)

Returns:

hours (int32):

minutes (int32):

seconds (double):

Return type:

tuple

classmethod ecefxyzau_to_geodetic_lat_lon(ecef_location_au) -> (latitude=double, longitude=double, altitude_meters=double)

Converts a ECEF Location for the WGS84 Ellipsoid into Geodetic Latitude and Longitude.

Be careful, XYZ coordinates are

  • ECEF Coordinates in the ECEF Right-Handed Frame (not the Left-handed UE ones in UE Units)

  • Expressed in Astronomical Units (AU)

Altitude is returned as Meters

Parameters:

ecef_location_au (Vector)

Returns:

latitude (double):

longitude (double):

altitude_meters (double):

Return type:

tuple

classmethod equation_of_the_equinoxes(julian_date) → double

Return the nutation in right ascension ( aka the equation of the equinoxes) in Degrees

This correction term is used when computing the Greenwich apparent sidereal from the Greenwich mean sidereal time

Parameters:

julian_date (double)

Return type:

double

classmethod geodetic_lat_lon_to_ecefxyzau(latitude, longitude, altitude) → Vector

Convert Geodetic Lat Lon to Geocentric XYZ position vector in ECEF coordinates, for the WGS84 Ellipsoid.

Be careful, XYZ coordinates are

  • ECEF Coordinates in the ECEF Right-Handed Frame (not the Left-handed UE ones in UE Units)

  • Expressed in Astronomical Units (AU)

Parameters:

  • latitude (double)

  • longitude (double)

  • altitude (double)

Return type:

Vector

classmethod get_body_celestial_coordinates_au(julian_date, vsop87_body_type, observer_latitude, observer_longitude, geo_centric_observer, ignore_relativistic_effect) -> (raj2000_hours=double, decj2000_degrees=double, ra_hours=double, dec_degrees=double, ra_geocentric_hours=double, dec_geocentric_degrees=double, distance_body_to_earth_au=double, distance_body_to_sun_au=double, distance_earth_to_sun_au=double)

Return the location of a Planetary Body relative to the Earth, expressed in Celestial Coordinates (RA, DEC, Distance) It requires the Observer location on Earth for more precise computations This function also returns the distance between bodies, as it can help for Magnitude computations

By default, the relativistic effects are considered (time taken for the light to reach the Observer body location) This function therefore returns the location of the Planetary Body as if it was seen from the Observer Body Location at this JulianDate With bIgnoreRelativisticEffect=true, one can ignore this and have the instant location. It can also save some computation cycles for close bodies like Moon. With bGeoCentricObserver=true, the observer is expected to be at the Earth center, and the Latitude/longitude are ignored.

Parameters:

  • julian_date (double)

  • vsop87_body_type (VSOP87BodyType)

  • observer_latitude (double)

  • observer_longitude (double)

  • geo_centric_observer (bool)

  • ignore_relativistic_effect (bool)

Returns:

raj2000_hours (double):

decj2000_degrees (double):

ra_hours (double):

dec_degrees (double):

ra_geocentric_hours (double):

dec_geocentric_degrees (double):

distance_body_to_earth_au (double):

distance_body_to_sun_au (double):

distance_earth_to_sun_au (double):

Return type:

tuple

classmethod get_body_celestial_coordinates_au_using_known_state(julian_date, vsop87_body_type, earth_kinematic_state, observer_latitude, observer_longitude, geo_centric_observer, ignore_relativistic_effect) -> (raj2000_hours=double, decj2000_degrees=double, ra_hours=double, dec_degrees=double, ra_geocentric_hours=double, dec_geocentric_degrees=double, distance_body_to_earth_au=double, distance_body_to_sun_au=double, distance_earth_to_sun_au=double)

Return the location of a Planetary Body relative to the Earth, expressed in Celestial Coordinates (RA, DEC, Distance) It requires the Observer location on Earth for more precise computations This function also returns the distance between bodies, as it can help for Magnitude computations

By default, the relativistic effects are considered (time taken for the light to reach the Observer body location) This function therefore returns the location of the Planetary Body as if it was seen from the Observer Body Location at this JulianDate With bIgnoreRelativisticEffect=true, one can ignore this and have the instant location. It can also save some computation cycles for close bodies like Moon. With bGeoCentricObserver=true, the observer is expected to be at the Earth center, and the Latitude/longitude are ignored.

This override can run faster if we provide it with a cache of the Earth Location and Velocity, because it won’t recompute it.

Parameters:
Returns:

raj2000_hours (double):

decj2000_degrees (double):

ra_hours (double):

dec_degrees (double):

ra_geocentric_hours (double):

dec_geocentric_degrees (double):

distance_body_to_earth_au (double):

distance_body_to_sun_au (double):

distance_earth_to_sun_au (double):

Return type:

tuple

classmethod get_earth_center_transform_ecef(latitude, longitude, altitude) → Transform

Return the Transformation to apply to a WGS84 Ellipsoid model so that its location in Lat,long,Altitude is tangent to the Origin The Transform is expressed in the ECEF Frame (Location units are meters, right-handed ECEF Frame)

Parameters:

  • latitude (double)

  • longitude (double)

  • altitude (double)

Return type:

Transform

classmethod get_earth_center_transform_ue_frame(latitude, longitude, altitude, geocentric) → Transform

Return the Transformation to apply to a WGS84 Ellipsoid model so that its location in Lat,long,Altitude is tangent to the Origin It’s used to locate the Rotating Celestial Vault for a specific UE Origin The Transform is expressed in the UE Frame (Location units are UE Units, left-handed Unreal Frame)

With Geocentric=true, the observer is expected to be at the Earth center, Latitude/longitude are ignored and this function returns an ECEF-Oriented transform.

Parameters:

  • latitude (double)

  • longitude (double)

  • altitude (double)

  • geocentric (bool)

Return type:

Transform

classmethod get_earth_rotation_angle(julian_date) → double

Retrurn the Earth Rotation Angle (In Degrees) as measured by GMST (Greenwich Mean Sidereal Time)

It refers to the angle of Earth’s rotation relative to the fixed stars, specifically the hour angle of the mean vernal equinox as observed from the Greenwich meridian. It represents how far Earth has rotated since the mean equinox crossed the Greenwich meridian; It is essentially a way to measure Earth’s rotation in angular terms based on a celestial reference point.

Parameters:

julian_date (double)

Return type:

double

classmethod get_illumination_percentage(normalized_age) → double

return the illumination factor (0..1) of a Body, considering his normalized age and the crescent effects

Parameters:

normalized_age (double)

Return type:

double

classmethod get_leap_seconds(julian_date) → double

Returns the Leap Seconds for a specific Julian Date

A leap second is a one-second adjustment that is occasionally applied to Coordinated Universal Time (UTC), to accommodate the difference between precise time (International Atomic Time (TAI), as measured by atomic clocks) and imprecise observed solar time (UT1), which varies due to irregularities and long-term slowdown in the Earth’s rotation.

Parameters:

julian_date (double)

Return type:

double

classmethod get_moon_normalized_age_simple(julian_date) → double

Returns the Moon Phase for a specific Date

This is an approximate computation using a number of lunar cycles with a synodic month equals to 29.53059 days Not very precise over more than 1 centuries before of after 2025

Parameters:

julian_date (double)

Return type:

double

classmethod get_nutation_matrix(julian_date) → Matrix
Return the Nutation Matrix

The Nutation matrix accounts for Nutation, the small, periodic wobble of Earth’s rotation axis – when transforming between “mean” and “true” celestial coordinate frames.

Parameters:

julian_date (double)

Return type:

Matrix

classmethod get_observer_geocentric_location_au(latitude, longitude, altitude, julian_date) → Vector

Return the Geocentric position of an observer located at the Earth surface, considering the rotation at this specific JulianDate, using the Greenwich Apparent Didereal Time.

The position is expressed relatively to the earth center, but on the solar system reference frame. Coordinates are Expressed in Astronomical Units (AU)

Parameters:

  • latitude (double)

  • longitude (double)

  • altitude (double)

  • julian_date (double)

Return type:

Vector

classmethod get_planetary_body_kinematic_state_au(julian_date, vsop87_body_type) → PlanetaryBodyKinematicState

Returns the Body location and velocity in the VSOP87 and FK5J2000 frames

This is a convenience function to keep a cache of a Body location (eg. Earth) and accelerate the computations when interested in several other bodies.

Parameters:
Return type:

PlanetaryBodyKinematicState

classmethod get_planetary_body_magnitude(vsop87_body_type, distance_to_sun_au, distance_to_earth_au, distance_earth_to_sun_au) -> (double, phase_angle=double)

Return the Magnitude of a Planetary Body as seen from the Earth *

Parameters:

  • vsop87_body_type (VSOP87BodyType)

  • distance_to_sun_au (double)

  • distance_to_earth_au (double)

  • distance_earth_to_sun_au (double)

Returns:

phase_angle (double):

Return type:

double

classmethod get_precession_matrix(julian_date) → Matrix
Return the Precession Matrix

The Precession matrix transforms coordinates from one equatorial reference epoch to another by accounting for Earth’s long-term, secular drift of its rotation axis (precession of the equinox). It’s used to compute RA, DEC between the J2000 Epoch and a specific date. (Earth’s rotation axis slowly traces a ~26,000-year cone because of gravitational torques from the Moon and Sun.)

Parameters:

julian_date (double)

Return type:

Matrix

classmethod get_precise_vector_string(vector, minimum_fractional_digits=10) → str

Returns a String displaying a vector with a large number of digits

Parameters:

  • vector (Vector)

  • minimum_fractional_digits (int32)

Return type:

str

classmethod get_solar_system_body_location_velocity_vsop87_au(vsop87_body_type, julian_date) -> (location_au=Vector, velocity=Vector)

Returns the location of a specific Solar System body, in the VSOP Coordinate system

The VSOP frame is a “heliocentric ecliptic frame of the J2000 equinox”

Origin = Sun (Heliocentric) Coordinates Axes = Mean ecliptic & equinox of J2000.0

XY-plane: the mean ecliptic plane at epoch J2000.0 X-axis: pointing toward mean equinox at J2000.0 Z-axis: perpendicular to the ecliptic

The returned location is expressed in Astronomical Units (AU) The relativistic effects are ignored (See GetBodyLocation_FK5J2000_AU_Relativistic )

Parameters:
Returns:

location_au (Vector):

velocity (Vector):

Return type:

tuple

classmethod get_solar_system_body_location_vsop87_relativistic(reference_body_location_heliocentric_au, vsop87_body_type, julian_date) → Vector

Returns the location of a specific Solar System Body, in the VSOP Coordinate system

The VSOP frame is a “heliocentric ecliptic frame of the J2000 equinox”

Origin = Sun (Heliocentric) Coordinates Axes = Mean ecliptic & equinox of J2000.0

XY-plane: the mean ecliptic plane at epoch J2000.0 X-axis: pointing toward mean equinox at J2000.0 Z-axis: perpendicular to the ecliptic

The returned location is expressed in Astronomical Units (AU)

The returned Location and the Observer Body location are expressed in Astronomical Units (AU) The relativistic effects are considered (time taken for the light to reach the Observer body location) This function therefore returns the location of the Planetary Body as if it was seen from the Observer Body Location at this JulianDate

Parameters:

  • reference_body_location_heliocentric_au (Vector)

  • vsop87_body_type (VSOP87BodyType)

  • julian_date (double)

Return type:

Vector

classmethod get_speed_of_light() → double

Returns the Speed of Light 299 792 458 (m/s) *

Return type:

double

classmethod get_sun_information(julian_date, observer_latitude, observer_longitude, geo_centric) → StellarBody

Compute all Sun Properties for a specific JulianDate

Parameters:

  • julian_date (double)

  • observer_latitude (double)

  • observer_longitude (double)

  • geo_centric (bool)

Return type:

StellarBody

classmethod get_sun_information_using_known_state(julian_date, earth_kinematic_state, observer_latitude, observer_longitude, geo_centric) → StellarBody

Compute all Sun Properties for a specific JulianDate

This override can run faster if we provide it with a cache of the Earth Location and Velocity, because it won’t recompute it. if bGeocentric is true, Latitude and Longitude are ignored.

Parameters:
Return type:

StellarBody

classmethod international_atomic_time_to_terrestrial_time(tai) → double

Returns the Terrestrial Time in SI seconds

TT = TAI + 32.184 seconds;

Parameters:

tai (double)

Return type:

double

classmethod julian_date_to_greenwich_apparent_sidereal_time(julian_date) → double

Return the Greenwich Apparent Sidereal Time (GAST) for a specific UTC DateTime, in Degrees.

The Greenwich apparent sidereal time is obtained by adding a correction to the Greenwich mean sidereal time. The correction term is called the nutation in right ascension or the equation of the equinoxes.

Parameters:

julian_date (double)

Return type:

double

classmethod julian_date_to_greenwich_mean_sidereal_time(julian_date) → double

Return the Greenwich Mean Sidereal Time (GMST) for a specific Julian Date, In Degrees

Parameters:

julian_date (double)

Return type:

double

classmethod julian_date_to_international_atomic_time(julian_date) → double

Returns the International Atomic Time in SI seconds

TAI = GetLeapSeconds(JulianDate) + DaysToSeconds(JulianDate);

Parameters:

julian_date (double)

Return type:

double

classmethod julian_date_to_julian_centuries(julian_date) → double

Returns the Julien Centuries

Julian Centuries = (JulianDate - 2451545.0) / 36525.0

Parameters:

julian_date (double)

Return type:

double

classmethod julian_date_to_utc_date_time(julian_date) → DateTime

Return the UTC Time for a specific Julian Date *

Parameters:

julian_date (double)

Return type:

DateTime

classmethod julian_date_to_vsop87_time(julian_date) → double

Converts a Julian Date to a proper VSOP87Time, suitable for the VSOP87 computations

In the VSOP87 equations, Time is not Julian centuries! > Given a Julian date JD expressed in dynamical time T = (TAI+32.184s), the VSOP equations exprect a Time = (T-2451545)/365250

> The denominator is 365250, not 36525. > That’s because VSOP87 expresses time in units of 10,000 Julian years (1 Julian millennium = 100 centuries = 36,525 × 100 days).

Parameters:

julian_date (double)

Return type:

double

classmethod local_sideral_time(longitude_degrees, greenwich_mean_sideral_time) → double

Return the Sidereal Time for a specific Longitude and GMST *

Parameters:

  • longitude_degrees (double)

  • greenwich_mean_sideral_time (double)

Return type:

double

classmethod local_time_to_utc_time(local_time, time_zone_offset, is_dst) → DateTime

Return the UTC for a specific Local Time, using the TimeZone and Daylight Saving Information *

Parameters:

  • local_time (DateTime)

  • time_zone_offset (double)

  • is_dst (bool)

Return type:

DateTime

classmethod meters_to_astronomical_units(meters) → double

Convert meters to Astronomical Unit (UA)

1 AU = 149 597 870 700 m

Parameters:

meters (double)

Return type:

double

classmethod mod_positive(value, modulo) → double

Special Mod function that makes sure to always return positive values

Parameters:

  • value (double)

  • modulo (double)

Return type:

double

classmethod nutation2000b_truncated(julian_date) -> (delta_psi_degrees=double, delta_epsilon_degrees=double)

Approximation of the IAU2000A/B nutation model used in the Equation Of The Equinoxes, accurate enough for VSOP87 computations

Parameters:

julian_date (double)

Returns:

delta_psi_degrees (double):

delta_epsilon_degrees (double):

Return type:

tuple

classmethod parsecs_to_astronomical_units(parsecs) → double

Convert Parsecs to Astronomical Unit (UA)

1 Parsec = 206 264.806 AU

Parameters:

parsecs (double)

Return type:

double

classmethod radec_to_xyz_rh(ra_degrees, dec_degrees, radius) → Vector

Convert Polar Coordinates to Cartesian Coordinates, using a Righ-Handed Frame

Parameters:

  • ra_degrees (double)

  • dec_degrees (double)

  • radius (double)

Return type:

Vector

classmethod seconds_to_day(seconds) → double

Converts Seconds to Decimal Days

Parameters:

seconds (double)

Return type:

double

classmethod utc_date_time_to_julian_date(utc_date_time) → double

Return the Julian Date for a specific UTC Time *

Parameters:

utc_date_time (DateTime)

Return type:

double

classmethod utc_time_to_local_time(utc_time, time_zone_offset, is_dst) → DateTime

Return the Local Time for a specific UTC Time, using the TimeZone and Daylight Saving Information *

Parameters:

  • utc_time (DateTime)

  • time_zone_offset (double)

  • is_dst (bool)

Return type:

DateTime

classmethod wgs84_geocentric_radius(latitude) → double

Return the WGS84 Radius (in Meters) for a specific Latitude

Parameters:

latitude (double)

Return type:

double

classmethod xyz_to_radec_rh(xyz) -> (ra_degrees=double, dec_degrees=double, radius=double)

Convert Cartesian Coordinates to Polar Coordinates, using a Righ-Handed Frame

Parameters:

xyz (Vector)

Returns:

ra_degrees (double):

dec_degrees (double):

radius (double):

Return type:

tuple