© Tweak Software

images/rv.png RV 4 Porting Guide

This document describes some of the issues involved in porting both RV Mu/Python packages and external code which generates session files for RV to play.

Session Files

RV4’s internal structure differs from RV3 in a number of ways. This means that the session file will contain some new node types as well as modified existing ones. In some cases the version number of a node has been bumped.

The session file version is now 4 (previous it was 2). The version number 3 was skipped to avoid any confusion with rv’s versioning.

When rv encounters a version 2 or 1 file it will translate the file into version 4 structures on the fly. New features will only be available to writers of version 4 files.

GTO Version 4

RV is now using version 4 GTO files (not to be confused with RV session file version 4). There are two significant changes between version 3 and 4 GTO:

Multidimensional Property Types

GTO version 4 adds four dimensional shape to properties. Version 3 files only allowed a single dimension with size (called width). For example, a 4x4 matrix can now be represented as float[4,4] instead of float[16]. At the extreme, a 32x32x32 3D LUT with a color at each point can be represented as float[3,32,32,32] property.

RV 4 only uses this feature for storage of static data currently. All other property types are the same as in RV 3.

To create a multdimensional property within RV, you’d use the newNDProperty() command.

Component Namespaces Can Be Nested

Components can now be nested. So where GTO 3 allowed only object.component.property GTO 4 allows object.comp1.comp2.comp3.property.

No changes to the GTO function API were necessary to add this feature, but a change in the data structs and a semantic change were made:

  1. The component header includes a "childLevel"

  2. The reader ComponentInfo structure contains a pointer to the parent ComponentInfo structure

  3. When writing, the component begin/end calls can be nested.

RV 4 uses nested components in node definition files. It does not (yet) use them in session files.

Connections in RVSession Object

The top level node connections in the connections object are now stored as pairs of strings in a proprety called "conections":

[ [ "left-hand-side-node" "right-hand-side-node" ] ... ]

previously the connections were stored as a separate lhs and rhs property. The old configuration will still work in the new RV, but RV will only write out the new way.

RVColor Node Split Into RVLinearize And RVColor

Some of the properties that were formerly in the #RVColor node are now located in a new #RVLinearize node. These are:

  • color.alphaType

  • color.logType

  • color.whiteCodeValue

  • color.blackCodeValue

  • color.YUV

  • color.sRGB2linear

  • color.Rec709ToLinear

  • color.fileGamma

  • color.ignoreChromaticities

So where previously the property name "#RVColor.color.logType" was used, now "#RVLinearize.color.logType" would be instead.

Because of the above changes, the RVColor node version has been bumped up to 2 (it was 1).

Source View/Layer/Channel Selection

As part of implementing the OPenEXR 2.0 spec and adding support for MuliPart files, these properties have been removed from the RvFileSource and RVImageSource nodes:


Any values are considered image layer names. These are passed to the image readers with the request that only these layers be read from the file.


Any values are considered image view names. These are passed to the image readers with the request that only these views be read from the file.

And replaced with this property:


This string array is of the form: type, view, [layer[, channel]]. The type describes what is defined in the remainder of the array. The type may be one of ”view”, ”layer”, or ”channel”. The 2nd element of the array must be defined and is the value of the view. If there are 3 elements defined then the 3rd is the layer name. If there are 4 elements defined then the 4th is the channel name.

Additional details on the handling of views/layers/channels in RV can be found in the section in the user manual concerning the OpenExr File Format.

Two CDL Slots Per-Source in Default Color Pipeline

There are now two CDL slots instead of one: one in the RVColor node (as in rv 3.X) and a new one in RVLinearize node. The new CDL in the RVLinearize node gets evaluated before linearization occurs, the one in the RVColor node is evaluated after linear color changes (exposure, hue, saturation, etc).

RVDisplayGroup split into RVDisplayGroup and RVViewGroup

The RVDisplayGroup which formerly included the RVSoundTrack and RVDispTransform2D nodes has been split apart. A new node group RVViewGroup has been added which includes the soundtrack and display transform nodes. The RVDisplayGroup is now only concerned with display color correction and stereo output mode.

Multiple RVDisplayGroup Nodes

RV 4 creates an RVDisplayGroup node for each attached display (and SDI device if present in RVSDI). Unlike RV 3, the display groups are not written to the session file.

Because of this, each display device can have a unique color correction. The name of the physical device can be found in the #RVDisplayGroup.device.name string property. When RV moves between devices on a virtual desktop RV will switch to using the corresponding RVDisplayGroup.

Separate RVColor Node

In RV 4 its now possible to use the RVColor (or one of the OCIO nodes) as a seperate top-level user node. For example, this makes it possible to have secondary color correction in a sequence when each input to the sequence is a top-level RVColor node with a source as its input.

Color, Viewing, and Display Pipelines

RV 4 has completely programmable color handling. There are now five locations which contain "pipelines" defaulting to standard RV color nodes like RVColor, RVLinearize, RVLookLUT, and RVDisplayColor. Each of these can be augmented or completely changed to have a different set of nodes than the default node. These are:

  • Pipelines in RVSourceGroup

    • RVLinearizePipelineGroup: Linearization Pipeline (defaults to RVLinearize node)

    • RVColorPipelineGroup: Color Pipeline (defaults to RVColor node)

    • RVLookPipelineGroup: Look Pipeline (defaults to RVLookLUT node)

  • Pipelines in RVViewGroup

    • RVViewPipelineGroup: empty by default

  • Pipelines in RVDisplayGroup (one per device)

    • RVDisplayPipelineGroup: Color Correction Pipeline (defaults to RVDisplayColor)

For example, RV’s OpenColorIO support is implemented by swapping in OCIO nodes for RV’s nodes in key locations.

Using RVX new nodes can be authored and packaged for use by RV. Changing a pipeline is as simple as modifying a string array property on one of the five pipeline group nodes: RVDisplayPipelineGroup, RVColorPipelineGroup, RVLinearizePipelineGroup, RVViewPipelineGroup or RVLookPipelineGroup.

propertyInfo() Command

The PropertyInfo structure has changed in rv4. Properties can now be multidimensional (up to 4 dimensions); the PropertyInfo struct was updated to reflect that:

    class: PropertyInfo
        string name
        int type
        (int,int,int,int) dimensions
        int size
        bool userDefined
        string info

Source Setup Package

The RV 4.0 version of source_setup is written in Python, to make it easier to use as a model. Some details about the way the package works can be found in the reference manual. Aside from being written in Python, one big difference int he new source setup is that its action is triggered by the "source-group-complete" event, rather than the "new-source" event. The new-source event was always problematic, since it is sent when the source is "half-constructed" and some command-line options are yet to be applied, for example.

If you have previously written a custom source_setup package, it should continue to work as before, as long as the new source setup is deactivated.

If you write a source setup package or expect an old one to work in concert with the standard source setup, it should be written or re-written on the model provided (IE using source-group-complete rather than new-source). The init() call of your package should use the "sortKey" "source_setup" and a "sortOrder" > 10, to ensure that your source setup runs after the installed one.

Python Default Values

In RV 4.0 we have figured out how to properly handle default values for the RV Command API in Python, so command arguments listed as optional in the API browser no longer need to be specified when the command is called from Python. This means that the documentation in the Help menu’s Mu API Browser is now really a fairly accurate description of the Python API as well.