OpenShot Library | libopenshot  0.2.7
KeyFrame.h
Go to the documentation of this file.
1 /**
2  * @file
3  * @brief Header file for the Keyframe class
4  * @author Jonathan Thomas <jonathan@openshot.org>
5  *
6  * @ref License
7  */
8 
9 /* LICENSE
10  *
11  * Copyright (c) 2008-2019 OpenShot Studios, LLC
12  * <http://www.openshotstudios.com/>. This file is part of
13  * OpenShot Library (libopenshot), an open-source project dedicated to
14  * delivering high quality video editing and animation solutions to the
15  * world. For more information visit <http://www.openshot.org/>.
16  *
17  * OpenShot Library (libopenshot) is free software: you can redistribute it
18  * and/or modify it under the terms of the GNU Lesser General Public License
19  * as published by the Free Software Foundation, either version 3 of the
20  * License, or (at your option) any later version.
21  *
22  * OpenShot Library (libopenshot) is distributed in the hope that it will be
23  * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25  * GNU Lesser General Public License for more details.
26  *
27  * You should have received a copy of the GNU Lesser General Public License
28  * along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>.
29  */
30 
31 #ifndef OPENSHOT_KEYFRAME_H
32 #define OPENSHOT_KEYFRAME_H
33 
34 #include <cmath>
35 #include <vector>
36 
37 #include "Fraction.h"
38 #include "Point.h"
39 #include "Json.h"
40 
41 namespace openshot {
42 
43  /// Check if the X coordinate of a given Point is lower than a given value
44  bool IsPointBeforeX(Point const & p, double const x);
45 
46  /// Linear interpolation between two points
47  double InterpolateLinearCurve(Point const & left, Point const & right, double const target);
48 
49  /// Bezier interpolation between two points
50  double InterpolateBezierCurve(Point const & left, Point const & right, double const target, double const allowed_error);
51 
52  /// Interpolate two points using the right Point's interpolation method
53  double InterpolateBetween(Point const & left, Point const & right, double target, double allowed_error);
54 
55  /**
56  * @brief A Keyframe is a collection of Point instances, which is used to vary a number or property over time.
57  *
58  * Keyframes are used to animate and interpolate values of properties over time. For example, a single property
59  * can use a Keyframe instead of a constant value. Assume you want to slide an image (from left to right) over
60  * a video. You can create a Keyframe which will adjust the X value of the image over 100 frames (or however many
61  * frames the animation needs to last) from the value of 0 to 640.
62  *
63  * Please see the following <b>Example Code</b>:
64  * \code
65  * Keyframe k1;
66  * k1.AddPoint(Point(1,0));
67  * k1.AddPoint(Point(100,640));
68  *
69  * kf.PrintValues();
70  * \endcode
71  */
72  class Keyframe {
73 
74 
75  private:
76  std::vector<Point> Points; ///< Vector of all Points
77 
78  public:
79  /// Default constructor for the Keyframe class
80  Keyframe() = default;
81 
82  /// Constructor which sets the default point & coordinate at X=1
83  Keyframe(double value);
84 
85  /// Constructor which adds a supplied vector of Points
86  Keyframe(const std::vector<openshot::Point>& points);
87 
88  /// Add a new point on the key-frame. Each point has a primary coordinate, a left handle, and a right handle.
89  void AddPoint(Point p);
90 
91  /// Add a new point on the key-frame, with optional interpolation type
92  void AddPoint(double x, double y, InterpolationType interpolate=BEZIER);
93 
94  /// Does this keyframe contain a specific point
95  bool Contains(Point p) const;
96 
97  /// Flip all the points in this openshot::Keyframe (useful for reversing an effect or transition, etc...)
98  void FlipPoints();
99 
100  /// Get the index of a point by matching a coordinate
101  int64_t FindIndex(Point p) const;
102 
103  /// Get the value at a specific index
104  double GetValue(int64_t index) const;
105 
106  /// Get the rounded INT value at a specific index
107  int GetInt(int64_t index) const;
108 
109  /// Get the rounded LONG value at a specific index
110  int64_t GetLong(int64_t index) const;
111 
112  /// Get the fraction that represents how many times this value is repeated in the curve
113  Fraction GetRepeatFraction(int64_t index) const;
114 
115  /// Get the change in Y value (from the previous Y value)
116  double GetDelta(int64_t index) const;
117 
118  /// Get a point at a specific index
119  Point const & GetPoint(int64_t index) const;
120 
121  /// Get current point (or closest point to the right) from the X coordinate (i.e. the frame number)
122  Point GetClosestPoint(Point p) const;
123 
124  /// Get current point (or closest point) from the X coordinate (i.e. the frame number)
125  /// Either use the closest left point, or right point
126  Point GetClosestPoint(Point p, bool useLeft) const;
127 
128  /// Get previous point (
129  Point GetPreviousPoint(Point p) const;
130 
131  /// Get max point (by Y coordinate)
132  Point GetMaxPoint() const;
133 
134  // Get the number of values (i.e. coordinates on the X axis)
135  int64_t GetLength() const;
136 
137  /// Get the number of points (i.e. # of points)
138  int64_t GetCount() const;
139 
140  /// Get the direction of the curve at a specific index (increasing or decreasing)
141  bool IsIncreasing(int index) const;
142 
143  // Get and Set JSON methods
144  std::string Json() const; ///< Generate JSON string of this object
145  Json::Value JsonValue() const; ///< Generate Json::Value for this object
146  void SetJson(const std::string value); ///< Load JSON string into this object
147  void SetJsonValue(const Json::Value root); ///< Load Json::Value into this object
148 
149  /// Remove a point by matching a coordinate
150  void RemovePoint(Point p);
151 
152  /// Remove a point by index
153  void RemovePoint(int64_t index);
154 
155  /// Scale all points by a percentage (good for evenly lengthening or shortening an openshot::Keyframe)
156  /// 1.0 = same size, 1.05 = 5% increase, etc...
157  void ScalePoints(double scale);
158 
159  /// Replace an existing point with a new point
160  void UpdatePoint(int64_t index, Point p);
161 
162  /// Print a list of points
163  void PrintPoints() const;
164 
165  /// Print just the Y value of the point's primary coordinate
166  void PrintValues() const;
167 
168  };
169 
170 }
171 
172 #endif
Header file for Fraction class.
Header file for JSON class.
Header file for Point class.
This class represents a fraction.
Definition: Fraction.h:48
A Keyframe is a collection of Point instances, which is used to vary a number or property over time.
Definition: KeyFrame.h:72
int64_t FindIndex(Point p) const
Get the index of a point by matching a coordinate.
Definition: KeyFrame.cpp:176
void RemovePoint(Point p)
Remove a point by matching a coordinate.
Definition: KeyFrame.cpp:522
void SetJson(const std::string value)
Load JSON string into this object.
Definition: KeyFrame.cpp:351
bool Contains(Point p) const
Does this keyframe contain a specific point.
Definition: KeyFrame.cpp:194
Point GetMaxPoint() const
Get max point (by Y coordinate)
Definition: KeyFrame.cpp:255
int GetInt(int64_t index) const
Get the rounded INT value at a specific index.
Definition: KeyFrame.cpp:292
void SetJsonValue(const Json::Value root)
Load Json::Value into this object.
Definition: KeyFrame.cpp:368
void AddPoint(Point p)
Add a new point on the key-frame. Each point has a primary coordinate, a left handle,...
Definition: KeyFrame.cpp:141
double GetDelta(int64_t index) const
Get the change in Y value (from the previous Y value)
Definition: KeyFrame.cpp:491
Point const & GetPoint(int64_t index) const
Get a point at a specific index.
Definition: KeyFrame.cpp:499
int64_t GetLength() const
Definition: KeyFrame.cpp:509
Fraction GetRepeatFraction(int64_t index) const
Get the fraction that represents how many times this value is repeated in the curve.
Definition: KeyFrame.cpp:388
void PrintValues() const
Print just the Y value of the point's primary coordinate.
Definition: KeyFrame.cpp:570
Point GetPreviousPoint(Point p) const
Get previous point (.
Definition: KeyFrame.cpp:236
int64_t GetLong(int64_t index) const
Get the rounded LONG value at a specific index.
Definition: KeyFrame.cpp:297
void UpdatePoint(int64_t index, Point p)
Replace an existing point with a new point.
Definition: KeyFrame.cpp:554
void ScalePoints(double scale)
Definition: KeyFrame.cpp:583
std::string Json() const
Generate JSON string of this object.
Definition: KeyFrame.cpp:328
double GetValue(int64_t index) const
Get the value at a specific index.
Definition: KeyFrame.cpp:268
Json::Value JsonValue() const
Generate Json::Value for this object.
Definition: KeyFrame.cpp:335
void FlipPoints()
Flip all the points in this openshot::Keyframe (useful for reversing an effect or transition,...
Definition: KeyFrame.cpp:597
void PrintPoints() const
Print a list of points.
Definition: KeyFrame.cpp:562
Keyframe()=default
Default constructor for the Keyframe class.
bool IsIncreasing(int index) const
Get the direction of the curve at a specific index (increasing or decreasing)
Definition: KeyFrame.cpp:302
int64_t GetCount() const
Get the number of points (i.e. # of points)
Definition: KeyFrame.cpp:516
Point GetClosestPoint(Point p) const
Get current point (or closest point to the right) from the X coordinate (i.e. the frame number)
Definition: KeyFrame.cpp:231
A Point is the basic building block of a key-frame curve.
Definition: Point.h:82
This namespace is the default namespace for all code in the openshot library.
Definition: Compressor.h:47
double InterpolateLinearCurve(Point const &left, Point const &right, double const target)
Linear interpolation between two points.
Definition: KeyFrame.cpp:52
double InterpolateBezierCurve(Point const &left, Point const &right, double const target, double const allowed_error)
Bezier interpolation between two points.
Definition: KeyFrame.cpp:60
bool IsPointBeforeX(Point const &p, double const x)
Check if the X coordinate of a given Point is lower than a given value.
Definition: KeyFrame.cpp:47
double InterpolateBetween(Point const &left, Point const &right, double target, double allowed_error)
Interpolate two points using the right Point's interpolation method.
Definition: KeyFrame.cpp:96
InterpolationType
This controls how a Keyframe uses this point to interpolate between two points.
Definition: Point.h:46
@ BEZIER
Bezier curves are quadratic curves, which create a smooth curve.
Definition: Point.h:47