mrViewer

Version 1.5

Instruction Manual

Table of Contents

Conventions Used in the Manual

To simplify the explanations in this manual, some simple conventions are used.

Clicking on any of the mouse buttons is referred with the nomenclature LMB, MMB and RMB for Left Mouse Button, Middle Mouse Button and Right Mouse Button.

Hotkeys and shortcuts are referred in bold, like:  CTRL + H.

Menus are often referred as Window->Preferences, which means go to the option Preferences in the Window menu.

Sections like the following:

> mrViewer --help

Represent commands you run in the windows console or the Unix shell.

Installing mrViewer

Installation of mrViewer is done simply by clicking on the icon for its installer or by executing the file in a console or shell window.
The installer is multiplatform, and will install all versions of mrViewer under a common root directory.
Installation of mrViewer often requires you to have root or System Administrator permissions.  If you run the installer as a normal user, you might only be able to install mrViewer to some non-standard installation directory, like your home directory.
The installer can also be run in silent mode for remote installs in case you want to install mrViewer locally on each machine on your network.

Starting mrViewer

mrViewer can be started in a variety of ways.  

By default, when installing mrViewer, you will also be given the choice to create an icon on your desktop.  If you have done that, you can often just click on the mrViewer icon on the desktop.

If you have no icon on your desktop, the simplest way is to go the place where mrViewer was installed, look for the directory for the appropiate platform and architecture for your machine and click on the mrViewer or mrViewer.exe application icon.

mrViewer can also be started from any command-line or shell window, as mrViewer may have already added its path to your standard system PATH variable.  Open any shell window and then you can type in:
> mrViewer [-options] [<images...>]
where -options are optional mrViewer command-line options and images are optionally a list of images or sequences you want to display.  For a list of valid options, use:
> mrViewer -h

On certain platforms, like Windows, mrViewer can also associate itself to several image and video files it knows about. In that case, opening a Windows Explorer window and double-clicking on a file that mrViewer recognizes may automatically invoke a new copy of mrViewer.

The Interface

mainWindow

The main interface of mrViewer is divided into 4 main sections:

The main toolbar

mainToolbar

The main toolbar allows you to perform several common operations common to the display of the image and bring up other image windows.  It consists, from left to right, of:
The W icon stands for Windows and clicking on it will list all possible windows that can be created.   Currently, these include:
The Channel display tells you what channel you are currently viewing (Color in the above picture).
The Gain control allows you to change the display gain of the image being displayed.
The F-Stop control is another way to control gain. It works in F-Stops, which is a common method used in photography and film to adjust a camera exposure.
The Normalization button allows you to normalize the image within the 0 and 1 range.  Its most common use is for properly viewing Z-Depth channels or shadow maps.
The Gamma control allows you to modify the display gamma.
The Field control allows you to display the image as a full frame or as video fields.
The 1:1 button allows you to toggle on and off a compensation for an image's pixel ratio.
The LUT button allows you to toggle the 3D LUT color correction for emulation of other media on your monitor.

The main toolbar can be toggled on and off by using the F1 hotkey.

The Image Area

The Image Area is your main viewport.  It usually displays one image at a time, albeit in the future it will be possible to display several images together.

Within your viewport, your mouse pointer will change to a cross to more clearly indicate what pixel you are pointing at.

You can manipulate the viewport using your mouse and hotkeys in a similar way to how maya and 3dmax work.  Using your mousewheel you are able to zoom in and out from the pixel your cursor is pointing at.

Using the MMB or ALT+LMB, you can scroll around the image canvas.

Using the LMB you can select an area.  The main purpose of selecting an area currently is to get the color information of the whole area.

The Pixel Toolbar

pixel bar

The pixel bar contains useful information about the current pixel that the mouse is located on, together with the zoom factor currently used to display the image.
The x1 box displays the current Zoom Factor.
Next to it are the X and Y coordinates of the current cursor location.
Afterwards comes the current pixel color value as an RGBA float.
Then comes the current pixel value in HSV (Hue, Saturation, Value).
Finally, the current pixel's Luminance is also shown.

