381 lines
19 KiBLFS
C++
381 lines
19 KiBLFS
C++
/**
|
|
* @file
|
|
*
|
|
* @author Max Lammers <max@senseglove.com>
|
|
* @author Mamadou Babaei <mamadou@senseglove.com>
|
|
*
|
|
* @section LICENSE
|
|
*
|
|
* Copyright (c) 2020 - 2022 SenseGlove
|
|
*
|
|
* @section DESCRIPTION
|
|
*
|
|
* An interface for the Sense Glove exoskeleton glove.
|
|
* Contains methods for Kinematics, Haptics and Serialization.
|
|
*/
|
|
|
|
|
|
#pragma once
|
|
|
|
#include <memory>
|
|
#include <string>
|
|
#include <vector>
|
|
|
|
#include "HapticGlove.hpp"
|
|
#include "Platform.hpp"
|
|
#include "SenseGloveThumperCommand.hpp"
|
|
|
|
namespace SGCore
|
|
{
|
|
namespace Haptics
|
|
{
|
|
class FingerCommand;
|
|
|
|
class ThumperCommand;
|
|
};// namespace Haptics
|
|
|
|
namespace Kinematics
|
|
{
|
|
class Quat;
|
|
|
|
class Vect3D;
|
|
};// namespace Kinematics
|
|
|
|
namespace SG
|
|
{
|
|
/// <summary> Interface for the Sense Glove; and exoskeleton Force-Feedback glove. </summary>
|
|
class SGCORE_API SenseGlove;
|
|
|
|
class SenseGloveInfo;
|
|
|
|
class SenseGlovePose;
|
|
|
|
class SenseGloveHandProfile;
|
|
|
|
class SenseGloveSensorData;
|
|
}// namespace SG
|
|
|
|
class HandPose;
|
|
}// namespace SGCore
|
|
|
|
/// <summary> Interface for the Sense Glove; and exoskeleton Force-Feedback glove. </summary>
|
|
class SGCORE_API SGCore::SG::SenseGlove : public SGCore::HapticGlove
|
|
{
|
|
public:
|
|
//---------------------------------------------------------------------------------------------------------------------
|
|
// Static Properties
|
|
|
|
/// <summary> Byte indicating a new Sense Glove haptic command. </summary>
|
|
static char GetHapticsByte();
|
|
|
|
/// <summary> Byte indicating a new Thumper command. </summary>
|
|
static char GetThumperByte();
|
|
|
|
public:
|
|
//--------------------------------------------------------------------------------------
|
|
// Kinematics
|
|
|
|
/// <summary> Calculates a GlovePose based on sensor angles and a glove model. </summary>
|
|
/// <remarks> Use this when you already have gloveAngles collected. </remarks>
|
|
static SenseGlovePose CalculateGlovePose(const SenseGloveSensorData& sensorData, const SenseGloveInfo& gloveModel);
|
|
|
|
/// <summary> Calculates a GlovePose based on gloveAngles and a glove model. </summary>
|
|
/// <remarks> Use this when you already have gloveAngles collected. </remarks>
|
|
static SenseGlovePose CalculateGlovePose(const std::vector<std::vector<Kinematics::Vect3D>>& gloveAngles,
|
|
const SenseGloveInfo& gloveModel);
|
|
|
|
///<summary> </summary>
|
|
///<remarks> Use this when you already have a GlovePose. </remarks>
|
|
static HandPose CalculateHandPose(const SenseGlovePose& glovePose, const Kinematics::BasicHandModel& handModel,
|
|
const SenseGloveHandProfile& profile);
|
|
|
|
public:
|
|
//--------------------------------------------------------------------------------------
|
|
// DeviceList Integration
|
|
|
|
///<summary> Deserializes a Sense Glove from its ConstantsString. Returns a nullptr if unsuccessful. </summary>
|
|
static std::shared_ptr<SGDevice> Parse(const std::string& constantsString);
|
|
|
|
/// <summary> Retrieve all Sense Gloves connected to this system. </summary>
|
|
static std::vector<SenseGlove> GetSenseGloves(bool bOnlyConnected = true);
|
|
|
|
/// <summary> Retrieve the first connected Sense Glove there is. </summary>
|
|
static bool GetSenseGlove(SenseGlove& out_glove);
|
|
|
|
/// <summary> Retrieve the first (connected) right or left handed sense glove. </summary>
|
|
static bool GetSenseGlove(bool bRightHanded, SenseGlove& out_glove);
|
|
|
|
public:
|
|
//--------------------------------------------------------------------------------------
|
|
// Calibration Methods
|
|
|
|
/// <summary> Convert a SenseGlove GlovePose into calibrationValues. </summary>
|
|
static std::vector<SGCore::Kinematics::Vect3D> GetCalibrationValues(const SenseGlovePose& glovePose);
|
|
|
|
/// <summary> Apply interpolation values to the correct fields in the SenseGlove Profile, based on min/max sensor values. </summary>
|
|
/// <param name="minValues"></param>
|
|
/// <param name="maxValues"></param>
|
|
/// <param name="bRightHand"></param>
|
|
/// <param name="profile"></param>
|
|
static void CalibrateInterpolation(const std::vector<Kinematics::Vect3D>& minValues,
|
|
const std::vector<Kinematics::Vect3D>& maxValues,
|
|
bool bRightHanded, SenseGloveHandProfile& profile);
|
|
|
|
public:
|
|
//--------------------------------------------------------------------------------------
|
|
// 6DoF Position Tracking
|
|
|
|
/// <summary> Retrieve the location of the glove origin, based on a reference location without requiring an object reference. </summary>
|
|
/// <param name="referencePosition">Position of the tracked object, in mm, relative to your origin</param>
|
|
/// <param name="referenceRotation">Rotation of the tracked object relative to your origin</param>
|
|
/// <param name="trackingHardware">The hardware mounted on the SenseGlove.</param>
|
|
/// <param name="bRightHanded">Whether or not this is a left or right handed glove.</param>
|
|
/// <param name="mountedOn">Which finger module the hardware is mounted on. Default is Middle finger.</param>
|
|
/// <param name="out_glovePosition">The 3D Position of the glove, in mm, relative to your origin</param>
|
|
/// <param name="out_gloveRotation">The 3D Rotation of the glove, relative to your origin</param>
|
|
static void CalculateGloveLocation(const Kinematics::Vect3D& referencePosition,
|
|
const Kinematics::Quat& referenceRotation,
|
|
EPositionalTrackingHardware trackingHardware,
|
|
bool bRightHanded, EFinger mountedOn,
|
|
Kinematics::Vect3D& out_glovePosition, Kinematics::Quat& out_gloveRotation);
|
|
|
|
/// <summary> Calculates the full wrist location. </summary>
|
|
/// <param name="referencePosition"></param>
|
|
/// <param name="referenceRotation"></param>
|
|
/// <param name="trackingHardware"></param>
|
|
/// <param name="bRightHanded"></param>
|
|
/// <param name="mountedOn"></param>
|
|
/// <param name="gloveWristPositionOffset"></param>
|
|
/// <param name="gloveWristRotationOffset"></param>
|
|
/// <param name="out_wristPosition"></param>
|
|
/// <param name="out_wristRotation"></param>
|
|
static void CalculateWristLocation(const Kinematics::Vect3D& referencePosition,
|
|
const Kinematics::Quat& referenceRotation,
|
|
EPositionalTrackingHardware trackingHardware,
|
|
bool bRightHanded, EFinger mountedOn,
|
|
const Kinematics::Vect3D& gloveWristPositionOffset,
|
|
const Kinematics::Quat& gloveWristRotationOffset,
|
|
Kinematics::Vect3D& out_wristPosition, Kinematics::Quat& out_wristRotation);
|
|
|
|
private:
|
|
struct Impl;
|
|
std::unique_ptr<Impl> Pimpl;
|
|
|
|
public:
|
|
SenseGlove();
|
|
|
|
/// <summary> Create a new instance of a Sense Glove. </summary>
|
|
SenseGlove(const SenseGloveInfo& model);
|
|
|
|
/**
|
|
* The copy constructor.
|
|
*/
|
|
SenseGlove(const SenseGlove& rhs);
|
|
|
|
/**
|
|
* The move constructor.
|
|
*/
|
|
SenseGlove(SenseGlove&& rhs) noexcept;
|
|
|
|
virtual ~SenseGlove() override;
|
|
|
|
public:
|
|
/**
|
|
* The copy assignment operator.
|
|
*/
|
|
SenseGlove& operator=(const SenseGlove& rhs);
|
|
|
|
/**
|
|
* The move assignment operator.
|
|
*/
|
|
SenseGlove& operator=(SenseGlove&& rhs) noexcept;
|
|
|
|
public:
|
|
/// <summary> Retrieve this glove's hardware model, which contains its hardware data. </summary>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
const SenseGloveInfo& GetGloveModel() const;
|
|
|
|
/// <summary> Check if this Sense Glove is right handed. </summary>
|
|
/// <remarks> While the variable is stored in SG_GloveModel, added direct access here since its frequently used. </remarks>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
virtual bool IsRight() const override;
|
|
|
|
public:
|
|
//--------------------------------------------------------------------------------------
|
|
// SGDevice Methods
|
|
|
|
///<summary> Get the DeviceType enumerator of this SenseGlove, used in DeviceList enumeration. </summary>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
virtual EDeviceType GetDeviceType() const override;
|
|
|
|
/// <summary> Retrieve this Sense Glove's unique identifier. </summary>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
virtual std::string GetDeviceId() const override;
|
|
|
|
/// <summary> Retrieve this glove's hardware (sub) version. </summary>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
virtual std::string GetHardwareVersion() const override;
|
|
|
|
/// <summary> Retrieve this device's firmware version. </summary>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
virtual int32_t GetFirmwareVersion() const override;
|
|
|
|
/// <summary> Retrieve this device's sub-firmware version. </summary>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
virtual int32_t GetSubFirmwareVersion() const override;
|
|
|
|
public:
|
|
/// <summary> Get the latest Sensor Data from this Sense Glove. </summary>
|
|
bool GetSensorData(SenseGloveSensorData& out_sensorData) const;
|
|
|
|
virtual bool GetImuRotation(Kinematics::Quat& out_imu) override;
|
|
|
|
/// <summary> Get the pose of this Sense Glove's hardware, based on its latest Sensor Data. </summary>
|
|
bool GetGlovePose(SenseGlovePose& out_glovePose);
|
|
|
|
/// <summary> Get the pose of this Sense Glove's hardware based on a set of Sensor Data. </summary>
|
|
bool GetGlovePose(const SenseGloveSensorData& sensorData, SenseGlovePose& out_glovePose);
|
|
|
|
/// <summary> Retrieve a new hand pose using this glove's data, based on (calibrated) user data. </summary>
|
|
bool GetHandPose(const Kinematics::BasicHandModel& handGeometry, const SenseGloveHandProfile& profile,
|
|
HandPose& out_handPose);
|
|
|
|
/// <summary> Calculate the Hand Pose of this device, provided it has Hand Tracking available. </summary>
|
|
virtual bool GetHandPose(const Kinematics::BasicHandModel& handGeometry, const HandProfile& handProfile,
|
|
HandPose& out_handPose) override;
|
|
|
|
/// <summary> Calculate the HandPose of this Device, taking into account user values, but not hand geometry. </summary>
|
|
bool GetHandPose(const HandProfile& handProfile, HandPose& out_handPose) override;
|
|
|
|
public:
|
|
//--------------------------------------------------------------------------------------
|
|
// Feedback Methods
|
|
|
|
/// <summary> Set the level(s) of Force and Vibrotactile feedback, with an optional thumper command. </summary>
|
|
bool SendHaptics(const Haptics::ForceFeedbackCommand& forceFeedbackCommand,
|
|
const Haptics::BuzzCommand& buzzCommand,
|
|
Haptics::ESenseGloveThumperCommand thumperCommand = Haptics::ESenseGloveThumperCommand::None);
|
|
|
|
/// <summary> Send a thumper command. </summary>
|
|
bool SendHaptics(Haptics::ESenseGloveThumperCommand thumperCommand);
|
|
|
|
/// <summary> Send Haptic Commands to this Glove. </summary>
|
|
virtual void SendHaptics(const Haptics::ForceFeedbackCommand& forceFeedbackCommand) override;
|
|
|
|
/// <summary> Send Haptic Commands to this Glove. </summary>
|
|
virtual void SendHaptics(const Haptics::BuzzCommand& buzzCommand) override;
|
|
|
|
/// <summary> Retrieve this device's firmware version. </summary>
|
|
virtual void SendHaptics(const Haptics::ForceFeedbackCommand& forceFeedbackCommand,
|
|
const Haptics::BuzzCommand& buzzCommand,
|
|
const Haptics::ThumperCommand& thumperCommand) override;
|
|
|
|
public:
|
|
//--------------------------------------------------------------------------------------
|
|
// Calibration Methods
|
|
|
|
/// <summary> Retrieve calibration values of this glove, as an array of size 5, containing x (roll), y (flexion), z (abduction) values. </summary>
|
|
virtual bool GetCalibrationValues(std::vector<SGCore::Kinematics::Vect3D>& out_values) override;
|
|
|
|
/// <summary> Reset the glove's calibration range. </summary>
|
|
virtual void ResetCalibrationRange() override;
|
|
|
|
/// <summary> Apply this glove's calibration range to a handProfile. </summary>
|
|
virtual void ApplyCalibration(HandProfile& profile) const override;
|
|
|
|
/// <summary> Apply this glove's calibration range to a SenseGloveHandProfile. </summary>
|
|
void ApplyCalibration(SenseGloveHandProfile& profile) const;
|
|
|
|
public:
|
|
//--------------------------------------------------------------------------------------
|
|
// 6DoF Position Tracking
|
|
|
|
/// <summary> Retrieve the location of the glove origin, based on a reference location. </summary>
|
|
/// <param name="referencePosition">Position of the tracked object, in mm, relative to your origin</param>
|
|
/// <param name="referenceRotation">Rotation of the tracked object relative to your origin</param>
|
|
/// <param name="trackingHardware">The hardware mounted on the SenseGlove.</param>
|
|
/// <param name="out_glovePosition">The 3D Position of the glove, in mm, relative to your origin</param>
|
|
/// <param name="out_gloveRotation">The 3D Rotation of the glove, relative to your origin</param>
|
|
virtual void GetGloveLocation(
|
|
const Kinematics::Vect3D& referencePosition, const Kinematics::Quat& referenceRotation,
|
|
EPositionalTrackingHardware trackingHardware,
|
|
Kinematics::Vect3D& out_glovePosition, Kinematics::Quat& out_gloveRotation) const override;
|
|
|
|
/// <summary> Retrieve the location of the glove origin, based on a reference location. </summary>
|
|
/// <param name="referencePosition">Position of the tracked object, in mm, relative to your origin</param>
|
|
/// <param name="referenceRotation">Rotation of the tracked object relative to your origin</param>
|
|
/// <param name="trackingHardware">The hardware mounted on the SenseGlove.</param>
|
|
/// <param name="mountedOn">Which finger module the hardware is mounted on.</param>
|
|
/// <param name="out_glovePosition">The 3D Position of the glove, in mm, relative to your origin</param>
|
|
/// <param name="out_gloveRotation">The 3D Rotation of the glove, relative to your origin</param>
|
|
void GetGloveLocation(const Kinematics::Vect3D& referencePosition, const Kinematics::Quat& referenceRotation,
|
|
EPositionalTrackingHardware trackingHardware, EFinger mountedOn,
|
|
Kinematics::Vect3D& out_glovePosition, Kinematics::Quat& out_gloveRotation) const;
|
|
|
|
/// <summary> Retrieve the location of the wrist, based on a reference location and default glove-hand offsets. </summary>
|
|
/// <remarks> The simplest interface, using default offsets </remarks>
|
|
/// <param name="referencePosition">Position of the tracked object, in mm, relative to your origin</param>
|
|
/// <param name="referenceRotation">Rotation of the tracked object relative to your origin</param>
|
|
/// <param name="trackingHardware">The hardware mounted on the SenseGlove.</param>
|
|
/// <param name="out_wristPosition">The 3D Position of the wrist, in mm, relative to your origin</param>
|
|
/// <param name="out_wristRotation">The 3D Rotation of the wrist, relative to your origin</param>
|
|
virtual void GetWristLocation(
|
|
const Kinematics::Vect3D& referencePosition, const Kinematics::Quat& referenceRotation,
|
|
EPositionalTrackingHardware trackingHardware,
|
|
Kinematics::Vect3D& out_wristPosition, Kinematics::Quat& out_wristRotation) const override;
|
|
|
|
/// <summary> Retrieve the location of the wrist, based on a reference location and default glove-hand offsets. </summary>
|
|
/// <param name="referencePosition"></param>
|
|
/// <param name="referenceRotation"></param>
|
|
/// <param name="trackingHardware">The hardware mounted on the SenseGlove.</param>
|
|
/// <param name="gloveWristPositionOffset">Position offset, in mm, from the glove origin to wrist (default = 0,0,-30 mm)</param>
|
|
/// <param name="gloveWristRotationOff">Rotation offset from the glove origin to wrist (default = 0,-5,0 degrees)</param>
|
|
/// <param name="out_wristPosition">The 3D Position of the wrist, in mm, relative to your origin</param>
|
|
/// <param name="out_wristRotation">The 3D Rotation of the wrist, relative to your origin</param>
|
|
void GetWristLocation(const Kinematics::Vect3D& referencePosition, const Kinematics::Quat& referenceRotation,
|
|
EPositionalTrackingHardware trackingHardware,
|
|
const Kinematics::Vect3D& gloveWristPositionOffset,
|
|
const Kinematics::Quat& gloveWristRotationOffset,
|
|
Kinematics::Vect3D& out_wristPosition, Kinematics::Quat& out_wristRotation) const;
|
|
|
|
public:
|
|
/// <summary> Create a string representation of this device for reporting purposes. </summary>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
virtual std::string ToString() const override;
|
|
|
|
protected:
|
|
//--------------------------------------------------------------------------------------
|
|
// Internal Methods
|
|
|
|
/// <summary> Convert a Force-Feedback command to a string which can be sent to this particular Sense Glove device. </summary>
|
|
/// <remarks> Implemented here because the conversion may depend on firmware/hardware version. </remarks>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
std::string ToBytes(const Haptics::FingerCommand& fingerCommand) const;
|
|
|
|
/// <summary> Convert a Thumper command into a string that this SenseGlove can understand. </summary>
|
|
/// <param name="thumperCommand"></param>
|
|
/// <returns></returns>
|
|
#if !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN )
|
|
[[nodiscard]]
|
|
#endif /* !defined ( SENSEGLOVE_UNREAL_ENGINE_PLUGIN ) */
|
|
std::string ToBytes(const Haptics::ThumperCommand& thumperCommand) const;
|
|
};
|