Sapphire Plug-ins v5 for Autodesk systems, General User Info


What's new in version 5.0

New Effects:

  1. TVDamage simulates various artifacts of television broadcast and display such as static, ghosting, interference, and more.
  2. Technicolor2Strip simulates a Technicolor 2-strip film process to give the look of 1930s Technicolor film.
  3. Technicolor3Strip simulates a Technicolor 3-strip film process to give the look of 1935-1955 Technicolor film.
  4. Swish3D dissolves between two input clips while performing 3D moves on each.
  5. TVChannelChange performs a transition by simulating a channel change on an old television set.
  6. WipePlasma transitions between two input clips using a moving plasma texture.
  7. WipePointalize wipes by adding random polygon brush shapes from one clip onto another.
  8. WipeWeave transitions using a texture resembling woven strands.
  9. WipeMoire transitions using a pattern of overlapping concentric rings.
  10. DissolveLensFlare transitions between two clips using an animated lens flare.
  11. DissolveEdgeRays transitions between two clips while applying beams of light from the image edges.
  12. DissolveGlint transitions between two clips while applying a star shaped glint effect.
  13. DissolveGlintRainbow transitions between two clips while applying a star shaped glint rainbow effect.
  14. DissolveDefocus dissolves between two clips while defocusing/focusing each.
  15. DissolveTiles transitions between two input clips by shifting tile shaped sections of each.
  16. DissolveDistort interpolates between two clips while distorting each using the other as a lens.

New Features and Parameters:

  1. All effects use floating point procesing for improved image quality and HDR support.
  2. Sapphire can now process 16-bit floating point footage.
  3. GPU acceleration improves performance for many effects.
  4. All threshold controls now go beyond 1 to support HDR.
  5. Param limits are widened for ShowBadColors to support HDR.
  6. All effects now automatically detect the field status of source clips with On Fields: Auto mode
  7. Z Defocus and Z Convolve now have Boost Highlights.
  8. Glint and Glare have new Blur, Hue Shift, and Invert Mask parameters.
  9. Glow has new Show Threshold, Invert Mask, and Combine parameters.
  10. LensFlare has a new Glint Rays Lens.
  11. On-screen widgets now have labels for easier identification.
  12. Etching has additional angle and frequency controls.

Loading a Spark

To load a Spark, select the "Effects" menu in your Autodesk systems product, hold down the 'Alt' key, and click on any Spark button. Select the "Titles" button and navigate to the sapphire_5 directory. Use the "Proxies" option to view the different Spark proxy images. Select a Spark and the name should now appear on the button. Click again on the button to initialize the Spark. Select the source and destination reels and the Spark interface window should be displayed.

To load a Spark in Batch, select "Spark" in the Add menu of Batch, and then click on "Add." On newer Autodesk versions, drag from the "Spark" button onto the batch tree instead. Navigate to the sapphire_5 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, GlowsMask takes Source and Mask inputs, GlowsComp takes Source, Back and Matte, and GlowsMaskCmp 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.


Resolution options

Every Spark includes a "Res" factor popup menu in the far right just below the "Pan" button. The resolution options allow trading off between result quality and speed. Lower Res factors can be helpful for faster testing of parameter values. The Res factor defaults to FULL. Field processing options will not output useful fields at lower resolutions. If you modify the Res factor, make sure you remember to set it back to FULL for the best quality during final processing!


On Fields options

All Sparks include an On Fields popup button on the right hand edge of the first Control page (except Temporal and FieldTool which do special field processing). This can be useful for processing interlaced video frames. When enabled, the two fields, the odd and even lines of each frame, are assumed to represent different time samples, and are processed independently. When the second field is processed, the values of all animated parameters are found at the current frame + .5. The Res factor should be set to FULL for useful field outputs. Four options for field processing are available:
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 modes

Each Spark includes a popup button in the right hand side of each Control page that allows selecting from the following Redraw modes. The default redraw mode is DRAG AUTO RES.

  1. 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.

  2. Redraw: DRAG. This output is recalculated during the adjustment of any parameter or widget.

  3. Redraw: PENUP. The output is recalculated after any parameter is adjusted or a widget is moved.

  4. 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 API).

  5. 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.

Undo & Load Defaults

Each Spark also includes two buttons in the lower right hand corner of each Control page for undoing previous parameter changes and loading default values for all parameters.

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.


Cropping

Each Spark includes cropping parameters on the "Crop/Help" or "Ctrl3" page which allow selecting a crop rectangle for processing a subsection of the result. This can be used for faster testing or for comparison of the processed result with the original.

  1. Enable Crop. Turns on or off cropping and the crop widget.

  2. 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.

  3. Surround. Selects the method for filling the areas beyond the crop rectangle, either with a given color or with any of the unprocessed Source inputs.

  4. 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.

  5. 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.

  6. Set Crop Defaults. When pushed, sets the crop rectangle to full frame.
