OpenShot Library | libopenshot  0.2.5
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::Value for this object
137  void SetJson(const std::string value); ///< Load JSON string into this object
138  void SetJsonValue(const Json::Value root); ///< Load Json::Value 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
openshot::Keyframe::IsIncreasing
bool IsIncreasing(int index) const
Get the direction of the curve at a specific index (increasing or decreasing)
Definition: KeyFrame.cpp:296
Point.h
Header file for Point class.
openshot::Keyframe::GetLong
int64_t GetLong(int64_t index) const
Get the rounded LONG value at a specific index.
Definition: KeyFrame.cpp:291
Fraction.h
Header file for Fraction class.
openshot::Keyframe::Keyframe
Keyframe()=default
Default constructor for the Keyframe class.
openshot::Keyframe::FindIndex
int64_t FindIndex(Point p) const
Get the index of a point by matching a coordinate.
Definition: KeyFrame.cpp:170
openshot::Keyframe::RemovePoint
void RemovePoint(Point p)
Remove a point by matching a coordinate.
Definition: KeyFrame.cpp:516
openshot
This namespace is the default namespace for all code in the openshot library.
Definition: AudioBufferSource.h:39
openshot::Keyframe::Json
std::string Json() const
Get and Set JSON methods.
Definition: KeyFrame.cpp:322
openshot::Keyframe::GetDelta
double GetDelta(int64_t index) const
Get the change in Y value (from the previous Y value)
Definition: KeyFrame.cpp:485
openshot::Fraction
This class represents a fraction.
Definition: Fraction.h:45
openshot::Keyframe::GetMaxPoint
Point GetMaxPoint() const
Get max point (by Y coordinate)
Definition: KeyFrame.cpp:249
openshot::Keyframe::SetJsonValue
void SetJsonValue(const Json::Value root)
Load Json::Value into this object.
Definition: KeyFrame.cpp:362
openshot::Keyframe::Contains
bool Contains(Point p) const
Does this keyframe contain a specific point.
Definition: KeyFrame.cpp:188
openshot::Keyframe::GetRepeatFraction
Fraction GetRepeatFraction(int64_t index) const
Get the fraction that represents how many times this value is repeated in the curve.
Definition: KeyFrame.cpp:382
openshot::Keyframe::JsonValue
Json::Value JsonValue() const
Generate Json::Value for this object.
Definition: KeyFrame.cpp:329
openshot::Keyframe::AddPoint
void AddPoint(Point p)
Add a new point on the key-frame. Each point has a primary coordinate, a left handle,...
Definition: KeyFrame.cpp:125
Coordinate.h
Header file for Coordinate class.
openshot::Keyframe
A Keyframe is a collection of Point instances, which is used to vary a number or property over time.
Definition: KeyFrame.h:64
openshot::Keyframe::SetJson
void SetJson(const std::string value)
Load JSON string into this object.
Definition: KeyFrame.cpp:345
openshot::Keyframe::PrintPoints
void PrintPoints() const
Print a list of points.
Definition: KeyFrame.cpp:555
openshot::Keyframe::UpdatePoint
void UpdatePoint(int64_t index, Point p)
Replace an existing point with a new point.
Definition: KeyFrame.cpp:547
openshot::Keyframe::GetPoint
Point const & GetPoint(int64_t index) const
Get a point at a specific index.
Definition: KeyFrame.cpp:493
openshot::Keyframe::PrintValues
void PrintValues() const
Print just the Y value of the point's primary coordinate.
Definition: KeyFrame.cpp:563
openshot::Keyframe::GetClosestPoint
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
openshot::Keyframe::GetLength
int64_t GetLength() const
Definition: KeyFrame.cpp:503
openshot::Keyframe::GetInt
int GetInt(int64_t index) const
Get the rounded INT value at a specific index.
Definition: KeyFrame.cpp:286
openshot::Keyframe::GetCount
int64_t GetCount() const
Get the number of points (i.e. # of points)
Definition: KeyFrame.cpp:510
openshot::Keyframe::ScalePoints
void ScalePoints(double scale)
Definition: KeyFrame.cpp:576
openshot::Keyframe::GetPreviousPoint
Point GetPreviousPoint(Point p) const
Get previous point (.
Definition: KeyFrame.cpp:230
openshot::InterpolationType
InterpolationType
This controls how a Keyframe uses this point to interpolate between two points.
Definition: Point.h:46
openshot::Keyframe::FlipPoints
void FlipPoints()
Flip all the points in this openshot::Keyframe (useful for reversing an effect or transition,...
Definition: KeyFrame.cpp:590
Json.h
Header file for JSON class.
openshot::Point
A Point is the basic building block of a key-frame curve.
Definition: Point.h:82
Exceptions.h
Header file for all Exception classes.
openshot::Keyframe::GetValue
double GetValue(int64_t index) const
Get the value at a specific index.
Definition: KeyFrame.cpp:262