Interface LookAtPilotingItf

  • All Superinterfaces:
    Activable, PilotingItf

    public interface LookAtPilotingItf
    extends PilotingItf, Activable
    Piloting interface used to keep the drone directed towards some target, in effect making it 'looking at' such a target.

    Availability

    This interface will be unavailable until a specific set of conditions are met:

    • the drone must be flying,
    • the drone must be properly calibrated,
    • the drone must have sufficient GPS location information,
    • the drone must be sufficiently far above the ground,
    • the drone must be sufficiently far away from the target,
    • the application must provide sufficient information to the drone so that it can identify and track the target (see Target selection for further information on how to provide target tracking information.)
    All unsatisfied conditions are reported by this interface, when unavailable, so that the application can inform the user and take appropriate measures to satisfy those conditions as appropriate. Once all conditions are satisfied, then the interface will become available and can be activated so that the drone starts looking at the target.

    Note that this interface, even while available or active may become unavailable back again, as soon as any of those conditions is not satisfied anymore.

    Alerts

    When available or active, this interface may also alert about specific conditions that hinders optimally accurate tracking of the target, although tracking remains feasible under such conditions:

    • TODO : refine and list exactly which cases can be forwarded as an 'alert' from the drone.
    The application may use such alerts to inform the user and take appropriate measures to improve tracking performance.

    Movement

    When this interface is active, the drone just rotates from its standstill position to follow the moving target but does not move by itself to follow the latter, unless instructed to move using this interface's setPitch(int), setRoll(int) or setVerticalSpeed(int) piloting commands.
    In any case, the drone will try to maintain its orientation towards the target, and thus may move independently of the provided piloting commands to do so.

    Target selection

    In order for this interface to be available, the application must instruct the drone how to identify and track the desired target. To do so, the TargetTracker peripheral must be used.

    Using this peripheral, the application may:

    • Require controller (remote control, or user device) barometer and location information to be sent regularly to the drone. In case sent information is sufficiently accurate, it may be sufficient to allow the drone to track the controller, in which case, provided other requirements are satisfied, the interface will become available and, when active, will make the drone look toward the controller.
    • Provide external information about where the desired target is located, its direction and current movement. Such information may for example come from results of image processing applied to the drone video stream. In case sent information is sufficiently accurate and coherent, it may be sufficient to allow the drone to track the desired target, in which case, provided other requirements are satisfied, the interface will become available and, when active, will make the drone look toward the desired target.

    Note that both controller barometer/location information and external target information may be sent to the drone at the same time, provided they give coherent positioning information on the SAME target.
    For instance, it is possible to perform image processing on the drone video stream to identify the controller and send the results to the drone, along with controller barometer/location updates, for better tracking performance.
    However, care must be taken not to provide incoherent information, such as forwarding controller/barometer location and, as the same time, external information on a different target than the controller; behavior is undefined in such a case.

    This piloting interface can be obtained from a drone using:

    drone.getPilotingItf(LookAtPilotingItf.class)
    See Also:
    PilotingItf.Provider.getPilotingItf(Class), PilotingItf.Provider.getPilotingItf(Class, Ref.Observer)
    • Method Detail

      • activate

        boolean activate()
        Activates this piloting interface.

        If successful, the currently active piloting interface (if any) is deactivated and this one is activated.

        Returns:
        true on success, false in case the piloting interface cannot be activated at this point
      • getAvailabilityIssues

        @NonNull
        EnumSet<TrackingIssue> getAvailabilityIssues()
        Tells why this piloting interface is currently be unavailable.

        The returned set may contain values only if the interface is unavailable.

        Returns:
        the set of reasons that preclude this piloting interface from being available at present
      • getQualityIssues

        @NonNull
        EnumSet<TrackingIssue> getQualityIssues()
        Alerts about issues that currently hinders optimal behavior of this interface.

        The returned set may contain values only if the interface is active.

        Returns:
        a set of issues that hinders optimal behavior of this interface
      • setPitch

        void setPitch​(int pitch)
        Sets the current pitch value.

        The drone tries to both conform to the requested pitch command and keep directed towards the target.

        value is expressed as a signed percentage of the max pitch/roll setting, in range [-100, 100].
        -100 corresponds to a pitch angle of max pitch/roll towards ground (drone will fly forward), 100 corresponds to a pitch angle of max pitch/roll towards sky (copter will fly backward).

        copter.

        Parameters:
        pitch - the new pitch value to set
      • setRoll

        void setRoll​(int roll)
        Sets the current roll value.

        The drone tries to both conform to the requested roll command and keep directed towards the target.

        value is expressed as a signed percentage of the max pitch/roll setting, in range [-100, 100].
        -100 corresponds to a roll angle of max pitch/roll to the left (copter will fly left), 100 corresponds to a roll angle of max pitch/roll to the right (copter will fly right).

        Note: value may be clamped if necessary, in order to respect the maximum supported physical tilt of the copter.

        Parameters:
        roll - the new pitch roll to set
        See Also:
        ManualCopterPilotingItf.getMaxPitchRoll()
      • setVerticalSpeed

        void setVerticalSpeed​(int verticalSpeed)
        Set the current vertical speed value.

        The drone tries to both conform to the requested vertical speed command and keep directed towards the target.

        value is expressed as as a signed percentage of the max vertical speed setting, in range [-100, 100].
        -100 corresponds to max vertical speed towards ground,100 corresponds to max vertical speed towards sky.

        Parameters:
        verticalSpeed - the new vertical speed value to set
        See Also:
        ManualCopterPilotingItf.getMaxVerticalSpeed()