text: 1 Introduction
  1.1 Overview
  RV and its companion tools, RVIO and RVLS have been created to support digital artists, directors, supervisors, and production crews who need reliable, flexible, high-performance tools to review image sequences, movie files, and audio. RV is clean and simple in appearance and has been designed to let users load, play, inspect, navigate and edit image sequences and audio as simply and directly as possible. RV's advanced features do not clutter its appearance but are available through a rich command-line interface, extensive hot keys and key-chords, and smart drag/drop targets. RV can be extensively customized for integration into proprietary pipelines. The RV Reference Manual has information about RV customization.
  This chapter provides quick-start guides to RV and RVIO. If you already have successfully installed RV, and want to get going right away, this chapter will show you enough to get started.
  1.2 Getting Started With RV
  1.2.1 Loading Media and Saving Sessions
  RV can load individual files or multiple files (i.e. a sequence) and it can also read directories and figure out the sequences they contain; you can pass RV a directory on the command-line or drag and drop a folder onto RV. RV's ability to read directories can be particularly useful. If your shots are stored as one take per directory you can get in the habit of just dropping directories into RV or loading them on the command line. Or you can quickly load multiple sequences or movies that are stored in a single directory.
  shell> rv foo.mov shell> rv [ foo.#.exr foo.aiff ] shell> rv foo_dir/ shell> rv .
  shell> rv -help
  The output of the -help flag is reproduced in this manual in the chapter on command-line usage, Chapter 3. editing operations to be processed by RVIO.
  1.2.2 Caching
  If your image sequences are too large to play back at speed directly from disk, you can cache them into system memory using RV's region cache. If you are playing compressed movies like large H.264 QuickTime movies, you can use RV's lookahead cache to smooth out playback without having to cache the entire movie. If your IO subsystems can provide the badwidth, RV can be used to stream large uncompressed images from disk. You can set the RV cache options from the Tools menu, using the hot keys ``Shift+C” and ``Ctrl-L” (``Command+L” on Mac) for the region cache and lookahead cache respectively, or from the command line using ``-c” or ``-l” flags. Also see the Caching tab of the Preferences dialog.
  1.2.3 Sources and Layers
  RV gives you the option to load media (image sequences or audio) as a Source or a Layer. A source is a new sequence or movie that gets added to the end of the default sequence of the RV session. Adding sources is the simplest way to build an edit in RV. Layers are the way that RV associates related media, e.g. an audio clip that goes with an EXR sequence can be added as a layer so that it plays back along with the sequence. Layers make it very simple to string together sequences with associated audio clips–each movie or image sequence can be added as source with a corresponding audio clip added as a layer (see soundfile commandline example above). RV's stereoscopic display features can interpret the first two image layers in a source as left and right views.
  1.2.4 RV Views
  RV provides three default views, and the ability to make views of your own. The three. See 5 for information about the process of creating and managing your own views.
  1.2.5 Marking and Navigating
  RV's timeline (hit TAB or F2 to bring it up) can be marked to make it easy to navigate around an RV session. RV can mark sequence boundaries automatically, but you can also use the ``m” key to place marks anywhere on the timeline. Once a session is marked you can use hot keys to quickly navigate the timeline, e.g. ``control+right arrow” (``command+right arrow'' on Mac) will set the in/out points to the next pair of marks so you can loop over that part of the timeline. If no marks are set, many of these navigation options interpret the boundaries between sources as “virutal marks”, so that even without marking you can easily step from one source to the next, etc.
  1.2.6 Color
  RV provides fine grained control over color management. Subsequent sections of this manual describe the RV color pipeline and options with a fair amount of technical detail. RV supports file LUTs and CDLs per source and an overall display LUT as well as a completely customizable 'source setup' function (described in the RV Reference Manual). For basic operation, however, you may find that the built in hardware conversions can do everything you need. A common example is playing a QuickTime movie that has baked-in sRGB together with an EXR sequence stored as linear floating point. RV can bring the QuickTime into linear space using the menu command Color->sRGB and then the whole session can be displayed to the monitor using the menu command View->sRGB.
  LUTs can be loaded into RV by dragging and dropping them onto the RV window, through the File->Import menus and on the command line using the -flut, -llut, -dlut, and -pclut options. Similarly CDLs can be loaded into RV by dragging and dropping them onto the RV window, through the File->Import menus and on the command line using the -fcdl and -lcdl options.
  1.2.7 Menus, Help and Hot Keys
  RV's Help menu contains a link to launch the RV Manual (this document) the RV Reference Manaul (for customizations), along with links to RV release notes, the draft Mu Users Manual, and some additional arcane sounding menu commands.
  Help->Show Current Bindings will print out all of RV's current key bindings to the shell or console (these are also included in chapter X of this manual). RV's menus can be reached through the menu bar or by using the right mouse button. Menus items with hot keys will display the hot key on the right side of the menu item. Some hot keys worth learning right away are:
  - Space - Toggle playback
  - Tab or F2 - Toggle Show Timeline
  - 'i' - Toggle Show Info Widget
  - '`' - (back-tick) Toggle Full Screen
  - F1 - Toggle Show Menu
  - Shift + Left Click - Open Pixel Inspector at pointer
  - “q” to quit RV (or close the current session)
  Also from the Help menu, you can reach all of Tweaks online resources, include the Tweak web site, demo videos, latest documentation, and the support forums. If you've having some problem with RV, you can also start a support ticket (either from email or the web) directly from the Help menu.
  1.2.8 Parameter Editing and Virtual Sliders
  Many settings in RV, like exposure, volume, or frame rate, can be changed quickly using Parameter Edit Mode. This mode lets you use virtual sliders, the mouse wheel or the keyboard to edit RV parameters. Hot keys and Parameter Editing Mode allow artists to easily and rapidly interact with images in RV. It is worth a little practice to get comfortable using these tools. For example, to adjust the exposure setting of a sequence you can use any of the following techniques:
  - Hit the 'e' key to enter exposure editing mode Then:
  - Click and drag left or right to vary the exposure, and then release the mouse button to leave the mode,
  - OR: Roll the mouse wheel to vary the exposure and then hit return to leave the mode.
  - OR: Hit return, type the new exposure value at the prompt, and hit return again (typing '.' or any digit also starts this text-entry mode)
  - OR: Use the '+' and '-' keys to vary the exposure and then hit return to leave the mode.
  - Use the 'r' 'g' 'b' keys to edit individual color channels. ('c' to return to editing all 3 channels.) Parameters that can be “unganged” in this way will display a 3-color glyph in the display feedback when you start editing.
  - Hit the 'l' to lock (or unlock) slider mode, so that you can repeatedly set the same parameter ('ESC' to exit).
  - The 'DEL' or 'BackSpace' key will reset the parameter to it's default value.
  - When multiple Sources are visible, as in a Layout view, parameter sliders will affect all Sources. Or you can use 's' to select only the source under the pointer for editing.
  Some parameters in RV don't use virtual sliders; you can edit these directly by entering the new value, e.g. to change the playback frames per second:
  1.2.9 Preferences and Command Line Parameters
  RV's Preferences can be opened with the RV->Preferences menu item. be set to a preferred default value in the Preferences. RV also has a -noPrefs command line flag so that you can temporarily ignore the preferences, and a -resetPrefs flag that will reset all preferences to their default values. The quickest way to take a look at all of RV's command line options is:
  shell> rv -help
  1.2.10 Customizing RV
  RV is built to be customized. For many users, this may be completely ignored or be limited to sharing startup scripts and packages created by other users or by Tweak. A package is a collection of script code (Mu or Python) and interface elements which can be automatically loaded into RV. A package can be installed site wide, per-show, or per-user and a command line tool (rvpkg) is included for package administration tasks.
  Customization is discussed in detail in the RV Reference Manual. The RV command API technical documentation can be browsed from Help->Mu Command API Browser.
  1.3 Getting Started with.
  1.3.1 Converting Sequences and Audio
  RVIO is a powerful pipeline tool. Like RV, the basic operation of RVIO is very simple, but advanced (and complex) operations are possible. RVIO can be used with a command line very similar to RV's, with additional arguments for specifying the output. Any number of sources and layers can be given to RVIO using the same syntax as you would use for RV. Some basic RVIO command line examples are:
  shell> rvio foo.exr -o foo.mov shell> rvio [ foo.#.exr foo.aiff ] -o foo.mov shell> rvio [ foo_right.#.exr foo_left.#.exr foo.aiff ] \ -outstereo -o foo.mov
  shell> rvio -help
  1.3.2 Processing RV Session Files
  RVIO can also take RV session files (.rv files) as input. RV session files can contain composites, color corrections, LUTs, CDLs, edits, and other information that might be easier to specify interactively in RV than by using the command line. RV session files can be saved from RV and then processed with RVIO. For example
  shell> rvio foo.rv -o foo_out.#.exr
  When rvio operates on a session file, any of the Views defined in the session file can be selected to provide rvio's output, so a single session could generate any number of different output sequences or movies, depending on which of the session's views you choose.
  1.3.3 Slates, Mattes, Watermarks, etc.
  RVIO uses Mu scripts to create slates, frame burn-in and other operations that are useful for generating dailies, client reviews and other outputs. These scripts are usable as is, but they can also be modified or replaced by users. Some examples are:
  shell> rvio foo.#.exr -overlay watermark "For Client Review" 0.5 \ -o foo.mov shell> rvio foo.#.exr -leader simpleslate \ "Tweak Films" \ "Artist=Jane Doe" \ "Shot=SC101_vfx_01" \ "Notes=Lighter/Darker" \ -o foo.mov
  2 Installation
  2.1 Overview
  On Windows, RV is packaged with an installer program or as a zip file. On Linux RV is packaged as a tarball. On Mac OS X, RV is packaged as a dmg file. In all cases, RV requires a Shotgun account or a license file from Tweak in order to run. See below for details on Shotgun licensing. If you elect to use a node-locked or floating “traditional” license, select the “I have an RV license” option from the License Manager and follow the directions. The Tweak License Installer will launch and you can browse to the license file from Tweak, install, save, and restart RV.
  Please Note: in large installations, where the license is installed and managed by a central authority and individual users should never be installing licenses, the environment variable TWEAK_NO_LIC_INSTALLER can be set in the global environment. This will prevent RV from ever launching the license installer, even when no valid license can be found.
  2.1.1 Shotgun Licensing on All Platforms
  When RV starts without a license (or when you select “License Manager” from the File menu), you'll be presented with this dialog:
  - The current licensing style is always configurable via the 'License Manager' item on the 'File' menu.
  - The RV (and RV-SDI) version 6.0 executables support both licensing systems (standard Tweak licensing and licensing via Shotgun).
  - RV-SDI can be licensed via Shotgun only at sites using "Super Awesome" support.
  - There's no requirement that a given site use only one style of licensing.
  - RV licensed via Shotgun is functionally identical to RV licensed the usual way.
  - A user can switch from Tweak-standard to via-Shotgun licensing and back (the choice is stored as a preference).
  - At a facility where standard Tweak RV licensing is set up and working, there will be no change when the user runs RV6 (they will be able to try out via-Shotgun licensing by selecting a menu item if they wish).
  - Licensing RV via Shotgun does not produce any requirement to use Shotgun for other purposes. For example, users may license RV via Shotgun, but not use Screening Room.
  - A user who authenticates RV via Shotgun username/passwd once, and then runs RV at least once a week, will not have to authenticate again. (The original authentication will be refreshed on each run, assuming that the Shotgun server is accessible, and the username/passwd is still valid).
  - Similarly, an RV user who authenticates via Shotgun will be able to use RV "offline" (when the Shotgun server is unavailable) for 30 days, starting from the most recent "online" use.
  - Using RVIO to export from RV is allowed as long as RV is licensed (with any licensing scheme). Usage of RVIO "on the farm" (or otherwise unassociated with any local RV process) still requires a standard Tweak license.
  For “traditional” licensing, select the second option in the License Manager dialog, and follow instructions to install a license (or just exit RV to return to an existing “traditional” licensing setup).
  Site-wide Control of Server URL or Login Default Values
  If the user hasn't authenticated with Shotgun yet, and the envronment varable RV_SHOTGUN_DEFAULT_SERVER_URL is set, its value will be used as the default server URL in the dialogs. If you as the admin of a site can predict the user name as well (for example if everyone uses First.Last) you could set the environment variable RV_SHOTGUN_DEFAULT_LOGIN in the user's dot files or whatever, and that value will be used as the default login.
  Proxy Configuration
  If a network proxy is required to access your Shotgun server, you can configure RV to use that proxy server with environment variables, as described below.
  A Note on “Legacy” Shotgun Integration Set-ups
  Prior to the release of Shotgun6 / RV6, users of the RV/Shotgun integration were required to set up a “custom config module” that specified the Shotgun URL server and “script key” in order to authenticate with the server. Since the new code will authenticate with login/password (and the script key authentication is a giant security hole), the custom config module is no longer needed for that purpose. However, you can also use a custom config to fit the integration to your non-standard Shotgun entity/field structure, or to add support for additional fields. If you have a custom config and want to continue using it for that purpose, we recommend that you adjust the serverMap() function in your config module to return an empty string. (Note that most of the new stuff should still work with the “old” serverMap, but it can interfere with env var control mentioned above.)
  Local Servers That Only Support HTTP (not HTTPS)
  The RV/Shotgun integration and licensing will always attempt to use the https protocol for maximum security. This can cause problems in some local Shotgun installations which only support http (or only partially support https). In those cases the environment variable RV_SHOTGUN_AUTH_NO_HTTPS can be set to prevent the use of https unless it is specifically requested in the URL.
  2.2 Mac OS X
  2.2.1 Requirements
  RV requires a recent mac running the latest OS X 10.6 (snow leapord) or better. In order to use new features OS X 10.7 (lion) is required in order to use OpenGL 3.2.
  2.2.2 Installation and Licensing
  Download the latest Mac version of RV onto your Macintosh. This will be a .dmg file. Double click on the .dmg icon. Once the folder opens, drag the RV application onto the Applications link.. Then restart RV.
  If you don't yet have a license, you will need to get one from Tweak. RV's licenses are locked to your computer using the Ethernet ID. Send this ID to Tweak to have a license generated for your computer. The Ethernet ID looks something like this: 00:19:E3:04:8B:80, and can be found in the OS X network preferences, under the option Built-in Ethernet in the Ethernet tab. It is easy to accidentally find the ID for the Airport or other device on your Macintosh, so double check to make sure you have the correct ID. If you computer has multiple network ports, choose the first one.
  2.2.3 Structure of RV on OS X
  In OS X, RV is built as an Application bundle (.app). The bundle contains all of the same types of files found in the Linux distribution tree, but also contains OS X specific files like icons and user interface elements (.nib files). The application bundle can be installed at any location in a Mac file system or may be installed on an NFS mounted file system.
  If you wish to use RV command line tools, you will need to add the MacOS directory to your path. The directory is located relative to wherever you have installed RV. For example, if you installed RV in the default location, the /Applications directory, then the path would be /Applications/RV.app/Contents/MacOS. Or /Applications/RV64.app/Contents/MacOS for the 64-bit version.)
  If you wish to use RV as the protocol handler for the rvlink URL protocol (see Appendix C), run RV once with the -registerHander command-line option. This will register the rvlink protocol handler with the operating system.
  2.3 Linux
  2.3.1 Requirements
  RV is built to work with NVidia graphics cards on Linux. A current NVidia driver (which supports OpenGL 3.2 or newer) is required.
  2.3.2 Installation and Licensing
  RV for Linux is distributed as a gzipped tarball. Un-tar this archive into the directory in which you would like to install RV with some version of the tar command, like this.
  tar -zxf rv-Linux-x86_64-3.5.1.tar.gz
  Edit your dot files to include the rv/bin directory in your PATH. You can use the Tweak license installer to install your license, or can copy it directly in the $RV_HOME/etc subdirectory and name it “license.gto.”
  2.3.3 Structure of RV on Linux
  On Linux, the directory tree resulting from the above 'untar' can be installed anywhere. The directory tree contains the RV binary, start-up script, and runtime support files as well as documentation. In order to use rv from a shell, you will need to have the bin directory of the RV distribution tree in your path.
  RV is split into two programs: rv and rv.bin. rv is a shell script which sets a number of environment variables including plugin directory locations in the RV tree and search paths for user plugins and scripts. Currently the shell script makes sure the following environment variables are set properly:
  - RV_HOME
  - The location of the RV distribution tree.
  - LD_LIBRARY_PATH
  - inserts $RV_HOME/lib in front of existing directories
  - MU_MODULE_PATH
  - sets to $RV_HOME/plugins/Mu
  - MAGICK_CONFIGURE_PATH
  - sets to $RV_HOME/etc/config
  The rv shell script also contains two optional environment variables related to RV's audio configuration. These are commented out, but you may need to or choose to set them to fine tune RV's audio performance depending on the vintage and flavor of Linux. See the appendix for an in depth discussion of Linux audio configuration.
  Once it has finished setting up the environment the startup script executes the RV binary rv.bin with the default UI script. If you have some of these variables set prior to calling the start up script, they will be modified or augmented to meet RV's requirements.
  If you wish to use RV as the protocol handler for the rvlink URL protocol (see Appendix C), the protocol handler must be registered., we as described here on the Mozilla website.. (see Appendix C)
  2.4 Windows
  2.4.1 Requirements
  RV requires NVIDIA or AMD FirePro graphics cards that are OpenGL 3.2 capable running up-to-date drivers.
  2.4.2 Installation and Licensing
  Download the latest Windows version of RV onto your Windows PC. For 32-bit RV, this will be a windows installer executable. Double click on the installer icon. Follow the instructions to install RV. For 64-bit windows, the download will by a zip file that you can unzip into the desired location..
  If you don't yet have a license, you will need to get one from Tweak. RV's licenses are locked to your computer using the HostID. Send this ID to Tweak to have a license generated for your computer. The Ethernet ID looks something like this: 00:19:E3:04:8B:80. The correct HostID for your computer will be displayed in the license manager dialog in the HostID field on the left.
  2.4.3 Structure of RV on Windows
  RV is installed by default into C:\Program Files\Tweak\RV-3.12. You are given the option of creating a desktop shortcut during installation. RV and other Tweak executable files (rv.exe, rvio.exe, etc.) are placed in the bin subdirectory.
  If you wish to use RV as the protocol handler for the rvlink URL protocol (see Appendix C), the protocol handler must be registered. If you used the .exe windows installer, RV was registered as the rvlink protocol handler as part of that process. If you installed from the zip package, you can edit the file rvlink.reg, in the etc directory, to point to the location where you installed RV. Then run this file (double-click) to edit the registry to register RV as the rvlink protocol handler.
  3 Command Line Usage
  In this chapter, the emphasis will be on using the software from a unix-like shell. On Windows, this can be done via Cygwin's bash shell or tcsh. If you choose to use the command.com shell, the command syntax will be the same, but some features (like pattern matching, etc) which are common with unix shells may not work.
  To use RV from a shell, you will need to have the binary executable in your path. On Linux and Windows the RV executable is located in the bin directory of the install tree.
  On OS X this can be done by including /Applications/RV.app/Contents/MacOS in your path (assuming you installed RV there). The executable on OS X is called RV; you can either type the name in as is or create an alias or symbolic link from rv to RV. (Similarly, the 64-bit version of RV is called RV64.)
  The command line options are not required and may appear throughout the command line. Sources are individual images, QuickTime .mov files, .avi files, audio files, image sequences or directory names. When specifying a .rv file, no other sources should be on the command line. (See Table cap:RV-Command-Line)
  The third example above uses square brackets around groups of sources. When sources appear between brackets they are called layers. These will be discussed in more detail below.
  If RV is started with no arguments, it will launch a blank window; you can later add source material to the window via file browser or drag and drop.
  Options are all preceded by a dash (minus sign) in the unix tradition, even on windows. Some of them take arguments and some of them are flags which toggle the associated feature on or off. For example:
  shell> rv -fullscreen foo.mov
  plays back a movie file in full screen mode. In this case -fullscreen is a toggle which takes no arguments and foo.mov is one of the source material. If an option takes arguments, you supply them directly after the option:
  shell> rv -fps 23.97 bar.#.exr
  Here the -fps option (frames per second) requires a single floating point number
  The most important option to remember is -help. The help option causes RV to print out all of the options and command line syntax and can be anywhere in a command line. When unsure of what the next argument is or whether you can add more options to a long command line, you can always add -help onto the end of your command and immediately hit enter. At that point, RV will ignore the entire command and print the help out. You can always use your shell's history to get the command back, remove the -help option, and continue typing the rest of the command.
  shell> rv -fps 30 -fullscreen -l -lram .5 -help (rv shows help) Usage: RV movie and image viewer ... (hit up arrow in shell, back up over -help and continue typing) shell> rv -fps 30 -fullscreen -l -lram .5 -play foo.mov
  Finally, you can do some simple arithmetic on option arguments. For example if you know you want to apply an inverse gamma of 2.2 to an image to view it you could do this:
  shell> rv -gamma 1/2.2
  shell> rv -gamma 0.454545454545
  Command-Line Options
  3.1 Image Sequence Notation
  RV has a special syntax to describe image sequences as source movies. Sequences are assumed to be files with a common base name followed by a frame number and an image type extension. For example, the filenames foo.1.tif and foo.0001.tif would be interpreted as frame 1 of the TIFF sequence foo. RV sorts images by frame numbers in numeric order. It sorts image base names in lexical order. What this means is that RV will sort images into sequences the way you expect it to. Padding tricks are unnecessary for RV to get the image order correct; image order will be interpreted correctly.
  foo.0001.tif foo.0002.tif foo.0003.tif foo.0004.tif foo.0005.tif foo.0006.tif foo.0007.tif foo.0008.tif foo.0009.tif foo.0010.tif
  shell> rv foo.*.tif
  and RV will automatically attempt to group the files into a logical movie. (Note: this will only work on Linux or Mac OS, or some other unix-like shell, like cygwin on Windows.)
  When you want to play a subset of frames or audio needs to be included, you can specify the sequence using the ``#'' or ``@'' notation (similar to Shake's) or the printf-like notation using ``%'' similar to Nuke.
  rv foo.#.tif rv foo.2-8#.tif rv foo.2-8@@@@.tif rv foo.%04d.tif rv foo.%04d.tif 2-8 rv foo.#.tif 2-8
  The first example above plays all frames in the foo sequence, the second line plays frames starting at frame 2 through frame 8. The third line uses the ``@'' notation which forces RV to assume 0 padded frame numbers–in this case, four ``@'' characters indicate a four character padding.
  The next two examples use the printf-like syntax accepted by nuke. In the first case, the entire frame range is specified with the assumption that the frame numbers will be padded with 0 up to four characters (this notation will also work with 6 or other amounts of padding). In the final two examples, the range is limited to frames 2 through 8, and the range is passed as a separate argument.
  Sometimes, you will encounter or create an image sequence which is purposefully missing frames. For example, you may be rendering something that is very expensive to render and only wish to look at every tenth frame. In this case, you can specify the increment using the ``x'' character like this:
  rv foo.1-100x10#.tif
  rv foo.1-100x10@@@@.tif
  rv foo.1-100x10@@@.tif
  In these examples, RV will play frames 1 through 100 by tens. So it will expect frames 1, 11, 21, 31, 41, on up to 91.
  If there is no obvious increment, but the frames need to be group into a sequence, you can list the frame numbers with commas:
  rv foo.1,3,5,7,8,9#.tif
  In many cases, RV can detect file types automatically even if a file extension is not present or is mis-labeled.
  3.1.1 Negative Frame Numbers
  RV can handle negative frames in image sequences. If the frame numbers are zero padded, they should look like so:
  foo.-012.tif foo.-001.tif
  To specify in and out points on the command line in the presence of negative frames, just include the minus signs:
  foo.-10-20#.tif foo.-10–5#.tif
  The first example uses frames -10 to +20. The second example uses frames -10 to -5. Although the use of the ``-'' character to specify ranges can make the sequence a bit visually confusing, the interpretation is not ambiguous.
  3.1.2 Stereo Notation
  RV can accept stereo notation similar to Nuke's ``%v'' and ``%V'' syntax. By default, RV can only recognize left, right, Left, and Right for %V and for %v it will try L, R, or l and r. You can change the substitutions by setting the environment variables RV_STEREO_NAME_PAIRS and RV_STEREO_CHAR_PAIRS. These should be set to a colon separated list of values (even on windows). For example, the defaults would look like this:
  RV_STEREO_NAME_PAIRS = left:right:Left:Right RV_STEREO_CHAR_PAIRS = L:R:l:r
  foo.0001.left.exr foo.0002.left.exr foo.0001.right.exr foo.0002.right.exr
  foo.%04d.%V.exr
  3.2 Source Layers from the Command Line
  You can create source material from multiple audio, image, and movie files from the command line by enclosing them in square brackets. The typical usage looks something like this:
  shell> rv [ foo.#.exr soundtrack.aiff ]
  Note that there are spaces around the brackets: they must be completely separated from subsequent arguments to be interpreted correctly. You cannot nest brackets and the brackets must be matched; for every begin bracket there must be an end bracket.
  3.2.1 Associating Audio with Image Sequences or Movie Files
  Frequently a movie file or image sequence needs to be viewed with one or more separate audio files. When you have multiple layers on the command line and one or more of the layers are audio files, RV will play back the all of the audio files mixed together along with the images or movies. For example, to play back a two wav files with an image sequence:
  shell> rv [ foo.#.exr first.wav second.wav ]
  If you have a movie file which already has audio you can still add additional audio files to be played:
  shell> rv [ movie_with_audio.mov more_audio.aiff ]
  3.2.2 Dual Image Sequences and/or Movie Files as Stereo
  It's not unusual to render left and right eyes separately and want to view them as stereo together. When you give RV multiple layers of movie files or image sequences, it uses the first two as the left and right eyes.
  shell> rv [ left.#.exr right.#.exr ]
  shell> rv [ left.mov right.100-300#.jpg ]
  shell> rv [ left.#.exr right.#.exr soundtrack.aiff ]
  3.2.3 Per-Source Arguments
  There are a few arguments which can be applied with in the square brackets (See Table 3.1). The range start sets the first frame number to its argument; so for example to set the start frame of a movie file with or without a time code track so that it starts at frame 101:
  shell> rv [ -rs 101 foo.mov ]
  You must use the square brackets to set per-source arguments (and the square brackets must be surrounded by spaces).
  The -in and -out per-source arguments are an easy way to create an EDL on the command line, even when playing movie files.
  3.2.4 A note on the -fps per-source argument
  The point of the -fps arg is to provide a scaling factor in cases where the frame rate of the media cannot be determined and you want to play an audio file with it. For example, if you want to play "[foo.#.dpx foo.wav]" in the same session with "[bar.#.dpx bar.wav]" but the "native frame rate of foo is 24fps and the native frame rate of bar is 30fps, then you might want to say:
  shell> rv [foo.#.dpx foo.wav -fps 24 ] [ bar.#.dpx bar.wav -fps 30 ]
  This will ensure that the video and audio are synced properly no matter what frame rate you use for playback. To clarify further, the per-source -fps flag has no relation to the frame rate that is used for playback, and in general RV plays media (all loaded media) at whatever single frame rate is currenly in use.
  3.2.5 Source Layer Caveats and Capabilities
  There are a number of things you should be aware of when using source layers. In most cases, RV will attempt to do something with what you give it. However, if your input is logically ambiguous the result may be different than what you expect. Here are some things you should avoid using in layers of a single source:
  - Images or movies with differing frame rates
  - Images or movies with different image or pixel aspect ratios
  - Images or movies which require special color correction for only one eye
  - Images or movies stored with differing color spaces (e.g. cineon log images + jpeg)
  - Images with different resolutions but the same image aspect ratio
  - Images with different bit depths or number of channels or chroma sampling
  - Audio files with different sample rates or bit depths
  - Mixing movies with audio and separate audio files
  - An image sequence for one eye and a movie for the other
  - A movie with audio for one eye and a movie without audio for the other
  - Audio files with no imagery
  3.3 Directories as Input
  If you give RV the name of a directory instead of a single file or an image sequence it will attempt to interpret the contents of the directory. RV will find any single images, image sequences, or single movie files that it can and present them as individual source movies. This is especially useful with the directory ``.'' on Linux and OS X. If you navigate in a shell to a directory that contains an image sequence for example, you need only type the following to play it:
  rv .
  You don't even need to get a directory listing. If RV finds multiple sequences or a sequence and movie files, it will sort and organize them into a playlist automatically. RV will attempt to read files without extensions if they look like image files (for example the file ends in a number). If RV is unable to parse the contents of a directory correctly, you will need to specify the image sequences directly to force it to read them.
  4 User Interface
  The goal of RV's user interface is to be minimal in appearance, but complete in function. By default, RV starts with no visible interface other than a menu bar and the timeline, and even these can be turned off from the command line or preferences. While its appearance is minimal, its interaction is not: almost every key on the keyboard does something and it's possible to use key-chords and prefix-keys
  RV makes one window per session. Each window has two main components: the viewing area—where images and movies are shown— and the menu bar. On OS X, the menu bar will appear at the top of the screen (like most native OS X applications). On Linux and Windows, each RV window has its own attached menu bar. (See Figure cap:RV-on-Linux)
  A single RV process can control multiple independent sessions on all platforms. On the Mac and Windows, it is common that there be only a single instance of RV running. On Linux it is common to have multiple separate RV processes running.
  Many of the tools that RV provides are heads up widgets. The widgets live in the image display are or are connected to the image itself. Aside from uniformity across platforms, the reason we have opted for this style of interface was primarily to make RV function well when in full screen mode.
  4.1 Feedback
  4.2 Main Window Tool Bars
  The main RV window has two toolbars which are visible by default. The upper toolbar controls which view is displayed, viewing options, and current display device settings. The lower toolbar control play back, has tool buttons to show more functions, and audio controls.
  The lower toolbar is in three sections from left to right: tool launch buttons, play controls, and audio/loop mode. The tool launch buttons toggle rv's main user interface components like the session manager or the heads-up timeline. The play controls control play back in the current view. These are similar to the heads-up play controls available from the timeline configuration. The loop mode determines what happens at the end of the timeline and the audio controls modify the volume and mute.
  The frame content, display device settings, channel view, and stereo mode on the top tool bar are also available under the View menu. See Chapter 7 for more information on what these settings do.
  4.3 Loading Images, Sequences, Movies and Audio
  4.3.1 Using the File Browser
  There are two options for loading images, sequences, and movies via the file browser: you can add to the existing session by choosing File → Open (or File → Open into Layer) or you can open images in a new window by choosing File → Open In New Session.
  In the file browser, you may choose multiple files. RV tries to detect image sequences from the names of image files (movie files are treated as individual sequences). If RV detects a pattern, it will create an image sequence for each unique pattern. If no pattern is found, each individual image will be its own sequence.
  Audio files can be loaded into RV using the file browser. To associate an audio file with its corresponding image sequence or movie open the audio file as a layer using File → Open into Layer. The first sequence in the layer will determine the overall length of the source, e.g. a longer audio file loaded as a layer after a sequence will be truncated to the duration of the sequence. Any number of Audio files can be added as layers to the same source and they will be mixed together on playback.
  The file browser has three file display modes: column view, file details view, and media details view. Sequences of images appear as virtual directories in the file browser: you can select the entire sequence or individual files if you open the sequence up. Note: you can multi-select in File Details and Media Details, but not in Column View. In general the File Details view will be the fastes.
  Favorite locations can be remembered by dragging directores from the main part of the file browser to the side bar on the left side of the dialog box. Recent items and places can be found under the path combo box. You can configure the way the browser uses icons from the preferences drop down menu on the upper right of the brower window.
  4.3.2 Dragging and Dropping
  On all platforms, you can drag and drop file and folder icons into the RV window. RV will correctly interpret sequences that are dropped (either as multiple files or inside of a directory folder that is dropped). LUT and CDL files can also be dropped.
  RV uses smart drop targets to give you control over how files are loaded into RV. You can drop files as a source or as a layer. As you drag the icons over the RV window, the drop targets will appear. Just drop onto the appropriate one.
  On Linux RV should be compatible with the KDE and Gnome desktops. It is possible with these desktops (or any that supports the XDnD protocol) to drag file icons onto an RV window.
  If multiple icons are dropped onto RV at the same time, the order in which the sequences are loaded is undefined.
  To associate an audio file with an image sequence or movie, drop the audio file as a layer, rather than as a source.
  4.4 Examining an Image
  RV normalizes image geometry to fit into its viewing window. If you load two files containing the same image but at different resolutions, RV will show you the images with the same apparent ``size''. So, for example, if these images are viewed as a sequence — one after another — the smaller of the two images will be scaled to fit the larger. Of course, if you zoom in on a high-resolution image, you will see detail compared to a lower-resolution image. When necessary you can view the image scaled so that one image pixel is mapped to each display pixel.
  On startup, RV will attempt to size the window to map each pixel to a display pixel, but if that is not possible, it will settle on a smaller size that fits. You can always set the scale to 1:1 with the '1' hotkey, and if it is possible to resize the window to contain the entire image at 1:1 scaling, you can do so via the Window → Fit or Window → Center Fit menu items.
  4.4.1 Panning, Zooming, and Rotating
  You can manipulate the Pan and Zoom of the image using the mouse or the row of number keys (or the keypad on an extended keyboard if numlock is on). By holding down the control key (apple key on a mac) and the left mouse button you can zoom the image in or out by moving to the left and right. By holding down the alt key (or option key on a mac) you can pan the image in any direction. If you are accustomed to Maya camera bindings, you can use those as well.
  Rotating the image is accessible from the Image → Rotation menu. By selecting Image → Rotation → Arbitrary it's possible to use the mouse to scrub the rotation as a parameter.
  To frame the image — automatically pan and zoom it to fit the current window dimensions — hit the 'f' key. If the image has a rotation, it will remain rotated.
  To precisely scale the image you can use the menu Image → Scale to apply one of the preset scalings. Selected 1:1 will draw one image pixel at every display pixel. 2:1 will draw 1 image pixel as 4 display pixels, etc.
  4.4.2 Inspecting Pixel Values
  The pixel inspector widget can be accessed from the Toools menu or by holding down Shift and clicking the left mouse button. The inspector will appear showing you the source pixel value at that point on the image (see Figure cap:Color-Inspector). If you drag the mouse around over the image while holding down the shift key the inspector widget will also show you an average value (see Figure cap:Average-Color). You can move the widget by clicking on it and dragging.
  To remove inspector widget from the view either movie the mouse to the top left corner of the widget and click on the close button that appears or toggle the display with the Tools menu item or hot key.
  The inspector widget is locked to the image. If you pan, zoom, flip, flop, or rotate the image, the inspector will continue to point to the last pixel read.
  If you play a sequence of images with the inspector active, it will average the pixel values over time. If you drag the inspector while playback occurs it will average over time and space.
  RV shows either the source pixel values or the final rendered values. The source value represents the value of the pixel just after it is read from the file. No transforms have been done on the pixel value at that point. You can see the final pixel color (the value after rendering) by changing the pixel view to the final pixel value from the right-click popup menu.
  The value is normalized if the image is stored as non-floating point — so values in these types of images will be restricted to the [0,1] range. Floating point images pass the value through unchanged so pixels can take values below zero or above one. Table 7.3 shows the range of each of the channel data types.
  From the right-click popup menu it's possible to view the pixel values as normalized to the [0,1] range or as 8, 16, 10, or 12 bit integer values.
  4.4.3 Comparing Images with Wipes
  Wipes allow you to compare two or more images or sequences when viewing a stack. Load the images or sequences that you wish to compare into RV as sources (not as layers). Put RV into stack mode or create a stack view from the Session Manager, and enable wipes from the Tools menu or with the “F6” hot key. Now you can grab on the edges of the top image and wipe them back to reveal the image below. You can grab any edge or corner, and you can move the entire wipe around by grabbing it in the exact center. Also, by clicking on the icon that appears at the center or corner of a wipe or via the Wipes menu, you can enable the wipe information mode, that will indicate which edge you are about to grab.
  Wipes can be used with any number of sources. The stack order can be cycled using the “(“ and “)” keys.
  4.4.4 Parameter Edit Mode and Virtual Sliders
  RV has a special UI mode for editing the parameters such as color corrections, volume, and image rotation. For example, hitting the ``y'' key enters gamma edit mode. When editing parameters, the mouse and keyboard are bound to a different set of functions. On exiting the editing mode, the mouse and keyboard revert to the usual bindings. (See Table 4.2)
  To edit the parameter value using the mouse you can either scrub (like a virtual slider) or use the wheel. If you want to eyeball it, hold the left mouse down and scrub left and right. By default, when you release the button, the edit mode will be finished, so if you want to make further changes you need to re-enter the edit mode. If you want to make many changes to the same parameter, you can “lock” the mode with the 'l' key. The scroll wheel increments and decrements the parameter value by a predefined amount. Unlike scrubbing with the left mouse button, the scroll wheel will not exit the edit mode. When multiple Sources are visible, as in a Layout view, parameter sliders will affect all Sources. Or you can use 's' to select only the source under the pointer for editing. You can exit the edit mode by hitting the escape key or space bar (or most other keys).
  To change the parameter value using the keyboard, hit the Enter (or Return) key; RV will prompt you for the value. For interactive changes from the keyboard, use the ``+'' and ``-'' keys (with or without shift held down). The parameter is incremented and decremented. To end the keyboard interactive edit, hit the Escape or Spacebar keys.
  4.4.5 Image Filtering
  When image pixels are scaled to be larger or smaller than display pixels, resampling occurs. When the image is scaled (zoomed) RV provides two resampling methods (filters): nearest neighbor and linear interpolation (the default).
  You can see the effects of the resampling filters by making the scale greater than 1:1. This can be done with any of the hot keys ``2'' through ``8'' or by zooming the image interactively. When the image pixels are large enough, you can switch the sampling method via View → Linear Filter or by hitting the ``n'' key. Figure 4.3 shows an example of an image displayed with nearest neighbor and linear filtering.
  Digression on Resampling
  It's important to know about image filtering because of the way in which RV uses the graphics hardware. When an image is resampled—as it is when zoomed in—and the resampling method produces interpolated pixel values, correct results are really only obtained if the image is in linear space. Because of the way in which the graphics card operates, image resizing occurs before operations on color. This sequence can lead to odd results with non-linear space images if the linear filter is used (e.g., cineon files).
  There are two solutions to the problem: use the nearest neighbor filter or convert the image to linear space before it goes to the graphics card. The only downside with the second method is that the transform must happen in software which is usually not as fast. Of course this only applies to images that are not already in linear space.
  Why does RV default to the linear filter? Most of the time, images and movies come from file formats that store pixel values in linear (scene-referred) space so this default is not an issue. It also looks better.
  Floating Point Images
  If RV is displaying floating point data directly, linear filtering may not occur even though it is enabled. This is a limitation of some graphics cards that will probably be remedied (via driver update or new hardware) in the near future. In this case You can make the filter work by disallowing floating point values via Image → Color Resolution → Allow Floating Point. Many graphics can do filtering on 16 bit floating point images but cannot do filtering on 32 bit floating point images. RV automatically detects the cards capabilities and will turn off filtering for images if necessary.
  Figure 4.4 shows an example of a floating point image with linear filtering enabled versus equivalent 8-bit images.
  Table 4.4:
  Floating point linear, 8 bit linear, and 8 bit nearest neighbor filtering.Graphics hardware does not always correctly apply linear filtering to floating point images. Filtering can dramatically change the appearance of certain types of images. In this case, the image is composed of dense lines and is zoomed out (scaled down).
  4.4.6 Big Images
  RV can display any size image as long as it can fit into your computer's memory. When an image is larger than the graphics card can handle, RV will tile the image display. This makes it possible to send all the pixels of the image to the card for display. The downside is that all of the pixels are sent to the display even though you probably can't see them all. However, if you zoom in (for example hit ``1'' for 1:1 scale) when a large image is loaded, RV will only draw pixels that are visible.
  One of the constraints that determines how big an image can be before RV will tile it is the amount of available memory in your graphics card and limitations of the graphics card driver. On most systems, up to 2k by 2k images can be displayed without tiling (as long as the image has 8-bit integer channels). In some cases (newer cards) the limit is 4k by 4k. However, there are other factors that may reduce the limit.
  If your window system uses the graphics card (like Mac OS X or Linux with the X.org X server)
  If you reduce the VRAM usage, RV will tile images of smaller size. For sequences, this may affect playback speed since tiling is slightly less efficient than not tiling. Tiling also affects interactive speed on single images; if tiling is not on, RV can keep all of the image pixels on the graphics card. If tiling is on, RV has to send the pixels every time it redraws the image.
  You can determine if RV is tiling the image by looking the image info widget under Tools → Image Info. If tiling is on there will be an entry called ``DisplayTiling'' showing the number of tiles in X and Y.
  4.4.7 Image Information
  The image information widget, can be shown or hidden via the Tools → Image Info menu item or using the hot key: ``i''. You can move the widget by clicking and dragging. The widget shows the geometry and data type of the image as well as associated meta-data (attributes in the file). Figure 4.9 shows an example of the information widget.
  Channel map information—the current mapping of file channels to display channels—is displayed by the info widget as well as the names of channels available in the image file; this display is especially useful when viewing an image with non-RGBA channels.
  If the image is part of a sequence or movie the widget will show any relevant data about both the current image as well as the sequence it is a part of. For movie files, the codecs used to compress the movie are also displayed. If the movie file has associated audio data, information about that will also appear.
  To remove the image information widget from the view either move the mouse to the top left corner of the widget and click on the close button that appears or toggle the display with the Tools menu item or hot key ('i').
  4.5 Playing Image Sequences, Movie Files, and Audio Files
  RV can play multiple images, image sequences and movie files as well as associated audio files. Play controls are available via the menus, keyboard, and mouse. Timing information and navigation is provided by the timeline widget which can be toggled via the Tools → Timeline menu item or by hitting the TAB key.
  4.5.1 Timeline
  This timeline shows in and out points, frame count between in and out points, total frames, target fps and current fps. In addition, if there are frame marks, these will appear on the timeline as seen in Figure 4.5.5.
  The current frame appears as a number positioned relative to the start frame of the session. If in and out points are set, the relative frame number will appear at the left side of the timeline — the total number of frames between the in and out points is displayed below the relative frame number.
  By clicking anywhere on the timeline, the frame will change. Clicking and dragging will scrub frames, as will rolling the mouse-wheel. Also note that you can shift-click drag to set an in/out range.
  The in/out range can also be manipulated witht he mouse. You can grab and drag either end, or grab in the middle to drage the whole range.
  There are two FPS indicators on the timeline. The first indicates the target FPS, the second the actual measured playback FPS.
  4.5.2 Timeline Configuration
  The timeline can be configured from its popup menu. Use the right mouse button anywhere on the timeline to show the menu. If you show the popup menu by pointing directly at any part of the timeline, the popup menu will show that frame number, the source media there, and the operations will all be relative to that frame. For example, without changing frames you can set the in and out point or set a mark via the menu.
  By default the timeline will show the ``source” frame number, the native number of the media. Alternately you can show the global frame number, global time code, or even the ``Footage” common in traditional animation (16 frames per foot).
  4.5.3 Realtime versus Play All Frames
  Control → Play All Frames determines whether RV should skip frames or not if it is unable to render fast enough during playback. Realtime mode (when play all frames is not selected) uses a realtime clock to determine which frame should be played. When in realtime mode, audio never skips, but the video can. When play all frames is active, RV will never skip frames, but will adjust the audio if the target fps cannot be reached.
  When the timeline is visible, skipped frames will be indicated by a small red circle towards the right hand side of the display. The number in the circle is the number of frames skipped.
  4.5.4 In and Out Points
  There are two frame ranges associated with each view in an RV Session: the start and end frames and the in and out frames (also known as in and out points). The in and out points are always within the range of the start and end frames. RV sets the start and end frames automatically based on the contents of the view. The in and out points are set to the start and end frames by default. However, you can set these points using the ``[“ and ``]'' keys, or by right-clicking on the timeline. You can also set an in/out range by shift-dragging with the left-button in the Timeline or the Timeline Magnifier. The in/out range displayed in the timeline can also be changed with the mouse, either by dragging the whole range (click down in the middle of the range), or by dragging one of the endpoints (click down on the endpoint).To reset the in and out points, use the ``\'' key.
  If frames have been marked, RV can automatically set the in and out points for you based on them (use the ctrl-right/left-arrow keys, or command-right/left-arrow on Mac).
  4.5.5 Marks
  A mark in RV is nothing more than a frame number which can be stored in an RV file for later use. To toggle a frame as being marked, use Mark → Mark Frame (or use the ``m'' hotkey). The timeline will show marks if any are present.
  While not very exciting in and of themselves, marks can be used to build more complex actions in RV. For example, RV has functions to set the in and out points based on marks. By marking shot boundaries in a movie file, you can quickly loop individual shots without selecting the in and out points for each shot. By selecting Mark → Next Range From Marks and Mark → Previous Range From Marks or using the associated hot keys ``control+right arrow” or ``control+left arrow” the in and out points will shift from one mark region to the next.
  Marking and associated hot keys for navigating marked regions quickly becomes indispensable for many users. These features make it very easy to navigate around a movie or sequence and loop over part of the timeline. Producers and coordinators who often work with movie files of complete sequences (for bidding or for client reviews) find it useful to mark up movie at the shot boundaries to make it easy to step through and review each shot.
  4.5.6 Timeline Magnifier
  The Timeline Magnifier tool (available from the Tools menu, default hotkey F3) brings up a special timeline that is ``zoomed'' to the region bounded by the In/Out Points. In addtion to showing only the in/out region, the timeline magnifier differs from the standard timeline in that it shows frame ticks and numbers on every frame, if possible. If there is not enough room for frames/ticks on every frame, the magnifier will fall back to frames/ticks every 5 or 10 frames. The frame numbers of the in/out points are displayed at either end of the magnified timeline.
  Audio Waveform Display
  The timeline magnifier can display the audio waveform of any loaded audio. Note that this is the normalized sum of all audio channels loaded for the given frame range. To preserve interactive speed, the audio data is not rendered into the timeline until that section of the frame range is played. You can turn on Scrubbing, in the Audio menu, to force the entire frame range to be loaded immediately. Also, if Scrubbing is on, audio will play during scrubbing, and during single frame stepping. See Section 4.6for further details on Audio in RV.
  In/Out Range Manipulation
  Note that on each end of the timeline magnifer, there are two triangular ``arrow” buttons. These are the in/out nudge buttons, and clicking on them will move the in or out point by one frame in the indicated direction. The in/out range displayed in the timeline can also be changed with the mouse, either by dragging the whole range (click down in the middle of the range), or by dragging one of the endpoints (click down on the endpoint). All these manipulations can be performed during playback. You can also set an in/out range by shift-dragging with the left-button in timeline magnifier.
  Configuration
  All the hotkeys mentioned in Table 4.5 are also relevant to the timeline magnifier. The timeline magnifier configuration menu is also a subset of the regular timeline menu (see Figure4.11), with additional items for setting the height of the audio waveform display.
  4.6 Audio
  When playing back audio with an image sequence or movie file, RV can be in one of two modes: video locked to audio or audio locked to video.
  When a movie with audio plays back at its native speed, the video is locked to the audio stream. This ensures that the audio and video are in sync.
  If you change the frame rate of the video, the opposite will occur: the audio will be locked to the video. When this happens, RV will synthesize new audio based on the existing audio in an attempt to either stretch or compress the playback in time. When pushed to the limits, the audio synthesis can create artifacts (e.g. when slowing down or speeding up by a factor of 2 or more).
  RV can handle audio files with any sample rate and can re-sample on the fly to match the output sample rate required by the available audio hardware. The recommended formats are AIFF or WAV. Use of mp3 and audio-only AAC files is not supported.
  Audio settings can be changed using the items on the Audio Menu. Volume, time Offset, and Balance can be edited per source or globally for the session. The RV Preferences Audio tab lets you choose the default audio device and set the initial volume (as well as some other technical options that are rarely changed).
  4.6.1 Audio Preferences
  RV provides audio preferences in the Preferences dialog. The most important audio preference is the choice of the output device from those listed. In practice this will rarely change. Preferences also let you set the initial volume for RV. The option to hold audio open is for use on Linux installations where audio system support is poor (see the next section on Linux Audio.) The other preferences are there for fine tuning performance in extreme cases of marginal audio hardware or support - they will almost never change.
  From RV version 4.0.11 onwards, we introduced a cross platform output module choice called “Platform Audio”. This is based on Qt audio. “Platform Audio” does support the use USB based audio peripherals for playback (e.g. Behringer UCA 202) on all platforms. These usb audio devices would typically appear as “USB Audio CODEC” (“front:CARD=CODEC,DEV=0” on Linux) in the “Output Device” pull down menu when “Platform Audio” is selected.
  Version 3.6 and higher have a new Output Module setting in the preferences. On the Mac and Windows there is only a single entry in this menu. On Linux, however, there may be many. (See Appendix E for details about Linux Audio).
  The Output Device, Output Channel Layout, Output Format, and Output Rate determine the sound quality and speakers (e.g. mono, stereo, 5.1 etc) to use. Typical output rates are 44100 or 48000 Hz and 32 bit float or 16 bit integer output format. This produced Audio CD or DAT quality audio.
  The Device Packet Size and Cache Packet Size can be changed, but not all output modules support arbitrary values. The default values are recommend. The Min/Max Buffer Size determines how much audio RV will cache ahead of the display frame. Ideally these numbers are low.
  Keep Audio Device Open When Not Playing should usually be set to ON. There are very few cicumstances in which it's a good idea to turn this off. When the value is OFF, RV may skip frames and audio when playback starts and can become unstable. On some linux distributions turning this OFF will result in no audio at all after the first play.
  Hardware Audio and Video Synchronization determines which clock RV will use to sync video and audio. When on, RV will use the audio hardware clock if one is available otherwise it will use a CPU timer in software. In most cases this should be left ON. RV can usually detect when the audio clock is unstable or inaccurate and switch to the CPU timer automatically. However if playback with audio appears jerky (even when caching is on) it might be worth turning it off.
  4.6.2 Audio on RV for Linux
  Linux presents special challenges for multimedia applications and audio is perhaps the worst case. RV audio works well on Linux in many cases, but may be limited in others. RV supports special configuration options so that users can get the best audio functionality possible within the limitations of the vintage and flavor of Linux being used. See the Appendix E for complete details.
  4.6.3 Multichannel Audio
  In RV, the audio output modules “Platform Audio” and “PortAudio” will support multichannel channel audio playback for devices that allow it. This would include six, eight or more channel layouts for surround sound speaker systems like 5.1 or 7.1. The list of available channel layouts for a chosen output device will be listed in the first pulldown menu for the “Output Format and Rate” setting.
  Note, for SDI audio, stereo, 5.1, 7.1 and 16 channel layout schemes are supported for AJA and Blackmagic cards.
  4.7 Caching
  RV has a three state cache: it's either off, caching the current in/out range, or being used as a look-ahead (also known as a ring) buffer.
  The region cache reads frames starting at the in point and attempts to fill the cache up to the out point. If there is not enough room in the cache, RV will stop caching. The region cache can be toggled on or off from the Tools menu or by using the shift-C hot key.
  Look-ahead caching can be activated from the Tools menu or by using the meta-l hot key. The look-ahead cache attempts to smooth out playback by pre-caching frames right before they are played. If RV can read the files from disk at close to the frame rate, this is the best caching mode. If playback catches up to the look-ahead cache, playback will be paused until the cache is filled or for a length of time specified in the Caching preferences. At that point playback will resume.
  RV caches frames asynchronously (in the background). If you change frames while RV is caching it will attempt to load the requested frame as soon as possible.
  If the timeline widget is visible, cached regions will appear as a dark green stripe along the length of the widget. The stripe darkens to blue as the cache fills. The progress of the caching can be monitored using the timeline. On machines with multiple processors (or cores) the caching is done in one or more completely separate threads.
  Note that there is usually no advantage to setting the lookahead cache size to something large (if playback does not overtake the caching, a small lookahead cache is sufficient, and if it does, you probably want to use region caching anyway).
  4.8 Color, LUTs, and CDLs
  RV provides users with fine grained color management and can support various color management scenarios. See 7.1 for detailed technical information about RV's color pipeline. Without adding any nodes the default graph in RV supports three LUTs and two CDLs per file, an overall display LUT, and has a number of useful color transforms built-in. You can load LUTs and CDLs using the File → Import menu (Display, Look, File, and Pre-Cache items), or you can drag and drop the files onto the RV window. Smart drop targets will allow you determine how the LUT or CDL will be applied. Note that there is no CDL slot for the display by default. See chapter 8 for more information about using LUTs and 9 for using CDLs in RV.
  RV's color transforms are separated into two menus. The Color menu contains transforms that will be applied to an individual source (whichever source is current in the timeline) and the View menu contains transforms that will be applied to all of the sources. This provides the opportunity to bring diverse sources (say Cineon Log files, QuickTime sRGB movies, and linear-light Exr's) all into a common working color space (typically linear) and then to apply a common output transform to get the pixels to the display. RV's built in hardware conversions can handle Cineon Log, sRGB, Viper Log and other useful transforms.
  4.9 Stereo
  RV supports playback of stereoscopic source material. RV has two methods for handling stereo source material: first any source may have multiple layers, and RV will treat the first two video layers of a source as left and right eyes for the purpose of stereo display. Left and right layers do not need to be the same resolution or format because RV always conforms media to fit the display window; Second, RV supports stereo QuickTime movies (taking the first two video tracks as left and right eyes) and multi-view EXR files. RVIO can author stereo QuickTime movies and multi-view EXR files as well, so a complete stereo publishing and review pipeline can be built with these tools. See the section on 12 for more information about how stereo is handled.
  4.10 Key and Mouse Bindings
  Key and mouse bindings as well as menu bar menus are loaded at run time. You can override and change virtually any key or mouse binding from a file called ~/.rvrc.mu if you need to. The bindings (and whole interface) that comes with RV are located at $RV_HOME/plugins/Mu/rvui.mu. Functions in this file can be called from ~/.rvrc.mu or overridden.
  To override bindings, copy the file $RV_HOME/scripts/rv/rvrc.mu to ~/.rvrc.mu. Start hacking! Extensive information about customizing RV can be found in the RV Reference Manual.
  4.11 Preferences File
  RV stores configuration information in a preferences file in the user home directory. Each platform has a different location and possibly a different format for the file.
  5 The Session and the Session Manager
  5.1 RV Session
  Each viewer window represents an RV session. A session is composed of one or more source movies, frame markers, image transforms, color corrections, and interactive states (like caching and playback speed). The source movies are combined according to the session type. The default RV session type is ``sequence,'' which plays back the source movies one after another.
  An RV session can be saved as an .rv file. The .rv file contains the entire state of its image processing tree—all of the variables that determine how it will work—as well as information about frame ranges, in/out points, etc. The .rv file stores references to movie files and images; it does not make copies of them. If you change source material on disk and load an .rv file that references those materials, the changes will be evident in RV.
  The .rv file is a GTO file. Tools that operate on GTO files can be used on .rv files. C++ and Python source code is available for creating, reading, and manipulating GTO files, including the ASCII GTO files used by RV. (See sec:RV-File-Format)
  5.1.1 What's in a Session
  A session is represented internally as a Directed Acyclic Graph (DAG) in which images and audio pass from the leaves to the root where they are rendered. Each node in the DAG can have a number of parameters or state variables which control its behavior. RV's user interface is essentially a controller which simply changes these parameters and state variables. An .rv file contains all of the state variables for the nodes in RV's image processing DAG. A description of each of the node types can be found in the Reference Manual.
  The DAG nodes that are visible in the user interface are called Views. RV provides three default views, and the ability to make views of your own. In addition to any Sources you've loaded, the three views. Whenever a Source is added to the session, it is automatically added to the inputs of each of the default views, not to user-defined views.
  5.2 Session Manager
  RV 3.10 includes a new way to examine and edit the contents of an RV session called the session manager. The session manager shows an outline of the session contents from which you can create, mofify, and edit new sequences, stacks, layouts, and more. By default, the Session Manage comes up ``docked'' at the left side of the RV window, but it can be un-docked (by clicking and dragging on the title) and positioned as a separate window, or docked at another edge of the RV window.
  The session manager interface is in two parts: the top panel shows an outline of the session contents, and the bottom shows either the inputs of the currently viewed object or user interface to edit the current view. By double clicking on an icon in the top portion of the session manager you can switch to another view. By default RV will create a default sequence, stack, and layout which includes all of the sources in the session. When a new source is added, these will be automatically updated to include the new source.
  5.3 Creating, Adding to, and Removing from a View
  A new view can be created via the add view menu. The menu is reachable by either the add view (+) button or by right clicking with the mouse in the session outline. Anything selected in the session outline becomes a member (input) of the newly created view. Alternately you can create a view and then add or subtract from it afterwards.
  The top items in the view create new views from existing views. The bottom items create new sources which can be used in other views.
  Folder views can be created either from the add menu or the folders menu. The folders menu lets you create a folder from existing views or with copies of existing views. When a view is copied in the session manager, the copy is really just a reference to a single object.
  You can add to an existing view by first selecting it by double clicking on it, then dragging and dropping items from the session outline into the inputs section of the session manager.
  Drag and drop of input items makes it possible to rearrange the ordering of a given view. For example, in a sequence the items are played in the order the appear in the inputs list. By rearranging the items using drag and drop or the up and down arrows in the inputs list you can reorder the sequence.
  To remove an item from a view select the item(s) in the inputs list and hit the delete (trash can) button to the right of the inputs list. Similarly, the trashcan button in the upper panel well delete a view from the session. Please Note: neither of these remove/delete operations is undoable.
  5.4 Navigating Between Views
  For each RV session, there is always a single ``current view'', whose name is displayed at the top of the Session Manager. As in a web browser, RV remembers the history of views you have ``visited'' and you can go backwards and forwards in that history.
  - Double-click on any of the views listed in the top panel of the Session Manager
  - Double-click on any input view of the current view (listed in the Inputs tab of the bottom panel of the Session Manager)
  - Double-click on any visible image in the main RV window
  - Click the left (backwards) and right (forwards) buttons at the top of the Session Manager
  - For backwards compatibility, the items at the top of the Tools menu navigate to the usual default views
  Once you have changed views, you can go backwards and forwards in the view history with the arrow buttons at the top of the Session Manager, or with the navigation hot keys ``Shift-left-arrow'' (backwards) and ``Shift-right-arrow'' (forwards). Note that you can easily navigate between views with out the Session Manager by double-clicking on the image to ``drill-down'' and then using ``Shift-left-arrow'' to go back.
  5.5 Source Views
  Source Views are the ``leaves'' of the graph in that they are views with no inputs (since they get their pixels from some external source, usually files on disk somewhere). The Edit interface for source views is currenly used only to adjust editorial information (in the future it may provide access to other per-source information like color corrections, LUTs, etc). In RV, each source has an Cut In/Out information which provide editorial information to views that use that source (like a Sequence view). These In/Out frame numbers can be set from the command line, or changed with the Edit panel of the Source View interface.
  By default, ``Sync GUI In/Out to Source'' is checked, and you can manipulate the Cut In/Out numbers by setting the in/out frames in the timeline in all the usual ways (see Section 4.5.4). You can also type frame numbers in the given fields, use the up/down nudge keys, or the mouse wheel (after clicking in the relevant field).
  5.5.1 Source Media Containing Multiple Images (Subcomponents)
  In the session manager, a source can be opened revealing the media it is composed of. If the media has multiple layers and/or views (e.g. a stereo OpenEXR file) the media can be further opened to reveal these.
  When multiple layers or views (subcomponents) are present in media the session manager will present a radio button interface in one of its columns. Each subcomponent in the media has its own selectable toggle button. When a subcomponent is selected, the source will show only that subcomponent; stereo or any other multiple view effect will be disabled.
  You can go back to the default by either double clicking on the media or deselecting the selected subcomponent (toggle it off).
  In addition to restricting the media to one of its subcomponents, the session manager also allows you to build new views which include more than one subcomponent. For example if you select all the layers in a multiple layer OpenEXR file, you can create a layout view (right popup menu or the '+' tool button) that shows all of them simultaneously. When RV does this, it creates new temporary sources dedicated to the subcomponent views, layers, or channels that were selected. These subcomponent sources are placed in their own folder.
  5.6 Group Views
  Folders, Sequence Views, Stack Views, Switch Views, and Layout Views are all ``Group Views'' in that they take multiple inputs and combine them in some way for viewing. A Sequence plays it's inputs in order, a Stack layers it's aligned inputs on top of each other, and a Layout arranges it's inputs in a grid, row, column or arbitrary user-determined format.
  The Group interface gives you control over the resolution of it's output. During interactive use, RV's resolution invariance means that the aspect ratio is the only important part of the size, but during output with RVIO, this size would be the default output resolution. If Size Determined from Inputs' is checked, the group take it's size from the maximum in each dimension of all it's inputs. If the size is not being progammatically determined, you can specify any size output in the provided fields.
  Similarly, the output frame rate can be specified in the Output FPS field. This is the frame rate that is used as the default for any RVIO output of this group, and is also passed to any view for which this group is an input. The output FPS is initialized from the default frame rate of the first input added to the group. If Retime Inputs to Output FPS is checked, inputs whose native frame rate differs from the group's output fps will be retimed so that they play correctly at the output fps. That is, a real-time pull up/down will be performed on the video, and the audio will be resampled to play at the output fps while preserving pitch.
  As long as Use Source Cut Information is checked in the Group interface, the group will adopt the editorial cut in/out information provided by the sources (see Section 5.5). This is particularly useful in the case of sequences, but also comes up with stacks and layouts, when, for example, you want to compare a matching region of movies with different overall frame ranges.
  5.6.1 Sequence Views
  A Sequence view plays back its inputs in the order specified in the Inputs tab of the the Squence interface. The order can be changed by dragging and dropping in the Inputs, or by selecting and using the arrow keys to the right of the list of Inputs. An input can be removed (dropped from the sequence) by selecting the input and then clicking the trashcan button.
  In addition to the order of the clips being determined by the order of the inputs, the actual cut in/out points for each clip can also be specified. At the moment, the easiest way to do this is to specify cut information for each source that you want to appear in the sequence with the Source view interface described in Section 5.5. As long as Use Source Cut Information is checked in the Sequence interface, the sequence will adopt the editorial cut in/out information provided by the sources.
  Since the sequence only shows you one input at a time, if Fill View with Content is checked and the sequence is the current view, the output size of the sequence will be dynamically adjusted so that the ``framed'' content always fills the RV window, even if different inputs of the sequence have different aspect ratios.
  5.6.2 Stack Views
  The Stack View presents it's inputs ``on top'' of each other, for comparing or compositing. In this case the order of the inputs determines the stacking order (first input on top). In addtion the usual ways of reordering the inputs, you can ``cycle'' the stack forwards or backwards with items on the Stack menu, or with hotkeys: ')' and '('.
  The compositing operation used to combine the inputs of the stack can be selected in the Edit inteface. At the moment, you can choose from Over, Replace, Add, Difference, and Inverted Difference.
  Because any or all of the inputs to the Stack may have audio, you can select which you want to hear. Either mix all the audio together (the default), play only the audio from the topmost input in the stack, or pick a particular input by name.
  By default, stack inputs will be displayed so that matching ``source'' frame numbers are aligned. For example if you stack foo.121-150#.exr on top of goo.56-200#.exr, you'll see frame foo.121.exr on top of goo.121.exr even though the two sequences have completely different frame ranges. If you don't want this behavior and you want the start frames of the inputs to be aligned regardless of their frame numbers, check Align Start Frames.
  Also note that the Wipes mode is usful when comparing images in a stack. The use of wipes is explained in Section 4.4.3.
  5.6.3 Layout Views
  A Layout is just what it sounds like; the inputs are aranged in a grid, column, row, or arbitrary user-defined pattern. In many ways, a Layout is similar to a stack (it even has a compositing operation for cases where you arrange on input ``over'' another). All the interface actions described in Section 5.6.2 for Stack Views also apply to Layout Views.
  To determine the arrangement of your layout, choose one of five modes. There are three procedural modes, which will rearrange themselves whenever the inputs are changed or reordered: Packed produces a tightly packed or tiled pattern, Row arranges all the inputs in a horizontal row, and Column arranges the inputs in a vertical column. If you want to position your inputs by hand, select the Manual mode. In this mode hovering over a given input image will show you a manipulater that can be used to reposition the image (by clicking and dragging near the center) or scale the image (by clicking and dragging the corners). After you have the inputs arranged to your liking, you may want to switch to the Static mode, which will no longer draw the manipulators, and will leave the images in your designated arrangement.
  5.6.4 Switch Views
  A Switch is a conceptually simpler than the other group views: it merely switches between its inputs. Only one input is active at a time and both the imagery and audio pass through the switch view. Otherwise, the switch shares the same output characteristics as the other group nodes (resolution, etc).
  5.7 Retime View
  The Retime View takes a single input and alters it's timing, making it faster or slower or offseting the native frame numbers. For example, to double the length of an input (IE make every frame play twice, which will have the effect of slowing the action without changing the frame rate), set the Length Multiplier to 2. Or to have frame 1 of the input present itself on the output as frame 101, set the Offset to 100.
  The Length Multiplier and Offset apply to both the video and audio of the input. If you want to apply an additional scale or offset to just the audio, you can use the Audio Offset and Audio Scale fields.
  5.8 Folders
  Folders are special kind of group view used to manage the contents of the session manager. Unlike other views in RV, when you create a folder its inputs will appear as a hierarchy in the session manager. You can drag and drop and move and copy views in and out of folders to organize them. They can be used as an input just like any other view so they can be nested, placed in a sequence, stack, or layout and can be manipulated in the inputs interface in the same way other views are.
  Folders have no display behavior themselves, but they can display their contents as either a switch or a layout.
  When a view becomes a member of a folder, it will no longer appear in one of the other categories of the session manager. If a view is removed as a member of a folder, it will once again appear in one of the other categories.
  5.8.1 Folders and Drag and Drop
  You can drag one or more views into a folder in the session manager to make it a member (input) of the folder. To make a copy of the dragged items hold down the drag copy modified while dragging. On the mac this is the option key, on windows and linux use the control key.
  The session manager will not allow duplication of folder members (multiple copies of the same view in a folder) although this is not strictly illegal in RV.
  Drag and drop can also be used to reorder the folder contents the same way the inputs are reordered. An insertion point will be shown indicating where the item will move to.
  6 Presentation Mode and Video Devices
  RV has a facility called presentation mode for use with machines with multiple attached display devices like projectors, SDI video hardware, second DVI/DisplayPort monitors or HDMI compatible stereo televisions.
  Presentation mode turns the main RV user interface into a control interface with output going to both it and a second video device. The secondary video device is always full screen. The primary use for presentation mode is multiple people viewing a session together.
  Typically a video device is set up once in the preferences and used repeatedly. Presentation mode can be turned on from the View → Presentation Mode menu item. It's also possible to pass command line arguments to RV to configure and start presentation mode automatically when it launches.
  6.1 Video Device Configuration
  Video devices are configured from the preferences Video tab. The interface is in two parts: the module/device selection and the video configuration parameters. For each module/device combination there is a unique set of configuration parameters.
  Different devices will have different configuration parameters and some devices may not use all of the available ones.
  - Output Module
  - A video output module can contain multiple devices. All of the devices in a module will have the choices for configuration parameters. For example, on a system with multiple monitors there will be a Desktop output module with a device for each connected monitor. In the video preferences window, you can also specify a default display profile for the module.
  - Output Device
  - The output devices are either numbered or named depending the module. For example, the NVIDIA-SDI module numbers its devices while the Desktop module uses the actual monitor name and manufacturer to identify them. In the video preferences you can specify a default display profile for the specific device or indicate that the device should use the default module profile.
  - Output Video Format
  - Video formats typically include a resolution and frequency. If the video format is not changable by the user this field will display the output resolution of the device. In the video preferences a specific profile for the selected video and data format can be assigned.
  - Output Data Format
  - The data format indicates how the the pixels are to be presented to the device. This can include the numerical precision as well as color space (e.g. RGB or YCbCr). For devices that support stereo this is usually where stereo options are found. To use HDMI 1.4a stereo modes like Side-by-Side or Top-and-Bottom, or HD-SDI dual stereo (RV-SDI product only), you select the appropriate Data Format here. PLEASE NOTE: if you use a stereo data format here, then the Stereo mode on RV's View menu should be set to “Off”.
  - Sync Method
  - If the device as multiple options for synchronization these will be selectable under the sync method. For example, desktop devices typically have vertical sync on/off as an option.
  - Sync Source
  - If the syncronization can come from an external device it can be configured here. This option will usually change depending on the sync method.
  - Use as Presentation Device
  - If this is checked, the device will be used by presentation mode. Only one device can be selected as the presentation device.
  - Output Audio to this Device
  - If checked, audio will be routed to the device if it has audio capabilities.
  - Incorporate Video Latency into Audio Offset
  - If checked, the total latency as indicated in the Configure Latency dialog box will be applied to the audio offset – but only if audio is being played by the controller instead of the output device (i.e. Output Audio to this Device is not checked). This is primarily useful if the video device has a large buffer causing a significant delay between the controller's audio output and the video output. Typically this is the case with SDI devices which may buffer multiple frames.
  6.2 Display Profiles
  Each video device configuration can have a unique display profile associated with it or can be made to use a default device or module profile. Profiles can be created and managed via View → Create/Edit Display Profiles.... Profiles are searched for in the RV_SUPPORT_PATH in the Profiles subdirectory (folder).
  Display profiles are snapshots of the view settings including a display LUT if present, the transfer function (sRGB, Rec.709, Gamma 2.2, etc), the primaries, the background, view channel ordering, stereo view modes, and dithering. If a custom nodes have been defined and are used in the display color pipeline than those will also be stored in the display profile.
  The display profile manager can be started from the view menu. This is where profiles can be created and deleted.
  When a profile is created, the values for the profile are taken from the current display device or you can select another device at creation time. Most of the view settings for the current device are present under the View menu
  If a profile is already assigned to a device, the device name will appear next to the profile in the manager.
  By selecting a profile and activating the Apply button, you can set the profile on the current view device. Applying a profile does not cause it to be remembered between sessions. In order to permanently assign a profile use the Video tab in the preferences.
  6.3 Video Device Command Line Arguments
  6.4 Presentation Mode Settings
  When the controller display mode is set to Seperate Output and Control Rendering you can choose which elements of the user interface are visible on the presnetation device. These can be enabled/disabled via the View → Presentation Settings menu. This includes not only things like the timeline and image info widget, but also whether or not the pointer location should be visible or not. In addition, you can show the actual video settings as an overlay on the display itself in order to verify the format is as expected. You can also control the display of feedback messages and remote sync pointers with items on this menu. The settings are retained in the preferences.
  If you want your custom-build widget to be rendered on the Presentation Device, your widget just needs to set the Widget class data member _drawOnPresentation to true.
  6.5 Platform Specific Considerations
  6.5.1 Linux Desktop Video Module Issues
  These issues apply only when using the desktop video module. NVIDIA-SDI or AJA modules do not apply here.
  The current state of the X server XRANDR extension and client library prevents us from implementing automatic resolution switching from RV. If your distribution has the xrandr binary available and installed, you can manually use that to force the presenation monitor into the proper resolution.
  When presentation mode starts up, RV will put the control window into a mode that allows tearing of the image in order to ensure that the presentation window will not tear. Be aware that the control window is no longer synced to a monitor.
  nVidia Driver
  RV will warn you if your presentation device is set to a monitor that the nVidia driver is not using for vertical sync. In that case you can continue, but tearing will probably occur if the attached monitors are not using identical timings. You can set the monitor which the driver syncs to using the __GL_SYNC_DISPLAY_DEVICE environment variable as per nVidia's driver documentation. See the nvidia-settings program to figure out the proper names (e.g. DPF-1 or CRT-1).
  nVidia recommends setting the driver V-Sync on and turning RV's V-Sync off if possible. If not, RV will attempt to sync using the appropriate GL extension. You can turn on/off RV's V-Sync via the checkbox under Preferences → Rendering.
  6.5.2 Mac Desktop Video Module Issues
  On OS X it's not a known fact, but it appears that vertical sync is timed to the primary monitor. This is the monitor on which the menu bar appears. You can change this via the system display settings Arrangement tab.
  RV will configure the controller display to prevent interfering with the playback of the presentation monitor. The control device may exhibit tearing or other artifacts during playback. On some versions of OS X, once the controller has entered this mode, it cannot be switched back even after presentation mode has been exitted.
  6.5.3 Windows 7 Video Module Issues
  On Windows, like OS X, the vertical sync is somewhat of an unknown. However, it appears that like OS X, the primary monitor (the one with the start menu) is the monitor the sync is derived from. So ideally, use the primary monitor as the presentation device, but your milage may vary.
  6.6 HDMI Frame Packed Mode
  As of RV 3.12.8, stereoscopic media can be displayed in Frame Packed (or “Frame Packing”) mode on any HDMI 1.4a-compliant device (AKA 3DTV). But in order for RV to make use of this display resolution (which is roughly a double-height HD frame), the monitor or other display device must have the appropriate resolution defined in advance. The timings from the HDMI 1.4a specification are shown in the following table:
  An additional important number is the required “pixel clock” or “pixel frequency”, which should be 148.5 MHz (for either 1080p or 720p),.
  Linux
  Sample Xorg.conf lines for 1080p 24Hz (720p 60Hz commented out), using the timings from the table above:
  Section "Monitor" ... Modeline "1920x2205_24" 148.32 1920 2558 2602 2750 2205 2209 2214 2250 +hsync +vsync #Modeline "1280x1470_60" 148.5 1280 1390 1430 1650 1470 1475 1480 1500 +hsync +vsync ... EndSection Section "Device" ... Option "ModeValidation" "NoDFPNativeResolutionCheck" Option "ExactModeTimingsDVI" "True" ... EndSection Section "Screen" ... Option "metamodes" "DFP-0: 1920x1080_60 +0+0, DFP-2: 1920x2205_24 +1920+0" ... EndSection
  Mac
  On OSX, we have used the shareware utility SwitchResX to add a Frame Packed resolution. Once the 1920x2205 resolution is visible in the Display preferences, it will show up in the Output Video Format selector on the Video Preference for the appropriate output device. If this device is selected as the presentation device, the monitor will go in and out of this mode when presentation mode is turned on and off.
  It's possible that there are various limitations to this approach. Our testing was on a MacBook Pro with Nvidia GFX (9600M GT), and we have reports of this working on a MacPro with Nvidia GFX (Quadro 4000) and a MacPro with ATI GFX (Radeon HD 5770), although the latter required some adjustments. Also, we have no reports of this working on OSX 10.7 yet. In one case, we haven't been able to make this work with a MacBookPro running 10.7 with ATI GFX. So, bottom line is that it can be made to work in some cases, but we can't guarantee it.
  Windows
  On Windows, you can use the NVIDIA control panel to create a custom resolution with the above timings. Go to “Change Resolution”, then “Custimize”, then “Create Custom Resolution”, then “Timing”, for the “Standard”, choose “Manual” and input the timings described above. Please note that RV cannot put the monitor in this Custom Resolution (the windows API does not expose the custom resolutions), so you need to choose the custom mode yourself (in the NVIDIA control panel, “Change Resolution” section) before you start RV. When RV starts, it will add the current (custom) mode to the Video Formats list in the Video Preferences tab, and you can select it there, then select the “Frame Packed” Data Format.
  7 How a Pixel Gets from a File to the Screen
  RV has a well defined image processing pipeline which is implemented as a combination of software and hardware (using the GPU when possible). Figure 7.1 shows the pixel pipeline.
  7.1 Image Layers
  Each image source may be composed of one or more layers. Layers may come from multiple files, or a single file if the file format supports it or a combination of the two. For example a stereo source can be constructed from a left and right movie file; in that case each file is a layer. Alternately, layers may come from a single file as would be the case with a stereo QuickTime file or EXR images with left and right layers.
  An image source may have any number of layers. By default, only the first layer is visible in RV unless an operation exposes the additional layers.
  7.1.1 Stereo Layers
  RV has a number of stereo viewing options which render image layers to a left and right eye image. The left and right eye images are both layers. RV doesn't require any specific method of storing stereo images: you can store them in a single movie file as multiple tracks, as multiple movie files, or as multiple image sequences. You can even have one eye be a completely different format than the other if necessary. Stereo viewing is discussed in Chapter 12.
  7.2 Image Attributes
  RV tries to read as many image attributes as possible from the file. RV may also add attributes to the image to indicate things like pixel aspect ratio, alpha type, uncrop regions (data and display windows) and to indicate the color space the pixels are in. The image info window in the user interface shows all of the relevant image attributes.
  Some of the attributes are treated as special cases and can have an effect on rendering. Internally, RV will recognize and use the ColorSpace/Primary attributes automatically. Other ColorSpace attributes are used by the default source setup package (See Reference Manual) to set file to linear properties correctly. For example, if the ColorSpace/Transfer attribute has the value “Kodak Log”, the default source setup function will automatically turn on the Kodak log to linear function for that source.
  Image attributes can be saved as a text file directly from the UI (File → Export → Image Attributes), viewed interactively with the Tools → Image Info widget, or using the rvls program from the command line.
  7.3 Image Channels
  RV potentially does a great deal of data conversion between reading a file and rendering an image on your display device. In some cases, you will want to have control over this process so it's important to understand what's occurring internally. For example, when RV reads a typical RGB TIFF file, you can assume the internal representation is a direct mapping from the data in the file. If, on the other hand, RV is reading an EXR file with A, B, G, T, and Z channels, and you are interested in the contents of the Z channel, you will need to tell RV specifically how to map the image data to an RGBA pixel.
  To see what channels an image has in it and what channels RV has decided to use for display you can select Tools → Image Info in the menu bar. The first two items displayed tell you the internal image format. In some cases you will see an additional item called ChannelNamesInFile which may show not only R, G, B channels, but additional channels in the file that are not being shown.
  RV stores images using between one and four channels. The channels are always the same data type and precision for a given image. If an image file on disk contains channels with differing precision or data type, the reader will choose the best four channels to map to RGBA (or fewer channels) and a data type and precision that best conserves the information present in the file. If there is no particular set of channels in the image that make sense to map to an internal RGBA image, RV will arbitrarily map up to the first four channels in order. By default, RV will interpret channel data as shown in Table 7.2
  When reading an image type that contains pixel data that is not directly mappable to RGB data (like YUV data), most of RV's image readers will automatically convert the data to RGB. This is the case for JPEG, and related image formats (QuickTime movies with JPEG compression for example). If the pixel data is not converted from YUV to RGB, RV will convert the pixels to RGB in hardware (if possible).
  7.3.1 Precision
  RV natively handles both integer and floating point images. When one of RV's image readers decides a precision and data type for an image, all of its channels are converted to that type internally.
  RV lets you modify how the images are stored internally. This ability is important because different internal formats can require different amounts of memory (see Table 7.3). In some cases you will want to reduce or increase that memory requirement to fit more images into a cache or for faster or longer playback.
  You can force RV to use a specific precision in the interface Color → Color Resolution menu. There are two options here: (1) whether or not to allow floating point and (2) the maximum bit depth to use.
  In the RV image processing DAG, precision is controlled by the Format node. There are two properties which determine the behavior: color.maxBitDepth and color.allowFloatingPoint.
  7.3.2 Channel Remapping
  RV provides a few similar functions which allow you to remap image channels to display channels. The most general method is called Channel Remapping.
  When Channel Remapping is active, RV reads all of the channel data in an image. This may result in images with too many channels internally (five or more), so RV will choose four channels to map to RGBA.
  You specify exactly which channels RV will choose and what order they should be in. The easiest way to accomplish this is in the user interface. By executing Tools → Remap Source Image Channels..., you can type in the names of the channels you want mapped to RGBA separated by commas. Using the previous example of an EXR with A, B, G, R, Z channels and you'd like to see Z as alpha, you could type in R,G,B,Z when prompted. If you'd like to see the value of Z as a greyscale image, you could type in Z or Z,A if you want to see the alpha along with it.
  It is also possible to add channels to incoming images using Channel Remapping. If you specify channel names that do not exist in the image file, new channels will be created. This is especially useful if you need to add an alpha channel to a three channel RGB image to increase playback performance
  1. (See sub:Pixel-and-Channel).
  Channel Remapping is controlled by the ChannelMap node. The names of the channels and their order is stored in the format.channels property. Channel Remapping occurs when the image data in the file is converted into one of the internal image formats.
  Note that there is overlapping functionality between Channel Remapping and Channel Reordering (See 7.8.1) and Channel Isolation (See 7.8.2) which are described below. However, Channel Remapping occurs just after pixels are read from a file. Channel Reordering and Isolation occur just before the pixel is displayed and typically happen in hardware. Channel Remapping always occurs in software.
  7.4 Crop and Uncrop
  Cropping an image discards pixels outside of the crop region. The image size is reduced in the process. This can be beneficial when loading a large number of cached images where only a small portion of the frame is interesting or useful (e.g. a rendered element). For some formats, RV may be able to reduce I/O bandwidth by reading and decoding pixels only within the crop region.
  Note that the four crop parameters describe the bottom and top corners not the origin, width, and height. So a “crop” of the entire image would be (0 , 0) to (w - 1 , h - 1) where w is the image width and h is the image height.
  Uncropping (in terms of RV) creates a virtual image which is typically larger than the input image
  It is also possible to uncrop an image to a smaller size (in which case some pixels are beyond the virtual image border) or partially in and out of the virtual uncrop image. This handles both the cases of a cropped render and an a render of pixels beyond the final frame for compositing slop.
  The OpenEXR format includes a display and data window. These are almost directly translated to uncrop parameters except that in RV the display window always has an origin of (0 , 0). When RV encounters differing display and data window attributes in an EXR file it will automatically convert these to uncrop values. This means that a sequence of EXR frames may have unique uncrop values for each frame.
  RV considers the uncropped image geometry as the principle image geometry. Values reported relating to the width and height in the user interface will usually refer to the uncropped geometry. Wipes, mattes, and other user interface will be drawing relative to the uncropped geometry.
  7.5 Conversion to Linear Color Space
  If an image format stores pixel values in a color space which is non-linear, the values should be converted to linear before any color correction or display correction is applied. In the ICC and EXR documentation, linear space is also called Scene Referred Space. The most important characteristic of scene referred space is that doubling a value results in twice the luminance.
  Although any image format can potentially hold pixel data in a non-linear color space, there are few formats which are designed to do so. Kodak Cineon files, for example, store values in a logarithmic color space.
  3JPEG images may be stored in ``video'' space
  The values in Cineon files are more complex than stated here. Color channel values are stored as code values which correspond to printing density – not luminance – as is the case with most other image file formats. Furthermore, the conversion to linear printing density is parameterized and these parameters can vary depending on the needs of the user. See the Kodak documentation on the Cineon format for a more detail description.
  If values are not in linear space, color correction and display correction transforms can still be applied, but the results will not be correct and in some cases will be misleading. So it's important to realize what color space an image is in and to tell RV to linearize it.
  7.5.1 Non-Rec. 709 Primaries
  If an image has attributes which provide primaries, RV will use this information to transform the color to the standard REC 709 primaries RGB space automatically. When the white points do not differ, this is done by concatenating two matrices: a transform to CIE XYZ space followed by a transform to RGB709 space. When the white points differ chromatic adaptation is used.
  7.5.2 Y RY BY Conversion
  OpenEXR files can be in stored as Y RY BY channels. The EXR reader will pass these files to RV as planar images (three separate images instead of one image with three channels). RV will then recombine the images in hardware into RGBA.
  This is advantageous when one or more of the original image planes are subsampled. Subsampled image planes have a reduced resolution. Typically the chroma channels (in this case RY and BY) are subsampled.
  7.5.3 YUV (YCbCr) Conversion
  Some formats may produce YUV or YUVA images to be displayed. RV can decode these in hardware for better performance. RV uses the following matrix to transform YUV to RGB:
  In the case of Photo-JPEG, the YUV data coming from a movie file is assumed to use the full gamut for the given number of bits. For example, an eight bit per channel image would have luminance values of [0, 255]. For Motion-JPEG a reduced color gamut is assumed.
  On hardware that cannot support hardware conversion, RV will convert the image in software. You can tell which method RV is using by looking at the image info. If the display channels are YUVA the image is being decoded in hardware
  5. On Linux, this option must be specified when RV is started using the -yuv flag.
  7.5.4 Log to Linear Color Space Conversion
  When RV reads a 10 bit Cineon or DPX file, it converts 10 bit integer pixel values into 16 bit integer values which are typically in a logarithmic color space. In order to correctly view one of these images, it is necessary to transform the 16 bit values into linear space. RV has two transforms for this conversion. You can access the function via the Color menu from the menu bar. For standard Cineon/DPX RV uses the default Kodak conversion parameters
  The Kodak Log conversion can produce values in range [0, ~13.5]. To see values outside of [0,1] use the exposure feature to stop down image. A value of -3.72 for relative exposure will show all possible output values of the Kodak log to linear conversion.
  7.5.5 ARRI LogC to Linear Color Space Conversion
  When viewing ARRI raw images, RV will use the header values to supply LogC parameters. In cases where no information is available (e.g. a DPX file encoded with LogC) the parameters for an 800 ASA exposure index will be used if no other information is available.
  7.5.6 File Gamma Correction
  If the image is stored in ``video'' or ``gamma'' space, you can convert to linear by applying a gamma correction. RV has three gamma transforms: one for linearization, one for display correction, and one in the middle for color correction. The gamma color correction can be activated via the Color → File Gamma menu items. When an image is stored in gamma space, it typically is transformed by the formula c1γ where γ is the gamma value and c is the channel value. When transforming back to linear space it's necessary to apply the inverse (cγ). RV's file gamma applies cγwhile the color correction gamma and the display gamma apply c1γ (in all cases γ refers to the value visible in the interface).
  7.5.7 sRGB to Linear Color Space Conversion
  If an image or movie file was encoded in sRGB space with the intention of making it easy to view with non-color aware software, RV can convert it to linear on the fly using this transform. In addition, some file LUTs are created to transform imagery from file space to sRGB space directly. If you apply one of these LUTs to an incoming image as a file LUT in RV you can then using the sRGB to linear function to linearize the output pixels.
  The sRGB to linear function can be activated via Color → sRGB and is stored per-source like the file gamma above or log to linear.
  7.5.8 Rec. 709 Transfer to Linear Color Space Conversion
  Similar to sRGB, The Rec. 709 non-linear transfer function is a gamma-like transform. High definition television imagery is often encoded using this color space. In order to view it properly on a computer monitor, it should be converted to linear and then to sRGB for display. The Rec. 709 to linear function can be activated via Color → Rec709 and is stored per-source like the file gamma, sRGB, or log to linear.
  7.5.9 Pre-Cache and File LUTs
  RV has four points in its pixel pipeline where LUTs may be used. The first of these is the pre-cache LUT. The pre-cache LUT is applied in software, and as the name implies, the results go into the cache. The primary use of the pre-cache LUT is to convert the image colorspace in conjunction with a bit depth reformatting to maximize cache use.
  The file LUT and all subsequent LUTs are applied in hardware and are intended to be used as a conversion to the color working space (usually some linear space). However, the file LUT can also be used for as a transform from file to display color space if desired.
  7.5.10 File CDLs
  In much the same way you can assign a File LUT to help linearize a file source into the working space in RV you can also use a file CDL. This CDL is applied before linearization occurs. There is also a look slot for CDL information described later.
  7.6 Color Correction
  None of the color corrections affects the Alpha channel. For a good discussion on linear color corrections, check out Paul Haeberli's Graphica Obscura websiteGraphica Obscura.
  Color corrections are applied independently to each image source in an RV session. For example, if you have two movies playing in sequence in a session and you change the contrast, it will only affect the movie that is visible when the contrast is changed. (If you want to apply the same color correction to all sources, perform the correction in tiled mode: Tools → Stack, Tools → Tile.)
  7.6.1 Luminance LUTs
  After conversion to linear, pixels may be passed though a luminance look up table. This can be useful when examining depth images or shadow maps. RV has a few predefined luminance LUTs: HSV, Random, and a number of contour LUTs. Each of these maps a luminance value to a color.
  7.6.2 Relative Exposure
  where c is the incoming color. So a relative exposure of -1.0 will cause the color to be divided by 2.0.
  Relative exposure can alternately be thought of as increasing or decreasing the stop on a camera. So a relative exposure of -1.0 is equivalent to viewing the image as if the camera was stopped down by 1 when the picture was taken.
  To map an exact range of values (where 0 is always the low value) set the exposure to log 21max where max is the upper bound.
  7.6.3 Hue Rotation
  The unit of hue rotation is radians. RV's hue rotation is luminance preserving. A hue rotation of 2π will result in no hue change.
  - Apply a rotation that maps the grey vector to the blue axis.
  - Compute the vector L that is perpendicular to the plane of constant luminance.
  - Apply a skew transform to map the vector L onto the blue axis.
  - Apply a rotation about the blue axis N radians where N is the amount of hue change.
  - Apply a rotation that maps the blue axis back to the grey vector.
  where
  7.6.4 Relative Saturation
  7.6.5 Contrast
  7.6.6 Inversion
  7.6.7 ASC Color Decision List (CDL) Controls
  7.7 Display Simulation and Correction
  After color corrections have been applied in linear space and before pixels are sent to the display device, they undergo display transformations. These transforms are intended to simulate the appearance of pixels on alternate display devices (like film) and to correct for any color transform that will be applied by the primary display device. In addition, RV provides a few tools to help visualize image pixel values in various ways.
  7.7.1 Display and Look LUTs
  There are times when it's necessary to have two separate display LUTs — one which might be per-shot and one which is global. For example, this can happen when digital intermediate color work is being done on plates while the un-corrected plates are being worked on; a temporary LUT may be needed to simulate the ``look'' of the final result.
  7.7.2 Display Gamma Correction
  This gamma correction is intended to compensate for monitor gamma. It is not related to File Gamma Correction, which is discussed in Section 7.5.6.
  For a given monitor, there is usually one good value (e.g., 2.2) which when applied corrects the monitor's response to be nearly linear. Note that you should not use the Display Gamma Correction if your monitor has been calibrated with a gamma correction built in.
  If you are using the X Window System (Linux/Unix) or Microsoft Windows, the default is not to add a gamma correction for the monitor.
  shell> xgamma
  -> Red 1.000, Green 1.000, Blue 1.000
  then your display has no gamma correction being applied. In this case you will want RV to correct for the non-linear response by setting the Display Gamma to correct for the monitor (e.g., 2.2).
  On Mac OS X, things are more complex. Typically, a ColorSync profile is created for your monitor and this includes a gamma correction. However, the monitor may be corrected to achieve a non-linear response. The best bet on OS X is to calibrate the display in such a way that a linear response is achieved and don't use a Display Gamma other than 1.0 in RV.
  7.7.3 sRGB Display Correction
  Most recently made monitors are built to have an sRGB response curve. This is similar to a Gamma 2.2 response curve, but with a more linear function in the blacks. RV supports this function directly for both input and output without the need to use a LUT. The sRGB display is a better default for most monitors than the display gamma correction above.
  RV's default rules for color set up use the sRGB display. RV also assumes by default that QuickTime movies and JPEG files are in sRGB color space unless they specifically indicate otherwise. This behavior can be overridden (see the Reference Manual).
  7.7.4 Rec. 709 Non-Linear Transfer Display Correction
  If the display device is an HD television or reference monitor it may be naturally calibrated to the Rec. 709 color space. Similar to sRGB, Rec. 709 is a gamma-like curve. RV uses the following formula to convert from linear to Rec. 709:
  7.7.5 Display Brightness
  There is a final multiplier on the color which can be made after the display gamma. This is analogous to relative exposure discussed above. The Display Brightness will never affect the hue of displayed pixels, but can be used to increase or decrease the final brightness of the pixel.
  This is most useful when a display LUT is being used to simulate an alternate display device (like projected film). In some cases, the display LUT may scale luminance of the image down in order to represent the entire dynamic range of the display device. In order to examine dark parts of the frame, you can adjust the display brightness without worrying about any chromatic changes to the image. Note that bright colors may become clipped in the process.
  7.8 Final Display Filters
  These operations occur after the display correction has been applied and before the pixel is displayed. Unlike color corrections, there is only a single instance of each of these for an RV session. So if you isolate the red channel for example, it will be isolated for all source material.
  7.8.1 Channel Reorder
  If you have RGBA or fewer channels read into RV and you need to rearrange them for some reason, you can do so without using the general remapping technique described above. In that case you can use channel reordering which makes it possible to reorder RGBA channels and set one or more of the channels to 0.0 or 1.0. Channel Reordering can be accessed in the menu bar under View → Channel Order. On supported machines, this function is implemented in hardware (so it's very fast).
  This function can be useful if the image comes from a format with unnamed RGB channels which are not in order. Another useful feature of Channel reordering is the ability to flood one or more channels with the constant value of 1.0 or 0.0. For example to see the red channel as red without green and blue you could set the order to R000 (R followed by three zeros). To see the red channel as a grey scale image you could use the order RRR0. (Yes, that is exactly what channel isolation does! See below.)
  Channel reordering is controlled by the Display node. The display.channelOrder attribute determines the order. Channel reordering occurs when the internal image is rendered to the display.
  7.8.2 Isolating Channels
  Finally, you can isolate the view to any single channel using the interface from the menu View → Channel Display. Since this is the most common operation when viewing channels, it is mapped to the keys ``r'', ``g'', ``b''and ``a'' by default (shows isolated red, green, blue, and alpha) and can be reset with the ``c'' key (show all color channels). You can also view luminance as a pseudo-channel with the ``l'' key.
  Channel isolation is controlled by the Display node. The display.channelFlood property controls which channel (or luminance) is displayed. Channel isolation occurs when the internal image is rendered to the display.
  7.8.3 Out-of-range Display
  The Out-of-Range color transform operates per channel. If channel data is 0.0 or less, the channel value is clamped to 0.0. If the channel data is greater than 1.0, the channel data is clamped to 1.0. If the channel data is in the range [0.0, 1.0] the data is clamped to 0.5.
  The idea behind the transform is to display colors that are potentially problematic. If the pixels are grey, then they are ``safe'' in the [0.0, 1.0] range. If they are brightly colored or dark, they are out-of-range.
  0.0 is usually considered an out-of-range color for computer graphics applications when the image is intended for final output.
  Note that HDR images will definitely display non-grey (bright) pixels when the out-of-range transform is applied. However, they probably should not display dark pixels.
  8 Using LUTs in RV
  Look up tables (LUTs) are useful for approximating complicated color transforms, especially those which have no known precise mathematical representation. RV provides four points in its color pipeline where LUTs can be applied: just after reading the file and before caching (pre-cache LUT 8.3) directly after the cache (file LUT), just before display transforms (look LUT), and as one of the display transforms (display LUT). The first three are per-source while there is only a single display LUT for each RV session. See 7.1
  Each of the LUTs can be either a channel LUT or a 3D LUT (the difference is explained below 8.1. In the case of a 3D LUT there can also be an additonal channel pre-LUT which can be used to shape the data. Both types of LUT are preceeded by an input matrix which can scale high dyamic range data into the range of the LUT input (which is the range [0,1]). The values the LUT produces can be outside of the [0,1] range. This makes it possible for any of the LUTs to transform colors outside of the typical [0,1] range on both input and output.
  Internally, RV will store the LUT as either half precision floating point or 16 bit integral. Not all hardware is capable of processing LUTs stored as floating point (esp. the 3D LUTs) so if you notice banding or noisy output when using floating point LUT storage, you may have better luck with the 16 bit integral representation. If RV can determine whether the floating point LUTs are usable itself it will default to whatever is appropriate.
  When applied in hardware, the LUTs are interpolated when a value is not exactly represented in the LUT. This is usually more of an issue with 3D LUTs than channel LUTs since they have fewer samples per dimension. When interpolating between sample values, RV uses linear interpolation for channel LUTs and tri-linear interpolation for 3D LUTs.
  There are a number of ways to create a LUT. For film look simulation, it's often necessary to have special hardware to measure and compare film recorder output. Alternately, you use a lightbox; and assuming you have a well calibrated neutral monitor, ``eyeball'' the LUT by comparing the film to the monitor.
  RV has two different algorithms for applying the LUTs on the GPU: using floating point or fixed-point integer textures. Not all cards are equally capable with 3D LUTs and floating point. If RV detects that the card probably can't do a good job with the floating point hardware it will switch to a fixed-point representation using 16 bit integer LUTs. Sometimes eventhough the driver reports that the LUTs can be floating point, you will see banding in the final images. If that occurs, try forcing the use fixed-point LUTs by turning off the Floating Point 3D LUTs item on the Rendering tab of the preferences. The fixed point LUT algorithm will perform just as well as floating point in 99% of normal use cases.
  8.1 Channel (1D) versus 3D LUTs
  A channel LUT (also called a 1D LUT) has three independent look-up tables: one each for the R G and B channels. The alpha channel is not affected by the channel LUT. Channel LUTs may be very high resolution with up to 4096 samples. Each entry in the channel LUT maps an input channel value to an output channel value. The input values are in the [0,1] range, but the output values are unbounded.
  Channel LUTs differ from 3D LUTs in one critical way: they can only modify channel values independently of one another. In other words, e.g., the output value of the red channel can only be a result of the incoming red value. In a 3D LUT, this is not the case: the output value of the red channel can be dependent on any or all of the input red, green, and blue values. This is sometimes called channel cross-talk.
  The other important difference between channel and 3D LUTs is the number of samples. Channel LUTs are one dimensional and therefor consume much less memory than 3D LUTs. Because of this, channel LUTs can have more samples per-channel than 3D LUTs.
  The implication of all this is that channel LUTs are useful for representing functions like gamma or log to linear which don't involve cross-talk between channels whereas 3D LUTs are good for representing more general color transforms and simulating physical output like film.
  3D LUTs can be very memory intensive. A 64 × 64 × 64 LUT requires 643 × 4 bytes of data (3Mb). You can quickly run out of memory for your image on the graphics card by making the 3D LUT too big (e.g. 128 × 128 × 128, this will slow RV down). RV does not require the 3D LUT to have the same resolution in each dimension. You may find that a particular LUT is smooth or nearly linear in one or more dimensions. In that case you can use a lower resolution in those dimensions.
  Some graphics cards have resolution issues with 3D textures which can cause loss of precision when RV's 3D LUT feature is enabled. On older NVidia cards and ATI cards in general, 3D textures may be limited to non-floating point color representations. Precision loss when using a LUT can be exacerbated by applying display gamma on these cards. To minimize precision loss on those types of cards, bake monitor gamma and/log-lin conversion directly into the display LUT. With newer GPUs this is not as much of an issue.
  8.2 Input Matrix and Pre-LUT
  For HDR applications, the incoming data needs to be rescaled and possibly shaped. RV has two separate components which do this: the LUT input matrix and a channel pre-LUT. The input matrix is a general 4 × 4 matrix. For HDR pixels, the matrix is used to scale the incoming pixel to range [0 , 1]. The pre-LUT, the channel LUT, and the 3D LUT all take inputs in that range. Figure 8.1 shows a diagram of the channel and 3D LUT components and their input and output ranges.
  The pre-LUT is identical to the channel LUT in implementation. It maps single channel values to new values. Unlike the general channel LUT, the pre-LUT must always map values in the [0 , 1] range into the same range. The purpose of the pre-LUT is to condition the data before it's transformed by the 3D LUT.
  For example, it may make sense for 3D LUT input values to be in a non-linear space – like log space. If the incoming pixels are linear they need to be transformed to log before the 3D LUT is applied. By using a relatively high resolution pre-LUT the data can be transformed into that space without precision loss.
  8.3 The Pre-Cache LUT
  The first LUT that the pixels can be transformed by is the pre-cache LUT. This LUT has the same parameters and features as the other LUTs, but it is applied before the cache. The pre-cache LUT is currently applied by the CPU (not on the GPU) whereas the file, look, and display LUTs are all used by the graphics hardware directly. For this reason the pre-cache LUT is slightly slower than the others.
  The pre-cache LUT is useful when a special caching format is desired. For example by using the pre-cache LUT and the color bit depth formatting, you can have RV convert linear OpenEXR data into 8 bit integer format in log space. By using RV's log to linear conversion on the cached 8 bit data you can effectively store high dynamic range data (albeit limimted range) and get double the number of frames into the cache. Many encoding schemes are possible by coupling a custom pre-cache LUT, change of bit depth, and the hardware file LUT to decode on the card.
  8.4 LUT File Formats
  RV supports several of the common LUT file formats (See Table 8.1). Unfortunately, not all LUT formats are equally capable and some of them are not terribly well defined. In most cases, you need to know the intended use of a particular LUT file. For example, it doesn't make sense to apply a LUT file which expects the incoming pixels to be in Kodak Log space to pixels from an EXR file (which is typically in a linear space). Often there is no way to tell the intended usage of a LUT file other than its file name or possibly comments in the file itself. Most formats do not have a public mechanism to indicate the usage to an application.
  To complicate matters, many LUT files are intended to map directly from the pixels in a particular file format directly to your monitor. When using these types of LUTs in RV you should be aware than making any changes to the color using RV's color corrections or display corrections will not produce expected results (because you are operation on pixels in the color space appropriate for the display, rather than in linear space).
  One of the more common types of LUT files you are likely to come across is one which maps Kodak Log space to sRGB display space. The file name of that kind of LUT might be log2sRGB or something similar. A variation on that same type of LUT might include an additonal component that simulates the look of the pixels when projected from a particular type of film stock. Strictly speaking, you do not need to use log to sRGB LUTs with RV because it implements these functions itself (and they are exact, not approximated). So ideally, if you require film output simulation you have a LUT which only does that one transform. Of course this is often not the case; the world of LUT formats is a complicated one.
  8.4.1 RSR .csp LUT Format
  Currently, the best LUT format for use with RV is the .csp format. This format handles high dynamic range input and output as well as non-linear and linear pre-LUTs. It maps most closely to RV's internal LUT functions.
  There is one type of .csp file which RV does not handle: a channel LUT with a non-linear pre-LUT. This is probably a very rare beast since an equivalent 1D LUT can be created with a linear pre-LUT. An error will occur if you attempt to use a channel LUT with a non-linear pre-LUT.
  When RV reads a pre-LUT from this file format and it can determine that the pre-LUT is linear, it will convert the pre-LUT into a matrix and apply it as the LUT input matrix. In that case the non-linear channel pre-LUT is not needed. If the pre-LUT is non-linear (in any channel) RV will construct a channel LUT which is used just before the 3D LUT. Input values in the .csp pre-LUT are normalized and the scaling is then moved to the input matrix. Using a matrix when possible frees up resources for other LUTs and images in the GPU. Any pre-LUT in a .csp file with only two values is by definition a linear pre-LUT.
  CSPLUTV100 3D 2 ^\label{preLUTStart}^ 0 13.5 0 1 2 0 13.5 0 1 2 0 13.5 0 1 ^\label{preLUTEnd}^ ...
  In the above listing, lines preLUTStart to preLUTEnd are linear pre-LUT values. In this case the pre-LUT values are mapping values int the range [0,13.5] down to [0,1] for processing by a 3D LUT (which is not shown). For a summary of the RSR .csp format see appendix G.
  For the most part, it's not necessary to know the distinction between a linear and non-linear pre-LUT in the file. However, the behavior of the pre-LUT outside the bounds of its largest and smallest input values will be different for linear pre-LUTs. Since the pre-LUT is represented as a matrix, it will not clamp values outside the specified range. Non-linear pre-LUTs will clamp values.
  9 Using CDLs in RV
  As discussed previously there are two default places to set ASC CDL properties in the RV node graph. One is as a file CDL on the RVLinearize node in the RVLinearizePipepline and the other is as a look CDL on the RVColor node in the RVLookPipeline. In the case of the RVLinearize node the CDL is applied before linearization occurs whereas in the case of the RVColor node the CDL s applied after linearization and linear color changes.
  9.1 CDL File Formats
  The types of files RV supports right now are Color Decision List (.cdl), Color Correction (.cc) and Color Correction Collection (.ccc) files. Color Correction Collection files can include multiple Color Corrections tagged by ids. We do not support reading the properties by id. Therefore the first Color Collection found in the file will be read and used.
  10 Packages
  There are multiple ways to customize and extend RV, and allmost all these ways can be enscapusulated in an RV Package. A package is a zip file with source or binary code that extends RV's feature set. Packages are constructed so that they can be automatically installed and removed. This makes it much easier for you to maintain RV than if you modify RV source directly. (Note: although packages are zip files, as of RV version 3.10 they are labeled with a .rvpkg extension to prevent mail programs, etc, from automatically unzipping them.
  Packages can encapsulate a wide variety of features: everything from setting the titile of the window automatically to implementing a paint annotation package. Some of RV's internal code is also in package form prior to shipping: e.g. the entire remote sync feature is initially constructed as a package of Mu source code (but is permanently installed when shipped).
  The package manager can be found in the preferences dialog. There are two sections to the user interface: the list of packages available and the description of the selected package. Some packages may be “hidden” by default; to see those packages toggle the show hidden packages button. To add and remove packages use the add and remove buttons located at the bottom left.
  This manual does not document any packages. See the Tweak Software website to download and get more information about particular packages.
  10.1 Package Support Path
  When a package is added, a list of permissable directories in the support path is presented. At that time you can choose which support directory to add the package to. When RV starts, these directories are automatically added to various paths (like image I/O plugins).
  By default, RV will include the application directory's plug-ins directory (which is probably not writable by the user) and one of the following which is usually writable by the user:
  You can override the default support path locations by setting the environment variable RV_SUPPORT_PATH. The variable contents should be the usual colon (Linux and Mac) or semicolon (Windows) separated list of directories. The user support directory is not included by default if you set the RV_SUPPORT_PATH variable, so be sure to explicitly include it if you want RV to include that path. Also note that the support path elements will have subdirectories called Mu, Packages, etc. In particular, when using the support path to install Packages, you want to include the directory above Packages in the path, not the Packages subdir itself.
  RV will create this structure if it's not already there the first time you add or install a package.
  10.2 Installation
  Once a package has been added, to install or uninstall simply click on the check box next to the name. The package is installed in the same support directory in which it was added.
  A package can be added, removed, installed, and uninstalled for all users or by a single user. Usually administrator priviliges are necessary to operate on packages system wide. When a package is added (the rvpkg file) it is copied into a known location in the support path.
  It's best to avoid editing files in these locations because RV tries to manage them itself. When a package is installed the contents will be installed in directories of the support directory.
  When first installed, packages are loaded by default. To prevent a packgae from loading uncheck the load check box. This is useful for installed packages which are not uninstallable because of permissions. While the install status of a package is universal to everyone that can see it, the load status is per-user.
  10.3 Package Dependencies
  Packages may be dependent on other packages. If you select a package to be installed but it requires that other packages be installed as well, RV will ask you if it can install them immediately. A similar situation can occur when setting the load flag for a package. When uninstalling/unloading the opposite can happen: a package may be required by another that is “using” it. In that case RV will ask to uninstall/unload the dependent packages as well.
  Some packages may require a minimum version of RV. If a package requires a newer version, RV will not allow you to install it.
  In some cases, manual editing of the support directory may lead to a partially installed or uninstalled package. The package manager has a limited ability to recover from that situation and will ask for guidance.
  11 OpenColorIO
  You can use OCIO in RV's display, look, viewing, linearize and color pipelines. In each case OCIO can be used to convert from an incoming and outgoing color space with a user defined OCIO context. OCIO requires some work to set up and should be considered an advanced feature. Large facilities may find OCIO particularily useful in RV when used in conjunction with Nuke, Mari, or other products which support it.
  You can learn about OpenColorIO at theOpenColorIO website.
  In order to use OCIO with RV a source setup package needs to be created along with OCIO configuration files, LUTs, and an appropriate user environment. RV comes with a package called ocio_source_setup which implements a default policy for using OCIO. We recommend the package be copied and modified to suit each facility that uses OCIO.
  There are four OCIO node types availble in RV: OCIOLook, OCIOFile, OCIODispay, and the generic OCIO node. The default ocio_source_setup will use these nodes to replace RV's existing color, look, and display pipelines.
  RV uses the OCIO GPU path instead of the more common CPU path for color computation. There are slight differences between the two which you will need to be aware of. Specifically, the color allocation parameters in the config file can have a big effect on the quality of the OCIO LUTs generated by the library.
  11.1 The ocio_source_setup Package
  OpenColorIO defines color spaces which are used to transform images for viewing or for storage in various file formats. It does not have any policy about when to apply these transforms.
  The provided ocio_source_setup package uses the default Sony Picture Imageworks method of detecting color space names in the incoming file names. The package querries OCIO and if the file name matches, the package will use OCIO nodes in various places in RV's pipelines instead of the usual RV color processing. If the incoming file name does not match an OCIO color space, the package will allow the existing RV color management to be used.
  One gotcha with this package is that once an OCIO managed file name has been detected, the package will use OCIO for the display correction as well. So mixed OCIO and RV managed imagery will always be viewed using OCIO's display color corrections.
  The package provides a basic menu fashioned after the OCIO display example program which allows you to file, look, and display transforms as well as forcing unrecognized media to use OCIO.
  - Find the “OpenColorIO Basic Color Management” package in the Packages tab of the preferences. Make sure the “load” button next to the package name is activated and restart RV.
  - Set the OCIO environment variable to the path to your config file.
  - Start RV and load an image with the color space in the name.
  - Note the "OCIO" top-level menu that appears when you use RV this way. You can use this menu to chose a Linearizing transform, or Display transform, from those provided by your config.
  The OpenColorIO mailing list and website is a good place to get help about config files, documentation, and general operation.
  12 Stereo Viewing
  - Anaglyph
  - Side-by-Side
  - Mirrored Side-by-Side
  - DLP Checker
  - Scanline Interleaved
  - Left or Right eye only
  - Hardware Left and Right Buffers
  The stereo rendering is designed to work with the other features of RV. In most cases, color corrections, image geometry manipulations, and display corrections will work in conjunctions with stereo viewing.
  When caching is on, all layers are cached (left and right eyes). You will need to reduce the image resolution to cache as many frames as non-stereo.
  The left and right eye images are normalized (i.e. conformed to fit the RV window) so they may have different resolutions and/or bit depths. However, it is not advisable to have differing aspect ratios.
  You can create stereo sources and set individual stereo parameters from the command line. See Section 3.2.2 to see how to do this.
  12.1 Anaglyph or Luminance Anaglyph
  The anaglyph modes display the left eye in the red channel and the right in eye in the green and blue channels (as cyan). If you were to wear colored red-cyan glasses and the eyes are correctly arranged, you should be able to see stereo with pseudo-color. Color anaglyph images work best for outdoor scenes (with lots of green) and in similar cases. They work very poorly with blue or green screen photography. For grey scale/non-color rendition of anaglyph, select the “Luminance Anaglyph” mode (Figure 12.4)..
  For color anaglyphs, if the color contrast is too great, the stereo effect will be difficult to see. If you turn on luminance viewing (hit the "l" key in the user interface), you can improve the effect (Figure 12.2). A similar solution is to desaturate the image slightly (hit shift "S" and scrub); this will reduce the color contrast but keep some hints of color (Figure 12.3).
  Compression artifacts can seriously degrade stereo viewing especially in anaglyph mode. QuickTime movies, for example, with low quality compression may look fine when viewed one eye at a time, but in anaglyph mode JPEG or similar artifacts will be greatly amplified by slight color differences. The best way to view compressed material is with luminance display turned on (no color).
  12.2 Side-by-Side and Mirror
  Side-by-Side mode displays the left and right eyes next to each other horizontally in full color. Some people are comfortable crossing their eyes to see stereo using this mode.
  Mirror mode is similar, but the right eye is flopped. If you need the left eye flopped, turn on mirror mode and select Image->Flop or hit shift-"X" this will have the effect of mirroring the left eye instead. Note that the same effect can be produced by flopping the right eye only in mirror mode.
  12.3 DLP Checker and Scanline
  These modes are designed to work with DLP projectors or LCD displays that directly support stereo display. In particular RV supports the SpectronIQ HD LCD display and DLP projectors using the Texas Instrument's checkerboard 3D DLP input.
  12.4 HDMI 1.4a or SDI Stereo Modes
  HDMI 1.4a stereo modes like (Side-by-Side and Top-and-Bottom) and HD-SDI dual stereo (RV-SDI product only) are supported via RV's Presentation Mode, descbied in Chapter 6. To select one of these modes for your Presentation Device, you choose the appropriate Output Data Format in the Video preferences.
  12.5 Hardware Stereo Support
  RV can render into left and right buffers if your graphics card supports hardware stereo. You can tell if this is the case by seeing if the menu item View → Stereo → Hardware can be selected. If so, RV should be able to create left and right buffers. There are a number of different ways to view stereo with a standard graphics card. See Chapter B for information about how to setup each platform and what options are available at the hardware level.
  Typically, hardware support requires shutter glasses (monitor or projection) or polarized glasses (projection only) in order to be useful.
  12.6 Additional Stereo Operations
  These options can be applied per-source as well as part of the global viewing stereo options. The per-source options can be found under the Image → Stereo menu and the global view options are under View → Stereo.
  12.6.1 Swap eyes
  Swap eyes changes the order of the left and right eyes (left becomes right and vice versa). If you are looking at stereo pairs and you just cannot see the stereo, you may want to try swapping the eyes. It is difficult to view stereo when the eyes are inverted.
  12.6.2 Relative Eye Offset
  Relative eye offset controls how separated the left and right images are horizontally. In the case of the anaglyph and hardware left and right buffer modes the offset value determines the fusion depth. Objects at the fusion depth appear coincident with the screen depth. In other words, they appear to be right on the screen: not behind it or in front of it. This is most evident in the anaglyph mode where the red and cyan components of a shape will not be separated if it's at the fusion depth. The units of the offset numbers are a percentage of the image width.
  You have a choice to either offset the eye images away from each other (both at the same time) or to offset the right eye only.
  12.6.3 Flip/Flop the Right Eye Only
  If you are projecting stereo and require one eye be flipped (vertical) or flopped (horizontal), you can select Image → Stereo → Flip Right Eye or Image → Stereo → Flop Right Eye. This can further be combined with Image → Flip and Image → Flop and rotation to move the images into the correct position.
  13 Networking
  RV implements a simple chat-like network protocol over TCP/IP. Network connections can be between two RVs or between a custom program and RV. The protocol is documented in the reference manual. This chapter discusses how to make network connections, how network permissions work, and how to synchronize two RVs using networking.
  Note that just turning on networking and establishing a connection doesn't actually do anything in RV. But this step is necessary before any of the features that use the networking can start.
  Some of the things you can do with networking include synchronizing to RV sessions across a network, sending pixels from another program to RV (e.g., a RenderMan display driver), or controlling RV from another program (remote control). Sync is part of RV, but remote control and sending pixels must be implemented in another program. RV comes with source code to a program called rvshell which shows you how to write software that connects with RV and controls playback remotely as well as sending images to RV over the connection. Some other applications are using special devices to control RV (like apple remote control for example) or controlling RV as an embedded playback component in a custom application on Linux.
  The reference manual has documentation about the networking protocol and how to create programs that talk to RV. The inner workings of the rvshell program are also discussed there.
  WARNING: Care should be taken with RV networking. Once a connection is established to a client application (RV or any other client) all scripting commands (including "system(...)") are allowed and executed with the user id and permissions of the local RV user. Local connections (from a client application running on the same machine as RV), are not authenticated and the user is not required to confirm connection. Remote connections must be explicitly allowed by the user, but the identity of the remote user can not be confirmed. Also note that traffic over RV network connections is generally not encrypted.
  Use of RV Remote Sync is at your own risk. Although we may recommend preferred configurations, we cannot guarantee that any configuration will be secure or that your use of RV Remote Sync will not introduce vulnerabilities into your systems. If you do not wish to accept this risk, please do not use RV Remote Sync.
  13.1 The Network Dialog
  Before you can use any of RV's networking features, you have to tell RV to begin listening for connections. There are two ways to do this: from the command line using the -network flag or interactively using the the Network dialog via the RV → Networking... menu item.
  The network dialog box has three pages: Configuration for setting up your identity and the port on which RV will communicate, the Contacts page for managing permissions, and the Connections page which shows a list of the currently active connections. At the bottom of the dialog are buttons for starting and stopping the networking and for initiating a new connection.
  13.1.1 Configuration
  The configuration requires two pieces of information: your identity (which appears at the other end of the connection) and a port number. Unless your systems adminitrator requires RV to use a different port you should leave the default value for the port number. Networking must be stopped in order to change the configuration.
  13.1.2 Starting a Connection
  To start networking and have RV accept connection just hit the Start Network button. Once running, the status indicator in the bottom left-hand corner of the dialog will show you the network status and the number of active connections (which starts out as 0).
  There are two ways to initiate a new connection: by pressing the Connect... button at the bottom of the dialog or by selecting a known address on the Contacts page.
  Using the Connect... button will show another dialog asking for the host name of the machine to connect to. Using this method, RV will not care which user it finds at the other end of the connection. If RV does not yet have record of the user it finds it will create one.
  13.1.3 Contacts and Permissions
  If networking is on, and a connection is initiated by another party, RV will ask whether or not you want the connection to occur. At that point you have three choices: accept the connection but ask for permission next time, always accept connection from the user/program that's asking, or deny the connection.
  Each new contact that RV receives (whether or not you accept) is recorded in the Contacts page. On this page you delete existing contacts, change permissions for contacts, and initiate connections to contacts. You can also specify the behavior RV when new contacts try to connect to your RV. This is most useful when RV is used by multiple people (for example in a common space like a view station). Often instances of RV running in common spaces should be more conservative about allowing connections without asking.
  To change an existing contacts permissions, double click on the current value (where it says, Allow, Ask, or Reject). You should see a pop-up menu which lets you change the value.
  13.1.4 Networking Across the Internet
  It's possible to connect to a remote RV across the internet in a peer-to-peer fashion, but special care needs to be taken. We recommend one of two methods: using ssh tunneling or using a VPN.
  SSH tunnelling is well known in the IT community. Since there is no standard firewall configuration, you will need to understand both the way in which ssh tunnelling is set up and the topology of the firewalls on both ends of the connection. No third party connection is needed to sync across ssh tunnels and the connection is relatively secure.
  Using a VPN is no different than a local area network once it has been established: you need to know the IP address or name of the host with which you want to connect. If you do not have a VPN in common with the remote participant, you can create one using Hamachi. The service is free for non-commercial use. See their website for more details.
  13.2 Synchronizing Multiple RVs
  To start sync select the menu item Tools → Sync With Connected RVs. You should see ``Sync ON'' in the feedback area on both RVs and a Sync menu will appear in the menu bar.
  Usually it's a good idea to have all participants looking at the similar media, but it's not enforced. In particular, note that RV's auto-conforming features mean that one party can be looking at a high-res OpenEXR sequence and another at a qucktime movie of the same sequence, and the sync can still be quite useful.
  13.2.1 Using Sync
  You can control which aspects of RV are transmitted to and received from remote RV's from the Sync menu. The menu is divided into to two main sections: things you can send and things you have agreed to receive. By default, sync mode will accept anything it gets, but will only send certain types of operations. So if one of the participants decides to send more than the default state the remote RVs will automatically use it.
  Sync mode will always send frame changes and playback options like the current fps, and the playback mode.
  13.3 “Streaming” Movie Media from Online Sources
  As of 4.0.13, media “paths” provided to RV may be URLs that link to online meda. These may be provided via the command line, in RVSession Files, or through scripting. This functionality should be considered “Beta” and there are several caveats you should be aware of:
  - At the moment “https” (SSL) URLs are only supported on OSX. On Linux/Windows URLs must be “http”.
  - The “media from online” workflow is a worst-case for RV's caching system, which generally assumes that the media can be accessed at arbitrary locations. In general, it's probably best to use Region Caching, with a large cache size, and allow the media to cache before playback begins. For media that is low-bandwidth, or for particularly low-latency connections, it may work well to use a large Lookahead Cache.
  - The URL needs to end in “.mov” or “.mp4” or some other extension that the MIO_FFMPEG plugin will recognize.
  - Audio may be a problem, since it is generally decoded and cached by a separate thread in RV. It may be best to turn on the “Cache All Audio” preference.
  - The movie should be created with the "faststart" property (for RVIO this means adding the "-outparams of:movflags=faststart" command-line options).
  14 Maximizing Performance
  RV is primarily a desktop playback program. As such, there are no guarantees about performance. That being said, there are a number of methods to tune performance for any particular hardware configuration and operating system. The most imporant parameters to tune for good performance in RV are:
  - The number of CPUs/cores available versus the number of reader threads used in RV
  - The specific file format being read (not all are created equal) and possible filesystem requirements like striping or guaranteed bandwidth constraints
  - The I/O method for each file format (if it has multiple methods) versus the type of mass storage (SAN, RAID, or stripped disks, etc)
  - If the file format decoder is threaded, the number of threads used for decoding (and balancing that with the number of reader threads)
  - A fast PCI bus and a recent GPU
  Most of these settings are available from either the caching preference pane or the rendering preference pane.
  14.1 File I/O and Decoding Latency
  When reading frames directly from disk, file I/O is often a huge bottleneck. If your frames live across a network connection (such as an NFS mount) the latency can be even greater. Ideally, if RV is playing frames without caching, those frames would be on a local disk drive, RAID, or SAN sitting on a fast bus.
  Part of the I/O process is decoding compressed image formats. If the decoding is compute intensive, the time spent decoding may become a bottleneck. If good playback performance off of disk is a requirement, you should choose a format that does not require extensive decoding (Cineon or DPX) or one that can be parallelized (EXR).
  As always, there is a tradeoff between file size and decoding time. If you have a very slow network, you might get better performance by using a format with complex expensive compression. If your computer is connected to a local high-speed RAID array or an SSD, then storing files that are easy to decompress but have larger file size may be better.
  14.1.1 EXR, DPX, JPEG, Cineon, TARGA, and Tiff I/O Methods
  The OpenEXR, DPX, JPEG, Cineon, TARGA, and Tiff file readers all allow you to choose between a few different I/O methods. The best method to use depends on the context RV is being used in. The method can be selected either from the command line or from the preferences (under each of the file formats). The command line options -exrIOMethod, -dpxIOMethod, -jpegIOMethod, -cinIOMethod, -tgaIOMethod, and -tiffIOMethod, require a number which corresponds to the methods listed in Table 14.1 and an optional I/O chunk size in bytes. Currently only the asynchronous methods use the chunk size.
  On Windows, the default is to use the Asynchronous Unbuffered method; this method generally produces the best results over the network and acceptable performance from a local drive.
  When using multiple reader threads, asynchronous methods may not scale as well as the synchronous ones.
  14.1.2 Multiple Reader Threads
  When caching to the region or look-ahead cache, multiple threads can be used to read and process the frames. This can have a profound impact on I/O speed for most formats. You can select the number of threads from the command line using -rthreads or via the preferences under Preferences → Caching (requires restarting RV to take effect).
  The optimal number of threads to use varies with file format, hardware, and network or storage. However a good rule of thumb is to use the number of cores minus one; this leaves one core to handle I/O overhead and other threads (like audio) which may need to run as well. In some cases using more threads may increase performance and in others it will decrease performance.
  The file format used can also have an impact on the number of threads. OpenEXR in particular has its own threaded decoder. It may be necessary to leave some cores free to decode only.
  With Quicktime movies, the codec becomes important when using multiple threads. For single frame codecs like Photo-JPEG using many threads is advantagous. For H.264 and similar inter-frame codecs, using a single thread is usually the best bet though internally the writer make create more threads.
  If your storage hardware has high latency (for instance network storage vs local disk) you may find that it makes sense to have more reader threads than cores. This is because the high latency means that most reader threads will sit in IO wait states and not compete for CPU cycles. In general, in network storage situations, it makes sense to start with a number of reader threads equal to cores-1 or cores-2 and then increase the number of reader threads until you see a drop in performance. Also note that it is dificult to test this kind of performance, since a modern operating system will cache pages read from the network or disk in a RAM filesystem cache. On Linux, you can clear the page cache by typing:
  shell> echo 1 > /proc/sys/vm/drop_caches
  14.2 Internal Software Operations
  Some operations occur in software in RV. For example, when you read images in at a reduced resolution, the image has to be resampled in software. When software operations are being performed on incoming images, it's a good idea to use caching. If direct from disk playback perforamnce is important than these operations should be avoided:
  - Image resolution changes
  - Pre-Cache LUT
  - Color resolution changes (e.g. float to 8 bit int color)
  - Cropping
  - Channel remapping
  14.3 RAM
  The fastest playback occurs when frames are cached in your computer's RAM. The more RAM you have, the more frames that RV can cache and the more interactive it becomes. By default RV will load images at their full bit depth and size. E.g. a 32 bit RGBA tiff will be loaded, cached and sent to the graphic card at full resolution and bit depth. This gives artists the ability to inspect images with access to the full range of color information and dynamic range they contain, and makes it possible to work with high-dynamic range imagery.
  However, for playback and review of sequences at speed users may wish to cache images with different settings so as to fit more frames into the available RAM. You increase the number of frames that will fit in the cache by having RV read the frames with reduced resolution. For example, reducing resolution by half can result in as many as four times the number of frames being cached.
  Similarly, reducing the color resolution can squeeze more frames into memory. For example a 1024x1024 4 channel 8-bit integer image requires 4Mb of memory internally while the same image as 16-bit floating point requires 8Mb and a 32-bit float image requires 16Mb. So by having RV reduce a 32-bit float image to an 8-bit image, you can pack four times the number of frames into memory without changing the image size.
  Not caching the Alpha channel of a 4 channel image will also reduce the memory footprint of the frames. You can tell RV to remap the image channels to R, G, B before caching (See 7.3.2). This may affect playback speed for other reasons, depending on your graphics card. You will need to experiment to determine if this works well on your system.
  14.3.1 Pixel Buffer Objects (PBOs) and Prefetch
  RV has an optional method of uploading pixels to the graphics card (PBOs). Normally, this is the fast path for maximum bandwidth to the card. However, some combinations of driver and GPU may result in poor performance. You can turn off the use of PBOs in the preferences or from the command line if you suspect PBOs are causing a bottleneck.
  Prefetch is only useful in conjunction with PBOs. Prefetch will attempt to asynchronously upload upcoming frames to the card ahead of the display frame. This option can add another 20% to display performance in some cases and cause a negative impact in others.
  If you're using a particular image format frequently it's a good idea to test using PBOs and prefetch to see how they perform on your hardware. To do so: cache a number of frames using the region cache. Make sure realtime mode is NOT on (in other words use play-all-frames mode). Set the target FPS to something impossible like 500 fps. With the preferences render pane open try playing back the frames from cache and see how fast it can go. Turn on and off PBO and prefetch usage to see what happens.
  14.4 Playback Sweet Spots
  There are a few combinations of hardware and file formats which lead to overall better performance. A couple of those are documented here.
  14.4.1 24 FPS 2048x1556 10 Bit DPX From Disk
  To achieve 24 fps DPX playback from disk at least a two core CPU with a RAID or other device which can achieve miniumum sustained bandwidth of 300+Mb/sec across the whole array and sufficient latency and I/O transactions per second. Using two or more reader threads (depending on the number of available cores) with the look-ahead cache on can result in 24 fps DPX playback. This configuration should be purely bandwidth limited meaning that more bandwidth would result in higher FPS.
  14.4.2 OpenEXR 24 FPS 2048x1556 3 Y-RY-BY 16 bit Floating Point B44 and B44A From Disk
  OpenEXR decoding benefits from more cores. For best results a 4 or 8 core machine is required. B44 2k full-aperture 4:2:0 sampled files are approximately 4Mb in size so they don't require as much bandwidth as DPX files of the same resolution. For 4:4:4 sampled or B44A with an alpha channel more bandwidth and cores may be required. Generally speaking you should have about as much bandwidth as similar DPX playback would require.
  When decoding EXR files, you have the option of setting both the number of reader threads in RV and the number of decoder threads used by the EXR libraries. The exact numbers depend on the flavor of B44/A files being decoded.
  14.4.3 Individual Desktop Review
  For individual desktop review the best quality and economy is undoubtably the use of QuickTime movies encoded with the Photo-JPEG codec. RV can play these back and create them on all three platforms. The image quality is good and the interactivity with the file is excellent (unlike H.264 which is slower when accessed randomly). If large QuickTime files are needed, RV can use multiple threads to decode the QuickTime movies efficiently. Many workstations can handle playback of 2k and 1080p Photo-JPEG QuickTime movies from the desktop using RV.
  15 File Formats
  Each platform has a different set of file formats which RV can read by default. In addition, it's possible to download or purchase additional file format plug-ins which allow RV to read even more. This chapter is an overview of the most important formats and how RV uses them.
  You can have RV dump out all of the formats and codecs which it understands on the command like by giving it the -formats option.
  shell> rv -formats
  If you don't see a codec or container format in the list, then RV doesn't support it without installing one or more plug-ins.
  15.1 Movie File Formats
  Movie files are single files which contain many images and often audio. These are often called container file formats because they usually specify how to store data, but not how it should be used. In most cases, that includes compression methods, play back algorithms, or even what the meaning of the data in the container is.
  Container file formats have additional sub-formats called codecs which determine things like compression and methods of play back. So even though a program like RV might be able to open a container file and look inside it, it might not understand one or more of the codecs which are being used in the container. In some cases the codec might be proprietary or meant to be used with a specific piece of software or hardware.
  15.1.1 Stereo Movie Files
  Most movie file formats can have multiple tracks. When RV reads a movie file with two or more tracks it uses the first two tracks as the left and right eye when in stereo mode. You can create these files using the Apple QuickTime Player or RVIO on OS X and Windows or RVIO on Linux.
  15.1.2 Text Tracks
  On Linux, RV will read the text track of a movie file if it exists and put the contents in an image attribute per frame. You can see this with the image info widget. Text tracks can be used to store metadata about the movie contents in a cross platform manner.
  15.1.3 QuickTime Movie Files (.mov)
  QuickTime is a wretched hoary beast. RV attempts to support QuickTime via two completely separate mechanisms: By default RV will use a plugin which leverages ffmpeg directly to handle as many formats and codecs as possible. Alternatively RV can use a plugin based on libquicktime. The libquicktime based plugin is outdated and only works on OS X and Linux.
  There are literally hundreds of codecs which can appear in a QuickTime file, but only some of them are useful in post-production. RV tries to support the most popular and useful ones.
  Photo-JPEG
  This codec has qualities which make it popular in film post production. Each frame is stored separately in the QuickTime file so moving to a random frame is fast. JPEG offers a number of ways to compress the image data including sub-sampling of color versus luminance and using sophisticated compression techniques. Color representation can be excellent when using Photo-JPEG. File sizes are moderate.
  Our ffmpeg plugin does not respect all of the QuickTime atom objects. Usually this is a good thing as Apple's own library produces inconsistent results from platform to platform when displaying movie files with gama and colr atoms. The most notorious of the color atoms which typically affects the color of Photo-JPEG movies is the gama atom. The gama atom causes Apple's Quicktime to apply two gamma corrections to the image before it is displayed. RV will not do that and RVIO does not include the gama atom when writing Quicktime movies.
  With our libquicktime plugin, Photo-JPEG is well supported and encoding and decoding make no changes to the color of pixels – even in the presence of the gama atom. Files encoded with libquicktime do not include the gama atom and play back will be as expected.
  Motion-JPEG
  Motion JPEG is similar to Photo-JPEG in that they both use the same compression algorithm. The main difference is that Motion-JPEG essentially stores a single frame in two parts: all of the even scanlines as a single JPEG image and all of the odd scanlines as a separate image. The codec interlaces the two parts together to form the final image.
  H.264 (avc1)
  This is the latest and greatest codec which is usually associated with MPEG-4. H.264 stores keyframes and data which helps it generate in-between frames on the fly. Because it doesn't store every frame individually, H.264 compressed files can be much smaller than codecs like Photo-JPEG. The image quality for H.264 can be good depending on how the movie was created. If relatively simple creation software was used (like Apple's QuickTime player or RVIO) the results are usually OK, but not nearly as good as Photo or Motion-JPEG.
  RAW Codecs
  There are a number of raw codecs for QuickTime. Some of these store the pixel data as RGB, others as YUV. The Raw codecs tend to be very fast to read and play back. RV supports a number of raw codecs on all platforms.
  Audio
  RV supports all of the raw uncompressed audio codecs across platforms. We are also licensed to read and write AAC audio.
  15.1.4 MPEG-4 Movie Files (.mp4)
  The MPEG-4 container file (.mp4) is almost identical to the QuickTime container file (.mov). The same codecs may be used to store data in either format. However, typically you find files encoded with H.264 or one of its predecessors.
  15.1.5 Windows AVI Files (.avi)
  15.1.6 Windows Media Files (.wmv)
  15.1.7 RV's movieproc Format (.movieproc)
  The movieproc ``format” is not really a file format— all of the information about the pixels is encoded in the name of the file. So the file doesn't even need to exist on disk to use it.
  You might use a movieproc as a source if you need a procedural movie object like color bars or a hold on a black or other solid color frame in in a sequence.
  where TYPE is one of solid, smptebars, colorchart, noise, blank, black, white, grey/gray, hramp/hbramp, hwramp, or error, and OPTION and VALUE are one of those listed in 15.1. A blank movieproc is one that will render no pixels but can occupy space in a sequence, and so can be used to form sequences with “holes”.
  smptebars,audio=sine,freq=1000,start=1,end=30,fps=30.movieproc
  solid,start=1,end=100,fps=24,width=1920,height=1080.movieproc
  solid,red=1,green=.5,blue=0,width=1920,height=1080.movieproc
  Anywhere you might use a normal file or sequence name in RV or RVIO you can use a movieproc instead.
  15.1.8 RED r3d
  RV can read RED r3d files directly. By default, the native pixels are converted to linear space by the RED SDK and displayed in RV without any linearizing transform. If you want to use alternate decoding parameters, you can use MOVIER3D_ARGS environment variable and set it to any or all of the five options. Note, the –hdrBlendAlgorithm and –hdrBias options apply to HDRx clips.
  shell> setenv MOVIER3D_ARGS "–videoDecodeMode <mode> –videoPixelType <type> \ –imageGammaCurve <transfer> –imageColorSpace <cs> –hdrBlendAlgorithm <blend> –hdrBias <bias>"
  If the clip is a HDRx clip, then the default hdrBlendAlgorithm option is HDRx_MAGIC_MOTION with a default hdrBias of 0.0. To decode just FrameA for a HDRx clip, use “–hdrBlendAlgorithm HDRx_SIMPLE_BLEND –hdrBias 1” and for FrameX (the under exposed frame) use “–hdrBlendAlgorithm HDRx_SIMPLE_BLEND –hdrBias -1”.
  shell> rvio in.r3d -o out.#.exr -outparams "passthrough=RED"
  Reading of RED R3D files supports more than one reading thread (i.e. Preferences window “Caching” tab “Reader Threads”). We suggest using a value thats no more than the number of cores on the playback machine. Please note that if you “kill -9” (send a SIGKILL signal to) the RV process after having played back a R3D file, you will need to check for defunct “redsidecar” reader processes and terminate them.
  15.2 Image File Formats
  Each platform which RV runs on has its own selection of image formats. There are few important ones which are implemented across all platforms. Some of the most important formats are discussed in this chapter.
  15.2.1 OpenEXR
  OpenEXR (EXR) is a high dynamic range floating point file format developed at ILM. It can store both 32 and 16 bit ``half'' floating point values with or without compression. RV supports the EXR half float type natively and when the GPU is capable, will render using type half type directly. RVIO is capable of converting to and from the half and full float formats.
  The EXR format is extremely flexible, capable of holding everything from multiple views (for stereo) to rendered layers like isolated diffuse and specular components as separate images. In addition it's possible to store subsampled chroma images or combinations of all the above.
  There have been at least two important revisions to the original OpenEXR specification, one the “multi-view” spec adds official support for top-level “view” objects that contain channels, and the most recent, the “multi-part” spec adjusts the file format so that groups of channels can be stored in discrete sections (“parts”) for efficient I/O. RV supports all varieties of EXR file supported by the latest specifications, but attempts to hide some of the resulting complexity from the user, as discussed below.
  Multiple Views
  Multiple view EXR files as defined by the Weta Multiview Extension are supported by RV. When in stereo mode, RV will look for views called ``left'' and ``right'' by default and can be programmatically told to use other channels (see the Reference Manual).
  You can also select one or more views in the UI to be loaded specifically when not in stereo mode. In stereo mode if you specify two views those will become the left and right.
  RV defaults to loading the default (or first) EXR layer from the view. The EXR views are independent of EXR layers which are described below — there can be multiple views each of which has multiple layers (or vice versa if you prefer to think of it that way).
  RV will recognize the file extensions ``exr”, ``sxr” (stereo exr), or ``openexr” as being OpenEXR files. Stereo views may be stored as either ``exr'' or ``sxr''; RV does not distinguish between the two extensions.
  Layers
  A layer in EXR terminology is a collection of channels which share a common channel name prefix separated by a dot character. Although EXR layers can have sub-layers and so on, in RV the layer hierarchy is flattened to a single level. So for example, an EXR channel in a traditional multi-view EXR file (multi-part files are discussed below), might have a channel called “left.keyLight.Diffuse.R”. In RV's simplified usage, the channel “R” is a member of the layer “keyLight.Diffuse”, which is a member of the view “left”.
  EXR layers are usually used to store components of images output by a renderer like Pixar's prman or Mental Image's Mental Ray. Often these layers are recombined in compositing software like Nuke which can handle the internal structure of the EXR file. This makes it easy for a compositor to control render output at a fine level to match it into a shot. Note that this not how EXR views are used — they are used for indicating stereo eyes (for examples) and each view may itself contain multiple EXR layers.
  RV initially will load the default layer (the one that has no name) or the first layer it finds. If this layer has R, G, B, A, Z, Y, RY, or BY channels, these will be assigned accordingly. If there are no obvious channel assignments to be made to the red, green, and blue channels, RV will take the first four channels it finds in the layer. If there are additional channels, you can assign these explicitly using the channel remap function in the UI under Image → Remap Source Image Channels.
  You can view alternate layers by selecting them in the Session Manager, or by selecting a layer on the command line.
  Y RY BY Images and Subsampling.
  By default, RV will read EXR files as planar images. Normally this distinction does not have any real effect at the user level, but in the case of Y RY BY images — which can be sub-sampled — it can have a big impact on playback performance. EXR has two special lossy compression schemes, B44 and B44A, which allow fast decode of high dynamic range imagery. B44 maintains a fixed size file regardless of the contents while B44A can potentially make smaller file sizes. As of OpenEXR v2.2.0, two further lossy DCT compression schemes were added i.e. DWAA (based on 32 scanlines) and DWAB (based on 256 scanlines). The level compression for DWAA and DWAB can be set through the '-quality <compression level value>' option in rvio when writing out EXR files. This value is stored in the exr header (single/multipart) as a float attribute called 'dwaCompressionLevel' and defaults to 45 for DWAA and DWAB.
  When used with Y RY BY images with sub-sampled chroma (the BY and RY channels) RV will use the GPU to resample the chroma on the card resulting in faster throughput. When coupled with one or more multi-core CPUs, RV can get good direct from disk performance for these types of images while keeping the HDR information in tact
  Chromaticities
  EXR files may have chromaticities (primaries) included in the image attributes. If RV sees the Color/Primaries attribute, it will apply the corresponding transform to the Rec 709 primaries by default. You can turn off this behavior by selecting Color → Ignore File Primaries to disable the transform.
  Channel Inheritance
  Some programs may assume channels should be “inherited” in EXR files. For example, a renderer may write a single alpha channel in the default layer and exclude redundant alpha channels from additional layers in the file like diffuse and specular. The idea is that these layers will share the default alpha during compositing.
  RV can attempt to aggregate channels assumed to be related like this by using either the command line option -exrInherit or by setting the flag in preferences (under the OpenEXR format).
  Data/Display Window Handling
  How an EXR image is displayed on screen, under certain data/display window overlap permutations, can vary across commercial and/or in-house viewing tools. To accomodate this and allow RV to emulate these differing behaviors, we provide several exr format preferences; see the table below for typical settings.
  The two OpenEXR preferences, found under Preferences-Format-OpenEXR, that define RV's data/display window handling behavior are -exrReadWindow and -exrReadWindowIsDisplayWindow. The flag -exrReadWindow specifies how the final data/display window (i.e ReadWindow) is defined. The choices are “Data Window”, “Display Window”, “Data Window Inside Display Window” and “Union of Data and Display Window”. In addition the flag -exrReadWindowIsDisplayWindow maybe optionally set to always make the ReadWindow the EXR display window; otherwise the display window is determined by source's EXR display window attributes.
  Parts
  As of OpenEXR version 2.0, EXR files can be written in separate sections, called “parts”. Each part has it's own header, and the underlying OpenEXR API can quickly skip to parts requested by the reader. Parts can contain layered and unlayered channels and be associated with views, but parts have names and so can also act as “layers” in the sense that unique parts can contain channels of the same name.
  In order to merge these possibly multiple and simultaneous uses of “parts” into the standard view/layer/channel hierarchy, RV subsumes EXR “parts” into the definition of “layer” when necessary. That is, as far as RV is concerned, a fully-specified channel name always looks like view.layer.channel, where (in the case of an EXR file) the three period-separated components of the name have these meanings:
  NB: One comment on performance; we have observed uncached playback FPS speedups of between 2-3x (OSX/Linux/Windows) with multipart exr files over single part exr files for deep channeled images.
  15.2.2 TIFF
  TIFF files come in many flavors some of which are rarely used. RV supports a useful subset of all possible TIFF files. This includes 32 bit floating point and multiple channels (beyond four) in both tiled and scanline. RV can read planar and interleaved TIFF files, but currently only reads the first image directory if there are more than one.
  15.2.3 DPX and Cineon
  RV and RVIO currently support 8 and16 bit, and the common 10 and 12 bit DPX and 10 bit Cineon files reading direct from disk on all platforms. The standard header fields are read and reported if they contain useful information (e.g., Motion Picture and TV fields). We do not currently support any of the vendor headers.
  RV supports the linear, log, and Rec. 709 transfer functions for DPX natively and others through the use of LUTs.
  RV decodes DPX and Cineon to 8 bit integer per channel by default. However, the reader can be configured from the command line or preferences to use 16 bit if needed. In addition the reader can use either planar or interleaved pixel formats. We have found that the combination of OS and hardware determines which format is fastest for playback, but we currently recommend RGB8_PLANAR on systems that can use OpenGL Pixel Buffer Objects (PBOs) and RGBA8 on systems that cannot. If you opt for 16 bit pixels, use the RGB16_PLANAR as the pixel format on PBO equipped hardware for maximum throughput.
  For best color fidelity use RV's built in Cineon Log → Linear option and sRGB display (or a particular display LUT if available). This option decodes the log space pixels directly to linear without interpolation inside a hardware shader and results in the full [0 , ∼ 13.5] range.
  15.2.4 IFF (ILBM)
  The IFF image format commonly created by Maya or Shake is supported by RV including the 32 bit float version.
  15.2.5 JPEG
  RV can read JPEG natively as Y U V or R G B formats. The reader can collect any EXIF tags and pass them along as image attributes. The reader is limited to 8 bits per channel files. Like OpenEXR, DPX, and Cineon, JPEG there is a choice of I/O method with JPEG images.
  15.2.6 ARRI Alexa
  The ARRI raw LogC or LogC-Film encoded files (.ari) can be read directly by RV and RVIO. In addition, non ari files with a LogC or LogC-Film curve applied (e.g. DPX) can be viewed in RV using a “generic” LogC or LogC-Film when no information about the transfer function is available; an exposure index (EI) value of 800 is assumed for the LogC/LogC-Film parameters in this case.
  RV computes the LogC/LogC-Film curve parameters directly from the exposure index (EI) in the file's metadata or from the “–iso” IOARI_ARGS parameter value which is used to override the file's metadata EI value. No LUTs are required. These EI dependant LogC parameter values are noted in the RV imageinfo attributes “ColorSpace/LogC<something>”.
  The color is transformed from the decode colorspace (which defaults to choice Arri Wide Gamut) to Rec709 primaries which is RV's internal working color space. The decode colorspace can be a colorspace other than LogC_WideGamut; the choices are listed in the table below. There are two variants for LogC_WideGamut. One is more colormetrically (scene referred) accurate than the other. The colorimetric mode is more appropriate for VFX use than say digital post production. The default behavior is to use the non-colorimetric version of the Wide Gamut to Rec709 transform which is preferred in digital post production (e.g. transcoding to ProRes). The IOARI_ARGS parameter “–enableColorimetricMode” lets you make this choice by enabling the colorimetric version of the Wide Gamut to Rec709 transform when set to '1'. This parameter defaults to '0' otherwise.
  For more information about color processing one can refer to the ARRI documentation on “Color Management for Alexa V3” and “Alexa Usage in VFX” .
  If you use RVIO to convert the raw images to EXR or similar formats which can hold the full dynamic range all of the camera's data should be preserved. In addition, you can pass all the raw metadata as well.
  shell> rvio in.ari -inlogc -o out.exr -outparams "passthrough=ARRI"
  You can control some aspects of the ARRI decoder by passing in parameter values to the io_ari plugin via an environment variable: IOARI_ARGS.
  Theses parameters are support in RV version 6.x onwards and reflect some of the choices provided by ArriRawSDK v5.3 or later. Example
  shell> setenv IOARI_ARGS "–colorspace LogC_WideGamut –enableColorimetricMode 1 –debayer ADA_5_SW –threads 8 –downScaleMode QUAD_HD_FROM_2880PX"
  15.2.7 RAW DSLR Camera Formats
  There are a number of camera vendor specific formats which RV can read through RV's cross platform image plugin io_raw. This plugin uses the open src package LibRAW. The table below list some of the common raw formats that are read with this plugin.
  15.3 Audio File Formats
  RV supports a number of basic uncompressed audio file formats across platforms. On Windows and OS X a number of compressed formats may be supported. Currently use of Microsoft wave files and Apple's AIFF formats are the best bet for cross platform use. RV does support multichannel audio files for playback to multichannel audio devices/SDI audio. (see Appendix J).
  15.4 Simple ASCII EDL Format
  Each line of the ASCII file is either blank, a comment, or an edit event. A comment starts with a '#' character and continues until the end of a line. A comment can appear on the same line as an edit event.
  "SOURCE" START END
  "/some/path/to/foo.mov" "/some/path/to/bar.1-100#.exr" "/some/other_path/baz.1-100#.exr"
  Note that the SOURCE name must always be in double quotes. If the path includes spaces, you do not need to use special escape characters to make sure they are accepted. So this:
  "/some/place with spaces/foo.mov"
  START and END are frame numbers in the movie. Note that START is the first frame to be include in the clip, and END is the last frame to be included (not, as in some edl formats, the frame after the last frame). For QuickTime .mov files or .avi files, the first frame of the file is frame 1.
  # # 4 source movies # "/movies/foo.mov" 1 100 "/movies/bar.mov" 20 50 "/movies/render.1-100#.exr" 25 100 "/movies/with a space.#.exr" 1 25
  16.
  RVIO is a command line (re)mastering tool–it converts image sequence, audio files, and movie files from one format into another including possible bit depth and image color and size resolution changes. RVIO can also generate custom slate frames, add per-frame information and matting directly onto output images, and change color spaces (to a limited extent).
  RVIO supports all of the same movie, image, and audio formats that RV does including the .rv session file. RV session files (.rv) can be used to specify compositing operations, split screens, tiling, color corrections, pixel aspect ratio changes, etc.
  16.1 Basic Usage
  16.1.1 Image Sequence Format Conversion
  RVIO's most basic operation is to convert a sequence of images from one format into another. RVIO uses the same sequence notation as RV to specify input and output sequences. For example:
  shell> rvio foo.#.exr -o foo.#.tif shell> rvio foo.#.exr -o foo.#.jpg
  16.1.2 Image sequence to QuickTime Movie Conversion
  RVIO can write out QuickTime movies. The default compression codec is PhotoJPEG with a default quality of 0.9.
  shell> rvio foo.#.exr -o foo.mov
  16.1.3 Resizing and Scaling
  Rvio does high quality filtering when it resizes images. Output resolution can be specified explicitly, in which case RVIO will conform to the new resolution, padding the image to preserve pixel aspect ratio.
  shell> rvio foo.1-100@@@@.tga -scale 0.5 -o foo.#.tga shell> rvio foo.#.exr -outres 640 480
  Or you can use the -resize x y option, in which case scaling will occur in either dimension (unless the number specified for that dimension is 0).
  16.1.4 Adding Audio to Movies
  RVIO uses the same layer notation as RV to combine audio with image sequences. Multiple audio sources can be mixed in a single layer.
  shell> rvio [ foo.1-300#.tif foo.aiff ] -o foo.mov shell> rvio [ foo.1-300#.tif foo.aiff bar.aiff ] -o foo.mov
  16.2 Advanced Usage
  16.2.1 Editing Sequences
  RVIO can combine multiple sequences and write out a single output sequence or movie. This allows you to quickly edit and conform.
  shell> rvio foo.25-122#.exr bar.8-78#.exr -o foo.mov shell> rvio [ foo.#.exr foo.aiff ] [ bar.#.exr bar.aiff ] \ -o foobar.mov
  shell> rvio [ foo.mov -in 101 -out 120 ] [ bar.mov -in 58 -out 123 ] -o out.mov
  16.2.2 Processing RV Session Files
  RV session files can be used as a way to author operations for processing with RVIO. Most operations and settings in RV can be used by RVIO. For example RV can be used in a compositing mode to do an over or difference or split-screen comparison. RV can also be used to set up edits with per source color corrections (e.g. a unique LUT for each sequences, exposure or color adjustments per sequences, an overall output LUT, etc.).
  shell> rvio foo.rv -o foo.mov
  shell> rvio foo.rv -o foo.mov -view "latest shots"
  16.2.3 Advanced Image Conversions
  RVIO has flags to handle standard colorspace, gamma, and log/lin conversions for both inputs and outputs
  shell> rvio foo.#.cin -inlog -o foo.#.exr shell> rvio foo.#.exr -o foo.#.cin -outlog shell> rvio foo.#.jpeg -insrgb -o foo.#.exr shell> rvio foo.#.exr -o foo.#.tiff -outgamma 2.2 shell> rvio foo.#.exr -o foo.#.jpeg -outsrgb shell> rvio foo.#.cin -inlog -o foo.mov -outsrgb \ -comment "Movie is in sRGB space"
  16.2.4 LUTs
  RVIO can apply a LUT to input files and an output LUT. RVIO's command line only supports one file LUT and one display LUT. The file LUT will be applied to all the input sources before conversion and and the output LUT will be applied to the entire session on output. If you need to process a sequences with a different file LUT per sequence, you can do that by creating an RV session file with the desired LUTs and color settings to use as input to RVIO.
  shell> rvio foo.#.cin bar.#.cin -inlog -flut in.cube \ -dlut out.cube -o foobar.mov
  16.2.5 Pixel Storage Formats and Channel Mapping
  RVIO provides control over pixel storage (floating point or integer, bit depth, planar subsampling) and channel mapping. The planar subsampling options are particularly used to support OpenExr's B44 compression, which is a fixed bandwidth, floating point, high-dynamic range compression scheme.
  shell> rvio foo.#.exr -outformat 8 int -o foo.#.tif shell> rvio foo.#.exr -outformat 8 int -o foo.#.tif -outrgb shell> rvio foo.#.cin -inlog -o foo..#.tiff -outformat 16 float shell> rvio foo.#.exr -outformat 32 float -o foo.#.tif shell> rvio foo.#.exr -codec B44A -yrybya 1 2 2 2 -outformat \ 16 float shell> rvio foo.#.exr -codec B44A -yryby 1 2 2 -outformat \ 16 float -outchannelmap R G B
  16.2.6 Advanced QuickTime Movie Conversions
  RVIO uses ffmpeg or libquicktime for reading and writing. You can find out what codecs are available for reading and writing by using the ``-formats” flag. This will also tell you the full name of the encoder, e.g. writing H.264 requires ``libx264” by ffmpeg and simply ``x264” by libquicktime. RVIO lets you specify the output codec and can collect parameters for the output from ``outparams”. Please examine the following two examples. The first is with the default settings for libx264's H.264 writting, and the second is a popular command derived from using the ffmpeg binary directly. Something of the form ``ffmpeg -i foo.%04d.tif -ac 2 -b:v 2000k -c:a aac -c:v libx264 -pix_fmt yuv420p -g 30 -b:a 160k -vprofile high -bf 0 -strict experimental -f mov outfile.mov”.
  shell> rvio foo.#.tif -codec libx264 -o foo.mov shell> rvio foo.#.tif -codec libx264 -audiocodec aac \ -outparams pix_fmt=yuv420p vcc:b=2000000 acc:b=160000 \ vcc:g=30 vcc:profile=high vcc:bf=0 -o foo.mov
  16.2.7 Audio Conversions
  RVIO can operate directly on audio files and can also add or extract audio to/from QuickTime movies. RVIO provides flags to set the audio codec, sample rate, storage format (8, 16, and 32 bits) storage type (int, float), and number of output channels. RVIO does high quality resampling using 32 bit floating point operations. RVIO will mix together multiple audio files specified in a layer.
  shell> rvio foo.mov -o foo.aiff shell> rvio foo.mov -o foo.aiff -audiorate 22050 shell> rvio [ foo.#.exr foo.aiff bar.wav ] -codec H.264 \ -quality 1.0 \ -audiocodec "Apple Lossless" -audiorate 44100 \ -audioquality 1.0 -o foo.mov
  16.2.8 Stereoscopic and Multiview Conversions
  RV and RVIO support stereoscopic playback and conversions. RVIO can be used to create stereo QuickTime files or multiview OpenExr files (Weta's SXR files) by specifying two input layers and using the -outstereo flag. Stereo QuickTime movies contain multiple video tracks. RV interprets the fist two tracks as left and right views. RVIO will also render output using stereo modes specified in an RV session file–this allows you to output anaglyph images from stereo inputs or to render out scanline or alternating pixel stereo material.
  shell> rvio [ foo_l.#.exr foo_r.#.exr foo.aiff ] -outstereo \ -o stereo.mov shell> rvio [ foo_left.#.exr foo_right.#.exr ] -outstereo \ -o stereo.#.exr
  shell> rvio [ foo_l.#.exr foo_r.#.exr foo.aiff ] -outstereo hsqueezed \ -o stereo.mov
  16.2.9 Slates, Mattes, Watermarks, and Burn-ins
  RVIO supports script based creation of slates and overlays. The default scripts that come with RV can be used as is, or they can be customized to create any kind of overlay or slate that you need. Customization of these scripts is covered in the RV Reference Manual. RVIO has two command line flags to manage these scripts, -leader and -overlay. -leader scripts are used to create Slates or other frames that will be added to the beginning of a sequence or movie. -overlay scripts will draw on top of the image frames. Multiple overlays can be layered on top of the image, so that you can build up a frame with mattes, frame burn-in, bugs, etc. The scripts that come with RV include:
  Simpleslate Leader
  Simpleslate allows you to build up a slate from a list of attribute/value pairs. It will automatically scale all of your text to fit onto the frame. It works like this:
  shell> rvio foo.#.exr -leader simpleslate \ "Acme Post" "Show=My Show" "Shot=foo" "Type=comp" \ "Artist=John Doe" "Comments=Lighter and Darker as \ requested by director" -o foo.mov
  Watermark Overlay
  The watermark overlay burns a text comment onto output images. This makes it easy to generate custom watermarked movies for clients or vendors. Watermark takes two arguments, the comment in quotes and the opacity (from 0 to 1).
  shell> rvio foo.mov -overlay watermark "For Client X Review" 0.1 \ -o foo_client_x.mov
  Matte Overlay
  The matte overlay mattes your images to the desired aspect ratio. It takes two arguments, the aspect ratio and the opacity.
  shell> rvio foo.#.exr -overlay matte 2.35 1.0 -o foo.mov
  Frameburn Overlay
  The frameburn overlay renders the source frame number onto each frame. It takes three arguments, the opacity, the luminance, and the size.
  shell> rvio foo.#.exr -overlay frameburn 0.1 0.1 50 -o foo.mov
  Bug Overlay
  The bug overlay lets you render an image o top of each output frame. It takes three arguments, the image name, the opacity, and the size
  shell> rvio foo.#.exr -overlay bug "/path/to/logo.tif" 0.5 48
  16.2.10 EXR Attributes
  RVIO can create and pass through header attributes. To create an attribute from the command line use -outparams:
  shell> rvio in.exr -o foo.exr -outparams NAME:TYPE=VALUE0,VALUE1,VALUE2,...
  Values are comma seperated. For example to create a Imath::V2i attribute called myvec with the value V2i(1,2):
  shell> rvio in.exr -o out.exr -outparams myvec:v2i=1,2
  shell> rvio in.exr -o out.exr -outparams mystringvector:sv=one,two,three,four
  shell> rvio in.exr -o out.exr -outparams myfloatmatrix:m33f=1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0,9.0
  If you want to pass through attributes from the incoming image to the output EXR file you can use the passthrough variable. Setting passthrough to a regular expression will cause the writer code to select matching incoming attribute names.
  shell> rvio in.exr -o out.exr -outparams "passthrough=.*"
  shell> rvio in.jpg -o out.exr -insrgb -outparams "passthrough=.*EXIF.*"
  16.2.11 IIF/ACES Files
  RVIO can convert pixels to the very wide gamut ACES color space for output using the -outaces flag. In addition, use of the .aces extenion will cause the OpenEXR writer to enforce the IIF container subset of EXR. For example, to convert an existing EXR file to an IIF file:
  shell> rvio in.exr -o out.aces -outaces
  16.2.12 DPX Header Fields
  Using -outparams it's possible to set almost any DPX header field. Setting the field will not change the pixels in the final file, just the value of the header field.
  There are a couple of fields treated in a special way: the frame_position, tv/time_code, and tv/user_bits fields are all increment automatically when a sequence of frames is output. In the case of tv/user_bits and tv/time_code, the initial value comes either from the output frame number, or starting at the time code passed in.
  shell> rvio in.#.tif -o out.#.dpx -outparams tv/time_code=00:11:22:00
  Currently, the DPX writer cannot automatically pass through header fields from input DPX images to the output DPX images.
  It is also possible to set the alignment of pixel data relative to the start of the file using alignment. For example, to force the pixel data to start at byte 4096 in the DPX file:
  shell> rvio in.#.tif -o out.#.dpx -outparams alignment=4096
  17 RVLS
  By default rvls with no arguments will list the contents of the current directory. Unlike its namesake ls, rvls will contract image sequences into a single listing. The output image sequences can be used as arguments to rv or RVIO
  For more detailed information about a file or sequence the -l option can be used: this will show each file or sequence on a separate line with the image width and height, channel bit depth, and number of channels. For movie files and audio files, additional information about the audio like the sample rate and number of channels will be displayed.
  shell> rvls -l w x h typ #ch file 623 x 261 16i 3 ./16bit.tiff 1600 x 1071 8i 3 ./2287176218_5514bbc63a_o.jpg 1024 x 680 8i 3 ./best-picture.jpg 2048 x 1556 16f 3 ./sheet.hi.90.exr 5892 x 4800 8i 1 ./BurialMount.psd 64 x 64 8i 1 ./caust19.bw 5892 x 4992 8i 1 ./common_sense.psd 640 x 486 16i 3 ./colorWheel.685.cin 640 x 480 8i 1 ./colour-bars-smpte-75-640x480.tiff
  shell> ls *.iff render_maya.1.iff render_maya.10.iff render_maya.2.iff render_maya.3.iff render_maya.4.iff render_maya.5.iff render_maya.6.iff render_maya.7.iff render_maya.8.iff render_maya.9.iff shell> rvls *.iff render_maya.1-10@.iff
  It is also possible to list the image attributes using RVLS using the -x option. This will display the same attribute information that is displayed in RV's Image Info Widget:
  shell> rvls -x unnamed_5_channel.exr unnamed_5_channel.exr: Resolution 640 x 480, 5ch, 16 bits/ch floating point Channels PixelAspectRatio 1 EXR/screenWindowWidth 1 EXR/screenWindowCenter (0 0) EXR/pixelAspectRatio 1 EXR/lineOrder INCREASING_Y EXR/displayWindow (0 0) - (639 479) EXR/dataWindow (0 0) - (639 479) EXR/compression ZIP_COMPRESSION Colorspace Linear
  18 RVPUSH
  The RVPUSH command-line utility allows you to communicate with a running RV (you can designate a “target” RV with the -tag option). The help output from the command is as follows:
  usage: rvpush [-tag <tag>] <command> <commandArgs> rvpush set <mediaArgs> rvpush merge <mediaArgs> rvpush mu-eval <mu> rvpush mu-eval-return <mu> rvpush py-eval <python> rvpush py-eval-return <python> rvpush py-exec <python> rvpush url rvlink://<rv-command-line> Examples: To set the media contents of the currently running RV: rvpush set [ foo.mov -in 101 -out 120 ] To add to the media contents of the currently running RV with tag "myrv": rvpush -tag myrv merge [ fooLeft.mov fooRight.mov ] To execute arbitrary Mu code in the currently running RV: rvpush mu-eval 'play()' To execute arbitrary Mu code in the currently running RV, and print the result: rvpush mu-eval-return 'frame()' To evaluate an arbitrary Python expression in the currently running RV: rvpush py-eval 'rv.commands.play()' To evaluate an arbitrary Python expression in the currently running RV, and print the result: rvpush py-eval-return 'rv.commands.frame()' To execute arbitrary Python statements in the currently running RV: rvpush py-exec 'from rv import commands; commands.play()' To process an rvlink url in the currently running RV, loading a movie into the current session: rvpush url 'rvlink:// -reuse 1 foo.mov' To process an rvlink url in the currently running RV, loading a movie into a new session: rvpush url 'rvlink:// -reuse 0 foo.mov' Set environment variable RVPUSH_RV_EXECUTABLE_PATH if you want rvpush to start something other than the default RV when it cannot find a running RV. Set to 'none' if you want no RV to be started. Exit status: 4: Connection to running RV failed 11: Could not connect to running RV, and could not start new RV 15: Cound not connect to running RV, started new one.
  Any number of media sources and associated per-source options can be specified for the set and merge commands. For the mu-eval command, it's probably best to put all your Mu code in a single quoted string. In the next release we'll have a python-eval command as well.
  If RVPUSH cannot find a running RV to talk to, it'll start one with the appropriate command-line options. Any later rvpush commands will use this RV until it exits. Note that the RV that RVPUSH starts will by default be the one in the same bin directory. If you'd rather start a different RV, or start a wrapper, etc, you can set the environment variable RVPUSH_RV_EXECUTABLE_PATH to point to the one you'd preffer. If you want RVPUSH to never start RV, you can set this environment variable to “none”.
  A Differences between RV 3 and RV 6
  RV 6 has a number of underlying changes which make it different from RV 3. Most of these are related to the underlying structure of a session. So unless you are writing session files you may not notice them.
  B Stereo Setup
  B.1 Linux
  This is taken from an NVIDIA README file. The portions pertaining to stereo modes are reproduced here:
  The following driver options are supported by the NVIDIA X driver. They may be specified either in the Screen or Device sections of the X config file.
  Option "Stereo" "integer"
  Enable offering of quad-buffered stereo visuals on Quadro. Integer indicates the type of stereo glasses being used
  Stereo is only available on Quadro cards. Stereo options 1, 2, and 3 (aka "active" stereo) may be used with TwinView if all modes within each metamode have identical timing values. Please see Appendix J.
  Option "AllowDFPStereo" "boolean"
  By default, the NVIDIA X driver performs a check which disables active stereo (stereo options 1, 2, and 3) if the X screen is driving a DFP. The "AllowDFPStereo" option bypasses this check.
  Some functionality, such as Active Stereo with TwinView, requires control over exactly what mode timings are used. There are several ways to accomplish that:
  If you only want to make sure that both display devices use the same modes, you only need to make sure that both display devices use the same HorizSync and VertRefresh values when performing mode validation; this would be done by making sure the HorizSync and SecondMonitorHorizSync match, and that the VertRefresh and the SecondMonitorVertRefresh match.
  A more explicit approach is to specify the modeline you wish to use (using one of the modeline generators available), and using a unique name. For example, if you wanted to use 1024x768 at 120 Hz on each monitor in TwinView with active stereo, you might add something like: # 1024x768 @ 120.00 Hz (GTF) hsync: 98.76 kHz; pclk: 139.05 MHz Modeline "1024x768_120" 139.05 1024 1104 1216 1408 768 769 772 823 -HSync +Vsync In the monitor section of your X config file, and then in the Screen section of your X config file, specify a MetaMode like this: Option "MetaModes" "1024x768_120, 1024x768_120"
  Support for GLX in Xinerama
  This (please refer to the XF86Config(5x) or xorg.conf(5x) manpages for details). The Xinerama extension can be enabled by adding the line
  It is recommended to use identical GPUs..
  X configuration options that affect GLX operation (e.g.: stereo, overlays) should be set consistently across all X screens in the X server.
  B.2 Mac OS X and Windows
  There are no special requirements (other than having a proper GPU that can produce stereo output). If the OS X or Windows graphical environment can provide RV with a stereo GL context, it will play back in stereo. If not, the console widget will pop up and you will see GL errors.
  If you have trouble with the stereo on the Mac, you might have some luck on one of Apple's mailing lists.
  C The RVLINK Protocol: Using RV as a URL Handler
  rvlink://<RV commandline>
  rvlink:// -l -play /path/to/my/movie.mov
  Will start RV (or on the mac, create a new session or replace the current session), load movie.mov, turn on the look-ahead cache, and start playback.
  C.1
  <a href="rvlink: -l -play /path/to/my/movie.mov">play movie</a> to humans, but as a last resort,'
  C.2 install location, then just double click on this file to edit the registry.
  Mac
  Run RV once with the ``-registerHandler” command-line option in order to register that executable as the default rvlink protocol handler (this is to prevent confusion between RV and RV64 when both are installed).
  Linux, I.
  Chrome uses the underlying system defaults to handle protocols. In most cases this means whatever "xdg-open" is configured to use. Running the rv.install_handler should be sufficient
  C.3 ensure that these environment variables are.
  C.4 Testing the Protocol Handler
  Once RV is properly registered as the rvlink protocol handler, go to this page to try it out on the rvlink test page.
  D Using RV as Nuke's Flip Book Player
  Nuke can easily be configured to use RV as a flipbook. Nuke can also be set up to render out OpenEXR temp files instead of the default rgb files.
  D.1 Setting up a custom plugins area for Nuke
  In order to configure Nuke to work with RV, you should set up a custom scripts/plugins directory where you can add new custom Nuke functionality without disturbing the default Nuke install. This directory can be anywhere on the NUKE_PATH environment variable, but note that the ``$HOME/.nuke'' directory is always on that NUKE_PATH, so we'll assume we're working there for now.
  1. In your $HOME/.nuke directory, create a file called ``init.py'', if it doesn't already exist, and also one called ``menu.py''.
  nuke.pluginAddPath('./python')
  mkdir $HOME/.nuke/python
  D.2 Adding RV support in the custom plugins area
  1. Download the script ``rv_this.py'' from this forum post.
  3. Add the following line to the $HOME/.nuke/init.py file, after the pluginAddPath lines mentioned above:
  import rv_this
  menubar = nuke.menu("Nuke"); menubar.addCommand("File/Flipbook Selected in &RV", "nukescripts.flipbook(rv_this.rv_this, nuke.selectedNode())", "#R")
  1. Find the file ``nukescripts/flip.py'' in your Nuke install and copy it to $HOME/.nuke/python/flipEXR.py.
  2. Edit $HOME/.nuke/python/flipEXR.py and find the two lines that specify the output file name (search for ``nuke_tmp_flip'') and change the file extension from ``rgb'' to ``exr''.
  menubar.addCommand("File/Flipbook Selected in &RV (EXR)", "flipExr.flipbook(rv_this.rv_this, nuke.selectedNode())", "#E")
  You can edit the rv_this.py script to specify any rv options you wish to set as your viewing defaults. For example you could un-comment the script lines that will apply -gamma 2.2 or enable -sRGB, or you could specify a file or display LUT for RV to use.
  E RV Audio on Linux
  E.1 Overview
  Linux suffers from historically poor support for audio and from a variety of sometimes incompatible audio frameworks. RV provides multiple audio modules so users can get the most audio functionality available given the constraints imposed by the Linux kernel version, the available audio frameworks, and the other audio applications in use.
  Potential user issues with audio on Linux are choppy playback (clicking, dead spots, drop-outs), or high latency (it takes a breath's worth of time to start playing). Both of these issues are extremely annoying and it is even worse when they both occur. Ideally latency is nearly 0 for high quality audio and drop-outs never occur.
  To make matters worse, there are two completely different audio drivers for Linux: OSS and ALSA. Only one of these can be present at a time (but both provide a ``compatibility'' API for the other). ALSA is the official Linux audio API and is shipped with almost all distributions. OSS is a cross platform API (for UNIX based machines).
  The Linux desktop projects, KDE and Gnome, both have sound servers build on top of OSS/ALSA. These are called esd and arts. Both of them have become deprecated in recent releases. If either of these processes is running you may find it difficult to use audio with RV (or other commercial products).
  Some distributions use a newer desktop sound server called PulseAudio . PulseAudio ships with most distributions and is on by default in RHEL, CentOS, and Fedora, and comes with Debian and Ubuntu. RV can use PulseAudio through the ALSA (Safe) module, however we strongly recommend against using PulseAudio. Though the PulseAudio server is designed to allow multiple applications to simultaneously play audio (and can run in real-time mode), we have found a decrease in stability with each new release of the module. Even for simple read-only API calls that query the state of the device. If possible for your workflow we suggest you remove PulseAudio, if it is not otherwise necessary.
  E.1.1 How RV Handles Linux Audio
  As of version 3.6, RV now has multiple native audio back ends for Linux as well as the original PortAudio
  On some systems, RV will fail to load one or more of its audio modules. This can occur of the API used by the module is newer than the one installed on the system. For example neither CentOS 4.6 or Fedora Core 4 can load the ALSA safe module unless the ALSA client library is upgraded. Any Linux system which uses ALSA 1.0 or newer should function with the ALSA old back end.
  E.2 ALSA (Old)
  The ALSA (Old) audio back end is new in version 3.6. This back end uses a subset of the ALSA API which was present on version 1.0 of ALSA's client library. Without modification, it will make hardware devices directly accessible. (In ALSA terms these are the hw:x,y devices). You can also add to the list of devices using an environment variable called RV_ALSA_EXTRA_DEVICES. The syntax is:
  See the ALSA documentation for the .asoundrc file for more information about devices and how they can be created. Devices defined in the configuration files will not automatically show up in RV; you'll need to add them to the environment variable.
  E.3 ALSA (Safe)
  The ALSA (Safe)
  2audio back end uses a more modern version of the ALSA client API. If the version of ALSA client library on your system is newer than 1.0.13 this back end might work better on your system. PulseAudio system should definitely be using this audio module.
  The term “Safe” here refers to the subset of the ALSA API deemed safe to use in the presence of PulseAudio. Programs that use features that PulseAudio cannot intercept will cause inconsistant audio availability or unstable output. Use of hardware devices in the presence of PulseAudio can prevent other applications from using the audio driver whether they be ALSA or OSS based.
  The ALSA safe back end can use the RV_ALSA_EXTRA_DEVICES variable (see above). However, user/system defined devices will typically show up in the device list automatically.
  The safe back end does not give you direct access to the hardware devices by default. Typically you will see devices which look like:
  The xxxx and n values correspond to the hardware device values used in the ALSA old back end. You can force the use of the hardware devices by adding them to the environment variable.
  front:CARD=xxxx,DEV=n
  For example, the first device on the first card would be hw:0,0 in ALSA parlance. So setting the value of RV_ALSA_EXTRA_DEVICES to:
  We recommend that you do not add hardware devices when using the safe ALSA module. The hardware devices will typically be accessible via the default device list under different names (like front:CARD=xxxx,DEV=n from above). Unlike the default list of devices, the hardware devices will shut out other software from using the audio even on systems using the PulseAudio sound server.
  E.4 PortAudio
  The PortAudio back end is more or less the same one used by versions of RV prior to 3.6. PortAudio supports most hardware and some plugin devices from ALSA, includes an OSS interface, and can talk to the JACK server directly. Unfortunately, on some newer systems, the method used by PortAudio when interfacing with ALSA is not stable. We recommend using the ALSA back ends directly instead of PortAudio.
  For OSS, PortAudio is currently the only choice. If your system requires the use of the OSS API you should be able to access it via the PortAudio back end.
  E.5 Platform Audio
  As of RV version 4.0.11 onwards, we introduced a new cross platform audio module based on Qt audio (which on Linux is ALSA based).Note Platform Audio supports playback on multichannel audio devices.
  F Troubleshooting Networking
  Connections only work from one direction or are always refused
  Some operating systems have a firewall on by default that may be blocking the port RV is trying to use. When you start RV on the machine with the firewall and start networking it appears to be functioning correctly, but no one can connect to it. Check to see if the port that RV wants to use is available through the firewall.
  This is almost certainly the case when the connection works from one direction but not the other. The side which can make the connection is usually the one that has the firewall blocking RV (it won't let other machines in).
  G Rising Sun Research CineSpace .csp File Format
  Header
  It is made up of the first two (2) valid lines in the file. See Notes below for a definition of a valid line.
  CSPLUTV100 3D
  CSPLUTV100 1D
  Metadata
  This section contains metadata not defined by the CSP format itself. RV will ignore everything here except a line containing a conditioningGamma. For example:
  BEGIN METADATA conditioningGamma=0.4545 END METADATA
  The conditioningGamma value is applied (in GLSL) to both the input lattice points and the input data to the LUT (so does not change the mathematical “meaning” of the LUT). Especially for LUTs expecting linear input, this can compensate for the fact that, when the LUT is applied in hardware the even spacing of the lattice points can cause artifacts. In particular, we've found that a conditioningGamma value of 0.4545 allows a ACES-to-ACESlog LUT applied in RV (in HW) to match the results of applying the same LUT in Nuke (in SW).
  1D preLUT data
  This section is designed to allow for unevenly spaced data and also to accommodate input data that maybe outside the 0.0 <-> 1.0 range. Each primary channel, red, green and blue has each own 3 line entry. The first line is the number of preLUT data entries for that channel. The second line is the input and the third line is the mapped output that will then become the input for the LUT data section.
  It is made up of the valid lines 3 to 11 in the LUT. See Notes below for a definition of a valid line.
  Access LUT data via a gamma lookup Red channel has gamma 2.0 Green channel has gamma 3.0 but also has fewer points Blue channel has gamma 2.0 but also has fewer points
  11 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0 0.0 0.01 0.04 0.09 0.16 0.25 0.36 0.49 0.64 0.81 1.0 6 0.0 0.2 0.4 0.6 0.8 1.0 0.0 0.008 0.064 0.216 0.512 1.0 6 0.0 0.2 0.4 0.6 0.8 1.0 0.0 0.04 0.16 0.36 0.64 1.0
  LUT data
  This section contains the LUT data. The input stimuli for the LUT data is evenly spaced and normalized between 0.0 and 1.0. All data entries are space delimited floats. For 3D LUTs the data is red fastest.
  It is made up of the valid lines 12 and onwards in the LUT. See Notes below for a definition of a valid line.
  2 3 4 0.0 0.0 0.0 1.0 0.0 0.0 0.0 0.5 0.0 1.0 0.5 0.0 0.0 1.0 0.0 1.0 1.0 0.0 0.0 0.0 0.33 1.0 0.0 0.33 0.0 0.5 0.33 1.0 0.5 0.33 0.0 1.0 0.33 1.0 1.0 0.33 0.0 0.0 0.66 1.0 0.0 0.66 0.0 0.5 0.66 1.0 0.5 0.66 0.0 1.0 0.66 1.0 1.0 0.66 0.0 0.0 1.0 1.0 0.0 1.0 0.0 0.5 1.0 1.0 0.5 1.0 0.0 1.0 1.0 1.0 1.0 1.0
  Notes:
  All lines starting with white space are considered not valid and are ignored. Lines can be escaped to the next line with “\” (but note that RV does not actually implement this part of the spec, so lines should not be broken in CSP files for RV). All values on a single line are space delimited.
  The third valid line (after any METADATA section) is the number of entries in the red 1D preLUT. It is an integer.
  The fourth valid line contains the input entries for the red 1D preLUT. These are floats and the range is not limited. The number of entries must be equal to the value on the third valid line.
  The fifth valid line contains the output entries for the red 1D preLUT. These are floats and the range is limited to 0.0 <-> 1.0. The number of entries must be equal to the value on the third valid line.
  The seventh valid line contains the input entries for the green 1D preLUT. These are floats and the range is not limited. The number of entries must be equal to the value on the sixth valid line.
  The eighth valid line contains the output entries for the green 1D preLUT. These are floats and the range is limited to 0.0 <-> 1.0. The number of entries must be equal to the value on the sixth valid line.
  The tenth valid line contains the input entries for the blue 1D preLUT. These are floats and the range is not limited. The number of entries must be equal to the value on the ninth valid line.
  The eleventh valid line contains the output entries for the blue 1D preLUT. These are floats and the range is limited to 0.0 <-> 1.0. The number of entries must be equal to the value on the ninth valid line.
  The thirteenth valid line and onwards contain the LUT data. For 3D LUTs the order is red fastest. The data are floats and are not range limited. The data is evenly spaced.
  H Crash Reporting
  RV includes google's crash reporting mechanism called breakpad on linux. If RV crashes it will produce a file in /tmp with an extension of .dmp. This file can be sent to our support email and used to determine exactly how the program crashed.
  I PySide example usage
  RV ships with PySide on all platforms. In this section, we present two simple examples of PySide usage. We also demonstrate how to access the RV session window in the second example.
  #!()
  The second example, shown below, is a RV python package that uses pyside for building its UI with Qt widgets that control properties values on an RVLensWarp node. Note too that in this example, the current RV session QMainWindow obtained from rv.qtutils.sessionWindow() and we use it to change the session window's opacity with the “Enable” checkbox.
  from PySide.QtCore import QFile from PySide.QtGui import QDoubleSpinBox, QDial, QCheckBox from PySide.QtUiTools import QUiLoader import types import os import math import rv import rv.qtutils import pyside_example # need to get at the module itself class PySideDockTest(rv.rvtypes.MinorMode): "A python mode example that uses PySide" def checkBoxPressed(self, checkbox, prop): def F(): try: if checkbox.isChecked(): if self.rvSessionQObject is not None: self.rvSessionQObject.setWindowOpacity(1.0) rv.commands.setIntProperty(prop, [1], True) else: if self.rvSessionQObject is not None: self.rvSessionQObject.setWindowOpacity(0.5) rv.commands.setIntProperty(prop, [0], True) except: pass return F def dialChanged(self, index, last, spins, prop): def F(value): diff = float(value - last[index]) if diff < -180: diff = value - last[index] + 360 elif diff > 180: diff = value - last[index] - 360 diff /= 360.0 last[index] = float(value) try: p = rv.commands.getFloatProperty(prop, 0, 1231231) p[0] += diff if p[0] > spins[index].maximum() : p[0] = spins[index].maximum() if p[0] < spins[index].minimum() : p[0] = spins[index].minimum() spins[index].setValue(p[0]) rv.commands.setFloatProperty(prop, p, True) except: pass return F def spinChanged(self, index, spins, prop): def F(value): try: rv.commands.setFloatProperty(prop, [p], True) except: pass def F(): try: p = spins[index].value() commands.setFloatProperty(prop, [p], True) except: pass return F def findSet(self, typeObj, names): array = [] for n in names: array.append(self.dialog.findChild(typeObj, n)) if array[-1] == None: print "Can't find", n return array def hookup(self, checkbox, spins, dials, prop, last): checkbox.released.connect(self.checkBoxPressed(checkbox, "%s.node.active"%prop)) for i in range(0,3): dial = dials[i] spin = spins[i] propName = "%s.warp.k%d" % (prop,i+1) dial.valueChanged.connect(self.dialChanged(i, last, spins, propName)) spin.valueChanged.connect(self.spinChanged(i, spins, propName)) last[i] = dial.value() def __init__(self): rv.rvtypes.MinorMode.__init__(self) self.init("pyside_example", None, None) self.loader = QUiLoader() uifile = QFile(os.path.join(self.supportPath(pyside_example, "pyside_example"), "control.ui")) uifile.open(QFile.ReadOnly) self.dialog = self.loader.load(uifile) uifile.close() self.enableCheckBox = self.dialog.findChild(QCheckBox, "enableCheckBox") # # To retrieve the current RV session window and # use it as a Qt QMainWindow, we do the following: self.rvSessionQObject = rv.qtutils.sessionWindow() # have to hold refs here so they don't get deleted self.radialDistortDials = self.findSet(QDial, ["k1Dial", "k2Dial", "k3Dial"]) self.radialDistortSpins = self.findSet(QDoubleSpinBox, ["k1SpinBox", "k2SpinBox", "k3SpinBox"]) self.lastRadialDistort = [0,0,0] self.hookup(self.enableCheckBox, self.radialDistortSpins, self.radialDistortDials, "#RVLensWarp", self.lastRadialDistort) def activate(self): rv.rvtypes.MinorMode.activate(self) self.dialog.show() def deactivate(self): rv.rvtypes.MinorMode.deactivate(self) self.dialog.hide() def createMode(): "Required to initialize the module. RV will call this function to create your mode." return PySideDockTest()
  J Supported Multichannel Audio Layouts
  Multichannel audio devices are supported by RV audio output module choices “Platform Audio” and “PortAudio”. The “Platform Audio” choice is available on all RV platforms ie. OSX, Linux and Windows, while the “PortAudio” choice is available on Linux and Windows.
  On OSX, you might need to enable the multichannel (e.g. 5.1) capability of your audio device using the OSX utility “Audio Midi Setup”.
  Note that RV will mix down, mix up or reorder channels for any given media to match the intended output device channel layout format.
  For example, playing back 5.1 media to a stereo audio device will see the 5.1 audio channels mixed downed to two channels.
  Similarly, playing back stereo media to a 5.1 device will see the media's stereo FL and FR content mixed up to the 5.1 device's FL, FR and FC only.
  For the case where the media and device have the same channel count and speaker types but different layout e.g. for 5.1 media and 5.1 (AC3) device, the media's channel layout is reordered to match the device channel layout when RV reads the media.
  For the case where the media and device have the same channel count but non-matching channel/speaker types, the channel layout of media is passed to the device as is; for example 5.1 (Back) media and 5.1 device.
  K Tuning Platform Audio for Linux
  On Linux, RV's Platform Audio module is based on Qt's QAudioOutput, which is implemented against ALSA's api. As such, we have added several environment variables that allow us to better debug audio issues and which also allows users to tune the audio data IO performance between RV and their chosen playback audio hardware device. Note these environment variables are only supported on linux.
  # setenv TWK_QTAUDIOOUTPUT_ENABLE_DEBUG 1 # setenv RV_NO_CONSOLE_REDIRECT= 5760 , period_frames= 960 # in sample count DEBUG: used: buffer_size= 23040 , period_size= 3840 # in bytes DEBUG: used: buffer_time= 120000 , period_time= 20000 # in microsecs DEBUG: used: chunks= 6 # no of periods per buffer DEBUG: used: max write periods/chunks=0 # 0 implies max possile. DEBUG: used: bytesAvailable= 23040 # amount of free space in the audio buffer on device open().
  The environment variables TWK_QTAUDIOOUTPUT_BUFFER_TIME and TWK_QTAUDIOOUTPUT_PERIOD_TIME can be used to set the buffer size and period size of the audio device. The audio buffer size is always an integral number of period sizes, in other words chose values such that TWK_QTAUDIOOUTPUT_BUFFER_TIME = N * TWK_QTAUDIOOUTPUT_PERIOD_TIME; where N is an integer. Experimentally we have found N = 6 produced a measured audio - video sync < 10ms; while increasing or decreasing N from this value seemed to produce larger and increasingly worst av sync lag numbers.
  It is worth remembering that TWK_QTAUDIOOUTPUT_BUFFER_TIME determines overall size of the audio buffer. The audio device will not start playing until the buffer is completely filled first. This means the buffer size can influence the lag at the beginning when play first starts.
  So for a given TWK_QTAUDIOOUTPUT_BUFFER_TIME, TWK_QTAUDIOOUTPUT_PERIOD_TIME determines the number of period buffers within the overall buffer size and this influences the average av sync value and if too small <=3 leads to buffer underun errors and crackles in audio.
  # setenv TWK_QTAUDIOOUTPUT_ENABLE_DEBUG 1 # setenv RV_NO_CONSOLE_REDIRECT 1 # setenv TWK_QTAUDIOOUTPUT_BUFFER_TIME 60000 # setenv TWK_QTAUDIOOUTPUT_PERIOD_TIME 200= 2880 , period_frames= 960 # in sample count DEBUG: used: buffer_size= 11520 , period_size= 3840 # in bytes DEBUG: used: buffer_time= 60000 , period_time= 20000 # in microsecs DEBUG: used: chunks= 3 # no of periods per buffer DEBUG: used: max write periods/chunks=0 # 0 implies max possile. DEBUG: used: bytesAvailable= 11520 # amount of free space in the audio buffer on device open(). DEBUG: *** Buffer underrun: -32 DEBUG: *** Buffer underrun: -32 DEBUG: *** Buffer underrun: -32 DEBUG: *** Buffer underrun: -32 DEBUG: *** Buffer underrun: -32
  - Launch RV and setup the File->Preferences->Audio tab settings as follows:
  - Determine the smallest TWK_QTAUDIOOUTPUT_BUFFER_TIME and TWK_QTAUDIOOUTPUT_PERIOD_TIME settings before buffer underruns occur.
  - Set Platform Audio debugging messaging on... TWK_QTAUDIOOUTPUT_ENABLE_DEBUG = 1.
  - Set values for TWK_QTAUDIOOUTPUT_BUFFER_TIME and TWK_QTAUDIOOUTPUT_PERIOD_TIME.
  - Try the following combinations of TWK_QTAUDIOOUTPUT_BUFFER_TIME / TWK_QTAUDIOOUTPUT_PERIOD_TIME i.e. 60000 / 10000 and 36000 / 6000.
  - Launch RV with a 48Khz video clip and enable lookahead/region caching. Either cache option would do as long as you size the video cache appropriately so the entire clip is cached. Playback and observe for buffer underruns messages. Note you should also stress test running multiple RVs with the same config.
  - If no underun errors occur; repeat the previous step, setting smaller values for TWK_QTAUDIOOUTPUT_BUFFER_TIME and TWK_QTAUDIOOUTPUT_PERIOD_TIME keeping in mind that the ratio of TWK_QTAUDIOOUTPUT_BUFFER_TIME/TWK_QTAUDIOOUTPUT_PERIOD_TIME must be greater than 3 and ideally around 6.
  - Once you have found the smallest value of TWK_QTAUDIOOUTPUT_BUFFER_TIME; use an av sync meter to measure the average av sync lag playing back RV's movieproc syncflash clip.
  - With TWK_QTAUDIOOUTPUT_BUFFER_TIME fixed to the value determined in the previous step; increase and decrease TWK_QTAUDIOOUTPUT_PERIOD_TIME, bearing in mind TWK_QTAUDIOOUTPUT_BUFFER_TIME must be a integer multiple of TWK_QTAUDIOOUTPUT_PERIOD_TIME. Find the multiple with the lowest measure average av sync values (i.e. the average of at least 25 av sync measurements).
  The table below provides the smallest values of TWK_QTAUDIOOUTPUT_BUFFER_TIME and TWK_QTAUDIOOUTPUT_PERIOD_TIME that prevents buffer underruns (i.e. audio corruption/static issues), minimizes the lag at play-start and average av sync. Note the default value for buffer time is 120000 and period time is 20000.