The pixel toolbar can be toggled on and off by using the F2 hotkey.

The Timeline

timelineBar

The timeline allows you to control what frame in a sequence or movie is displayed.
It can be toggled on and off by using the F3 hotkey.

The slider allows you to easily jump around the video sequence being displayed.  When in EDL mode (see EDL), the timeline will also display each movie sequence as a video segment.  The current video segment will be highlited.

Timecode / Frame Display

The Fbutton button refers to the current frame being displayed.  Clicking on it will toggle between displaying the timeline and frame information as either frames or timecode.

Playback Controls

playbackControls.gif

The playback controls function very similarly to those in your VCR or Stereo.  They allow you to, from left to right: go to the beginning of the movie, play the movie backwards, go back a single frame, pause the playback, go forwards one frame, play the movie forwards and go to the end of the movie.
Unlike your VCR, there is no fast-forward or rewinding controls.  That functionality can be obtained by changing the frame rate and then playing the movie.
If you play a sequence of images, playback will not be smooth at first.  mrViewer will first try to cache all the images in memory before playback.  If you run out of memory or you start swapping, you might not be able to play back the sequence smoothly.
Smooth reverse playback of movie files is largely dependant on the codec used in the movie file.

Playback Speed (FPS)

FPScontrol.gif

The FPS (Frames per Second) control allows you to adjust the speed of playback.   This allows you to play the sequence in slow motion or at several times its normal speed.

Audio Control (Volume)

audioControl.gif

The audio control can be used to switch between different audio tracks by clicking on the A button.  In addition, the audio volume can be controlled with the slider next to it.  Note that, depending on your platform, changing the volume may effect all other applications that use sound.

Timeline Display

Finally, the S and E inputs allow you to change the start and end of the timeline.  This has no effect on changing the actual length of the movie or image sequence, and is only provided for playback looping and display purposes.

Image Information Window


You can bring up the Image Information window by doing any of:



















The Image Information window displays detailed information about the image, movie or sequence being displayed in the foreground.  The available information is:

Directory refers to the directory where the file resides.
Filename refers to the filename(s) the movie, image or sequence refers to.
Sequence true if the filename refers to a whole sequence of images, false if it refers to a single image or movie.
Width the actual width of the image, sequence or movie.
Height the actual height of the image, sequence of movie.
Aspect Ratio the actual aspect ratio of the image (ie. resolution width / resolution height ).
Pixel Ratio the shape of the pixels in the image.  A pixel ratio of 1 refers to square pixels (like those of a printer or monitor).  A different value refers to pixels for other media (usually, NTSC or PAL video).
Depth the color depth of each channel (8-bit, 16-bit, or 32-bit for float images).
Image Channels Number of image channels in the image.
Rendering Intent The embedded rendering intent for this image.
Gamma the built-in gamma of the image.
Render Transform
Any embedded CTL (Color Transformation Language) rendering transform.
ICC Profile Any embedded ICC (International Color Consortium) profile in the image.
Format the format of the image.
Line Order The line order of the image (if applicable)
Memory The amount of memory the image uses.
Disk space The amount of disk space the image uses (only applicable if the image is on the filesystem)
Compression Compression type used to save the image.  Some formats allow changing the compression type before saving.
Compression Ratio The percentage of compression (ie. the difference between the space the image uses on memory and the space it uses on disk)
Creation Date the date the image was created or last modified.
IPTC IPTC (International code) attributes if applicable.
EXIF EXIF attributes (if applicable)
Video when a video file is displayed, it shows codec, number of video streams and frames per second.
Audio when an audio file is attached, it shows codec, number of audio streams, number audio channels and audio frequency.
 
Some of these attributes may be interactively modified, either to change the display behavior of the image or to modify how an image is saved.

Reel List Window

reelList.pngYou can bring up the Image Information window by doing any of:














