Plugin/Source/SenseGloveCoreKismet/Public/SGCoreKismet/SGSenseGloveKismetLibrary.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 Sense Glove exoskeleton glove.
 * Contains methods for Kinematics, Haptics and Serialization.
 */


#pragma once

#include "SGCore/SGHandPose.h"
#include "SGCore/SGHandProfile.h"
#include "SGCore/SGSenseGlove.h"
#include "SGCore/SGSenseGlovePose.h"
#include "SGCore/SGSenseGloveSensorData.h"
#include "SGKismet/SGBlueprintFunctionLibrary.h"
#include "SGTypes/SGVectorArray.h"

#include "SGSenseGloveKismetLibrary.generated.h"

class USGBuzzCommand;
class USGDevice;
class USGForceFeedbackCommand;
class USGSenseGlove;

/**
 * Interface for the Sense Glove; and exoskeleton Force-Feedback glove.
 */
UCLASS(meta=(ScriptName = "SesneGloveSenseGloveKismetLibrary"))
class SENSEGLOVECOREKISMET_API USGSenseGloveKismetLibrary final : public USGBlueprintFunctionLibrary
{
    GENERATED_BODY()

public:
    /**
     * Byte indicating a new Sense Glove haptic command.
     */
    UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | SG | Sense Glove")
    static FString GetHapticsByte();

    /**
     * Byte indicating a new Thumper command.
     */
    UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | SG | Sense Glove")
    static FString GetThumperByte();

    /**
     * Calculates a GlovePose based on sensor angles and a glove model.
     *
     * @remarks Use this when you already have gloveAngles collected.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Calculate Glove Pose", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static USGSenseGlovePose* CalculateGlovePose_SD_GM(
        UObject* WorldContextObject,
        const USGSenseGloveSensorData* SensorData, const USGSenseGloveInfo* GloveModel);

    /**
     * Calculates a GlovePose based on gloveAngles and a glove model.
     *
     * @remarks Use this when you already have gloveAngles collected.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Calculate Glove Pose", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static USGSenseGlovePose* CalculateGlovePose_GA_GM(
        UObject* WorldContextObject,
        const TArray<FSGVectorArray>& GloveAngles, const USGSenseGloveInfo* GloveModel);

    /**
     * @remarks Use this when you already have a GlovePose.
     */
    UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static USGHandPose* CalculateHandPose(
        UObject* WorldContextObject,
        const USGSenseGlovePose* GlovePose, const USGBasicHandModel* HandModel,
        const USGSenseGloveHandProfile* Profile);

    /**
     * Deserializes a Sense Glove from its ConstantsString. Returns a nullptr if unsuccessful.
     */
    UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static USGDevice* Parse(UObject* WorldContextObject, const FString& ConstantsString);

    /**
     * Retrieve all Sense Gloves connected to this system.
     */
    UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static TArray<USGSenseGlove*> GetSenseGloves(UObject* WorldContextObject);

    /**
     * Retrieve the first connected Sense Glove there is.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Sense Glove", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static bool GetSenseGlove_OutG(UObject* WorldContextObject, USGSenseGlove*& OutGlove);

    /**
     * Retrieve the first (connected) right or left handed sense glove.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Sense Glove", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static bool GetSenseGlove_bRH_OutG(UObject* WorldContextObject, bool bRightHanded, USGSenseGlove*& OutGlove);

    /**
     * Convert a SenseGlove GlovePose into calibrationValues.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Calibration Values", Category="SenseGlove | Core | SG | Sense Glove")
    static TArray<FVector> GetCalibrationValues_GlovePose(const USGSenseGlovePose* GlovePose);

    /**
     * Apply interpolation values to the correct fields in the SenseGlove Profile, based on min/max sensor values.
     */
    UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static void CalibrateInterpolation(UObject* WorldContextObject,
                                       const TArray<FVector>& MinValues, const TArray<FVector>& MaxValues,
                                       bool bRightHanded, USGSenseGloveHandProfile*& OutProfile);

