spline.h

//
// Copyright 2023 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
 
#ifndef PXR_BASE_TS_SPLINE_H
#define PXR_BASE_TS_SPLINE_H
 
#include "pxr/pxr.h"
#include "pxr/base/ts/api.h"
#include "pxr/base/ts/keyFrame.h"
#include "pxr/base/ts/keyFrameMap.h"
#include "pxr/base/ts/types.h"
#include "pxr/base/ts/loopParams.h"
#include "pxr/base/vt/value.h"
 
#include <vector>
#include <limits>
#include <map>
#include <typeinfo>
#include <iostream>
#include <optional>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class TsSpline_KeyFrames;
 
class TsSpline final
{
public:
    TS_API
    TsSpline();
 
    TS_API
    TsSpline(const TsSpline &other);
 
    TS_API
    explicit TsSpline( const TsKeyFrameMap & keyFrames,
             TsExtrapolationType leftExtrapolation = TsExtrapolationHeld,
             TsExtrapolationType rightExtrapolation = TsExtrapolationHeld,
             const TsLoopParams &loopParams = TsLoopParams());
 
    TS_API
    explicit TsSpline( const std::vector<TsKeyFrame> & keyFrames,
             TsExtrapolationType leftExtrapolation = TsExtrapolationHeld,
             TsExtrapolationType rightExtrapolation = TsExtrapolationHeld,
             const TsLoopParams &loopParams = TsLoopParams());
 
    TS_API
    bool operator==(const TsSpline &rhs) const;
 
    TS_API
    bool operator!=(const TsSpline &rhs) const;
 
    TS_API
    bool IsEmpty() const;
 
    TS_API
    void SwapKeyFrames(std::vector<TsKeyFrame>* swapInto);
 
    TS_API
    bool ClearRedundantKeyFrames( const VtValue &defaultValue = VtValue(),
                                  const GfMultiInterval &intervals =
                                        GfMultiInterval(GfInterval(
                                    -std::numeric_limits<double>::infinity(),
                                    std::numeric_limits<double>::infinity())));
 
 
    TS_API
    const TsKeyFrameMap& GetKeyFrames() const;
 
    TS_API
    const TsKeyFrameMap& GetRawKeyFrames() const;
 
    TS_API
    std::vector<TsKeyFrame>
    GetKeyFramesInMultiInterval(const GfMultiInterval &) const;
 
    TS_API
    GfInterval GetFrameRange() const;
 
    TS_API
    void SetKeyFrame(
        TsKeyFrame kf, GfInterval *intervalAffected=nullptr );
 
    TS_API
    bool CanSetKeyFrame(
        const TsKeyFrame & kf, std::string *reason=nullptr ) const;
 
    TS_API
    std::optional<TsKeyFrame>
    Breakdown( double x, TsKnotType type,
               bool flatTangents, double tangentLength,
               const VtValue &value = VtValue(),
               GfInterval *intervalAffected=nullptr );
 
    TS_API
    void
    Breakdown( const std::set<double> & times, TsKnotType type,
               bool flatTangents, double tangentLength,
               const VtValue &value = VtValue(), 
               GfInterval *intervalAffected=nullptr,
               TsKeyFrameMap *keyFramesAtTimes=nullptr);
 
    TS_API
    void
    Breakdown( const std::vector<double> & times, TsKnotType type,
               bool flatTangents, double tangentLength,
               const std::vector<VtValue> & values,
               GfInterval *intervalAffected=nullptr,
               TsKeyFrameMap *keyFramesAtTimes=nullptr);
 
    TS_API
    void
    Breakdown( const std::vector<double> & times, 
               const std::vector<TsKnotType> & types,
               bool flatTangents, double tangentLength,
               const std::vector<VtValue> & values,
               GfInterval *intervalAffected=nullptr,
               TsKeyFrameMap *keyFramesAtTimes=nullptr);
 
    TS_API
    void RemoveKeyFrame(
        TsTime time, GfInterval *intervalAffected=nullptr);
 
    TS_API
    void Clear();
 
    TS_API
    std::optional<TsKeyFrame>
    GetClosestKeyFrame( TsTime targetTime ) const;
 
    TS_API
    std::optional<TsKeyFrame>
    GetClosestKeyFrameBefore( TsTime targetTime )const;
 
    TS_API
    std::optional<TsKeyFrame>
    GetClosestKeyFrameAfter( TsTime targetTime ) const;
 
    TS_API
    bool IsKeyFrameRedundant( const TsKeyFrame &keyFrame,
                              const VtValue &defaultValue = VtValue() ) const;
 
    TS_API
    bool IsKeyFrameRedundant( TsTime keyFrameTime,
                              const VtValue &defaultValue = VtValue() ) const;
 
    TS_API
    bool HasRedundantKeyFrames( const VtValue &defaultValue = VtValue() ) const;
 
    TS_API
    bool IsSegmentFlat( const TsKeyFrame &kf1, 
                        const TsKeyFrame &kf2 ) const;
 
    TS_API
    bool IsSegmentFlat( TsTime startTime, TsTime endTime ) const;
                         