The Reel List Window allows you to see all reels loaded as well as all images loaded in the currently active reel.
It also allows you to perform some additional operations on the images loaded.

A reel is basically a list of images stored under a particular name.  This list of images can be reordered simply by doing drag and drop of the image.  You can also quickly switch from one image or movie to another by clicking on any item on the list.

mrViewer allows you to also load reels (.reel files) from the command line or by doing drag and drop.  When loading a reel, all the images listed in the reel will be loaded.

The reel window also allows you to open a new image or movie, save the current image or frame, make a clone of the current image (useful for 3d renders) or remove the image from the reel.
You can also attach a new CTL transform (3D Lut) to an image, make an image always appear as part of the background or play back the whole reel as an EDL.

Compositing Images

mrViewer supports some basic, non destructive A over B compositing.  This compositing is for display purposes only and it is not intended for saving composited images.

Within the Reel List Window, it is possible to select an image and then click on the BG button to make that image be a background image.  Afterwards, you can then switch to a new image and the background image will be displayed in the background.  The background image is always stretched to fit the size of the foreground image.

The main purpose of this feature is to allow you to interactively see your 3d renders over a background plate.  This works particularly well when reading a foreground image that is a file that changes on disk or when reading a virtual image, such as a mental ray render stub.

Playing Movies as an EDL Reel

One feature of mrViewer is that it allows you to display multiple sequences or movies together.  If you load several files into a reel, you can then toggle EDL mode on and off from the Reel List Window.
The EDL mode allows you to show all movies in a reel one after the other, as if all of them had been edited together into a big movie file.

The Color Area Window


You can bring up the Color Area Window by doing any of:









In addition to the pixel information that is provided in the Pixel Toolbar, mrViewer also supports a Color Area Window that displays color information about the currently selected area.
For the window to display any information, you need to have an image or movie loaded and select an area of it with the LMB.
The Color Area window displays the coordinates of the rectangle area selected, its width and height in pixels as well as its total size in pixels.
The information displayed are the minimum and maximum values of the Red, Green, Blue and Alpha channels for the currently selected layer and area.  The range represents the absolute difference between the maximum and minimum values.  Finally, the mean represents the mean average of the pixels in the area for that particular channel.
Similar information is displayed for the Hue, Saturation, Value and Luminance.

The Histogram Window

You can bring up the Color Area Window by doing any of:










The Histogram Window allows you to see different types of histograms for the current image or movie file.
A Histogram represents a chart mapping the occurrance of each color in the image, going from black or darker colors on the left side, to white or brighter colors on the right side.
Histograms are often used as a debugging aid to interpret color information in an image and can easily pinpoint problems in contrast in an image.
In the example image above, you can see for example that in the blue channel, black or close to black appears often in the image, which may or may not be what you want (depending on the image).
A histogram can be shown using a linear, logarithmic or square root counter.  
A linear display shows a proportianal line for each color count in an image.  On images where some color like black appears too often, it may result in a big spike while all other colors remain flat.   A logarithmic or square root histogram takes that same count and applies a log or square root operation which makes the chart a little bit flatter and often nicer to interpret.
The default histogram type is a logarithmic histogram.

The Vectorscope Window

You can bring up the Color Area Window by doing any of:










A Vectorscope is a tool used mainly in video productions as a debugging aid.  It basically shows you color information.
The display represents color in a circle or pie and each square (R,M,B,C,G,Y) represents a pure primary or secondary color according to the NTSC or PAL standards.  No red, magenta, blue, cyan, green or yellow color is expected to be brighter/more saturated than the squares (ie. go beyond them).
Each color of the color bars, for example, is expected to land perfectly within each of the squares.
However, when dealing with computer graphics or bad video, it is perfectly possible for a signal to create colors that are too bright or saturated for the TV standards.   If a color is too bright or saturated, it might lead to problems in the broadcasting of the transmission and may force the tv channel to have to desaturate all your image.

Asset Tracking

