README.md
1OpenFX-Misc [](https://github.com/devernay/openfx-misc/blob/master/LICENSE) [](https://travis-ci.org/devernay/openfx-misc) [](https://scan.coverity.com/projects/2945 "Coverity Badge")
2===========
3
4Miscellaneous OFX / OpenFX / Open Effects plugins.
5
6These plugins were primarily developped for
7[Natron](http://natron.inria.fr), but may be used with other
8[OpenFX](http://openeffects.org) hosts.
9
10More information about OpenFX Hosts, OpenFX Plugins (commercial or
11free), and OpenFX documentation can be found at
12<http://devernay.free.fr/hacks/openfx/>.
13
14License
15-------
16
17<!-- BEGIN LICENSE BLOCK -->
18Copyright (C) 2013-2018 INRIA
19
20openfx-misc is free software: you can redistribute it and/or modify
21it under the terms of the GNU General Public License as published by
22the Free Software Foundation; either version 2 of the License, or
23(at your option) any later version.
24
25openfx-misc is distributed in the hope that it will be useful,
26but WITHOUT ANY WARRANTY; without even the implied warranty of
27MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
28GNU General Public License for more details.
29
30You should have received a copy of the GNU General Public License
31along with openfx-misc. If not, see <http://www.gnu.org/licenses/gpl-2.0.html>
32<!-- END LICENSE BLOCK -->
33
34Contents
35--------
36
37Below is a short description of each plugin. The title of each section
38is the plugin grouping (the OpenFX host may classify plugins by
39grouping).
40
41### Image
42
43* CheckerBoardOFX: Generate an image with a checkerboard
44* ColorBarsOFX: Generate an image with SMPTE color bars
45* ColorWheelOFX: Generate an image with a color wheel
46* ConstantOFX: Generate an image with a uniform color
47* SolidOFX: Generate an image with a uniform opaque color
48
49### Draw
50
51* Rand: Generate a random field of noise.
52* NoiseCImg: Generate different kinds of noise.
53* PlasmaCImg: Generate plasma noise.
54* RadialOFX: Radial ramp.
55* RampOFX: Draw a ramp between 2 edges.
56* RectangleOFX: Draw a rectangle.
57* RotoOFX: Create masks and shapes. Requires a host with mask editing
58 capabilities (such as Natron).
59
60
61### Time
62
63* AppendClipOFX: Put one clip after another.
64* Deinterlace: Deinterlace input stream.
65* FrameBlendOFX: Blend frames.
66* FrameHoldOFX: Hold a frame, or subsample the input frames.
67* FrameRangeOFX: Change the frame range of a clip. Useful with AppendClip
68* RetimeOFX: Change the timing of the input clip.
69* SlitScan: Per-pixel retiming.
70* TimeOffsetOFX: Move the input clip forward or backward in time.
71* TimeBlurOFX: Average frames over a fractional shutter period.
72* NoTimeBlurOFX: Round fractional frames to integer values.
73* TimeBufferRead/TimeBufferWrite: Read from an buffer written during a previous render.
74
75### Channel
76
77* ShuffleOFX: Rearrange channels from one or two inputs, and convert to a different bit depth (on hosts that support it).
78
79### Color
80
81* ClampOFX: Clamp values to a given interval.
82* ColorCorrectOFX: Adjusts the saturation, constrast, gamma, gain and offset of an image.
83* ColorLookupOFX: Apply a parametric lookup curve to each channel separately.
84* ColorSuppress: Remove a color/tint, or create a mask from that color.
85* EqualizeCImg: Equalize the histogram.
86* GradeOFX: Modify the tonal spread of an image from the white and black points.
87* HistEqCImg: Equalize the luminance histogram.
88* HSVToolOFX: Adjust hue, saturation and brightnes, or perform color replacement.
89* HueCorrectOFX: Apply hue-dependent color adjustments using lookup curves.
90* InvertOFX: Inverse the selected channels.
91* Log2LinOFX: Convert from/to the logarithmic space used by Cineon files
92* Math/AddOFX: Add a constant to the selected channels.
93* Math/ClipTestOFX: Draw zebra stripes on all pixels outside of the specified range.
94* Math/ColorMatrixOFX: Multiply the RGBA channels by an arbitrary 4x4 matrix.
95* Math/GammaOFX: Apply gamma function to the selected channels.
96* Math/MultiplyOFX: Multiply the selected channels by a constant.
97* PLogLinOFX: Convert between linear and log representations using the Josh Pines log conversion.
98* Quantize: Reduce the number of color levels with posterization or dithering.
99* SaturationOFX: Modify the color saturation of an image.
100* Threshold: Threshold the selected channels to bring them within the 0-1 range.
101* Transform/RGBToHSV and HSVToRGB: Convert to/from HSV color representation.
102* Transform/RGBToHSL and HSLToRGB: Convert to/from HSL color representation.
103* Transform/RGBToHSI and HSIToRGB: Convert to/from HSI color representation.
104* Transform/RGBToYCbCr601, YCbCrToRGB601, RGBToYCbCr709 and YCbCrToRGB709: Convert to/from YCbCr color representation.
105* Transform/RGBToYPbPr601, YPbPrToRGB601, RGBToYPbPr709 and YPbPrToRGB709: Convert to/from YPbPr color representation.
106* Transform/RGBToYUV601, YUVToRGB601, RGBToYUV709 and YUVToRGB709: Convert to/from YUV color representation.
107* Transform/RGB709ToLab and LabToRGB709: Convert to/from Lab color representation.
108* Transform/RGB709ToXYZ and XYZToRGB709: Convert to/from XYZ color representation.
109* VectorToColor: Convert x and y vector components to a color representation.
110
111### Filter
112
113* BlurCImg: Blur input stream by a quasi-Gaussian or Gaussian filter (recursive implementation), or compute derivatives.
114* ChromaBlurCImg: Blur the chrominance components (usually to prep strongly compressed and chroma subsampled footage for keying).
115* DenoiseSharpen: Denoise and/or sharpen images using wavelet-based algorithms.
116* DilateCImg/ErodeCImg: Dilate/erode input stream by a rectangular structuring element of specified size and Neumann (a.k.a. nearest) boundary conditions.
117* DirBlurOFX: Directional blur.
118* Distance: Compute the distance from each pixel to the closest zero-valued pixel.
119* EdgeDetectCImg: Perform edge detection by computing the image gradient magnitude.
120* EdgeExtend: Fill a matte (i.e. a non-opaque color image with an alpha channel) by extending the edges of the matte.
121* ErodeBlurCImg: Erode or dilate a mask by smoothing.
122* ErodeSmoothCImg: Erode or dilate input stream using a [normalized power-weighted filter](http://dx.doi.org/10.1109/ICPR.2004.1334273).
123* GMICExpr: Quickly generate or process image from mathematical formula evaluated for each pixel.
124* GodRays: Average an image over a range of transforms, or create crepuscular rays.
125* InpaintCImg: Inpaint the areas indicated by the Mask input using patch-based inpainting.
126* Matrix3x3 and Matrix5x5: Apply a filter given by a 3x3 or 5x5 matrix.
127* Shadertoy: Apply a [Shadertoy](http://www.shadertoy.com) fragment shaders (multipass shaders are not supported).
128* SharpenCImg: Sharpen the input stream by enhancing its Laplacian.
129* SharpenInvDiffCImg: Sharpen selected images by inverse diffusion.
130* SharpenShockCImg: Sharpen selected images by shock filters.
131* SmoothAnisotropicCImg: Smooth/Denoise input stream using anisotropic PDE-based smoothing.
132* SmoothBilateralCImg: Blur input stream by bilateral filtering.
133* SmoothBilateralGuidedCImg: Apply joint/cross bilateral filtering on image A, guided by the intensity differences of image B.
134* SmoothGuidedCImg: Blur image, with the [Guided Image filter](http://research.microsoft.com/en-us/um/people/kahe/publications/pami12guidedfilter.pdf).
135* SmoothMedianCImg: Apply a [median filter](https://en.wikipedia.org/wiki/Median_filter) to input images.
136* SmoothPatchBasedCImg: Denoise selected images by non-local patch averaging.
137* SmoothRollingGuidanceCImg: Filter out details under a given scale using the [Rolling Guidance filter](http://www.cse.cuhk.edu.hk/~leojia/projects/rollguidance/).
138* SoftenCImg: Soften the input stream by reducing its Laplacian.
139
140### Keyer
141
142* ChromaKeyerOFX: Apply chroma keying, as described in "Video Demystified" by Keith Jack.
143* Despill: Remove the unwanted color contamination of the foreground (spill) caused by the reflected color of the bluescreen/greenscreen, as described in "Digital Compositing for Film and Video" by Steve Wright.
144* DifferenceOFX: Produce a rough matte from the difference of two images.
145* HueKeyerOFX: Compute a key depending on hue value.
146* KeyerOFX: A collection of simple keyers.
147* MatteMonitor: A Matte Monitor, as described in "Digital Compositing for Film and Video" by Steve Wright.
148* PIK: A per-pixel color difference keyer that uses a mix operation instead of a max operation to combine the non-backing screen channels.
149* note that HSVToolOFX (in the "Color" section) can also be used as a keyer.
150
151### Merge
152
153* ContactSheetOFX: Make a contact sheet from several inputs or frames.
154* CopyRectangleOFX: Copies a rectangle from the input A to the input B in output.
155* DissolveOFX: Weighted average of two inputs.
156* KeyMixOFX: Copies A to B only where Mask is non-zero.
157* LayerContactSheetOFX: Make a contact sheet from layers.
158* MergeOFX: Pixel-by-pixel merge operation between the two inputs.
159* PreMultOFX/UnpremultOFX: Multiply/divide the selected channels by alpha (or another channel).
160* SwitchOFX: Lets you switch between any number of inputs.
161* TimeDissolve: Dissolve from input A to input B over time.
162
163### Transform
164
165* AdjustRoD: Enlarges the input image by a given amount of black and transparent pixels.
166* Card3DOFX: Transform and image as if it were projected on a 3D card.
167* CornerPinOFX and CornerPinMaskedOFX: Fit an image to another in translation, rotation, scale, and shear
168* CropOFX: Remove everything outside from the image of a rectangle.
169* IDistortOFX: Distort an image, based on a displacement map.
170* LensDistortionOFX: Apply nonlinear lens distortion.
171* MirrorOFX: Flip or flop the image.
172* PositionOFX: Translate image by an integer number of pixels.
173* Reformat: Convert image to a different image format and size.
174* SpriteSheet: Use an image as a sprite sheet.
175* STMapOFX: Move pixels around an image, based on a UVmap.
176* TrackerPM: Point tracker based on pattern matching using an exhaustive search within an image region.
177* TransformOFX and TransformMaskedOFX: Translate / Rotate / Scale a 2D image.
178
179### Views
180
181These plugins are compatible with the Sony Vegas and Nuke [multiview extensions](http://openeffects.org/standard_changes/multi-view-effects).
182
183* JoinViewsOFX: JoinView inputs to make a stereo output.
184* OneViewOFX: Takes one view from the input.
185* Stereo/AnaglyphOFX: Make an anaglyph image out of the two views of the input.
186* Stereo/MixViewsOFX: Mix two views together.
187* Stereo/ReConvergeOFX: Shift convergence so that a tracked point appears at screen-depth.
188* Stereo/SideBySideOFX: Put the left and right view of the input next to each other.
189
190### Other
191
192* ImageStatisticsOFX: Compute statistics over an image or a rectangular area.
193* NoOpOFX: Copies the input to the ouput. Useful for inspecting the properties of input and output clips.
194* TestRenderOFX: Test some rendering features of the OFX host.
195
196Notes & Caveats
197---------------
198
199### What does the Roto plugin do?
200
201If you use the Roto plugin in any other host than [Natron](http://natron.inria.fr), you will notice that it doesn't do much. Its role is just to provide an entry point for a host-based rotoscoping tool, which provides a roto mask to this plugin.
202
203### The default parameters are too small on DaVinci Resolve
204
205This is because Resolve does not support the `kOfxParamPropDefaultCoordinateSystem` property. A solution was implemented in CornerPin (look for the comment "Some hosts (e.g. Resolve) may not support normalized defaults"), but the following plugins still have to be fixed:
206
207- CopyRectangle
208- Crop
209- HSVTool
210- ImageStatistics
211- ofxsGenerator
212- ofxsPositionInteract
213- ofxsTransformInteract
214- Position
215- ReConverge
216- TestPosition
217- TrackerPM
218
219### ColorLookup does not work on Nuke 8/9, DaVinci Resolve...
220
221Although Nuke 8 & 9 claim via OpenFX that they support parametric parameters (i.e. adjustable parametric curves), these don't work (at least on OS X, and maybe on other platforms). The plugin appears in the plugin list, but cannot be instanciated. Nothing seems to happen, and the following message appears on the console (on OS X):
222
223 Exception thrown
224 basic_string::_S_construct NULL not valid
225
226The same happens with other plugins using parametric parameters, such as [TuttleHistogramKeyer](http://www.tuttleofx.org/).
227
228Parametric parameters work in older versions of Nuke (at least in Nuke 6 & 7).
229
230DaVinci Resolve does not support parametric parameters.
231
232Please [file an issue](https://github.com/devernay/openfx-misc/issues) if you think openfx-misc is doing something wrong, or you know of other hosts which have problems with parametric paremeters.
233
234Although ColorCorrect uses parametric parameters, it can still be instanciated on Nuke 8 & 9 and on DaVinci Resolve, but the curve ranges are not adjustable (shadows are decreasing linearly from 0 to 0.09, and highlights are increasing linearly from 0.5 to 1.0).
235
236
237### Retime output does not contain motion blur, where is the "box" filter and the "shutter" parameter?
238
239We should take the code from FrameBlend, simplify, and incorporate it in Retime.
240
241
242Installation
243------------
244
245These plugins are included in the binary distributions of [Natron](http://natron.inria.fr).
246
247If you want to compile the plugins from source, you may either use the
248provided Unix Makefile, the Xcode project, or the Visual Studio project.
249
250### Getting the sources from github
251
252To fetch the latest sources from github, execute the following commands:
253
254 git clone https://github.com/devernay/openfx-misc.git
255 cd openfx-misc
256 git submodule update -i -r
257
258In order to get a specific tag, corresponding to a source release, do `git tag -l`
259to get the list of tags, and then `git checkout tags/<tag_name>`
260to checkout a given tag.
261
262### Unix/Linux/FreeBSD/OS X, using Makefiles
263
264On Unix-like systems, the plugins can be compiled by typing in a
265terminal:
266- `make [options]` to compile as a single combined plugin (see below
267 for valid options).
268- `make nomulti [options]` to compile as separate plugins (useful if
269only a few plugins are is needed, for example). `make` can also be
270executed in any plugin's directory.
271- `make [options] CXXFLAGS_ADD=-fopenmp LDFLAGS_ADD=-fopenmp` to compile
272 with OpenMP support (available for CImg-based plugins and DenoiseSharpen).
273
274The most common options are `CONFIG=release` to compile a release
275version, `CONFIG=debug` to compile a debug version. Or
276`CONFIG=relwithdebinfo` to compile an optimized version with debugging
277symbols.
278
279Another common option is `BITS=32`for compiling a 32-bits version,
280`BITS=64` for a 64-bits version, and `BITS=Universal` for a universal
281binary (OS X only).
282
283See the file `Makefile.master`in the toplevel directory for other useful
284flags/variables.
285
286The compiled plugins are placed in subdirectories named after the
287configuration, for example Linux-64-realease for a 64-bits Linux
288compilation. In each of these directories, a `*.bundle` directory is
289created, which has to be moved to the proper place
290(`/usr/OFX/Plugins`on Linux, or `/Library/OFX/Plugins`on OS X), using
291a command like the following, with the *same* options used for
292compiling:
293
294 sudo make install [options]
295
296### OS X, using Xcode
297
298The latest version of Xcode should be installed in order to compile this plugin.
299
300Open the "Terminal" application (use spotlight, or browse `/Applications/Utilities`), and paste the following lines one-by-one (an administrator password will be asked for after the second line):
301
302 xcodebuild -configuration Release install
303 sudo mkdir /Library/OFX/Plugins
304 sudo mv /tmp/Misc.dst/Library/OFX/Plugins/Misc /Library/OFX/Plugins
305
306The plugins may also be compiled by compiling the Xcode project called
307`Misc.xcodeproj` in the toplevel directory. The bundles produced by
308this project have to be moved to `/Library/OFX/Plugins`.
309
310### MS Windows, using Visual Studio
311
312Compile using the provided `Misc.vcxproj`project found in the `Misc`
313directory.
314
31532-bits plugins should be installed in the directory `c:\Program Files
316(x86)\Common Files\OFX\Plugin`, 64-bits plugins should be installed in
317`c:\Program Files\Common Files\OFX\Plugins`.
318
319Credits
320-------
321
322The stereoscopic plugins Anaglyph, JoinViews, MixViews, OneView,
323ReConverge, SideBySide are by Frederic Devernay.
324
325ColorLookup, Switch, TimeOffset, ChromaKeyer, Difference, Constant,
326Shuffle, Rectangle, Radial, HSVTool, ImageStatistics, CheckerBoard,
327Retime, SlitScan, ColorWheel, the color transform plugins and the
328CImg plugins are by Frederic Devernay.
329
330Merge, ColorCorrect, Grade, Roto, Crop, CopyRectangle are by
331Alexandre Gauthier.
332
333Transform and CornerPin are by Frederic Devernay and Alexandre Gauthier.
334
335Deinterlace/yadif was first ported to OFX by [George Yohng](http://yohng.com) and rewritten by Frederic Devernay when yadif was relicensed to LGPL.
336
){kind=link}
){kind=link}
){kind=link}