    /**
     * Retrieve the location of the glove origin, based on a reference location without requiring an object reference.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Calculate Glove Location",
        Category="SenseGlove | Core | SG | Sense Glove")
    static void CalculateGloveLocation_RP_FQuat_RR_TH_bRH_MO_OutGP_FQuat_OutGR(
        const FVector& ReferencePosition, const FQuat& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded, ESGFinger MountedOn,
        FVector& OutGlovePosition, FQuat& OutGloveRotation);

    /**
     * Retrieve the location of the glove origin, based on a reference location without requiring an object reference.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Calculate Glove Location",
        Category="SenseGlove | Core | SG | Sense Glove")
    static void CalculateGloveLocation_RP_FRotator_RR_TH_bRH_MO_OutGP_FRotator_OutGR(
        const FVector& ReferencePosition, const FRotator& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded, ESGFinger MountedOn,
        FVector& OutGlovePosition, FRotator& OutGloveRotation);

    /**
     * Calculates the full wrist location.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Calculate Wrist Location",
        Category="SenseGlove | Core | SG | Sense Glove")
    static void CalculateWristLocation_RP_FQuat_RR_TH_bRH_MO_GWPOffset_FQuat_GWRO_OutWP_FQuat_OutWR(
        const FVector& ReferencePosition, const FQuat& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded, ESGFinger MountedOn,
        const FVector& GloveWristPositionOffset, const FQuat& GloveWristRotationOffset,
        FVector& OutWristPosition, FQuat& OutWristRotation);

    /**
     * Calculates the full wrist location.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Calculate Wrist Location",
        Category="SenseGlove | Core | SG | Sense Glove")
    static void CalculateWristLocation_RP_FRotator_RR_TH_bRH_MO_GWPOffset_FRotator_GWRO_OutWP_FRotator_OutWR(
        const FVector& ReferencePosition, const FRotator& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded, ESGFinger MountedOn,
        const FVector& GloveWristPositionOffset, const FRotator& GloveWristRotationOffset,
        FVector& OutWristPosition, FRotator& OutWristRotation);

    /**
     * Retrieve this glove's hardware model, which contains its hardware data.
     */
    UFUNCTION(BlueprintPure, Category="SenseGlove | Core | SG | Sense Glove", meta=(WorldContext="WorldContextObject"))
    static USGSenseGloveInfo* GetGloveModel(UObject* WorldContextObject, const USGSenseGlove* SenseGlove);

    /**
     * Check if this Sense Glove is right handed.
     *
     * @remarks While the variable is stored in SG_GloveModel, added direct access here since its frequently used.
     */
    UFUNCTION(BlueprintPure, Category="SenseGlove | Core | SG | Sense Glove")
    static bool IsRight(const USGSenseGlove* SenseGlove);

    /**
     * Get the DeviceType enumerator of this SenseGlove, used in DeviceList enumeration.
     */
    UFUNCTION(BlueprintPure, Category="SenseGlove | Core | SG | Sense Glove")
    static ESGDeviceType GetDeviceType(const USGSenseGlove* SenseGlove);

    /**
     * Retrieve this Sense Glove's unique identifier.
     */
    UFUNCTION(BlueprintPure, Category="SenseGlove | Core | SG | Sense Glove")
    static FString GetDeviceId(const USGSenseGlove* SenseGlove);

    /**
     * Retrieve this glove's hardware (sub) version.
     */
    UFUNCTION(BlueprintPure, Category="SenseGlove | Core | SG | Sense Glove")
    static FString GetHardwareVersion(const USGSenseGlove* SenseGlove);

    /**
     * Retrieve this device's firmware version.
     */
    UFUNCTION(BlueprintPure, Category="SenseGlove | Core | SG | Sense Glove")
    static int32 GetFirmwareVersion(const USGSenseGlove* SenseGlove);

    /**
     * Retrieve this device's sub-firmware version.
     */
    UFUNCTION(BlueprintPure, Category="SenseGlove | Core | SG | Sense Glove")
    static int32 GetSubFirmwareVersion(const USGSenseGlove* SenseGlove);

    /**
     * Get the latest Sensor Data from this Sense Glove.
     */
    UFUNCTION(BlueprintPure, Category="SenseGlove | Core | SG | Sense Glove", meta=(WorldContext="WorldContextObject"))
    static bool GetSensorData(UObject* WorldContextObject,
                              const USGSenseGlove* SenseGlove, USGSenseGloveSensorData*& OutSensorData);