One unique feature of mrViewer is its built-in asset tracking system.  With it, every image or movie file that any person in your facility views will be recorded into a generic database and it will be sorted by show, sequence and shot.
This database can also be accessed through your browser, as a Ruby on Rails project for it is also provided.

Color Management

mrViewer supports probably the most advanced color management system in use today, called CTL (Color Transform Language).  CTL was developed by AMPAS, the Academy of Motion Picture Arts and Sciences, with the help of Industrial Light and Magic (ILM).
As the name implies, CTL is an actual language, similar to a shading language, which can be used for color transformation of images.  Its feature set is similar to that of ICC, albeit it goes beyond it, to also support particular features specific to the movie production business.  Being a full featured language, the possibilities for color correction are unlimited and since CTL scripts are just ASCII files, it becomes harder to misinterpret.
Within mrViewer, two or more CTL files are processed and baked into a 64x64x64 3D Lut which then operates on the image completely with 32-bit float information.   This will often give you a pretty accurate approximation of even the most complex transformations.

In addition to CTL, mrViewer also supports ICC, which is still pretty common with the print industry as well as some monitor manufacturers.  In the future, it is likely that ICC support will be vanished and that an internal ICC to CTL converter will be provided instead.

Environment Variables

On startup and during different operations, mrViewer reads several environment variables that allow you to customize its operation.  Here's a list of them:

Variable Explanation Default Value
CTL_MODULE_PATH A string of colon (Unix) or semicolon (Windows) separated paths that mrViewer will use to find .ctl scripts. If unset, mrViewer's ctl directory
CTL_DISPLAY_TRANSFORM The CTL script used to transform images from CIExy space for display on your screen transform_display_video
CTL_IMAGE_DEFAULT_TRANSFORM A default CTL script used to transform images from RGB to CIExy space transform_RRT
CTL_DISPLAY_CHROMATICITIES Chromaticities of your display Rec. ITU-R BT.709 chromaticities
CTL_DISPLAY_WHITE_LUMINANCE White Luminance of your display 120 candelas per square meter
CTL_DISPLAY_SURROUND_LUMINANCE Luminance of the surrounding environment 12 candelas per square meter
MRV_HOST Machine where mrViewer's database resides localhost
MRV_PORT TCP/IP Port override to use to connect to database Uses default for database type
MRV_USER User used to login to mrViewer's database mrviewer
MRV_PASSWORD Password used to login to mrViewer's database mrviewer
MRV_DATABASE Name of mrViewer's database assets2d_production
SHOW If set, any image viewed will be stored in the database as belonging to that show. Undefined
SEQ If set, any image viewed will be stored in the database as belonging to that sequence. Undefined
SHOT If set, any image viewed will be stored in the database as belonging to that shot. Undefined
ICC_PROFILES Directory where ICC and ICM profiles reside %WINDIR%/SYSTEM32/spool/drivers/color on Windows and /usr/share/color/icc on Unix
HOME Home directory for user where mrViewer's preferences will be stored $HOME on Unix and %HOMEDIR% on Windows

Hotkeys

Currently, mrViewer does not yet allow you to redefine your hotkeys, albeit this limitation will certainly be lifted in the near future.

The default hotkey configuration is the following:

Display

R Display Red   Channel
G Display Green Channel
B Display Blue  Channel
A Display Alpha Channel
O Display Alpha Overlayed over RGB
L Display Luminance (if available)
Z Display Z Depth (if available)
T Display Tag Channel (if available)
S Toggle Safe Area Display
F1 Toggle Top Toolbar
F2 Toggle Pixel Info Toolbar
F3 Toggle Timeline
Spacebar Toggle full-screen
F12 Toggle Presentation Mode
This mode is mrViewer's full screen, best antialiased mode, suitable for exhibition or projection.

Navigation

1-9     Zoom to # times
Alt + RMB or ALT + LMB + MMB Zoom view window arbitrarily
Alt + MMB Scroll view window
Mousewheel Zoom in/out

Timeline

