Orbit#

class SpaceCenter.Orbit#

Describes an orbit. For example, the orbit of a vessel, obtained by calling SpaceCenter.Vessel.orbit, or a celestial body, obtained by calling SpaceCenter.CelestialBody.orbit.

static create_from_position_and_velocity(body, position, velocity, ut[, reference_frame = Types.none])#

Create the orbit that passes through a given position at a given velocity. The orbit coasts freely under the gravity of the body being orbited, so it describes where an object left to fall from that position and velocity would be at any later time.

Parameters:

body (SpaceCenter.CelestialBody) – The celestial body being orbited.
position (Tuple) – The position, as a position vector.
velocity (Tuple) – The velocity, as a vector pointing in the direction of travel, whose magnitude is the speed in meters per second.
ut (number) – The universal time, in seconds, at which the object is at position traveling at velocity.
reference_frame (SpaceCenter.ReferenceFrame or Types.none) – The reference frame that position and velocity are in. Defaults to SpaceCenter.CelestialBody.non_rotating_reference_frame of body.

Return type:

SpaceCenter.Orbit

Note

The orbit is a single conic around body. It never changes sphere of influence, so SpaceCenter.Orbit.next_orbit is nil, and no atmosphere slows it. A vessel held on rails follows its own orbit exactly, while one inside the physics bubble is simulated and drifts from it a little.

SpaceCenter.Orbit.radius, SpaceCenter.Orbit.speed, SpaceCenter.Orbit.position(), SpaceCenter.Orbit.velocity() and the like describe the orbit at ut and stay there. Use SpaceCenter.Orbit.radius_at(), SpaceCenter.Orbit.speed_at(), SpaceCenter.Orbit.position_at(), SpaceCenter.Orbit.velocity_at() and SpaceCenter.Orbit.true_anomaly_at_ut() for another time, and SpaceCenter.Orbit.reference_frame and SpaceCenter.Orbit.orbital_reference_frame to follow the orbit as time passes.

The orbit is held until SpaceCenter.Orbit.remove() is called on it or the client that created it disconnects. Remove each one created by a script that creates them repeatedly, for example once per update.

static create_from_orbital_elements(body, semi_major_axis, eccentricity, inclination, longitude_of_ascending_node, argument_of_periapsis, mean_anomaly_at_epoch, epoch)#

Create the orbit with the given orbital elements around a given body. The orbit coasts freely under the gravity of that body, so it describes where an object on it would be at any time.

Parameters:

body (SpaceCenter.CelestialBody) – The celestial body being orbited.
semi_major_axis (number) – The semi-major axis of the orbit, in meters. Positive for an ellipse and negative for a hyperbola.
eccentricity (number) – The eccentricity of the orbit. Below one for an ellipse and above one for a hyperbola.
inclination (number) – The inclination of the orbit, in radians.
longitude_of_ascending_node (number) – The longitude of the ascending node, in radians.
argument_of_periapsis (number) – The argument of periapsis, in radians.
mean_anomaly_at_epoch (number) – The mean anomaly at epoch, in radians.
epoch (number) – The universal time, in seconds, that mean_anomaly_at_epoch is measured at.

Return type:

SpaceCenter.Orbit

Note

The orbit is a single conic around body. It never changes sphere of influence, so SpaceCenter.Orbit.next_orbit is nil, and no atmosphere slows it.

The angles are measured against the reference plane and direction that SpaceCenter.Orbit.inclination, SpaceCenter.Orbit.longitude_of_ascending_node and SpaceCenter.Orbit.argument_of_periapsis report them against. SpaceCenter.Orbit.reference_plane_normal() and SpaceCenter.Orbit.reference_plane_direction() give these as vectors in a reference frame.

remove()#: Remove the orbit, releasing the memory the server holds for it.

Note

Only an orbit created by SpaceCenter.Orbit.create_from_position_and_velocity() or SpaceCenter.Orbit.create_from_orbital_elements() can be removed. Every other orbit belongs to something in the game, and the server holds one of each.

Any further use of this object throws an exception, as does use of a reference frame defined against it. An orbit belongs to the client that created it, and is removed when that client disconnects.

body: SpaceCenter.CelestialBody#

The celestial body (e.g. planet or moon) around which the object is orbiting.

Attribute:: Read-only, cannot be set
Return type:: SpaceCenter.CelestialBody

reference_frame: SpaceCenter.ReferenceFrame#

