.. default-domain:: java
.. highlight:: java
.. package:: krpc.client.services.SpaceCenter

AutoPilot
=========


.. type:: public class AutoPilot

   Provides basic auto-piloting utilities for a vessel.
   Created by calling :meth:`Vessel.getAutoPilot()`.

   .. note::

      If a client engages the auto-pilot and then closes its connection to the server,
      the auto-pilot will be disengaged and its target reference frame, direction and roll
      reset to default.

   .. method:: void engage()

      Engage the auto-pilot.

      :Game Scenes: Flight

   .. method:: void disengage()

      Disengage the auto-pilot.

      :Game Scenes: Flight

   .. method:: void wait_()

      Blocks until the vessel is pointing in the target direction and has
      the target roll (if set). Throws an exception if the auto-pilot has not been engaged.

      :Game Scenes: Flight

   .. method:: float getError()


      The error, in degrees, between the direction the ship has been asked
      to point in and the direction it is pointing in. Throws an exception if the auto-pilot
      has not been engaged and SAS is not enabled or is in stability assist mode.

      :Game Scenes: Flight

   .. method:: float getPitchError()


      The error, in degrees, between the vessels current and target pitch.
      Throws an exception if the auto-pilot has not been engaged.

      :Game Scenes: Flight

   .. method:: float getHeadingError()


      The error, in degrees, between the vessels current and target heading.
      Throws an exception if the auto-pilot has not been engaged.

      :Game Scenes: Flight

   .. method:: float getRollError()


      The error, in degrees, between the vessels current and target roll.
      Throws an exception if the auto-pilot has not been engaged or no target roll is set.

      :Game Scenes: Flight

   .. method:: ReferenceFrame getReferenceFrame()

   .. method:: void setReferenceFrame(ReferenceFrame value)

      The reference frame for the target direction (:meth:`AutoPilot.getTargetDirection()`).

      :Game Scenes: Flight


      .. note::

         An error will be thrown if this property is set to a reference frame that rotates with
         the vessel being controlled, as it is impossible to rotate the vessel in such a
         reference frame.

   .. method:: float getTargetPitch()

   .. method:: void setTargetPitch(float value)

      The target pitch, in degrees, between -90° and +90°.

      :Game Scenes: Flight

   .. method:: float getTargetHeading()

   .. method:: void setTargetHeading(float value)

      The target heading, in degrees, between 0° and 360°.

      :Game Scenes: Flight

   .. method:: float getTargetRoll()

   .. method:: void setTargetRoll(float value)

      The target roll, in degrees. ``NaN`` if no target roll is set.

      :Game Scenes: Flight

   .. method:: org.javatuples.Triplet<Double,Double,Double> getTargetDirection()

   .. method:: void setTargetDirection(org.javatuples.Triplet<Double,Double,Double> value)

      Direction vector corresponding to the target pitch and heading.
      This is in the reference frame specified by :type:`ReferenceFrame`.

      :Game Scenes: Flight

   .. method:: void targetPitchAndHeading(float pitch, float heading)

      Set target pitch and heading angles.

      :param float pitch: Target pitch angle, in degrees between -90° and +90°.
      :param float heading: Target heading angle, in degrees between 0° and 360°.
      :Game Scenes: Flight

   .. method:: boolean getSAS()

   .. method:: void setSAS(boolean value)

      The state of SAS.

      :Game Scenes: Flight


      .. note::

         Equivalent to :meth:`Control.getSAS()`

   .. method:: SASMode getSASMode()

   .. method:: void setSASMode(SASMode value)

      The current :type:`SASMode`.
      These modes are equivalent to the mode buttons to the left of the navball that appear
      when SAS is enabled.

      :Game Scenes: Flight


      .. note::

         Equivalent to :meth:`Control.getSASMode()`

   .. method:: double getRollThreshold()

   .. method:: void setRollThreshold(double value)

      The threshold at which the autopilot will try to match the target roll angle, if any.
      Defaults to 5 degrees.

      :Game Scenes: Flight

   .. method:: org.javatuples.Triplet<Double,Double,Double> getStoppingTime()

   .. method:: void setStoppingTime(org.javatuples.Triplet<Double,Double,Double> value)

      The maximum amount of time that the vessel should need to come to a complete stop.
      This determines the maximum angular velocity of the vessel.
      A vector of three stopping times, in seconds, one for each of the pitch, roll
      and yaw axes. Defaults to 0.5 seconds for each axis.

      :Game Scenes: Flight

   .. method:: org.javatuples.Triplet<Double,Double,Double> getDecelerationTime()

   .. method:: void setDecelerationTime(org.javatuples.Triplet<Double,Double,Double> value)

      The time the vessel should take to come to a stop pointing in the target direction.
      This determines the angular acceleration used to decelerate the vessel.
      A vector of three times, in seconds, one for each of the pitch, roll and yaw axes.
      Defaults to 5 seconds for each axis.

      :Game Scenes: Flight

   .. method:: org.javatuples.Triplet<Double,Double,Double> getAttenuationAngle()

   .. method:: void setAttenuationAngle(org.javatuples.Triplet<Double,Double,Double> value)

      The angle at which the autopilot considers the vessel to be pointing
      close to the target.
      This determines the midpoint of the target velocity attenuation function.
      A vector of three angles, in degrees, one for each of the pitch, roll and yaw axes.
      Defaults to 1° for each axis.

      :Game Scenes: Flight

   .. method:: boolean getAutoTune()

   .. method:: void setAutoTune(boolean value)

      Whether the rotation rate controllers PID parameters should be automatically tuned
      using the vessels moment of inertia and available torque. Defaults to ``true``.
      See :meth:`AutoPilot.getTimeToPeak()` and :meth:`AutoPilot.getOvershoot()`.

      :Game Scenes: Flight

   .. method:: org.javatuples.Triplet<Double,Double,Double> getTimeToPeak()

   .. method:: void setTimeToPeak(org.javatuples.Triplet<Double,Double,Double> value)

      The target time to peak used to autotune the PID controllers.
      A vector of three times, in seconds, for each of the pitch, roll and yaw axes.
      Defaults to 3 seconds for each axis.

      :Game Scenes: Flight

   .. method:: org.javatuples.Triplet<Double,Double,Double> getOvershoot()

   .. method:: void setOvershoot(org.javatuples.Triplet<Double,Double,Double> value)

      The target overshoot percentage used to autotune the PID controllers.
      A vector of three values, between 0 and 1, for each of the pitch, roll and yaw axes.
      Defaults to 0.01 for each axis.

      :Game Scenes: Flight

   .. method:: org.javatuples.Triplet<Double,Double,Double> getPitchPIDGains()

   .. method:: void setPitchPIDGains(org.javatuples.Triplet<Double,Double,Double> value)

      Gains for the pitch PID controller.

      :Game Scenes: Flight


      .. note::

         When :meth:`AutoPilot.getAutoTune()` is true, these values are updated automatically,
         which will overwrite any manual changes.

   .. method:: org.javatuples.Triplet<Double,Double,Double> getRollPIDGains()

   .. method:: void setRollPIDGains(org.javatuples.Triplet<Double,Double,Double> value)

      Gains for the roll PID controller.

      :Game Scenes: Flight


      .. note::

         When :meth:`AutoPilot.getAutoTune()` is true, these values are updated automatically,
         which will overwrite any manual changes.

   .. method:: org.javatuples.Triplet<Double,Double,Double> getYawPIDGains()

   .. method:: void setYawPIDGains(org.javatuples.Triplet<Double,Double,Double> value)

      Gains for the yaw PID controller.

      :Game Scenes: Flight


      .. note::

         When :meth:`AutoPilot.getAutoTune()` is true, these values are updated automatically,
         which will overwrite any manual changes.