Movie In TOP

Summary

The Movie In TOP loads movies, still images, or a sequence of still images into TOPs. It will read images in .jpg, .gif, .tif, or .bmp format. It will read movies in QuickTime's .mov format, .mp4, .mpg, .mpeg, .avi, .wmv. It also supports .swf and .flv Flash files as well as DXT1, 3, and 5 compressed .DDS files. Images and movies can also be fetched from the web by using http:// to specify a URL.

For a complete list, see File Types. TouchDesigner uses libavcodec by default. You can switch to Apple QuickTime by enabling it through Edit -> Preferences -> TOPs, though .wmv, .avi and some other formats are not supported.

Examine the state of a Movie In TOP by attaching an Info CHOP to it. This will show static info like movie length, resolution, frames per second, and whether there is audio in the file. It also shows dynamic information like movie open status, current frame, readahead frames and queue size, dropped frame count, CPU decode time and GPU upload time.

See also memory Command, unloadmovie Command.

Parameters - Play Page

File /file - The path and name of the image or movie file to load. Image and movie formats are those found in File Types.

To treat a folder of images as if they are one movie, specify the folder containing the images instead of a filename. It will treat all stills/movies in that folder as if each is a frame in one movie. The order of the movies is the alphanumeric order you find in the operating system file browser. By default the first image has an index of 0, second is 1, etc, regardless of their file names. Overriding the sample rate on the Trim parameter page will let you playback the image sequence at any frame rate.

Using an info.xml file in the directory containing a sequence of images allows you to specify the frames per second and an audio file to be used with the sequence of images. Example xml file:

 <?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>
 <Settings>
     <attributes fps="30.0" />
     <audio filename="audio.wav" />
 </Settings>

URLs can be used to fetch images and movies. The image or movie is downloaded to the user's Derivative temp directory and is read into the Movie In TOP.

Reload /reload - Change from 0 to 1 to force the image to reload, useful when the file changes or did not exist at first.

Play Mode /playmode - Specifies the method used to play the movie, there are 3 options.

• Locked to Timeline /locked - This mode locks the movie position to the timeline. Scrubbing or jumping in the timeline will change the movie position accordingly. The parameters Play, Reset, Speed, and Index are disabled in this mode since the timeline is directly tied to movie position.
• Specify Index /specify - This mode allows the user to specify a particular position in the movie using the Index parameter below. Use this mode for random access to any location in the movie.
• Sequential sequential - This mode continually plays regardless of the timeline position (the Index parameter is disabled). Reset and Speed parameters below are enabled to allow some control.

Play /play - Movie plays when 1, movie stops when 0.

Speed /speed - This is a speed multiplier which only works when Play Mode is Sequential. A value of 1 is the default playback speed. A value of 2 is double speed, 0.5 is half speed and so on. Negative values will play the movie backwards.

Cue /cue - jumps to Cue Point when set to 1. Only available when Play Mode is Sequential.

Cue Point /cuepoint - Set any index in the movie as a point to jump to.

Index /index - This parameter explicitly sets the movie position when Play Mode is set to Specify Index. The units menu on the right lets you specify the index in the following units: Index, Frames, Seconds, and Fraction (percentage). For example, assume you have a movie that internally is 25 fps, and the timeline that is 60 fps. If you set Units to Index and the parameter value to 25, you get the image that is 1 second into the movie. If you set the Units to Frames and set the value to 60 you get the same image at 1 second into the movie.

Loop Crossfade /loopcrossfade - Crossfades the beginning and end of the movie together to create a smooth transition when looping. If the movie uses Trim options, it will crossfade Trim Start with Trim End positions.

Step Size /stepsize - Sets how many frames to skip before displaying next frame. For example, a StepSize of 30 will display every 30th frame. This timing of movie playback does not change, so with a Step Size of 30 and a sample rate of 30, a new frame will be displayed every second.

