.. default-domain:: lua
.. highlight:: lua
.. currentmodule:: SpaceCenter

Closest Approach
================


.. class:: ClosestApproach

   A close approach between an orbit and a target orbit. Obtained by calling
   :meth:`SpaceCenter.Orbit.next_closest_approach` or :meth:`SpaceCenter.Orbit.closest_approaches`.

   .. note::

      The object names the approach rather than describing it once: each member
      estimates the time of closest approach from where the two orbits are now, and
      describes the state at that time. The estimate moves as the game runs, so
      members read at different moments can differ a little; members read in one
      physics tick all describe the same estimate. Relative quantities are the target
      relative to the orbiting object (target minus self).

      The search runs forward over one orbital period from the current time. Once an
      approach has passed and the two orbits are moving apart, the closest point in
      that period is the current one, so the object reports the approach as now, at
      the present separation, until the orbits bring another one within range.

   .. attribute:: ut: number

      The universal time of the closest approach, in seconds.

      :Attribute: Read-only, cannot be set
      :rtype: number

   .. attribute:: time_to: number

      The time until the closest approach, in seconds.

      :Attribute: Read-only, cannot be set
      :rtype: number

   .. attribute:: distance: number

      The distance between the objects at the closest approach, in meters.

      :Attribute: Read-only, cannot be set
      :rtype: number

   .. attribute:: relative_speed: number

      The relative speed of the objects at the closest approach, in meters per
      second. This is the magnitude of :meth:`SpaceCenter.ClosestApproach.relative_velocity`, and does
      not depend on the choice of reference frame.

      :Attribute: Read-only, cannot be set
      :rtype: number

   .. attribute:: vessel: SpaceCenter.Vessel

      The vessel doing the approaching, or ``nil`` if it is not a vessel.

      :Attribute: Read-only, cannot be set
      :rtype: :class:`SpaceCenter.Vessel` or ``Types.none``

   .. attribute:: body: SpaceCenter.CelestialBody

      The celestial body doing the approaching, or ``nil`` if it is not a
      celestial body.

      :Attribute: Read-only, cannot be set
      :rtype: :class:`SpaceCenter.CelestialBody` or ``Types.none``

   .. attribute:: target_vessel: SpaceCenter.Vessel

      The vessel being approached, or ``nil`` if the target is not a vessel.

      :Attribute: Read-only, cannot be set
      :rtype: :class:`SpaceCenter.Vessel` or ``Types.none``

   .. attribute:: target_body: SpaceCenter.CelestialBody

      The celestial body being approached, or ``nil`` if the target is not a
      celestial body.

      :Attribute: Read-only, cannot be set
      :rtype: :class:`SpaceCenter.CelestialBody` or ``Types.none``

   .. method:: position([reference_frame = Types.none])

      The position of the orbiting object at the closest approach.

      :param reference_frame: The reference frame that the returned position vector is in. Defaults to the orbital reference frame of the object the orbit belongs to.
      :type reference_frame: :class:`SpaceCenter.ReferenceFrame` or ``Types.none``
      :returns: The position as a vector.
      :rtype: Tuple

   .. method:: target_position([reference_frame = Types.none])

      The position of the target object at the closest approach.

      :param reference_frame: The reference frame that the returned position vector is in. Defaults to the orbital reference frame of the object the orbit belongs to.
      :type reference_frame: :class:`SpaceCenter.ReferenceFrame` or ``Types.none``
      :returns: The position as a vector.
      :rtype: Tuple

   .. method:: velocity([reference_frame = Types.none])

      The velocity of the orbiting object at the closest approach.

      :param reference_frame: The reference frame that the returned velocity vector is in. Defaults to the orbital reference frame of the object the orbit belongs to.
      :type reference_frame: :class:`SpaceCenter.ReferenceFrame` or ``Types.none``
      :returns: The velocity as a vector.
      :rtype: Tuple

   .. method:: target_velocity([reference_frame = Types.none])

      The velocity of the target object at the closest approach.

      :param reference_frame: The reference frame that the returned velocity vector is in. Defaults to the orbital reference frame of the object the orbit belongs to.
      :type reference_frame: :class:`SpaceCenter.ReferenceFrame` or ``Types.none``
      :returns: The velocity as a vector.
      :rtype: Tuple

   .. method:: relative_position([reference_frame = Types.none])

      The position of the target relative to the orbiting object at the closest
      approach.

      :param reference_frame: The reference frame whose axes the returned vector is expressed in. Defaults to the orbital reference frame of the object the orbit belongs to.
      :type reference_frame: :class:`SpaceCenter.ReferenceFrame` or ``Types.none``
      :returns: The relative position as a vector.
      :rtype: Tuple

   .. method:: relative_velocity([reference_frame = Types.none])

      The velocity of the target relative to the orbiting object at the closest
      approach.

      :param reference_frame: The reference frame whose axes the returned vector is expressed in. Defaults to the orbital reference frame of the object the orbit belongs to.
      :type reference_frame: :class:`SpaceCenter.ReferenceFrame` or ``Types.none``
      :returns: The relative velocity as a vector.
      :rtype: Tuple