Plugin/Source/SenseGloveCore/Public/SGCore/SGNovaGlove.h

/**
 * @file
 *
 * @author  Mamadou Babaei <mamadou@senseglove.com>
 *
 * @section LICENSE
 *
 * (The MIT License)
 *
 * Copyright (c) 2020 - 2023 SenseGlove
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * @section DESCRIPTION
 *
 * An interface for the "Nova" - a soft glove.
 * Contains methods for Kinematics, Haptics and Serialization.
 */


#pragma once

#include "SGHapticGlove.h"
#include "Containers/Array.h"
#include "HAL/Platform.h"
#include "Math/Quat.h"
#include "Math/Vector.h"

#include "SGCore/SGHapticGlove.h"
#include "SGTypes/SGCoreTypes.h"

#include "SGNovaGlove.generated.h"

class FSGNovaGloveImpl;
class USGBuzzCommand;
class USGForceFeedbackCommand;
class USGNovaGloveInfo;
class USGNovaGloveSensorData;
class USGThumperCommand;

/**
 * A soft glove with Force- and Vibrotactile Feedback and limited tracking.
 */
UCLASS(BlueprintType)
class SENSEGLOVECORE_API USGNovaGlove final : public USGHapticGlove
{
    GENERATED_BODY()

public:
    static USGNovaGlove* NewNovaGlove(UObject* Outer, const FSGNovaGloveImpl& NovaGloveImpl);

    static USGNovaGlove* NewNovaGlove(UObject* Outer, TSharedRef<FSGNovaGloveImpl> NovaGloveImpl);

public:
    /**
     *
     */
    static USGNovaGlove* NewNovaGlove(UObject* Outer);

    /**
     *
     */
    static USGNovaGlove* NewNovaGlove(UObject* Outer, const USGNovaGloveInfo& DeviceInfo);

public:
    /**
     * Byte indicating a new Nova haptic command.
     */
    static ANSICHAR GetHapticsByte();

    /**
     * Minimum calibration value distance until we apply the range.
     */
    static FVector GetMinCalibrationRange();

public:
    /**
     * Calculate a Hand Pose based on a HandMode; sensor data from a Nova, and a UserProfile.
     */
    static USGHandPose* CalculateHandPose(UObject* Outer,
                                          const USGBasicHandModel* HandModel,
                                          const USGNovaGloveSensorData* NovaData,
                                          const USGNovaGloveHandProfile* Profile);

public:
    /**
     * Deserializes a Nova from its ConstantsString. Returns a nullptr if unsuccessful.
     */
    static USGDevice* Parse(UObject* Outer, const FString& ConstantsString);

    /**
     * Retrieve all Nova's.
     */
    static TArray<USGNovaGlove*> GetNovaGloves(UObject* Outer);

    /**
     * Retrieve the first connected Nova there is.
     */
    static bool GetNovaGlove(UObject* Outer, USGNovaGlove*& OutGlove);

    /**
     * Retrieve the first (connected) right or left handed Nova.
     */
    static bool GetNovaGlove(UObject* Outer, bool bRightHanded, USGNovaGlove*& OutGlove);

public:
    /**
     * Convert a SenseGlove GlovePose into calibrationValues.
     */
    static TArray<FVector> GetCalibrationValues(const USGNovaGloveSensorData* SensorData);

    /**
     *
     */
    static void CalibrateInterpolation(UObject* Outer,
                                       const TArray<FVector>& MinValues, const TArray<FVector>& MaxValues,
                                       USGNovaGloveHandProfile*& OutProfile);

public:
    /**
     * Retrieve the location of the glove origin, based on a reference location without requiring an object reference.
     */
    static void CalculateGloveLocation(const FVector& ReferencePosition, const FQuat& ReferenceRotation,
                                       ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded,
                                       FVector& OutGlovePosition, FQuat& OutGloveRotation);

    /**
     * Retrieve the location of the glove origin, based on a reference location without requiring an object reference.
     */
    static void CalculateGloveLocation(const FVector& ReferencePosition, const FRotator& ReferenceRotation,
                                       ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded,
                                       FVector& OutGlovePosition, FRotator& OutGloveRotation);