Image Sequence Indexing /imageindexing - When playing a sequence of images the default mode is to index them starting at 0, after they have been sorted alpha-numerically. This is 'Zero Based'. Selecting 'Filename Based' instead will cause the numbers on the end of the filename to define the frame index of that image. The filename format for Filename based indexing must be filename.<indexnumber>.<extension>. So filesnames such as image.1.tiff, hello.004.tiff are legal, but hello0001.tiff is not.

Parameters - Image Page

Interpolate Frames /interpolation - Interpolates between frames based based on exact time. For example, if the index (in frames) is 1.5, then frames 1 and 2 will be blended 50-50. If the index is 1.7 then 30% of frame 1 is blended with 70% of frame 2 and so on.

Deinterlace /deinterlace - For movies that are stored as fields, where each image is made of two images interleaved together. A 30-frame per second movie would contain 60 fields per second. For each image, the even scanlines of the first field are interleaved with the odd scanlines of the second field. The Movie In TOP has several ways of dealing with this:

• Off /off - Output the movie images unchanged.

• Even /even - Take only the even scanlines of the file's images and create the odd scanlines by interpolating between the even scanlines. (For historic reasons, scanline 0 is at the top of the images for the purpose of the deinterlacing.)

• Odd /odd - Take only the odd scanlines of the file's images and create the even scanlines by interpolating between the odd scanlines.

• Bob (Split) /bob - This produces 60 images per second for a 30 frame-per-second movie file. It first outputs the even image (as in Even above) followed by the Odd image. This has the best time-smoothness.

Field Precedence /precedence - Where fields are extracted one field at a time, this will extract the Even field first by default, otehrwise it will extract the odd field first. The video industry has not standardized on one or the other.

Bottom Half of Image is Alpha (AAA) /bottomhalfalpha - This is a way of encoding alpha into RGB-only formats like H.264. and several other QuickTime formats. You need to create your movies so that the bottom half of the image is the alpha (RGB = AAA). Turning on this features tells the Movie In TOP to take the bottom half of the image and put it into the alpha channel of the output. The image height will be cut in half.

Multiply RGB by Alpha /multalpha - Premultiplies the image.

Parameters - Trim Page

Trim /trim - Enables the Trim parameters below.

Trim Start /tstart - Sets an In point from the beginning of the movie, allowing you to trim the starting position of the movie. The units menu on the right let you specify this position by index, frames, seconds, or fraction (percentage).

Trim End /tend - Sets an Out point from the end of the movie, allowing you to trim the ending position of the movie. The units menu on the right let you specify this position by index, frames, seconds, or fraction (percentage).

Extend Left /textendleft - Determines how the MovieIn TOP handles movie positions that lie before the Trim Start position. For example, if Trim Start is set to 1, and the movie's current index is -10, the Extend Left menu determines how the movie position is calculated.

• Hold - Displays the first frame in the movie range (the frame specified by Trim Start) for any position before Trim Start.
• Cycle - Loops the movie range continuously.
• Mirror - Loops the movie range in a zig-zag pattern. For example, playing backwards from Trim Start the movie will index will climb towards Trim End, at which point is will decend down towards Trim Start again and continue to zig-zag (or mirror) the further the movie plays backwards.
• Black - Displays black frame for any movie position before Trim Start.

Extend Right /textendright - Determines how the MovieIn TOP handles movie positions that lie after the Trim End position. For example, if Trim End is set to 20, and the movie's current index is 25, the Extend Right menu determines how the movie position is calculated.

• Hold - Displays the last frame in the movie range (the frame specified by Trim End) for any position after Trim End.
• Cycle - Loops the movie range continuously.
• Mirror - Loops the movie range in a zig-zag pattern. For example, playing forwards from Trim End the movie will index will start decending towards Trim Start, at which point is will start climbing towards Trim End and continue to zig-zag (or mirror) the further the movie plays.
• Black - Displays black frame for any movie position after Trim End.

Override Sample Rate /overridesample - Enables the Override Sample Rate parameter below.

Sample Rate /samplerate - Allows you to change the playback frame rate of the movie. Think of this as overriding the frame rate, helpful when using the Sequential Play Mode.

Parameters - Tune Page