    /**
     *
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Imu Rotation", Category="SenseGlove | Core | SG | Sense Glove")
    static bool GetImuRotation_FQuat_OutI(UPARAM(ref) USGSenseGlove* SenseGlove, FQuat& OutImu);

    /**
     *
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Imu Rotation", Category="SenseGlove | Core | SG | Sense Glove")
    static bool GetImuRotation_FRotator_OutI(UPARAM(ref) USGSenseGlove* SenseGlove, FRotator& OutImu);

    /**
     * Get the pose of this Sense Glove's hardware, based on its latest Sensor Data.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Glove Pose", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static bool GetGlovePose_OutGP(UObject* WorldContextObject,
                                   UPARAM(ref) USGSenseGlove* SenseGlove,
                                   USGSenseGlovePose*& OutGlovePose);

    /**
     * Get the pose of this Sense Glove's hardware based on a set of Sensor Data.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Glove Pose", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static bool GetGlovePose_SD_OutGP(UObject* WorldContextObject,
                                      UPARAM(ref) USGSenseGlove* SenseGlove,
                                      const USGSenseGloveSensorData* SensorData,
                                      USGSenseGlovePose*& OutGlovePose);

    /**
     * Retrieve a new hand pose using this glove's data, based on (calibrated) user data.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Hand Pose", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static bool GetHandPose_HM_P_OutHP(UObject* WorldContextObject,
                                       UPARAM(ref) USGSenseGlove* SenseGlove,
                                       const USGBasicHandModel* HandModel,
                                       const USGSenseGloveHandProfile* Profile,
                                       USGHandPose*& OutHandPose);

    /**
     * Calculate the Hand Pose of this device, provided it has Hand Tracking available.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Hand Pose", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static bool GetHandPose_HG_HP_OutHP(UObject* WorldContextObject,
                                        UPARAM(ref) USGSenseGlove* SenseGlove,
                                        const USGBasicHandModel* HandGeometry,
                                        const USGHandProfile* HandProfile,
                                        USGHandPose*& OutHandPose);

    /**
     * Calculate the HandPose of this Device, taking into account user values, but not hand geometry.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Hand Pose", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static bool GetHandPose_HP_OutHP(UObject* WorldContextObject,
                                     UPARAM(ref) USGSenseGlove* SenseGlove,
                                     const USGHandProfile* HandProfile,
                                     USGHandPose*& OutHandPose);

    /**
     * Set the level(s) of Force and Vibrotactile feedback, with an optional thumper command.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Send Haptics", Category="SenseGlove | Core | SG | Sense Glove")
    static bool SendHaptics_FFC_BC_ESGSenseGloveThumperCommand_TC(
        UPARAM(ref) USGSenseGlove* SenseGlove,
        const USGForceFeedbackCommand* ForceFeedbackCommand, const USGBuzzCommand* BuzzCommand,
        ESGSenseGloveThumperCommand ThumperCommand = ESGSenseGloveThumperCommand::None);

    /**
     * Send a thumper command.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Send Haptics", Category="SenseGlove | Core | SG | Sense Glove")
    static bool SendHaptics_TC(UPARAM(ref) USGSenseGlove* SenseGlove, ESGSenseGloveThumperCommand ThumperCommand);

    /**
     * Send Haptic Commands to this Glove.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Send Haptics", Category="SenseGlove | Core | SG | Sense Glove")
    static void SendHaptics_FFC(UPARAM(ref) USGSenseGlove* SenseGlove,
                                const USGForceFeedbackCommand* ForceFeedbackCommand);

    /**
     * Send Haptic Commands to this Glove.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Send Haptics", Category="SenseGlove | Core | SG | Sense Glove")
    static void SendHaptics_BC(UPARAM(ref) USGSenseGlove* SenseGlove, const USGBuzzCommand* BuzzCommand);

    /**
     * Retrieve this device's firmware version.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Send Haptics", Category="SenseGlove | Core | SG | Sense Glove")
    static void SendHaptics_FFC_BC_TC(
        UPARAM(ref) USGSenseGlove* SenseGlove,
        const USGForceFeedbackCommand* ForceFeedbackCommand,
        const USGBuzzCommand* BuzzCommand,
        const USGThumperCommand* ThumperCommand);

    /**
     * Retrieve calibration values of this glove, as an array of size 5, containing x (roll), y (flexion), z (abduction) values.
     */
    UFUNCTION(BlueprintCallable, DisplayName="Get Calibration Values", Category="SenseGlove | Core | SG | Sense Glove")
    static bool GetCalibrationValues_OutV(UPARAM(ref) USGSenseGlove* SenseGlove, TArray<FVector>& OutValues);

    /**
     * Reset the glove's calibration range.
     */
    UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | SG | Sense Glove")
    static void ResetCalibrationRange(UPARAM(ref) USGSenseGlove* SenseGlove);