    /**
     * Retrieve the location of the wrist, based on a reference location and default glove-hand offsets, without needing an object reference.
     */
    static void CalculateWristLocation(const FVector& ReferencePosition, const FQuat& ReferenceRotation,
                                       ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded,
                                       FVector& OutWristPosition, FQuat& OutWristRotation);

    /**
     * Retrieve the location of the wrist, based on a reference location and default glove-hand offsets, without needing an object reference.
     */
    static void CalculateWristLocation(const FVector& ReferencePosition, const FRotator& ReferenceRotation,
                                       ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded,
                                       FVector& OutWristPosition, FRotator& OutWristRotation);

public:
    /**
     * Converts a thumper command into bytes that the Nova can understand.
     */
    static FString ToBytes(const USGThumperCommand* ThumperCommand);

    /**
     * Converts a force-feedback command into bytes that the Nova can understand.
     */
    static FString ToBytes(const USGForceFeedbackCommand* ForceFeedbackCommand);

    /**
     * Converts a buzz-motor command into bytes that the Nova can understand.
     */
    static FString ToBytes(const USGBuzzCommand* BuzzCommand);

protected:
    USGNovaGlove();

    explicit USGNovaGlove(const USGNovaGloveInfo& DeviceInfo);

public:
    /**
     * The cast from underlying parent type constructor.
     */
    explicit USGNovaGlove(const FSGDeviceImpl& SGDeviceImpl);

    /**
     * The cast from underlying parent type constructor.
     */
    explicit USGNovaGlove(const FSGHapticGloveImpl& HapticGloveImpl);

    /**
     * The cast from underlying type constructor.
     */
    explicit USGNovaGlove(const FSGNovaGloveImpl& NovaGloveImpl);

protected:
    /**
     * The cast from underlying parent pointer type constructor.
     */
    explicit USGNovaGlove(TSharedRef<FSGDeviceImpl> SGDeviceImpl);

    /**
     * The cast from underlying parent pointer type constructor.
     */
    explicit USGNovaGlove(TSharedRef<FSGHapticGloveImpl> HapticGloveImpl);

    /**
     * The cast from underlying pointer type constructor.
     */
    explicit USGNovaGlove(TSharedRef<FSGNovaGloveImpl> NovaGloveImpl);

public:
    /**
     * The destructor.
     */
    virtual ~USGNovaGlove() override;

public:
    /**
     * The cast to underlying type method.
     */
    TSharedRef<FSGNovaGloveImpl> ToNovaGloveImpl() const;

public:
    /**
     * Return the DeviceType of this Nova.
     */
    virtual ESGDeviceType GetDeviceType() const override;

    /**
     * Returns this device's unique identifier.
     */
    virtual FString GetDeviceId() const override;

    /**
     * Access this device's hardware designation.
     */
    virtual FString GetHardwareVersion() const override;

    /**
     * Access this device's main firmware version. (ex: v3.2 -> 3).
     */
    virtual int32 GetFirmwareVersion() const override;

    /**
     * Access this device's sub-firmware version. (ex: v3.2 -> 2).
     */
    virtual int32 GetSubFirmwareVersion() const override;

public:
    /**
     * Returns true if this device operates on a battery.
     */
    virtual bool HasBattery() const override;

    /**
     * Returns true if this device is currently charging.
     */
    virtual bool IsCharging() override;

    /**
     * Returns the device's battery level, as a value between 0 (empty) and 1 (full).
     */
    virtual bool GetBatteryLevel(float& OutBatteryLevel) override;

public:
    /**
     * Get the latest Sensor Data from this Sense Glove.
     */
    bool GetSensorData(UObject* Outer, USGNovaGloveSensorData*& OutSensorData);

    /**
     * Retrieve Nova rotation.
     */
    virtual bool GetImuRotation(FQuat& OutImu) override;