Home Go to start of sequence
End Go to end of sequence
Ctrl + Home Go to start of timeline
Ctrl + End Go to end of timeline
PgUp Go to previous image
PgDown Go to next image
Left Arrow or NumPad 4 Go back a frame or previous image
Right Arrow or NumPad 6 Go to next frame or next image
Alt + Mousewheel Scrub playback
Ctrl + Left Arrow Go back 1 second
Ctrl + Right Arrow Advance 1 second

Playback

Down Arrow or NumPad 2 Play movie forwards
Up Arrow or NumPad 8 Play movie backwards
Shift + Down Arrow Play movie 1/2 normal speed
Shift + Up   Arrow Play movie backwards 1/2 normal speed
Ctrl  + Down Arrow Play movie x2 normal speed
Ctrl  + Up   Arrow Play movie backwards x2 normal speed
NumPad 5 Stop playback.

File Formats

mrViewer supports a number of image formats for reading and writing.  Here's a brief summary of them:

Extension

 Name

 Read

 Write

 Comments

.avi AVI Yes No All Channels, all codecs
.bmp Microsoft's Bitmap Yes Yes
.cin Cineon Yes No
.ct mental ray floating point color images Yes No
.dds Microsoft Direct Draw Surface Yes No
.dpx DPX Yes No
.exr ILM OpenEXR Yes Yes All Channels and Layers displayed
.gif GIF Yes Yes
.iff Maya IFF Yes No
.jpeg JPEG Yes Yes
.map mental ray textures Yes No Only non-tiled maps supported
.mi mental ray network render file stubs Yes No Floating point connections
.mov Quicktime Movies Yes No
.mpeg Motion Pictures Group Yes No
.nt mental ray floating point normal images Yes No
.ogg OGG Yes No
.pdf Adobe Postscript Yes No Single page, converted to a bitmap
.pic Softimage pic Yes No
.png PNG Yes Yes
.psd Photoshop Yes Yes All Layers displayed, paths and vector graphics lost
.reel mrViewer's reel (EDL) files Yes Yes
.rpf Autodesk 3DS Rich Picture Format Yes No Some layers supported
.shmap mental ray floating point shadow maps Yes No
.st mental ray floating point scalar images Yes No
.tga Targa Yes Yes
.tif TIFF Yes Yes All Layers displayed
.wmv Microsoft WMV Yes No WMV9 supported, but slow
.z Rendeman Shadow Maps Yes No
.zt mental ray floating point z-depth images Yes No

Licenses

OpenEXR libraries are distributed under the following License:

Copyright (c) 2006, Industrial Light & Magic, a division of Lucas Digital Ltd. LLC
All rights reserved.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


ImageMagick libraries are distributed under the following License:


Copyright 1999-2007 ImageMagick Studio LLC, a non-profit organization dedicated to making software imaging solutions freely available.
http://www.imagemagick.org/script/license.php


CTL and OpenEXR_CTL libraries are distributed under the following License:
 
Copyright © 2006 Academy of Motion Picture Arts and Sciences ("A.M.P.A.S."). Portions contributed by others as indicated.
All rights reserved.
 
A world-wide, royalty-free, non-exclusive right to distribute, copy, modify, create derivatives, and use, in source and binary forms, is
hereby granted, subject to acceptance of this license. Performance of any of the aforementioned acts indicates acceptance to be bound by the
following terms and conditions:
This license shall be governed by the laws of the State of California, and subject to the jurisdiction of the courts therein.
 
Disclaimer of Warranty: THIS SOFTWARE IS PROVIDED BY A.M.P.A.S. AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE DISCLAIMED. IN NO EVENT SHALL A.M.P.A.S., ANY CONTRIBUTORS OR DISTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Boost libraries are distributed under the following License:

Boost Software License - Version 1.0 - August 17th, 2003

Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following:

The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

libtiff is distributed under a BSD license.

zlib is distributed under the Zlib license:

Copyright (C) 1995-2004 Jean-loup Gailly and Mark Adler

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.