The reference frame that moves along the orbit, and is orientated in a fixed direction.

The origin is at the point the orbit has reached at the current time.
The axes do not rotate. They point in the same fixed directions as those of SpaceCenter.CelestialBody.non_rotating_reference_frame of SpaceCenter.Orbit.body.

Attribute:: Read-only, cannot be set
Return type:: SpaceCenter.ReferenceFrame

Note

For the orbit of a vessel, the origin is the point the vessel’s orbit has reached rather than the vessel’s own center of mass. The two are a few meters apart, as a vessel inside the physics bubble is simulated rather than being held on its orbit.

orbital_reference_frame: SpaceCenter.ReferenceFrame#

The reference frame that moves along the orbit, and is orientated with its prograde/normal/radial directions.

The origin is at the point the orbit has reached at the current time.
The axes rotate with the orbital prograde/normal/radial directions.
The x-axis points in the orbital anti-radial direction.
The y-axis points in the orbital prograde direction.
The z-axis points in the orbital normal direction.

Attribute:: Read-only, cannot be set
Return type:: SpaceCenter.ReferenceFrame

Note

For the orbit of a vessel, the origin is the point the vessel’s orbit has reached rather than the vessel’s own center of mass, which is what SpaceCenter.Vessel.orbital_reference_frame is centered on.

apoapsis: number#

Gets the apoapsis of the orbit, in meters, from the center of mass of the body being orbited.

Attribute:: Read-only, cannot be set
Return type:: number

Note

For the apoapsis altitude reported on the in-game map view, use SpaceCenter.Orbit.apoapsis_altitude.

periapsis: number#

The periapsis of the orbit, in meters, from the center of mass of the body being orbited.

Attribute:: Read-only, cannot be set
Return type:: number

Note

For the periapsis altitude reported on the in-game map view, use SpaceCenter.Orbit.periapsis_altitude.

apoapsis_altitude: number#

The apoapsis of the orbit, in meters, above the sea level of the body being orbited.

Attribute:: Read-only, cannot be set
Return type:: number

Note

This is equal to SpaceCenter.Orbit.apoapsis minus the equatorial radius of the body.

periapsis_altitude: number#

The periapsis of the orbit, in meters, above the sea level of the body being orbited.

Attribute:: Read-only, cannot be set
Return type:: number

Note

This is equal to SpaceCenter.Orbit.periapsis minus the equatorial radius of the body.

semi_major_axis: number#

The semi-major axis of the orbit, in meters.

Attribute:: Read-only, cannot be set
Return type:: number

semi_minor_axis: number#

The semi-minor axis of the orbit, in meters.

Attribute:: Read-only, cannot be set
Return type:: number

semi_latus_rectum: number#

The semi-latus rectum of the orbit, in meters.

Attribute:: Read-only, cannot be set
Return type:: number

radius: number#

The current radius of the orbit, in meters. This is the distance between the center of mass of the object in orbit, and the center of mass of the body around which it is orbiting.

Attribute:: Read-only, cannot be set
Return type:: number

Note

This value will change over time if the orbit is elliptical.

altitude: number#

The current altitude of the object, in meters above the sea level of the body being orbited.

Attribute:: Read-only, cannot be set
Return type:: number

Note

This is equal to SpaceCenter.Orbit.radius minus the equatorial radius of the body.

radius_at(ut)#

The orbital radius at the given time, in meters.

Parameters:: ut (number) – The universal time to measure the radius at.
Return type:: number

radius_at_true_anomaly(true_anomaly)#

The orbital radius at the point in the orbit given by the true anomaly.

Parameters:: true_anomaly (number) – The true anomaly.
Return type:: number

position([reference_frame = Types.none])#

The position the orbit has reached at the current time, in the given reference frame.

Parameters:: reference_frame (SpaceCenter.ReferenceFrame or Types.none) – The reference frame that the returned position vector is in. Defaults to SpaceCenter.CelestialBody.non_rotating_reference_frame of SpaceCenter.Orbit.body.
Returns:: The position as a vector.
Return type:: Tuple

position_at(ut[, reference_frame = Types.none])#

The position at a given time, in the specified reference frame.

Parameters:

ut (number) – The universal time to measure the position at.
reference_frame (SpaceCenter.ReferenceFrame or Types.none) – The reference frame that the returned position vector is in. Defaults to SpaceCenter.CelestialBody.non_rotating_reference_frame of SpaceCenter.Orbit.body.

