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 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 conv_declination_to_string(dec_degrees) → str

Declination String Builder

Parameters:

dec_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_info_to_string(planetary_body_info) → str

PlanetaryBodyInfo String Builder

Parameters:

planetary_body_info (PlanetaryBodyInfo)

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_star_info_to_string(star_info) → str

StarInfo String Builder

Parameters:

star_info (StarInfo)

Return type:

str

classmethod conv_sun_info_to_string(sun_info) → str

SunInfo ToString String Builder

Parameters:

sun_info (SunInfo)

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 days_to_seconds(days) → double

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 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, planetary_body, observer_latitude, observer_longitude) -> (ra_hours=double, dec_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 to the Sun, as it can help for Magnitude computations

Parameters:

  • julian_date (double)

  • planetary_body (PlanetaryBodyInputData)

  • observer_latitude (double)

  • observer_longitude (double)

Returns:

ra_hours (double):

dec_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_location_fk5j2000_au(planetary_body, julian_date) → Vector

Returns the location of a specific Planetary body, in the FK5 J2000 Coordinate System

The FK5 is an equatorial coordinate system (coordinate system linked to the Earth) based on its J2000 position. As any equatorial frame, the FK5-based follows the long-term Earth motion (precession).

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

Parameters:
Return type:

Vector

classmethod get_body_location_fk5j2000_au_relativistic(observer_body_fk5j2000_location_au, planetary_body, julian_date) → Vector

Returns the location of a specific Planetary body, in the FK5 J2000 Coordinate System

The FK5 is an equatorial coordinate system (coordinate system linked to the Earth) based on its J2000 position. As any equatorial frame, the FK5-based follows the long-term Earth motion (precession).

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

Parameters:
Return type:

Vector

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_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_planet_center_transform(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 It’s used to locate the Rotating Celestial Vault for a specific UE Origin

Parameters:

  • latitude (double)

  • longitude (double)

  • altitude (double)

Return type:

Transform

classmethod get_planetary_body_magnitude(planetary_body, 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:

  • planetary_body (PlanetaryBodyInputData)

  • 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_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_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) → SunInfo

Compute all Sun Properties for a speficic JulianDate

Parameters:

  • julian_date (double)

  • observer_latitude (double)

  • observer_longitude (double)

Return type:

SunInfo

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 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=double, delta_epsilon=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 (double):

delta_epsilon (double):

Return type:

tuple

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

Seconds to Day

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 UTC for a specific Time, using the TimeZone and Daylight Saving Information *

Parameters:

  • utc_time (DateTime)

  • time_zone_offset (double)

  • is_dst (bool)

Return type:

DateTime

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