    /**
     * Retrieve Nova rotation.
     */
    virtual bool GetImuRotation(FRotator& OutImu) override;

    /// HACK
    /// 'FSGNovaGlove::GetHandPose' hides overloaded virtual functions [-Werror,-Woverloaded-virtual]
    /// tell the compiler we want both the GetHandPose from USGHapticGlove and USGNovaGlove
    using USGHapticGlove::GetHandPose;

    /**
     * Retrieve a new hand pose using this glove, based on (calibrated) user data.
     */
    bool GetHandPose(UObject* Outer, const USGBasicHandModel* HandModel, const USGNovaGloveHandProfile* Profile,
                     USGHandPose*& OutHandPose);

    /**
     * Retrieve a new hand pose using this glove, based on (calibrated) user data.
     */
    virtual bool GetHandPose(UObject* Outer, const USGBasicHandModel* HandGeometry, const USGHandProfile* HandProfile,
                             USGHandPose*& OutHandPose) override;

    /**
     * Calculate the HandPose of this Device, taking into account user values, but not hand geometry.
     */
    virtual bool GetHandPose(UObject* Outer, const USGHandProfile* HandProfile, USGHandPose*& OutHandPose) override;

public:
    /**
     * Send all available haptics to a Nova.
     */
    virtual void SendHaptics(const USGForceFeedbackCommand* ForceFeedbackCommand,
                             const USGBuzzCommand* BuzzCommand,
                             const USGThumperCommand* ThumperCommand) override;

    /**
     * Send Haptic Commands to this Glove.
     */
    virtual void SendHaptics(const USGForceFeedbackCommand* ForceFeedbackCommand) override;

    /**
     * Send Haptic Commands to this Glove.
     */
    virtual void SendHaptics(const USGBuzzCommand* BuzzCommand) override;

    /**
     * Send Haptic Commands to this Glove.
     */
    virtual void SendHaptics(const USGThumperCommand* ThumperCommand) override;

public:
    /**
     * Retrieve calibration values of this glove, as an array of size 5, containing x (roll), y (flexion), z (abduction) values.
     */
    virtual bool GetCalibrationValues(TArray<FVector>& OutValues) override;

    /**
     * Applies the calibration range of this Nova a HandProfile.
     */
    virtual void ApplyCalibration(UObject* Outer, USGHandProfile*& OutProfile) const override;

    /**
     * Applies the calibration range of this SenseGlove to a NovaGloveHandProfile.
     */
    void ApplyCalibration(UObject* Outer, USGNovaGloveHandProfile*& OutProfile) const;

public:
    /**
     * Retrieve the location of the glove origin, based on a reference location.
     */
    virtual void GetGloveLocation(const FVector& ReferencePosition, const FQuat& ReferenceRotation,
                                  ESGPositionalTrackingHardware TrackingHardware,
                                  FVector& OutGlovePosition, FQuat& OutGloveRotation) const override;

    /**
     * Retrieve the location of the glove origin, based on a reference location.
     */
    virtual void GetGloveLocation(const FVector& ReferencePosition, const FRotator& ReferenceRotation,
                                  ESGPositionalTrackingHardware TrackingHardware,
                                  FVector& OutGlovePosition, FRotator& OutGloveRotation) const override;

    /**
     * Retrieve the location of the wrist, based on a reference location and default glove-hand offsets.
     */
    virtual void GetWristLocation(const FVector& ReferencePosition, const FQuat& ReferenceRotation,
                                  ESGPositionalTrackingHardware TrackingHardware,
                                  FVector& OutWristPosition, FQuat& OutWristRotation) const override;

    /**
     * Retrieve the location of the wrist, based on a reference location and default glove-hand offsets.
     */
    virtual void GetWristLocation(const FVector& ReferencePosition, const FRotator& ReferenceRotation,
                                  ESGPositionalTrackingHardware TrackingHardware,
                                  FVector& OutWristPosition, FRotator& OutWristRotation) const override;

public:
    /**
     * Create a string representation of this device for reporting purposes.
     */
    virtual FString ToString() const override;
};