Cinelerra Bézier Patch

by Ichthyostega, August 2006. While working on some automation-heavy parts of our film project, I found the bezier curve feature of Cinelerra incomplete and cumbersome to use, to a degree that it's almost worthles for all but the simplest needs.

• by default, there are no visual clues with regard to the existence of this feature, so that for most users it remains concealed unnecessarily.
• but the defaults are to simple and incomplete in implementation in order to »just work«, indeed they cause problems if you insert additional keyframes in between, as the progression of the automated value is no longer continuous, but stops at the interjacent keyframe.
• so you are forced to pull off the two bézier control points independently for almost all and every keyframe by ctrl-dragging, in order to activate and edit the curvature
• this produces a lot of visible control points, and as it's difficult to distinguish control points and keyframes, the resulting display will be confusing.
• morover, the behaviour of control points and curvature is somewhat strange and broken and differs from the commonly known behavior of bezier curves in all graphics packages.

1. the internal calculation of the bézier function is handled correctly in cinelerra and needn't be changed. Only the GUI needs improvement. As a consequence, the patch can retain backwards and (partially) upwards compatibility of session files.
2. the GUI should reflect the exact mathematical properties of the bezier function control points. When there need to be limits, they should be made obvious to the user.
3. and indeed: as we just want to calculate the bézier function for a given x value and don't want to go into the trouble to solve for an arbritrary bezier curve, there is a limitation: the x-positions of the control points are fixed to 1/3 and 2/3 of the distance between nighbouring keyframes. So there is no room for the ability to drag control points horizontally and there is no need to persist the horizontal position of the control points, as this value can't ever be used for the calculation.
4. the patch can provide several different tangent modes for each keyframe, some of which are for hand-editing the curvature and others can calculate and adjust the control points automatically, thus providing smoothed and linear automation curves.
5. defaulting to automatically smothed tangents, the rule for this smoothing should assure that the automated value never "overshots", i.e. never goes beyond extremal points defined by the given keyframes.

Features for Bézier Automation

This patch changes the handling of the so called "FloatAutos" in Cinelerra. This term denotes all automation controlling a float valued parameter where in-between values are interpolated using a cubic bézier function: Fades, camera and projector automation (but not the parameter values of plugin/effect keyframes). Such Float Automation is defined by a set of automation nodes (sometimes called keyframes as well). This nodes will be joined by a smooth curve, the tangents of this curve at each node being defined by the bézier control points of each curve segment.

By default, for new keyframes this tangents are calculated automatically. So, if we add nodes by clicking and dragging, or by "create keyframes while tweaking", we allways get a smooth curve through all given points. Note, that for extremal node points, the tangent is forced to be horizontal allways. This means, you can set a fade automation node at value=0, another at value=100 and be sure the in-between values will stay 0 <= value <= 100 allways.

You can set the tangent mode of every float automation node by using the node's popup menu (right click on the node).

[smooth curve]

the control points are calculated and adjusted automatically. This is the default.

[linear segments]

this also works automatically, but the tangents are choosen such as to aim at the neighbouring nodes. If two neighbouring nodes have linear tangent mode, the joining curve segment will be a stright line. (Note that it is possible to have linear mode only on one end of the segment).

[tangent edit]

this mode enables manual editing of the control points, while both control points of a node stay coupled such as to yield one single tangent through this node. This means, you can control the slope at the node but the curve will remain smooth allways.

[disjoint edit]

this enables to edit the two control points of a node independent of each other, so you can have a sharp edge in the curve (an instantanous change in progression of the automated value).

If we change a node to one of the manual tangent modes, the control points and the tangents of this node will show up. The location of the control points is fixed by the mathematical properties of the bézier function to be at 1/3 and 2/3 of each line segment (and will be adjusted automatically when you drag, insert or delete nodes), but the y-value of the control point is editable by Ctrl-clicking and dragging with the mouse. You can Ctrl-click and drag at the tangent line as well, in which case it will behave like a lever. While dragging, you can move beyond the control point and even to the opposite side of the node, thus beeing able to point the tangent in the direction of every location on screen.