Read Ahead Size /readaheadsize - Sets how many video frames Touch reads ahead and stores in memory. Using this, smooth reading of an image stream is possible even when the disk files are fragmented. Touch will read frames of the movie into memory before they are used. By reading ahead into the movie and storing the frames away, Touch can eliminate pops or stutters in playback that occur from fragmented files, other resources accessing the hard drive, or movie looping.

Frame Read Timeout /frametimeout - The time (in milliseconds) TouchDesigner will wait for a frame from the hard drive before giving up. If the Disk Read Timeout time is reached, that frame is simply skipped. This also works for network files that are downloaded via http://.

Always Load Initial Frame /alwaysloadinitial - If this parameter is turned on, then for the first loaded frame the Frame Read Timeout will be ignored, and it will always wait for the first frame to ensure the node always starts up with a valid image.

File Open Timeout /opentimeout - The time (in milliseconds) TouchDesigner will wait for a movie to open. If the Disk Open Timout is reached, the Movie In TOP will stop waiting and make its image all black, with a grey square in the bottom right corner. If the file still isn't opened the next time the TOP cooks, it'll wait again, and do the same. It'll keep doing this until the file is opened, or the open fails.

On Timeout, use Latest Avail /uselatestontimeout - When on, if the Disk Read Timeout is reached Touch will use the latest available frame in place of the skipped frame.

Use Global CPU Cache /usecpucache - Uses CPU cache to store image into main memory. The size of the Global CPU Cache is set under Edit > Preferences > TOPs.

Async Upload to GPU /asyncupload - When enabled, this will use OpenGL features to upload movie images to the GPU asynchronously. This will reduce the cook time of the Movie In TOP considerably (in the performance monitor the lines that say "Uploading Image to GPU" will go down to almost nothing). There is a GPU memory cost to using this feature however. It uses up another (Width * Height * 4 * Read Ahead Size) bytes of GPU memory. If you are having poor results with this feature, make sure your graphics drivers are up to date.

Update Image /updateimage - Image will not update when set to 0. Movie index will continue to move forward but the output image will not update. This is useful when you are using a Movie Audio CHOP to get audio from the movie, but you don't care about the video.

Interpolate Frames /interpolation - Interpolates between frames based based on exact time. For example, if the index (in frames) is 1.5, then frames 1 and 2 will be blended 50-50. If the index is 1.7 then 30% of frame 1 is blended with 70% of frame 2 and so on.

Reload /reload - Reloads the file when set to 1.

Parameters - Common Page

Resolution - quickly change the resolution of the TOP's data.

• Input - uses the input's resolution.
• Eighth, Quarter, Half, 2X, 4X, 8X - multiply the input's resolution by that amount.
• Custom Resolution - enables the Custom Res parameter below, giving direct control over res in the X and Y axis.

Custom Res - enabled only when the Resolution parameter is set to Custom Resolution. Some Generators like Constant and Ramp do not use inputs and only use this field to determine their size. The drop down menu on the right provides some commonly used resolutions.

Use Global Resolution Multiplier - Uses the Global Resolution Multiplier found in Edit>Preferences>TOPs. This multiplies all the TOPs resolutions by the set amount. This is handy when working on computers with different hardware specifications. If a project is designed on a desktop workstation with lots of graphics memory, a user on a laptop with only 64MB VRAM can set the Global Resolution Multiplier to a value of half or quarter so it runs at an acceptable speed. By checking this checkbox on, this TOP is affected by the global multiplier.

Aspect Ratio - sets the image aspect ratio allowing any textures to be viewed in any size. Watch for unexpected results when compositing TOPs with different aspect ratios.

• Input - uses the input's aspect ratio.
• Resolution - uses the aspect of the image's defined resolution (ie 512x256 would be 2:1), whereby each pixel is square.
• Custom Aspect Ratio - lets you explicitly define a custom aspect ratio.

Fill Viewer - determine how the TOP image is displayed in the viewer.