    /**
     * Apply this glove's calibration range to a handProfile.
     */
    UFUNCTION(BlueprintPure, DisplayName="Apply Calibration", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static void ApplyCalibration_USGHandProfile_OutP(UObject* WorldContextObject,
                                                     const USGSenseGlove* SenseGlove,
                                                     USGHandProfile*& OutProfile);

    /**
     * Apply this glove's calibration range to a SenseGloveHandProfile.
     */
    UFUNCTION(BlueprintPure, DisplayName="Apply Calibration", Category="SenseGlove | Core | SG | Sense Glove",
        meta=(WorldContext="WorldContextObject"))
    static void ApplyCalibration_USGSenseGloveHandProfile_OutP(UObject* WorldContextObject,
                                                               const USGSenseGlove* SenseGlove,
                                                               USGSenseGloveHandProfile*& OutProfile);

    /**
     * Retrieve the location of the glove origin, based on a reference location.
     */
    UFUNCTION(BlueprintPure, DisplayName="Get Glove Location", Category="SenseGlove | Core | SG | Sense Glove")
    static void GetGloveLocation_RP_FQuat_RR_TH_OutGP_FQuat_OutGR(
        const USGSenseGlove* SenseGlove,
        const FVector& ReferencePosition, const FQuat& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware,
        FVector& OutGlovePosition, FQuat& OutGloveRotation);

    /**
     * Retrieve the location of the glove origin, based on a reference location.
     */
    UFUNCTION(BlueprintPure, DisplayName="Get Glove Location", Category="SenseGlove | Core | SG | Sense Glove")
    static void GetGloveLocation_RP_FRotator_RR_TH_OutGP_FRotator_OutGR(
        const USGSenseGlove* SenseGlove,
        const FVector& ReferencePosition, const FRotator& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware,
        FVector& OutGlovePosition, FRotator& OutGloveRotation);

    /**
     * Retrieve the location of the glove origin, based on a reference location.
     */
    UFUNCTION(BlueprintPure, DisplayName="Get Glove Location", Category="SenseGlove | Core | SG | Sense Glove")
    static void GetGloveLocation_RP_FQuat_RR_TH_MO_OutGP_FQuat_OutGR(
        const USGSenseGlove* SenseGlove,
        const FVector& ReferencePosition, const FQuat& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware, ESGFinger MountedOn,
        FVector& OutGlovePosition, FQuat& OutGloveRotation);

    /**
     * Retrieve the location of the glove origin, based on a reference location.
     */
    UFUNCTION(BlueprintPure, DisplayName="Get Glove Location", Category="SenseGlove | Core | SG | Sense Glove")
    static void GetGloveLocation_RP_FRotator_RR_TH_MO_OutGP_FRotator_OutGR(
        const USGSenseGlove* SenseGlove,
        const FVector& ReferencePosition, const FRotator& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware, ESGFinger MountedOn,
        FVector& OutGlovePosition, FRotator& OutGloveRotation);

    /**
     * Retrieve the location of the wrist, based on a reference location and default glove-hand offsets.
     */
    UFUNCTION(BlueprintPure, DisplayName="Get Wrist Location", Category="SenseGlove | Core | SG | Sense Glove")
    static void GetWristLocation_RP_FQuat_RR_TH_OutWP_FQuat_OutWR(
        const USGSenseGlove* SenseGlove,
        const FVector& ReferencePosition, const FQuat& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware,
        FVector& OutWristPosition, FQuat& OutWristRotation);

    /**
     * Retrieve the location of the wrist, based on a reference location and default glove-hand offsets.
     */
    UFUNCTION(BlueprintPure, DisplayName="Get Wrist Location", Category="SenseGlove | Core | SG | Sense Glove")
    static void GetWristLocation_RP_FRotator_RR_TH_OutWP_FRotator_OutWR(
        const USGSenseGlove* SenseGlove,
        const FVector& ReferencePosition, const FRotator& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware,
        FVector& OutWristPosition, FRotator& OutWristRotation);

    /**
     * Retrieve the location of the wrist, based on a reference location and default glove-hand offsets.
     */
    UFUNCTION(BlueprintPure, DisplayName="Get Wrist Location", Category="SenseGlove | Core | SG | Sense Glove")
    static void GetWristLocation_RP_FQuat_RR_TH_GWPO_FQuat_GWRO_OutWP_FQuat_OutWR(
        const USGSenseGlove* SenseGlove,
        const FVector& ReferencePosition, const FQuat& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware,
        const FVector& GloveWristPositionOffset,
        const FQuat& GloveWristRotationOffset,
        FVector& OutWristPosition, FQuat& OutWristRotation);

    /**
     * Retrieve the location of the wrist, based on a reference location and default glove-hand offsets.
     */
    UFUNCTION(BlueprintPure, DisplayName="Get Wrist Location", Category="SenseGlove | Core | SG | Sense Glove")
    static void GetWristLocation_RP_FRotator_RR_TH_GWPO_FRotator_GWRO_OutWP_FRotator_OutWR(
        const USGSenseGlove* SenseGlove,
        const FVector& ReferencePosition, const FRotator& ReferenceRotation,
        ESGPositionalTrackingHardware TrackingHardware,
        const FVector& GloveWristPositionOffset,
        const FRotator& GloveWristRotationOffset,
        FVector& OutWristPosition, FRotator& OutWristRotation);

    /**
     * Create a string representation of this device for reporting purposes.
     */
    UFUNCTION(BlueprintPure, Category="SenseGlove | Core | SG | Sense Glove")
    static FString ToString(const USGSenseGlove* SenseGlove);
};