Sapphire Plug-ins for Autodesk systems, General User Info
- S_Mocha uses Mocha to create a tracked mask. The output of the effect is the tracked mask. S_Mocha has more options for controlling and adjusting the resulting mask than are found in other effects that include Mocha.
- S_VignetteMocha ) creates a vignette using a Mocha-tracked mask as the shape of the vignette. All the options of regular Vignette are available.
- S_ZapMask creates lightning like S_Zap, but the zap only appears where the mask is white.
- S_ZapToMask creates lightning like S_ZapTo, but the lightning is only attracted to edges where the mask is white.
- Mocha tracking and masking is added to most effects. The Mocha params are found on the Crop/Help page.
- Exceptions: Transitions, Z effects, Retime, RackDfComp, RepairFrames
- S_Grunge now has a Crop Grunge to Mask parameter.
- Glint, GlintRainbow and Glare can now select luma, color or alpha for the mask using new Mask Type parameter.
- S_Swish3D's default wrap behavior has been changed to Repeat.
- Sparks field-mode popup is now reversed, and should work correctly on all footage. Auto field mode should work better now too.
- Streaks, Rays and EdgeRays are now more stable when downsampling via Streaks/Rays Res and cropping. Projects with these may look slightly different.
New in 11.01:
Fixed a bug that changed the
of several effects between v10 and v11.0
if the user provided a color mask. These effects are now compatible with v10's output but
the output will change relative to v11.0! To get the output from v11.0 back, apply S_Monochrome
to the mask before passing it to the effect.
- All Glows
- All Sparkles
- GrainMask (all modes except Grain Remove Mask)
- GrainComp (all modes)
- Fixed update_setups. update_setups now upgrades all v10 effects in setup files (eg. batch, desktop files) to v11.
- VignetteMocha mode of S_Vignette now starts with an empty Mocha project. In this case VignetteMocha will use a circular mask until a Mocha Mask is set. This circular mask will not show up in the Mocha UI.
- S_Mocha now starts with an empty Mocha project which means the effect will generate a black screen when first applied.
- Fixed a bug that caused the Mocha UI to crop when the plugin is set to downsample.
- Mocha help link now points to Sapphire Mocha help instead of BCC Mocha help.
- Mocha now remembers the previous Open Project and Export Project locations.
- Mocha in Sapphire and Mocha in BCC now save preferences and settings separately.
- New Mocha projects now display one-based frame numbers to match the host. Existing projects will continue to display zero-based frame numbers to maintain backwards compatibility.
- Updated list of known issues (below).
- Minor preset improvements.
To load a Spark in Batch, drag from the "Spark" button onto the batch tree instead. Navigate to the sapphire_11 directory and choose a Spark. Edit the Spark node to bring up the Spark interface window.
Most Sapphire Sparks include several different effect variations. For example the S_Wipes Spark contains 17 different kinds of Wipe transitions. For these Sparks there is always a popup menu in the upper left hand corner of the "Params" or "Ctrl1" page, which allows selecting between the different effect options.
Multiple versions of some Sparks are provided with different input combinations. For example, Glows takes just a Source input, Glows Mask takes Source and Mask inputs, Glows Comp takes Source, Back and Matte, and Glows MaskCmp takes Source, Back, and Mask. Autodesk systems don't allow plug-ins with optional inputs, so this lets you to pick the appropriate version of the plug-in for the input clips you want to provide or not provide.
Some parameters are "shared" across the different effect options within a plug-in. If you modify the value of a shared parameter and then switch to a different effect, you will also see the new value there. Other parameters are not shared and can retain different values between the effect options, even though they may have the same name. The on-line documentation indicates which parameters are shared. The Wipe Amt parameter in S_Wipes is an example of a shared parameter. It is shared because you would probably want the same transition value regardless of the specific wipe pattern selected later.
Loading:In the preset browser you'll see all the presets available for the current plug-in, both GenArts-supplied presets and the ones you've created yourself. You can filter by tags on the left side to quickly find the look you're interested in.
The main top window shows the preset on your footage (unless the plug-in can't access the AE layer for some reason, in which case you'll see a poster frame) and various information about the preset.
At the bottom you see all the presets; you can enlarge or shrink them with the slider at the bottom. You can also switch to a table view there, as well as viewing the preset on your source, over black, or over the sample footage. You can also see the source all by itself for comparison.
Saving:Clicking Save Preset brings up the Save Preset dialog. Here you can name the preset, and add various other information. Particularly important is the tagging system; you can apply as many tags as you want to your presets. You can even create new tags. Tags are grouped into categories, so all the color names appear under Colors, for instance.
You can create new categories as well, by typing into the Category drop-down menu after clicking Add New Tag.... GenArts recommends sticking to the shipped categories when possible, for compatibility. But adding your own tags within categories (new color names, for example) is encouraged.
While the preset browser, save dialog, or flare designer are open, the main AE window will be unresponsive. This is normal. Close the preset browser or flare designer and AE will wake up again.
Certain parameters, like Lens Flare hotspot, are not saved in presets; we thought it would be less than useful for the flares to jump around as you load presets.
It may take a few seconds to load the preset browser if a plug-in has many presets. Be patient.
The Flare Designer lets you completely customize a lens flare. You can add or remove elements, copy them, customize how each element looks, and even how it reacts to the center or edge of the image. You can also interactively move the flare around to see how it will look as it moves.
All the panels of the Flare Designer are movable, so you can adjust the user interface itself to suit your work flow. The main panels are the view window, where you see the flare you're working on, the Elements panel which lists all the elements of the flare, and the Properties panel, which lets you adjust the properties of the currently selected element (or elements). There's also a toolbar of element templates at the top.
View PanelThe main view window is where you see how your flare will look; you can click and drag to move the flare around. You can see it over the background or just over black, adjust the gamma, and Solo only the selected elements. Use Plug-in Settings makes the flare designer import the plug-in settings currently active in the host app. If you have that selected, the flare will look the same back in the host app when you're done designing it. On the other hand, if you want to create a "reusable" flare preset, it's probably a good idea to un-check Use Plug-in Settings so the flare will look good with default settings in the plug-in.
Elements PanelThe Elements panel shows you all the elements, with thumbnails. If you mouse over them, an overlay shows where they are in the main view window. When you click on an element to select it, it also flashes brighter in the main window to help you find the element you're looking for. Clicking Identify in the Properties panel does the same flashing.
To add new elements, just click the element template picture in the top toolbar. You can then rename the element, move it in the list by dragging and dropping, or hide it by un-checking the checkbox.
To delete an elements, select it and click the trash can icon at the bottom of the Elements panel, or click Delete. There is full undo, so feel free to experiment!
You can also duplicate an element using standard copy/paste operations, or select it and click the two pages icon at the bottom of the Elements panel. You can then adjust the copy's parameters in the Parameters panel.
The gear-looking element is the "advanced element" type; it has lots of controls and is very customizable, but it's recommended for advanced users only. The other types get you most of the same looks with simpler parameters.
Along with all the standard element types, you can import your own images to use as elements. Click the picture frame to import an image file. The image data will become part of the flare, so it doesn't need to keep a reference to the original file.
To combine two flares into one, or add many elements at once, you can import another flare into your current flare; this will add all the other flare's elements to your current flare. You can also just open that flare, which replaces your current flare with that one. To import and add to your flare, use Insert Flare (down-right pointing arrow in the toolbar), or File... Insert Flare. To import and replace, use Open Flare (folder icon in the toolbar), or use File... Open Flare.
Parameters PanelThe Parameters panel is where you adjust all the details of a single element -- or multiple elements together, if you select multiple elements in the Elements panel. (Use Shift-click or Control-click to select multiple elements.)
There are a few common control types. Sliders with numbers to the left control numeric params; you can drag the slider thumb, but you can also drag in the number text field to increase or decrease the value. You can also click in the number field and type any value you want.
Color controls are just a swatch of color; click to bring up a standard color picker.
Some elements have a Gradient; there's a special gradient control to adjust those. The stops are below the color swatch; you can drag them left and right to move them. Drag down to delete. Click in the color gradient to add a stop there. Control-drag to "stretch" neighboring colors, and shift-drag to push neighboring colors. The triangles above the color gradient allow you to control the interpolation of the colors between stops. Ring Thickness lets you easily turn a spot or fan of rays into a ring; turning Ring Thickness down from 1 hollows out the center. This lets you still have fine control of the colors within the ring, even if it's very thin.
Different element types will have various parameters you can adjust, but here are some common ones:
- Where the element occurs, along the line between the hotspot and pivot point. Position 1.0 is at the hotspot, 0.0 is at the pivot. Note that you don't have to stay in that range; you can use any value you like. Bigger than 1 will be past the hotspot, and less than zero will look like a reflection because it's on the other side of the pivot point.
- How big the image is.
- Rel Width, Rel Height
- Use these to squash and stretch.
- Rotates the element around, in degrees.
More InformationIf you open the flare designer from the plug-in, you can just click OK to close the window when you're done; your current flare will be used in your project and saved with it. But you can do more than that; you can save the flare definition to disk separately, so you can recall it later, or use it in other flares. You can also open the flare designer directly from the Start menu or Applications folder to create flares independent of your host product. In this case, use File...Save Lens As... to save the flare definition. That dialog will allow you to name the lens and tag it so it's easy to find later.
Note that saving a lens this way does not save your plug-in settings; it only saves the lens flare definition itself (the things you can change in the flare designer). You can save a preset in the host application to save everything -- the flare and all the regular plug-in parameters.
While the preset browser, save dialog, or flare designer are open, the main AE window will be unresponsive. This is normal. Close the preset browser or flare designer and AE will wake up again.
What is Mocha?
Mocha is a planar tracking and masking utility that can save time on the most difficult motion tracking and masking shots. It tracks the entire area of the mask, not just individual points, to significantly reduce the tedium of manual keyframing.
Mocha looks for 3-d planes in the image: pixels that move together. Screens and signs are clear candidates, but Mocha can also track faces. It can handle objects obscured by foreground elements, and can track unlimited layers all at once.
There's a lot more to Mocha than we can explain here; there are plenty of tutorials online at http://borisfx.com.
In Sapphire, Mocha works as a mask for the effect, similarly to the mask input, but with all the tracking features of Mocha. For instance, in S_DistortRGB, the mask affects the amount of RGB distortion. In S_Glow, the mask masks out the areas you want to emit glowing light, without chopping off the smooth edges of the glow.
How to use it
- Apply a Sapphire effect
- Click Edit Mocha to launch Mocha
- Create a spline
- Track it
- Save and exit back to host
- Adjust in Sapphire
- Moving masks between effects
- go into Mocha with Edit Mocha , then File > Export to export the Mocha project to a file.
- Exit Mocha and delete the old effect.
- Apply the new effect, Edit Mocha , and File > Merge the project from the file you saved.
- S_Mocha spark
Most Sapphire effects now feature Mocha planar tracking integrated within the effect. Certain effects were omitted because utilizing a mask made no logical sense; for example, none of the S_Transition effects incorporate S_Mocha, and the Z_effects which require a Z_depth matte to work were also skipped.
When you click the Edit Mocha button, you will launch the Mocha UI, which will allow you to create and track a mask for use back with the selected Sapphire effect in your host application.
You can create a shape to track within Mocha utilizing either an X-spline or Bezier splines. X-splines are recommended for most uses.
Draw one or more splines around the planar areas you would like to track.
You can use backwards and forward tracking from whatever frame you're parked on. You can often get a great result with default settings, but if you're getting a lot of drifts, try increasing the Min K Pixels Used .
For your mask to appear back in your host application, YOU MUST SAVE AND EXIT. If you exit without saving, all you current work will be lost. Always save and exit!
You can make additional fine tuning adjustments after tracking in Mocha by opening the "Mocha" pulldown in your selected Sapphire effect. Additional softness and position/scale paramters can be found here, as well as checkboxes for soloing/hiding/inverting the Mocha mask.
Sometimes you track a shot with Mocha in one Sapphire effect and would like to reuse the track in a different effect. The simplest way is to export it from the first effect and re-import into the second effect.
Alternatively, if you want to share a Mocha mask with several effects, track the mask in a simple Sapphire effect such as S_HueSatBright. In there, select Show Mocha Only . Then use that as the Mask input to the effects where you want the mask used. This is easiest to do in Batch. Since the Mocha mask acts just like a regular mask input, this will allow you to update the mask once and all the other effects will use it.
Sapphire 11 introduces a new S_Mocha spark which just runs Mocha and outputs the Mocha matte. It can be very useful in batch to share a tracked mask between several effects. It includes options to resize and shift the mask, which the other effects that include Mocha don't have room for.
AUTO: the scan format is automatically detected, and field rendering is enabled or disabled as necessary. This is the default
NO: field rendering is disabled.
YES, 1DOM: field rendering is enabled with field 1 first in time.
YES, 2DOM: field rendering is enabled with field 2 first in time.
Redraw: DRAG AUTO RES. This output is relcaulated during the adjustment of
any parameter or widget. The resolution is automatically reduced to preserve interactive
performance. When the parameter is released, the output is rendered at the resolution
given by the Res Factor parameter.
Redraw: DRAG. This output is recalculated during the
adjustment of any parameter or widget.
Redraw: PENUP. The output is recalculated after any parameter
is adjusted or a widget is moved.
Redraw: PROCESS. Spark rendering is performed only when a
Process is performed. Adjustments to the frame number or total frames
will also perform a Process of the current frame (in the current Spark
- Redraw: NEVER. Spark rendering is disabled, and black frames are shown instead. This can be used for quickly setting up parameter values and curves without ever taking the time to re-render any result. On-screen widgets can still be used in this mode.
Pushing the Undo button removes changes made to the parameters of the current effect. You can undo as many changes back in time as you want until it signals that there is nothing to undo. Undo can undo a Load Defaults, however it can not currently undo a loaded setup file. Undo records are not remembered when you switch to a different Spark.
Pushing the Load Defaults button returns each parameter value of the current effect to its default setting. If additional parameters exist on the "Params2" or "Ctrl2" page, it will also reset their values. Load Defaults does not change Widget Enables, Res Factors, or Redraw Modes, and it does not change parameter values of other effect options within the same Spark except for the parameters that are shared. It also will not reset the special "AutoTransition" parameters Wipe Amt or Dissolve Amt. The Crop/Help page has its own Load Page Defaults button which sets all the parameters on that page to their default values.
Enable Crop. Turns on or off cropping and the crop widget.
Crop Widget. Turns on or off the crop screen interface widget
for adjusting the crop rectangle. This is normally set by Enable Crop
to agree with its state, but it can also be adjusted independently.
Surround. Selects the method for filling the areas beyond
the crop rectangle, either with a given color or with any of the unprocessed
Crop Top, Left, Right, Bottom. Specifies the values for the
borders of the crop rectangle. These parameters are most easily
adjusted using the Crop Widget.
Crop Input. When this option is turned on, the input is cropped
before performing the effect. For effects such as Warps, this
allows you to distort the shape of the cropped image, or remove
unwanted black borders on the input that may otherwise become more
visible after they are warped or wrapped. This parameter is not
available for all effects.
- Set Crop Defaults. When pushed, sets the crop rectangle to full frame.
The LUT popup allows you to select custom LUT files for working in log or other non-linear colorspaces. You can add your own options to the popup by installing LUT files in /usr/discreet/sparks/luts , with the names <lut-name>-in.lut for the input LUT and <lut-name>-out.lut for the corresponding output LUT.
Sparks that take a Mask, Matte or other input clip that is apt to be monochromatic also include a parameter that specifies which input clips should not be affected by the Gamma and LUT settings. Those clips are assumed to already be in linear colorspace. For example, the S_GlowMaskComp spark has options for Linear Matte Mask, Linear Matte, Linear Mask, or Gamma/LUT All. The default Linear Matte Mask setting causes the Use Gamma and LUT parameters to only affect the Front and Back clips. The Linear Matte setting causes these colorspace controls to affect the Front, Back and Mask but not the Matte clip, and the Gamma/LUT All setting causes all input clips to be affected.
Troubleshooting GPU ProblemsIf a Spark is unable to render on the GPU, it will automatically fall back to the CPU and continue processing. The text of the GPU Enable button will change to indicate the problem.
GPU SelectionOn machines with more than one GPU that supports CUDA, you can select which GPU Sapphire Plug-ins will use by changing the value of use_gpu in the s_config.text file.
No GPU: no CUDA-capable graphics card was found.
GPU Out of Memory: there is not enough memory on the GPU to render this effect
GPU Disable: GPU processing is disabled in the s_config.text file.
GPU Error: an error occurred while rendering on the GPU. This may be due to a bug in Sapphire
GPU Rendering on BurnBy default, Burn nodes will ignore the value of the GPU Enable button, and always use the GPU if available. You can override this behavior by changing the value of the "use_gpu_on_burn" setting in the s_config.text file.
yes: Burn nodes always use the GPU if available. This is the default.
no: Burn nodes never use the GPU.
button: Burn nodes check the GPU Enable button to decide whether the render on the GPU.
To compensate for this, all Sapphire Plug-ins pre-stretch or shrink their effect in the vertical direction by the inverse of this pixel aspect ratio which is normally read from the meta-data of the input clip. You can override this for all effects by changing the value of force_pixel_aspect_ratio in the s_config.text file. A value of 1.111 is usually right for NTSC resolution, 0.916 is often appropriate for PAL resolution, and 1.0 will always give square pixels.
Most plug-ins also have a parameter for adjusting the relative width or height of the effect, which can be used to stretch the effect as needed on a case by case basis.
The pixel aspect ratio makes no difference for basic pixel processing effects such as MathOps and color processing.
A facility is included with Sapphire Plug-ins that allows users with some programming experience to define and customize new effects. A number of parameters are also available that can be adjusted to customize the behavior of all Sapphire plug-ins. The load_save_channel_setups parameter can be enabled to save animation curves in the channel editor between uses of the same Spark. Lookup tables can be specified for more accurate Spark processing of log format images. For additional information on these, or to modify a parameter, see the s_config.text file.
On Linux the config file is located at /usr/discreet/sparks/sapphire_11/s_config.text
On Mac the config file is located at /Applications/GenArtsSapphireSparks11/config/s_config.text
Some Spark parameters have changed between Sapphire version 9 and 10, so we have provided an update_setups unix command to automatically convert 9.0 (or 9.x) setup files to 10.0 (or 10.x).
update_setups [ -backup ] [ -recurse ] file1 [file2 ...]This converts Spark setup files and/or Batch setup files to use Sapphire 10. It can accept multiple file names separated by spaces, and wildcards (*) can be used. It ignores anything that doesn't look like a setup file with Sapphire Plug-ins, so you can use wildcards or directories that include extraneous files. If you convert the Spark setup files for a Batch setup, you must also convert the corresponding .batch file and vice versa. If "sapphire_9" is included in the setup file name, update_setups will also rename the file to say "10" to allow Batch setup conversions to work properly.
The -recurse or -r option allows update_setups to recurse into directory trees and convert all setup files within that directory (but it does not follow symlinks). It will also cause any sapphire_9 setup directories to be renamed to sapphire_11. Use the -r flag with care, because it could search and update a large number of files.
The -backup or -b option causes a 'v8' backup file to be made for each setup file before it is modified. This will not replace existing 'v9' backups, so if you run it twice the backup should still be the original. If you need to access a backup of a Spark setup, you can load the 'v9' setup file directly into Sapphire 9.0. If you need to revert to a backup of a Batch setup, you should rename the 'v8' backup files to their original names. If you are converting many files, it is often better to first backup the entire directory yourself instead.
In some effects we have fixed long-standing bugs or made improvements that will significantly change the results of old projects in ways that update_setups can't correct for. These exceptions are noted below:
- Improved accuracy of gamma correction when rendering on the CPU. This can change the results for effects with extreme gamma values (large or small).
- In CardFlip , corrected the direction for Up and Down spin directions. Old projects should automatically update and continue to render without changes.
Example 1: If you want to convert a single setup file for S_Clouds called TestSetup which you have stored in /tmp , you could open a shell window and type:
% cd /usr/discreet/sparks/sapphire_11
% ./update_setups -backup /tmp/TestSetup.S_Clouds
This will replace /tmp/TestSetup.S_Clouds with a version that uses Sapphire 10. The -backup flag causes the original file to be saved first as /tmp/TestSetup.v9.S_Clouds .
Example 2: If you want to make a backup copy of your batch directory and then convert all the setups in it to Sapphire 10 format, you could type:
% cd /usr/discreet/flame_9.5
% cp -r batch batch-backup
% /usr/discreet/sparks/sapphire_11/update_setups -r batch
Example 3: If you want to convert all the setups in an entire project, you could type:
% cd /usr/discreet/project/effects
% /usr/discreet/sparks/sapphire_11/update_setups -r your-project
This will apply update_setups to all files anywhere in the your-project directory, and rename any sapphire_9 setup directories and files to sapphire_11 . Make sure your project directory is somehow backed up first!
On Mac, update_setups is located in /Applications/GenArtsSapphireSparks11/config .
Note to system administrators: update_setups is a Perl script, and requires Perl 5. You don't need to be root to run the script, but you do need write permission in the setup directory.
- Trimming clips from the head may invalidate the Mocha track.
- Tracking data exported from Mocha when using proxies may be incorrect. Always switch to full resolution before exporting tracking data.
- On CentOS 5, saving shape data from Mocha may cause Mocha or Flame to hang.
Temporal effects in Batch that access frames other than the single
current frame may not process efficiently. It is recommended that you
make the input to temporal effects in Batch be a clip or a cached node
rather than a tree of other nodes. These effects include S_Temporal,
S_FieldTool, S_FieldRemove, and S_Feedback:TimeAverage. Also in
Batch, the Feedback effects will not work properly if they are
upstream of any temporal effect. For Autodesk releases prior to
4.0/7.0 the temporal effects do not work in Batch at all.
Only one set of keyframes is kept for a given Spark. Some Sparks
contain multiple effect options, and the names of parameters can
change when you switch between them. If you set some keyframe values,
and then switch to a different effect option in the same Spark, the
old keyframes will continue to affect the new parameter values.
Sometimes this can give inappropriate values. If this occurs, use
Reset All in the channel editor to clear any existing keyframes, and
use Load Defaults to set the new parameters to reasonable values.
- Autodesk-certified NVidia driver 346.35 is required for GPU acceleration, but on Linux this disables GPU acceleration in older versions of Sapphire. We hope a future update from NVidia will resolve this problem.