    TS_API
    bool
    IsSegmentValueMonotonic( const TsKeyFrame &kf1, 
                             const TsKeyFrame &kf2 ) const;
 
    TS_API
    bool 
    IsSegmentValueMonotonic( TsTime startTime, TsTime endTime ) const;
 
    TS_API
    bool
    IsVarying() const;
 
    TS_API
    bool
    IsVaryingSignificantly() const;
 
    TS_API
    void SetExtrapolation(
            TsExtrapolationType left, TsExtrapolationType right);
 
    TS_API
    std::pair<TsExtrapolationType, TsExtrapolationType>
    GetExtrapolation() const;
 
    TS_API
    const std::type_info &
    GetTypeid() const;
 
    TS_API
    TfType
    GetType() const;
 
    TS_API
    std::string GetTypeName() const;
    
    TS_API
    VtValue Eval(
        TsTime time, TsSide side=TsRight ) const;
 
    TS_API
    VtValue EvalHeld( TsTime time, TsSide side=TsRight ) const;
 
    TS_API
    VtValue EvalDerivative(
        TsTime time, TsSide side=TsRight ) const;
 
    TS_API
    bool DoSidesDiffer(TsTime time) const;
 
    TS_API
    TsSamples Sample(
        TsTime startTime, TsTime endTime,
        double timeScale, double valueScale,
        double tolerance ) const;
 
    TS_API
    std::pair<VtValue, VtValue>
    GetRange( TsTime startTime, TsTime endTime ) const;
 
    TS_API
    bool IsLinear() const;
 
    TS_API
    bool KeyFrameIsInLoopedRange(const TsKeyFrame & kf);
 
    TS_API
    TsLoopParams GetLoopParams() const;
 
    TS_API
    void SetLoopParams(const TsLoopParams&);
 
    // If this spline is a looping spline, bakes the looped key frames
    // out and turns looping off.  Hidden keyframes will be lost.
    TS_API
    void BakeSplineLoops();
 
    TS_API
    bool IsTimeLooped(TsTime time) const;
 
    typedef TsKeyFrameMap::const_iterator const_iterator;
    typedef TsKeyFrameMap::const_reverse_iterator const_reverse_iterator;
 
    typedef const_iterator iterator;
    typedef const_reverse_iterator reverse_iterator;
 
 
    TS_API
    size_t size() const {
        return GetKeyFrames().size();
    }
 
    TS_API
    bool empty() const {
        return GetKeyFrames().empty();
    }
    
    TS_API
    const_iterator begin() const {
        return const_iterator(GetKeyFrames().begin());
    }
 
    TS_API
    const_iterator end() const {
        return const_iterator(GetKeyFrames().end());
    }
 
    TS_API
    const_reverse_iterator rbegin() const {
        return const_reverse_iterator(GetKeyFrames().rbegin());
    }
 
    TS_API
    const_reverse_iterator rend() const {
        return const_reverse_iterator(GetKeyFrames().rend());
    }
 
 
    TS_API
    const_iterator find(const TsTime &t) const;
 
    TS_API
    const_iterator lower_bound(const TsTime &t) const;
 
    TS_API
    const_iterator upper_bound(const TsTime &t) const;
 
    TS_API
    size_t count(const TsTime &t) const {
        return GetKeyFrames().find(t) != GetKeyFrames().end();
    }
 
 
private:
 
    void _BreakdownMultipleValues( const std::vector<double> &times,
       TsKnotType type, bool flatTangents, double tangentLength,
       const std::vector<VtValue> &values,
       GfInterval *intervalAffected,
       TsKeyFrameMap *keyFramesAtTimes);
 
    void _BreakdownMultipleKnotTypes( const std::vector<double> &times,
       const std::vector<TsKnotType> &types,
       bool flatTangents, double tangentLength,
       const std::vector<VtValue> &values,
       GfInterval *intervalAffected,
       TsKeyFrameMap *keyFramesAtTimes);
 
    // Fills \p keyframes with the new keyframes to effect a breakdown
    // at \p x.  Subclasses can use this to implement \c Breakdown();
    // they'll call this then set each key frame in \p keyframes.
    void
    _GetBreakdown( TsKeyFrameMap* newKeyframes, double x, TsKnotType type,
                   bool flatTangents, double tangentLength,
                   const VtValue &value ) const;
 
    typedef std::vector<std::pair<TsTime, VtValue>> _Samples;
 
    // Helper for _BreakdownMultipleKnotTypes. Performs the Breakdown on the 
    // given list of samples, i.e. time/value pairs.
    void _BreakdownSamples(
        const _Samples &samples,
        TsKnotType type, 
        bool flatTangents,
        double tangentLength,
        GfInterval *intervalAffected,
        TsKeyFrameMap *keyFramesAtTimes);
 
    // Helper for the forms of IsVarying*; allows subseqent keyframes to vary
    // by 'tolerance'.
    bool _IsVarying(double tolerance) const;
 
    void _Detach();
 
private:
    std::shared_ptr<TsSpline_KeyFrames> _data;
};
 
TS_API
std::ostream& operator<<(std::ostream &out, const TsSpline &val);
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif