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

/**
 * @file
 *
 * @author  Mamadou Babaei <mamadou@senseglove.com>
 *
 * @section LICENSE
 *
 * (The MIT License)
 *
 * Copyright (c) 2020 - 2022 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
 *
 *
 */


#pragma once

#include "Containers/Array.h"
#include "Containers/UnrealString.h"
#include "Templates/UniquePtr.h"

#include "SGCore/SGHapticGloveCalibrationSequence.h"

#include "SGHapticGloveQuickCalibration.generated.h"

class FSGHapticGloveQuickCalibrationImpl;

/**
 *
 */
UCLASS(BlueprintType)
class SENSEGLOVECORE_API USGHapticGloveQuickCalibration final : public USGHapticGloveCalibrationSequence
{
    GENERATED_BODY()

public:
    static USGHapticGloveQuickCalibration* NewHapticGloveQuickCalibration(
        UObject* Outer, const FSGHapticGloveQuickCalibrationImpl& HapticGloveQuickCalibration);

    static USGHapticGloveQuickCalibration* NewHapticGloveQuickCalibration(
        UObject* Outer, TSharedRef<FSGHapticGloveQuickCalibrationImpl> HapticGloveQuickCalibration);

public:
    /**
     *
     */
    static USGHapticGloveQuickCalibration* NewHapticGloveQuickCalibration(UObject* Outer);

    /**
     * Create a new instance of a QuickCalibration for Haptic Gloves.
     */
    static USGHapticGloveQuickCalibration* NewHapticGloveQuickCalibration(
        UObject* Outer,
        const USGHapticGlove* GloveToCalibrate,
        float AutoEndTimeout = GetDefaultAutoEndTimeout());

public:
    /**
     * Default time in seconds, to end this sequence. 15 seconds is very quick for some people. 
     */
    static float GetDefaultAutoEndTimeout();

private:
    struct FImpl;

    struct FImplDeleter
    {
        void operator()(const FImpl* P) const;
    };

    TUniquePtr<FImpl, FImplDeleter> Pimpl;
    FImplDeleter PimplDeleter;

public:
    /**
     *
     */
    USGHapticGloveQuickCalibration();

    /**
     * Create a new instance of a QuickCalibration for Haptic Gloves.
     */
    explicit USGHapticGloveQuickCalibration(const USGHapticGlove* GloveToCalibrate,
                                            float AutoEndTimeout = GetDefaultAutoEndTimeout());

public:
    /**
     * The cast from underlying type constructor.
     */
    explicit USGHapticGloveQuickCalibration(const FSGHapticGloveQuickCalibrationImpl& HapticGloveQuickCalibrationImpl);

protected:
    /**
     * The cast from underlying pointer type constructor.
     */
    explicit USGHapticGloveQuickCalibration(
        TSharedRef<FSGHapticGloveQuickCalibrationImpl> HapticGloveQuickCalibrationImpl);

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

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

protected:
    /**
     * Allows the child classes to synchronize the parent's underlying object at any time.
     */
    virtual void SyncImplObject() const override;

    /**
     * Allows the child classes to synchronize the parent's uproperties at any time.
     */
    virtual void SyncUProperties() override;

public:
    /**
     * Time, in seconds, after which this sequence stops gathering data. Based on the deltaSeconds variable passed in the Update() function.
     */
    float GetAutoEndTimeout() const;

    /**
     * When compiling the final profile, we use a Weighted Moving Average filter with this period to filer out some outliers.
     */
    int32 GetSmoothingSamples() const;

    /**
     * The min/max values recorded during this calibration sequence.
     */
    USGSensorRange* GetSensorRange(UObject* Outer) const;

    /**
     * A temporary profile to apply the sensorRange to. Used to generate a 'preview' HandPose.
     */
    USGHandProfile* GetTemporaryProfile(UObject* Outer) const;

    /**
     * Determines if the user has moved enough so that we can animate.
     */
    bool CanAnimate() const;

public:
    /**
     * This sequence autocompletes after its autoEndTime has elapsed.
     */
    bool AutoCompleted() const;

public:
    /**
     * Resets data points, min/max ranges and profile.
     */
    void Reset();

    /**
     * Update this calibration sequence with new data. We use deltaSeconds to check for things like stability.
     */
    void Update(float DeltaSeconds);

    /**
     * Add a new datapoint to this sequence's collection. Updates the range and profile used to generate a preview.
     */
    void AddDataPoint(const TArray<FVector>& CalibrationData);

    /**
     * After we confirm the current step, we're basically done.
     */
    void ConfirmCurrentStep();

    /**
     * Compile a sensor range from the data points collected while the sequence was running. Smoothed by a Moving Average Filter.
     */
    bool CompileRange(UObject* Outer, USGSensorRange*& OutSensorRange) const;

    /**
     * Returns a 'preview' of what a HandPose with this sequence's current settings would look like.
     */
    bool GetHandPose(UObject* Outer, bool bRightHanded, USGHandPose*& OutCurrentHandPose) const;

    /**
     * Retrieve instructions on what to do during the current step.
     */
    FString GetCurrentInstruction(const FString& NextStepKey = FString{""}) const;
};