OpenShot Library | libopenshot  0.2.4
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 <iostream>
35 #include <iomanip>
36 #include <math.h>
37 #include <assert.h>
38 #include <vector>
39 #include "Exceptions.h"
40 #include "Fraction.h"
41 #include "Coordinate.h"
42 #include "Point.h"
43 #include "Json.h"
44 
45 namespace openshot {
46 
47  /**
48  * @brief A Keyframe is a collection of Point instances, which is used to vary a number or property over time.
49  *
50  * Keyframes are used to animate and interpolate values of properties over time. For example, a single property
51  * can use a Keyframe instead of a constant value. Assume you want to slide an image (from left to right) over
52  * a video. You can create a Keyframe which will adjust the X value of the image over 100 frames (or however many
53  * frames the animation needs to last) from the value of 0 to 640.
54  *
55  * Please see the following <b>Example Code</b>:
56  * \code
57  * Keyframe k1;
58  * k1.AddPoint(Point(1,0));
59  * k1.AddPoint(Point(100,640));
60  *
61  * kf.PrintValues();
62  * \endcode
63  */
64  class Keyframe {
65  private:
66  std::vector<Point> Points; ///< Vector of all Points
67 
68  public:
69 
70  /// Default constructor for the Keyframe class
71  Keyframe() = default;
72 
73  /// Constructor which sets the default point & coordinate at X=1
74  Keyframe(double value);
75 
76  /// Add a new point on the key-frame. Each point has a primary coordinate, a left handle, and a right handle.
77  void AddPoint(Point p);
78 
79  /// Add a new point on the key-frame, with some defaults set (BEZIER)
80  void AddPoint(double x, double y);
81 
82  /// Add a new point on the key-frame, with a specific interpolation type
83  void AddPoint(double x, double y, InterpolationType interpolate);
84 
85  /// Does this keyframe contain a specific point
86  bool Contains(Point p) const;
87 
88  /// Flip all the points in this openshot::Keyframe (useful for reversing an effect or transition, etc...)
89  void FlipPoints();
90 
91  /// Get the index of a point by matching a coordinate
92  int64_t FindIndex(Point p) const;
93 
94  /// Get the value at a specific index
95  double GetValue(int64_t index) const;
96 
97  /// Get the rounded INT value at a specific index
98  int GetInt(int64_t index) const;
99 
100  /// Get the rounded LONG value at a specific index
101  int64_t GetLong(int64_t index) const;
102 
103  /// Get the fraction that represents how many times this value is repeated in the curve
104  Fraction GetRepeatFraction(int64_t index) const;
105 
106  /// Get the change in Y value (from the previous Y value)
107  double GetDelta(int64_t index) const;
108 
109  /// Get a point at a specific index
110  Point const & GetPoint(int64_t index) const;
111 
112  /// Get current point (or closest point to the right) from the X coordinate (i.e. the frame number)
113  Point GetClosestPoint(Point p) const;
114 
115  /// Get current point (or closest point) from the X coordinate (i.e. the frame number)
116  /// Either use the closest left point, or right point
117  Point GetClosestPoint(Point p, bool useLeft) const;
118 
119  /// Get previous point (
120  Point GetPreviousPoint(Point p) const;
121 
122  /// Get max point (by Y coordinate)
123  Point GetMaxPoint() const;
124 
125  // Get the number of values (i.e. coordinates on the X axis)
126  int64_t GetLength() const;
127 
128  /// Get the number of points (i.e. # of points)
129  int64_t GetCount() const;
130 
131  /// Get the direction of the curve at a specific index (increasing or decreasing)
132  bool IsIncreasing(int index) const;
133 
134  /// Get and Set JSON methods
135  std::string Json() const; ///< Generate JSON string of this object
136  Json::Value JsonValue() const; ///< Generate Json::JsonValue for this object
137  void SetJson(std::string value); ///< Load JSON string into this object
138  void SetJsonValue(Json::Value root); ///< Load Json::JsonValue into this object
139 
140  /// Remove a point by matching a coordinate
141  void RemovePoint(Point p);
142 
143  /// Remove a point by index
144  void RemovePoint(int64_t index);
145 
146  /// Scale all points by a percentage (good for evenly lengthening or shortening an openshot::Keyframe)
147  /// 1.0 = same size, 1.05 = 5% increase, etc...
148  void ScalePoints(double scale);
149 
150  /// Replace an existing point with a new point
151  void UpdatePoint(int64_t index, Point p);
152 
153  /// Print a list of points
154  void PrintPoints() const;
155 
156  /// Print just the Y value of the point's primary coordinate
157  void PrintValues() const;
158 
159  };
160 
161 }
162 
163 #endif
double GetDelta(int64_t index) const
Get the change in Y value (from the previous Y value)
Definition: KeyFrame.cpp:497
Header file for Fraction class.
Point GetMaxPoint() const
Get max point (by Y coordinate)
Definition: KeyFrame.cpp:249
void FlipPoints()
Flip all the points in this openshot::Keyframe (useful for reversing an effect or transition...
Definition: KeyFrame.cpp:602
Point const & GetPoint(int64_t index) const
Get a point at a specific index.
Definition: KeyFrame.cpp:505
int64_t GetLong(int64_t index) const
Get the rounded LONG value at a specific index.
Definition: KeyFrame.cpp:291
Header file for Point class.
void ScalePoints(double scale)
Definition: KeyFrame.cpp:588
A Point is the basic building block of a key-frame curve.
Definition: Point.h:82
Point GetPreviousPoint(Point p) const
Get previous point (.
Definition: KeyFrame.cpp:230
bool IsIncreasing(int index) const
Get the direction of the curve at a specific index (increasing or decreasing)
Definition: KeyFrame.cpp:296
bool Contains(Point p) const
Does this keyframe contain a specific point.
Definition: KeyFrame.cpp:188
void UpdatePoint(int64_t index, Point p)
Replace an existing point with a new point.
Definition: KeyFrame.cpp:559
int GetInt(int64_t index) const
Get the rounded INT value at a specific index.
Definition: KeyFrame.cpp:286
void SetJsonValue(Json::Value root)
Load Json::JsonValue into this object.
Definition: KeyFrame.cpp:374
void AddPoint(Point p)
Add a new point on the key-frame. Each point has a primary coordinate, a left handle, and a right handle.
Definition: KeyFrame.cpp:125
Keyframe()=default
Default constructor for the Keyframe class.
Header file for all Exception classes.
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:225
void PrintPoints() const
Print a list of points.
Definition: KeyFrame.cpp:567
void RemovePoint(Point p)
Remove a point by matching a coordinate.
Definition: KeyFrame.cpp:528
Header file for JSON class.
This class represents a fraction.
Definition: Fraction.h:45
void SetJson(std::string value)
Load JSON string into this object.
Definition: KeyFrame.cpp:345
void PrintValues() const
Print just the Y value of the point&#39;s primary coordinate.
Definition: KeyFrame.cpp:575
InterpolationType
This controls how a Keyframe uses this point to interpolate between two points.
Definition: Point.h:46
This namespace is the default namespace for all code in the openshot library.
Json::Value JsonValue() const
Generate Json::JsonValue for this object.
Definition: KeyFrame.cpp:329
int64_t FindIndex(Point p) const
Get the index of a point by matching a coordinate.
Definition: KeyFrame.cpp:170
Header file for Coordinate class.
int64_t GetCount() const
Get the number of points (i.e. # of points)
Definition: KeyFrame.cpp:522
double GetValue(int64_t index) const
Get the value at a specific index.
Definition: KeyFrame.cpp:262
Fraction GetRepeatFraction(int64_t index) const
Get the fraction that represents how many times this value is repeated in the curve.
Definition: KeyFrame.cpp:394
A Keyframe is a collection of Point instances, which is used to vary a number or property over time...
Definition: KeyFrame.h:64
int64_t GetLength() const
Definition: KeyFrame.cpp:515
std::string Json() const
Get and Set JSON methods.
Definition: KeyFrame.cpp:322