Returns:

The position as a vector.

Return type:

Tuple

position_at_true_anomaly(true_anomaly[, reference_frame = Types.none])#

The position at the point in the orbit given by the true anomaly, in the specified reference frame.

Parameters:

true_anomaly (number) – The true anomaly.
reference_frame (SpaceCenter.ReferenceFrame or Types.none) – The reference frame that the returned position vector is in. Defaults to SpaceCenter.CelestialBody.non_rotating_reference_frame of SpaceCenter.Orbit.body.

Returns:

The position as a vector.

Return type:

Tuple

velocity([reference_frame = Types.none])#

The velocity the orbit has reached at the current time, in the given reference frame.

Parameters:: reference_frame (SpaceCenter.ReferenceFrame or Types.none) – The reference frame that the returned velocity vector is in. Defaults to SpaceCenter.CelestialBody.non_rotating_reference_frame of SpaceCenter.Orbit.body.
Returns:: The velocity as a vector. The vector points in the direction of travel, and its magnitude is the speed in meters per second.
Return type:: Tuple

velocity_at(ut[, reference_frame = Types.none])#

The velocity at a given time, in the specified reference frame.

Parameters:

ut (number) – The universal time to measure the velocity at.
reference_frame (SpaceCenter.ReferenceFrame or Types.none) – The reference frame that the returned velocity vector is in. Defaults to SpaceCenter.CelestialBody.non_rotating_reference_frame of SpaceCenter.Orbit.body.

Returns:

The velocity as a vector. The vector points in the direction of travel, and its magnitude is the speed in meters per second.

Return type:

Tuple

velocity_at_true_anomaly(true_anomaly[, reference_frame = Types.none])#

The velocity at the point in the orbit given by the true anomaly, in the specified reference frame.

Parameters:

true_anomaly (number) – The true anomaly.
reference_frame (SpaceCenter.ReferenceFrame or Types.none) – The reference frame that the returned velocity vector is in. Defaults to SpaceCenter.CelestialBody.non_rotating_reference_frame of SpaceCenter.Orbit.body.

Returns:

The velocity as a vector. The vector points in the direction of travel, and its magnitude is the speed in meters per second.

Return type:

Tuple

speed: number#

The current orbital speed of the object in meters per second.

Attribute:: Read-only, cannot be set
Return type:: number

Note

This value will change over time if the orbit is elliptical.

speed_at(ut)#

The orbital speed at the given time, in meters per second.

Parameters:: ut (number) – The universal time to measure the speed at.
Return type:: number

speed_at_radius(radius)#

The orbital speed at the given orbital radius, in meters per second.

Parameters:: radius (number) – The orbital radius in meters.
Return type:: number

Note

This is the vis-viva speed. A radius the orbit never reaches is accepted. On an ellipse the speed is NaN above twice the semi-major axis.

speed_at_true_anomaly(true_anomaly)#

The orbital speed at the point in the orbit given by the true anomaly, in meters per second.

Parameters:: true_anomaly (number) – The true anomaly.
Return type:: number

specific_energy: number#

The specific orbital energy, in Joules per kilogram (equivalently, meters squared per second squared).

Attribute:: Read-only, cannot be set
Return type:: number

Note

This is the sum of the orbit’s specific kinetic and potential energy, and is negative for a bound (elliptical) orbit.

specific_angular_momentum: number#

The specific relative angular momentum, in meters squared per second.

Attribute:: Read-only, cannot be set
Return type:: number

period: number#

The orbital period, in seconds.

Attribute:: Read-only, cannot be set
Return type:: number

mean_motion: number#

The mean motion, in radians per second.

Attribute:: Read-only, cannot be set
Return type:: number

time_to_apoapsis: number#

The time until the object reaches apoapsis, in seconds.

Attribute:: Read-only, cannot be set
Return type:: number

time_to_periapsis: number#

The time until the object reaches periapsis, in seconds.

Attribute:: Read-only, cannot be set
Return type:: number

eccentricity: number#

The eccentricity of the orbit.

Attribute:: Read-only, cannot be set
Return type:: number

inclination: number#

The inclination of the orbit, in radians.

Attribute:: Read-only, cannot be set
Return type:: number

longitude_of_ascending_node: number#

The longitude of the ascending node, in radians.

Attribute:: Read-only, cannot be set
Return type:: number

Note

For a near-equatorial orbit, the ascending node is ill-defined and this value may vary erratically over time.