Not all plug-ins render faster when the crop area is reduced. Effects that require processing beyond the crop area, such as the Blurs, Glows, Glints, and Glares, require nearly the same processing whether cropped or not. However, other effects such as RackDefocus, EdgeRays, BlurMotion, Streaks, MathOps and Color Operations, should render faster when the crop area is reduced.


Adding Noise

Each spark has an Add Noise parameter on the Crop/Help parameter page. If this parameter is greater than zero, a corresponding amount of color noise is added to the result. This can be used to reduce banding due to quantization, or create a grainy effect. Set this to 1.0 or slightly higher to enable appropriate debanding for 8bit images.


Colorspace Controls

Each spark has two parameters that control the colorspace: Use Gamma and a LUT popup. The Use Gamma parameter applies a gamma correction before performing the effect, then reverses the gamma correction before displaying the processed frame. This allows linear processing of gamma-corrected images, can help preserve highlights when blurring, and sometimes gives more correct results when compositing.

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.


GPU Acceleration

Many effects can use the GPU to speed up rendering. This requires an NVIDIA graphics card which supports CUDA, such as a Quadro FX 5600 or 5800. If a suitable GPU is found, a GPU Enable button will appear on the Crop/Help parameter page, and the message "GPU Accelerated" will be printed to the shell when the Spark is loaded. GPU acceleration is enabled by default if it's available, but if you experience performance or stability problems, you can turn it off by deselected the GPU Enable button.

Troubleshooting GPU Problems

If 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.
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 Burn

By 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.

Online documentation

An online "Help" button is accessible via the "Crop/Help" or "Ctrl3" page for each plug-in and gives easy access to HTML documentation via your browser. The "Help" button loads locally installed documentation for the current effect with information about each input and parameter. The "Sapphire Intro" button loads the Sapphire plug-ins introduction page with links to the other documents and example pictures. The "GenArts Web Site" button connects to the home page of GenArts, Inc. if your workstation is on the Internet, for current information and updates.

Complete documentation is also available in PDF format on the Sapphire Plug-ins CDROM in /CDROM/Sapphire-Users-Guide-Autodesk.pdf. You can also download it directly from our website.


Aborting a Spark process

Any Spark process can be aborted by holding down the pointer for a few seconds. Some effects have combinations of parameter settings that can cause unacceptably long process times. This feature provides a way to abort a render mid-frame, so the parameters can then be reset to acceptable values, without waiting for the frame to finish.


Pixel aspect ratios

For some image formats, the digital form of the image is scaled non-uniformly to produce the final viewed picture. For example NTSC resolution is normally 720x486 with an aspect ratio of 1.481. However, the final NTSC picture has an aspect ratio of 1.333. Thus the original digital image is scaled in the horizontal direction by a factor of 0.9 and shapes rendered as circles can end up squashed slightly into ovals. The original pixels are effectively rectangular shaped instead of squares, and have an aspect ratio of 1.48/1.333 = 1.111.

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.


Customizing Sparks

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, open the config file by typing the following command to a unix shell:
%  jot /usr/discreet/sparks/sapphire_5/s_config.text


Updating v4 Setups to v5

Some Spark parameters have changed between Sapphire version 4 and 5, so we have provided an update_setups unix command to automatically convert 4.0 (or 4.x) setup files to 5.0 (or 5.x).
update_setups [ -backup ] [ -recurse ] file1 [file2 ...]
This converts Spark setup files and/or Batch setup files to use Sapphire 5. 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_4.0" is included in the setup file name, update_setups will also rename the file to say "5" 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_4.0 setup directories to be renamed to sapphire_4. Use the -r flag with care, because it could search and update a large number of files.

The -backup or -b option causes a 'v4' backup file to be made for each setup file before it is modified. This will not replace existing 'v4' 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 'v4' setup file directly into Sapphire 4.0. If you need to revert to a backup of a Batch setup, you should rename the 'v4' backup files to their original names. If you are converting many files, it is often better to first backup the entire directory yourself instead.

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_5
%  ./update_setups -backup /tmp/TestSetup.S_Clouds

This will replace /tmp/TestSetup.S_Clouds with a version that uses Sapphire 5. The -backup flag causes the original file to be saved first as /tmp/TestSetup.v4.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 5 format, you could type:

%  cd /usr/discreet/flame_9.5
%  cp -r batch batch-backup
%  /usr/discreet/sparks/sapphire_5/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_5/update_setups -r your-project

This will apply update_setups to all files anywhere in the your-project directory, and rename any sapphire_4.0 setup directories and files to sapphire_5. Make sure your project directory is somehow backed up first!

Note to system administrators: update_setups is a Perl script, and requires Perl 5. If you don't have Perl in /usr/bin/perl, you can install it from the SGI OS Foundation CD, in the eoe.sw.gifts_perl package. You don't need to be root to run the script, but you do need write permission in the setup directory.


Known problems

  1. 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.

  2. 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.


To Sapphire Plug-ins Introduction


© 2010, GenArts, Inc. All rights reserved.