You can toggle or cycle through the possible tangent modes of a node by Ctrl-clicking at the node itself (not at the control point). As a plus, you can just Ctrl-click at a node and start dragging; if the tangent mode was automatic prior to this operation, it will be switched to one of the manual modes by the click and you will start dragging the tangent immediately. (and if it was manual, the click will change it to be automatic again and the drag operation will have no effect)

For dragging the automation nodes themselves, there are two additional modifiers: If you Alt-drag an automation node, the movement will be constrained to only changing the value, i.e. the node will stay at the original position. If, on the other hand, you Shift-drag an automation node, the value will snap to the value of other automation nodes near by, so you can create segments with constant value easily.

When working with automation nodes in cinelerra, you have to consider one fundamental rule: their operation will allways take effekt to the right. The influence of a given node starts at its position in time and lasts to the future. And, on the other hand, if you modify a parameter (and don't have the "create keyframes"-toggle on), you actually will be shifting the value of the nearest node to the left.

The behaviour of the automatic tangent modes fits into this rule: If the tangent mode of a given node is set to "linear" and you create another node to the right, this one will get the automatic mode "linear" as well. So, if you create additional nodes by tweaking parameters with the "create keyframes"-toggle set on, in case of the "linear" tangent mode this will create a sequence of line segments.

As an additional "convienience shortcut", for camera and projector automation there is a tangent mode toggle in the tool window of the compositor. Remember the camera (and projector) automation is compriesd of three indepenent automation curves (X,Y and Zoom). The mentioned toggle reflects and modifies the tangent mode of all three curves together. If the nearest keyframe to the left of the current position for all three curves has tangent mode "automatic linear", then the corresponding icon will show up selected, and if you push the toggle, the tangent mode of the nearest neighbouring node on all three curves will be changed simultanously. If there is a mixed state, none of the toggles will be highlighted.

One final word to the compatibility with earlier versions of cinelerra: If you open a existing session file with the patched version, there will be an internal conversion such that the effective calculated automation curve will stay exactly the same. Of course, the display of the control points and tangens will look quite different. Earlier version session files allowed to arbitrarily drag the horizontal position of control points and persisted this alleged degree of freedom. But, as this horizontal position actually is never used in the calculations, I choose to throw away this information. So, if you afterwards open a session file edited with the patched Cinelerra in a old version of Cinelerra, your control points will again show up in the old (strange) way, but with their horizontal position reset to zero, i.e. they will show up exactly above and below the corresponging automation node.

get the patch

I'll provide here the current state of my Bézier patch as a diff against Subversion-Rev 909.
Please note: this is an developement/beta version and in no way "official". It can be considered feature-complete and adapted to Cinelerra 2.1CV, but most likely will have to undergo some changes in order to be accepted for the official codebase.

Update (Mai 2007): some work for this has been done, but the effort has stalled due to other obligations. I am using this patch since then for my own work with cinelerra. The latest version is in my GIT, please contact me if interested!

If you are on Debian and AMD64, as a convienience you can download and try out my own binary packages. They are just working for me, please don't blame me if they don't work for you...

bezier_patch-svn20061010hiv.patch

cinelerra_2.1.0-svn20061010hiv_amd64.deb

libguicast_2.1.0-svn20061010hiv_amd64.deb

libquicktimehv_2.1.0-svn20061010hiv_amd64.deb

libquicktimehv-dev_2.1.0-svn20061010hiv_amd64.deb

libmpeg3hv_2.1.0-svn20061010hiv_amd64.deb

libmpeg3hv-dev_2.1.0-svn20061010hiv_amd64.deb

hvirtual_2.1.0-svn20061010hiv_amd64.changes

Have fun
Hermann