• Input - uses the same Fill Viewer settings as it's input.
• Fill - stretches the image to fit the edges of the viewer.
• Fit Horizontal - stretches image to fit viewer horizontally.
• Fit Vertical - stretches image to fit viewer vertically.
• Fit Best - stretches or squashes image so no part of image is cropped.
• Fit Worst - stretches or squashes image so image fills viewer while constraining it's proportions. This often leads to part of image getting cropped by viewer.
• Native Resolution - displays the native resolution of the image in the viewer.

NOTE: To get an understanding of how TOPs works with images, you will want to set this to Native Resolution as you lay down TOPs when starting out. This will let you see what is actually happening without any automatic viewer resizing.

Viewer Smoothness - This controls pixel filtering in the viewers.

• Nearest Pixel - uses nearest pixel or accurate image representation. Images will look jaggy when viewing at any zoom level other than Native Resolution.
• Interpolate Pixels - uses linear filtering between pixels. This is how you get TOP images in viewers to look good at various zoom levels, especially useful when using any Fill Viewer setting other than Native Resolution.
• Mipmap Pixels - uses mipmapfiltering when scaling images. This can be used to reduce artifacts and sparkling in moving/scaling images that have lots of detail. When the input is 32-bit float format nearest filtering will always be used, regardless of what is selected in the menu.

Pixel Format - format used to store data for each channel in the image (ie. R, G, B, and A). Refer to Pixel Formats for more information.

• Input - uses the input's pixel format.
• 8-bit fixed (RGBA) - uses 8-bit integer values for each channel.
• 16-bit float (RGBA) - uses 16-bits per color channel, 64-bits per pixel.
• 32-bit float (RGBA) - uses 32-bits per color channel, 128-bits per pixels.

• 10-bit RGB, 2-bit Alpha, fixed (RGBA) - uses 10-bits per color channel and 2-bits for alpha, 32-bits total per pixel.
• 16-bit fixed (RGBA) - uses 16-bits per color channel, 64-bits total per pixel.
• 11-bit float (RGB), Positive Values Only - A RGB floating point format that has 11 bits for the Red and Green channels, and 10-bits for the Blue Channel, 32-bits total per pixel (therefore the same memory usage as 8-bit RGBA). The Alpha channel in this format will always be 1. Values can go above one, but can't be negative. ie. the range is [0, infinite).
• 8-bit fixed (R) - has 8-bits for the red channel, 8-bits total per pixel.
• 16-bit fixed (R) - has 16-bits for the red channel, 16-bits total per pixel.
• 16-bit float (R) - has 16-bits for the red channel, 16-bits per pixel.
• 32-bit float (R) - has 32-bits for the red channel, 32-bits per pixel.
• 8-bit fixed (RG) - has 8-bits for the red and green channels, 16-bits total per pixel.
• 16-bit fixed (RG) - has 16-bits for the red and green channels, 32-bits total per pixel.
• 16-bit float (RG) - has 16-bits for the red and green channels, 32-bits per pixel.
• 32-bit float (RG) - has 32-bits for the red and green channels, 64-bits per pixel.
• 8-bit fixed (A) - An Alpha only format that has 8-bits per channel, 8-bits per pixel.
• 16-bit float (A) - An Alpha only format that has 16-bits per channel, 16-bits per pixel.
• 32-bit float (A) - An Alpha only format that has 32-bits per channel, 32-bits per pixel.

Feature Technology Notes

Read-Ahead

Through Touch's Read-Ahead setting, smooth reading of an image stream is possible, even when the disk files are fragmented. Touch will read frames of the movie into memory before they are used. By reading ahead into the movie and storing the frames away, Touch can eliminate pops or stutters in playback that occur from fragmented files, other resources accessing the hard drive, or movie looping.

Working with TOPs

Using the Global Resolution Multiplier

The Global Resolution Multiplier is found under Edit>Preferences>TOPs. This multiplier is applied to the resolution of all TOPs in the project. This lets you tailor the TOPs resolution based on the computer or footage you are using. This can be very useful for running on slower computers, as setting this value to 0.5 will reduce the resolution of the TOPs images to half. Inversely, if you have a fast workstation which can handle higher resolutions, a setting above 1.0 will multiply the resolution to a larger value, letting you process movies at higher res. Default value is 1.0.