argument_of_periapsis: number#

The argument of periapsis, in radians.

Attribute:: Read-only, cannot be set
Return type:: number

Note

For a near-circular orbit, the periapsis is ill-defined and this value may vary erratically over time.

mean_anomaly_at_epoch: number#

The mean anomaly at epoch.

Attribute:: Read-only, cannot be set
Return type:: number

epoch: number#

The universal time, in seconds, at which the mean anomaly at epoch is measured.

Attribute:: Read-only, cannot be set
Return type:: number

mean_anomaly: number#

The mean anomaly.

Attribute:: Read-only, cannot be set
Return type:: number

mean_anomaly_at_ut(ut)#

The mean anomaly at the given time.

Parameters:: ut (number) – The universal time in seconds.
Return type:: number

eccentric_anomaly: number#

The eccentric anomaly.

Attribute:: Read-only, cannot be set
Return type:: number

eccentric_anomaly_at_ut(ut)#

The eccentric anomaly at the given universal time.

Parameters:: ut (number) – The universal time, in seconds.
Return type:: number

true_anomaly: number#

The true anomaly.

Attribute:: Read-only, cannot be set
Return type:: number

true_anomaly_at_ut(ut)#

The true anomaly at the given time.

Parameters:: ut (number) – The universal time in seconds.
Return type:: number

true_anomaly_at_radius(radius)#

The true anomaly at the given orbital radius.

Parameters:: radius (number) – The orbital radius in meters.
Return type:: number

ut_at_true_anomaly(true_anomaly)#

The universal time, in seconds, corresponding to the given true anomaly.

Parameters:: true_anomaly (number) – True anomaly.
Return type:: number

true_anomaly_at_an(target)#

The true anomaly of the ascending node with the given target orbit.

Parameters:: target (SpaceCenter.Orbit) – Target orbit.
Return type:: number

true_anomaly_at_dn(target)#

The true anomaly of the descending node with the given target orbit.

Parameters:: target (SpaceCenter.Orbit) – Target orbit.
Return type:: number

orbital_speed: number#

Warning

Deprecated. Use SpaceCenter.Orbit.speed instead.

The current orbital speed in meters per second.

Attribute:: Read-only, cannot be set
Return type:: number

orbital_speed_at(ut)#

Warning

Deprecated. Use SpaceCenter.Orbit.speed_at() instead.

The orbital speed at the given time, in meters per second.

Parameters:: ut (number) – The universal time to measure the speed at.
Return type:: number

orbital_energy: number#

Warning

Deprecated. Use SpaceCenter.Orbit.specific_energy instead.

The specific orbital energy of the orbit, in Joules per kilogram.

Attribute:: Read-only, cannot be set
Return type:: number

static reference_plane_normal(reference_frame)#

The direction that is normal to the orbits reference plane, in the given reference frame. The reference plane is the plane from which the orbits inclination is measured.

Parameters:: reference_frame (SpaceCenter.ReferenceFrame) – The reference frame that the returned direction is in.
Returns:: The direction as a unit vector.
Return type:: Tuple

static reference_plane_direction(reference_frame)#

The direction from which the orbits longitude of ascending node is measured, in the given reference frame.

Parameters:: reference_frame (SpaceCenter.ReferenceFrame) – The reference frame that the returned direction is in.
Returns:: The direction as a unit vector.
Return type:: Tuple

relative_inclination(target)#

Relative inclination of this orbit and the target orbit, in radians.

Parameters:: target (SpaceCenter.Orbit) – Target orbit.
Return type:: number

time_to_soi_change: number#

The time until the object changes sphere of influence, in seconds. Returns NaN if the object is not going to change sphere of influence.

Attribute:: Read-only, cannot be set
Return type:: number

next_orbit: SpaceCenter.Orbit#

If the object is going to change sphere of influence in the future, returns the new orbit after the change. Otherwise returns nil.

Attribute:: Read-only, cannot be set
Return type:: SpaceCenter.Orbit or Types.none

next_closest_approach(target)#

The next closest approach to a target orbit.

Parameters:: target (SpaceCenter.Orbit) – Target orbit.
Return type:: SpaceCenter.ClosestApproach

closest_approaches(target, orbits)#

A list of the closest approaches to a target orbit, one for each of the next orbits orbital periods.

Parameters:

target (SpaceCenter.Orbit) – Target orbit.
orbits (number) – The number of future orbits to search.

Return type:

List