OpenShot Library | libopenshot  0.1.2
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  * @section LICENSE
7  *
8  * Copyright (c) 2008-2014 OpenShot Studios, LLC
9  * <http://www.openshotstudios.com/>. This file is part of
10  * OpenShot Library (libopenshot), an open-source project dedicated to
11  * delivering high quality video editing and animation solutions to the
12  * world. For more information visit <http://www.openshot.org/>.
13  *
14  * OpenShot Library (libopenshot) is free software: you can redistribute it
15  * and/or modify it under the terms of the GNU Lesser General Public License
16  * as published by the Free Software Foundation, either version 3 of the
17  * License, or (at your option) any later version.
18  *
19  * OpenShot Library (libopenshot) is distributed in the hope that it will be
20  * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22  * GNU Lesser General Public License for more details.
23  *
24  * You should have received a copy of the GNU Lesser General Public License
25  * along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>.
26  */
27 
28 #ifndef OPENSHOT_KEYFRAME_H
29 #define OPENSHOT_KEYFRAME_H
30 
31 #include <iostream>
32 #include <iomanip>
33 #include <math.h>
34 #include <assert.h>
35 #include <vector>
36 #include "Exceptions.h"
37 #include "Fraction.h"
38 #include "Coordinate.h"
39 #include "Point.h"
40 #include "Json.h"
41 
42 using namespace std;
43 using namespace openshot;
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  bool needs_update;
67  double FactorialLookup[4];
68 
69  /*
70  * Because points can be added in any order, we need to reorder them
71  * in ascending order based on the point.co.X value. This simplifies
72  * processing the curve, due to all the points going from left to right.
73  */
74  void ReorderPoints();
75 
76  // Process an individual segment
77  void ProcessSegment(int Segment, Point p1, Point p2);
78 
79  // create lookup table for fast factorial calculation
80  void CreateFactorialTable();
81 
82  // Get a factorial for a coordinate
83  double Factorial(long int n);
84 
85  // Calculate the factorial function for Bernstein basis
86  double Ni(long int n, long int i);
87 
88  // Calculate Bernstein Basis
89  double Bernstein(long int n, long int i, double t);
90 
91  public:
92  vector<Point> Points; ///< Vector of all Points
93  vector<Coordinate> Values; ///< Vector of all Values (i.e. the processed coordinates from the curve)
94  float Auto_Handle_Percentage; ///< Percentage the left and right handles should be adjusted to, to create a smooth curve
95 
96  /// Default constructor for the Keyframe class
97  Keyframe();
98 
99  /// Constructor which sets the default point & coordinate at X=0
100  Keyframe(float value);
101 
102  /// Add a new point on the key-frame. Each point has a primary coordinate, a left handle, and a right handle.
103  void AddPoint(Point p);
104 
105  /// Add a new point on the key-frame, with some defaults set (BEZIER, AUTO Handles, etc...)
106  void AddPoint(float x, float y);
107 
108  /// Add a new point on the key-frame, with a specific interpolation type
109  void AddPoint(float x, float y, InterpolationType interpolate);
110 
111  /// Does this keyframe contain a specific point
112  bool Contains(Point p);
113 
114  /// Set the handles, used for smooth curves. The handles are based on the surrounding points.
115  void SetHandles(Point current);
116 
117  /// Flip all the points in this openshot::Keyframe (useful for reversing an effect or transition, etc...)
118  void FlipPoints();
119 
120  /// Get the index of a point by matching a coordinate
121  long int FindIndex(Point p) throw(OutOfBoundsPoint);
122 
123  /// Get the value at a specific index
124  float GetValue(long int index);
125 
126  /// Get the rounded INT value at a specific index
127  int GetInt(long int index);
128 
129  /// Get the rounded LONG value at a specific index
130  long int GetLong(long int index);
131 
132  /// Get the fraction that represents how many times this value is repeated in the curve
133  Fraction GetRepeatFraction(long int index);
134 
135  /// Get the change in Y value (from the previous Y value)
136  float GetDelta(long int index);
137 
138  /// Get a point at a specific index
139  Point& GetPoint(long int index) throw(OutOfBoundsPoint);
140 
141  /// Get current point (or closest point) from the X coordinate (i.e. the frame number)
142  Point GetClosestPoint(Point p);
143 
144  // Get the number of values (i.e. coordinates on the X axis)
145  long int GetLength();
146 
147  /// Get the number of points (i.e. # of points)
148  long int GetCount();
149 
150  /// Get the direction of the curve at a specific index (increasing or decreasing)
151  bool IsIncreasing(int index);
152 
153  /// Get and Set JSON methods
154  string Json(); ///< Generate JSON string of this object
155  Json::Value JsonValue(); ///< Generate Json::JsonValue for this object
156  void SetJson(string value) throw(InvalidJSON); ///< Load JSON string into this object
157  void SetJsonValue(Json::Value root); ///< Load Json::JsonValue into this object
158 
159  /**
160  * @brief Calculate all of the values for this keyframe.
161  *
162  * This clears any existing data in the "values" vector. This method is automatically called
163  * by AddPoint(), so you don't typically need to call this method.
164  */
165  void Process();
166 
167  /// Remove a point by matching a coordinate
168  void RemovePoint(Point p) throw(OutOfBoundsPoint);
169 
170  /// Remove a point by index
171  void RemovePoint(long int index) throw(OutOfBoundsPoint);
172 
173  /// Scale all points by a percentage (good for evenly lengthening or shortening an openshot::Keyframe)
174  /// 1.0 = same size, 1.05 = 5% increase, etc...
175  void ScalePoints(float scale);
176 
177  /// Replace an existing point with a new point
178  void UpdatePoint(long int index, Point p);
179 
180  /// Print a list of points
181  void PrintPoints();
182 
183  /// Print just the Y value of the point's primary coordinate
184  void PrintValues();
185 
186  };
187 
188 }
189 
190 #endif
vector< Coordinate > Values
Vector of all Values (i.e. the processed coordinates from the curve)
Definition: KeyFrame.h:93
Header file for Fraction class.
Header file for Point class.
A Point is the basic building block of a key-frame curve.
Definition: Point.h:81
Header file for all Exception classes.
Header file for JSON class.
This class represents a fraction.
Definition: Fraction.h:42
float Auto_Handle_Percentage
Percentage the left and right handles should be adjusted to, to create a smooth curve.
Definition: KeyFrame.h:94
vector< Point > Points
Vector of all Points.
Definition: KeyFrame.h:92
InterpolationType
This controls how a Keyframe uses this point to interpolate between two points.
Definition: Point.h:45
This namespace is the default namespace for all code in the openshot library.
Header file for Coordinate class.
Exception for invalid JSON.
Definition: Exceptions.h:152
Exception for an out of bounds key-frame point.
Definition: Exceptions.h:213
A Keyframe is a collection of Point instances, which is used to vary a number or property over time...
Definition: KeyFrame.h:64