Pantarheon

Where everything flows. In 3D.

Pantarheon 3D AviSynth Toolbox

Current version: 1.1

The Pantarheon 3D AviSynth Toolbox is a set of scripted functions for AviSynth. I wrote the Toolbox to complement the Bororo 3D plug-in because some things are simply difficult to do with the current version of Sony Vegas. And because not everyone has Sony Vegas (AviSynth is free, Vegas is not).

To use the Toolbox, first, if you have not done so yet, download and install Avisynth, then download the Windows Installer file for the Pantarheon 3D Avisynth Toolbox and install it, or download the .zip version of the Toolbox, unzip it, and copy the file Pantarheon3D.avsi to the Avisynth plugins directory (which will be something along the lines of C:\Program Files\AviSynth 2.5\plugins, then read the rest of this page to learn how to use the Toolbox.

Basic Functions

The Toolbox contains a number of basic functions which allow you to multiplex the left and right views found in two separate videos into one video, using several of the common methods currently in use. All of these functions take two parameters, the first one with the left view, the second with the right view, like this:

lv = AviSource("left.avi")
rv = AviSource("right.avi")

LeftRight3D(lv, rv)

You can also name the two arguments left and right, and then you can list them in any order:

LeftRight3D(right = rv, left = lv)

To illustrate the basic functions visually, we will not use actual left and right stereoscopic footage. For the left view we will use this:

Left View

And for the right view, we will use this:

Right View

This will allow you to see exactly what the various functions do without having to analyze the image to see which view is left, and which is right.

Additionally, to save on bandwidth we will, in most cases, reduce the size of the above images to one quarter, so the results will be smaller than the originals.

The most important basic functions are:

LeftRight3D(left, right)
CrossEyed3D(left, right)
TopDown3D(left, right)
DownTop3D(left, right)
HDMI3D(left, top)

I said they were the most important ones because they have a very important property: They do not change the quality of the video. This is because all they do is arrange the two videos into one, and do so without changing their resolution. Here is what each of them does:

LeftRight3D will create a video whose width is double that of either the left or the right video (they both must be of the same size and pixel type, this is true of all Toolbox functions that take two arguments), and will place the left view in the left half of the new video, and the right view into its right half. So, for example, if your left.avi and right.avi are 1920x1080 pixels, the result will be 3840x1080 pixels. This is the best format to store all of your 3D videos in for archiving purposes, and then convert that to whatever format you need to publish your videos in.

LeftRight3D

CrossEyed3D does the same, but places the left view in the right half and the right view in the left half of the new video.

CrossEyed3D

TopDown3D will create a video whose height is double that of the two original videos and will place the left view in the top half and the right view in the bottom half of the new video. So, if your originals are 1920x1080 pixels, the new video will have 1920x2160 pixels.

TopDown3D

DownTop3D does the same but will store the left view in the bottom and the right view in the top half of the video.

DownTop3D

By the way, these two formats are great for comparing how the different objects within your videos are shifted to the left and to the right in the two different views, a useful tool for learning 3D.

HDMI3D will produce a video in the HDMI v.1.4a format. It will create a new video whose height is twice the originals, plus 45. It will place the left view at the top and the right view at the bottom of the video, and leave 45 empty lines between the two.

There is a catch: It is impossible to create the HDMI v.1.4a 3D in the YUV format. Why? Because the YUV format compresses two lines at the same time. But the HDMI format always produces a video with an odd number of lines (2 * height + 45 = an odd number). That means that HDMI did not create the standard for storage in files but for video players and games to produce the image from some other format, or even on the fly. This is particularly clear when you consider that MPEG files use the YUV format. So, do not blame me, blame HDMI.

Anyway, you can always use AviSynth to convert your MPEG files into another format, such as YUY2, for example:

lv = DirectShowSource("left.mpg")
rv = DirectShowSource("right.mpg")

lv = lv.ConvertToYUY2
rv = rv.ConvertToYUY2

HDMI3D(lv, rv)

You can even combine it all into one line:

HDMI3D(DirectShowSource("left.mpg").ConvertToYUY2, DirectShowSource("right.mpg").ConvertToYUY2)

I think, however, that it is obvious the multiline version is easier to write, easier to read, and easier to debug!

If you do not perform this conversion, don’t worry. HDMI3D checks what format the videos are in and will convert them to YUY2 as needed. Just do not be surprised when your videos converted into the HDMI v.1.4a 3D format end up in the YUY2 mode. It’s not a bug, it’s a feature.

HDMI3D

Now, here are the remaining basic functions:

LeftRight3DReduced(left, right)
CrossEyed3DReduced(left, right)
Yt3D(left, right)
TopDown3DReduced(left, right)
DownTop3DReduced(left, right)

The main difference between them and the ones discussed above is they do not change the size of the original videos, so 1920x1080 originals will produce a 1920x1080 video. That means the originals will be squeezed to fit. That also means they lose one half of their resolution and, therefore, are not ideally suited for archiving purposes, only for delivery to those people whose software requires them (e.g., YouTube).

LeftRight3DReduced changes the width of the left and right video to one half, then places the reduced left view to the left half of the output and the right view to the right half of the output. So, if the left and right videos are both 1920x1080, they are reduced to 960x1080 each, placed next to each other, and the result will have 1920x1080 pixels.

LeftRight3DReduced

CrossEyed3DReduced is the same, but the reduced left view goes to the right half and the reduced right view to the left half of each frame of the output video.

Yt3D is exactly the same as CrossEyed3DReduced. It exists as a separate function only because it is the 3D format used by YouTube, and having it as a separate function allows you to produce 3D videos for YouTube without having to remember just which format YouTube uses. It is simply a function of convenience, as are all the other functions with Yt3D in their name listed below.

CrossEyed3DReduced / Yt3D

TopDown3DReduced changes the height of the left and right videos by half, then places the reduced left view to the top half and the reduced right view to the bottom half of the output video. So, if your originals are 1920x1080, they are reduced to 1920x540 each, then combined to a 1920x1080 output.

TopDown3DReduced

DownTop3DReduced is the same, but the reduced left view goes to the bottom and the reduced right half to the top half of the final output.

DownTop3DReduced

Please note there is no HDMI3DReduced function because the HDMI 1.4a 3D specification does not mention any reduced format.

Anaglyph Functions

For decades the main way of presenting 3D movies, videos, photographs, as well as comics and other graphics, was the anaglyph, which uses glasses with a different color lens in front of each eye. While most of us working with 3D would like the anaglyph to die of old age, it is still in use.

Therefore, the Toolbox allows you to create four basic types of anaglyphs, made possible by the MergeRGB function built into AviSynth. Many various algorithms for “better” anaglyphs exist, but they require more than an AviSynth script to create. If you need them, my Bororo 3D plug-in can create just about any anaglyph.

Here are the four anaglyph functions offered by the Toolbox. Like the basic functions, they take two arguments each, a left and a right clip:

Anaglyph(left, right)
RCAnaglyph(left, right)
GMAnaglyph(left, right)
YBAnaglyph(left, right)

Anaglyph produces the “classical” anaglyph, which is strictly monochrome (“black & white”). It can be viewed with red/blue, red/green, or red/cyan glasses, with the red lens going in front of the left eye.

The remaining three anaglyph functions create color anaglyphs (but read the next paragraph!), red/cyan, green/magenta and yellow/blue respectively.

There is a catch: Due to the way the MergeRGB function of AviSynth works, only videos in the RGB format can produce color anaglyphs. The functions still work, mind you, but you will end up with monochrome results. This may be exactly what you want, so the functions do not convert the left and right videos to RGB automatically. If you want, for example, a yellow/blue anaglyph in color from MPEG videos, you need to write something along these lines:

lv = DirectShowSource("left.mpg").ConvertToRGB
rv = DirectShowSource("right.mpg").ConvertToRGB

YBAnaglyph(lv, rv)

The same precaution holds true for any conversion to anaglyph functions listed below.

Extraction Functions

The Pantarheon 3D AviSynth Toolbox not only lets you combine two videos into one 3D video, it also makes it possible for you yo extract the left or the right view from anything created with the Basic Functions into a 2D video. Note I only mentioned the Basic Functions, but not anaglyphs. That is because the anaglyphs do not have enough of the original video data available to reconstruct the left and right originals.

All of these functions have a name of the corresponding Basic Function followed by either ToLeft or ToRight respectively. They all take one parameter, namely the clip that contains the 3D video.

Here is a list of all the functions that extract the left view from a 3D video without having to resize the video frames:

LeftRight3DToLeft(c)
CrossEyed3DToLeft(c)
TopDown3DToLeft(c)
DownTop3DToLeft(c)
HDMI3DToLeft(c)

Next is the list of all the functions that extract the left view from a reduced 3D video. Because the original videos were reduced in half width or half height, the functions resize the extracted view into its original size.

CrossEyed3DReducedToLeft(c)
Yt3DToLeft(c)
LeftRight3DReducedToLeft(c)
TopDown3DReducedToLeft(c)
DownTop3DReducedToLeft(c)

Note: LeftRight3DReducedToLeft was missing in version 1.0. If that is what you have, please download the current version.

That means that if you pass a reduced left/right video to the CrossEyed3DReducedToRight function, it will extract the left view of your left/right video.

The list of functions that extract the right view without having to resize it follows:

LeftRight3DToRight(c)
CrossEyed3DToRight(c)
TopDown3DToRight(c)
DownTop3DToRight(c)
HDMI3DToRight(c)

And here are the functions that extract the right view from reduced videos:

CrossEyed3DReducedToRight(c)
Yt3DToRight(c)
TopDown3DReducedToRight(c)
DownTop3DReducedToRight(c)

Note: LeftRight3DReducedToRight was missing in version 1.0. If that is what you have, please download the current version.

Conversion Functions

The Toolbox also contains various functions to convert among the various types of 3D formats. Each of them takes one parameter, the clip from which to convert. The names of the functions consist of the name of the format we are converting from, followed by To, followed by the name of the format we are converting to but without the final 3D (except for Yt3D):

LeftRight3DToCrossEyed(c)
LeftRight3DToTopDown(c)
LeftRight3DToDownTop(c)
LeftRight3DToHDMI(c
LeftRight3DToLeftRightReduced(c)
LeftRight3DToCrossEyedReduced(c)
LeftRight3DToYt3D(c)
LeftRight3DToTopDownReduced(c)
LeftRight3DToDownTopReduced(c)
LeftRight3DToAnaglyph(c)
LeftRight3DToRCAnaglyph(c)
LeftRight3DToGMAnaglyph(c)
LeftRight3DToYBAnaglyph(c)

CrossEyed3DToLeftRight(c)
CrossEyed3DToTopDown(c)
CrossEyed3DToDownTop(c)
CrossEyed3DToHDMI(c)
CrossEyed3DToLeftRightReduced(c)
CrossEyed3DToCrossEyedReduced(c)
CrossEyed3DToYt3D(c)
CrossEyed3DToTopDownReduced(c)
CrossEyed3DToDownTopReduced(c)
CrossEyed3DToAnaglyph(c)
CrossEyed3DToRCAnaglyph(c)
CrossEyed3DToGMAnaglyph(c)
CrossEyed3DToYBAnaglyph(c)

TopDown3DToLeftRight(c)
TopDown3DToCrossEyed(c)
TopDown3DToDownTop(c)
TopDown3DToHDMI(c)
TopDown3DToLeftRightReduced(c)
TopDown3DToCrossEyedReduced(c)
TopDown3DToYt3D(c)
TopDown3DToTopDownReduced(c)
TopDown3DToDownTopReduced(c)
TopDown3DToAnaglyph(c)
TopDown3DToRCAnaglyph(c)
TopDown3DToGMAnaglyph(c)
TopDown3DToYBAnaglyph(c)

DownTop3DToLeftRight(c)
DownTop3DToCrossEyed(c)
DownTop3DToTopDown(c)
DownTop3DToHDMI(c)
DownTop3DToLeftRightReduced(c)
DownTop3DToCrossEyedReduced(c)
DownTop3DToYt3d(c)
DownTop3DToTopDownReduced(c)
DownTop3DToDownTopReduced(c)
DownTop3DToAnaglyph(c)
DownTop3DToRCAnaglyph(c)
DownTop3DToGMAnaglyph(c)
DownTop3DToYBAnaglyph(c)

HDMI3DToLeftRight(c)
HDMI3DToCrossEyed(c)
HDMI3DToTopDown(c)
HDMI3DToDownTop(c)
HDMI3DToLeftRightReduced(c)
HDMI3DToCrossEyedReduced(c)
HDMI3DToYt3D(c)
HDMI3DToTopDownReduced(c)
HDMI3DToDownTopReduced(c)
HDMI3DToAnaglyph(c)
HDMI3DToRCAnaglyph(c)
HDMI3DToGMAnaglyph(c)
HDMI3DToYBAnaglyph(c)

LeftRight3DReducedToLeftRight(c)
LeftRight3DReducedToCrossEyed(c)
LeftRight3DReducedToTopDown(c)
LeftRight3DReducedToDownTop(c)
LeftRight3DReducedToHDMI(c)
LeftRight3DReducedToCrossEyedReduced(c)
LeftRight3DReducedToYt3D(c)
LeftRight3DReducedToTopDownReduced(c)
LeftRight3DReducedToDownTopReduced(c)
LeftRight3DReducedToAnaglyph(c)
LeftRight3DReducedToRCAnaglyph(c)
LeftRight3DReducedToGMAnaglyph(c)
LeftRight3DReducedToYBAnaglyph(c)

CrossEyed3DReducedToLeftRight(c)
CrossEyed3DReducedToCrossEyed(c)
CrossEyed3DReducedToTopDown(c)
CrossEyed3DReducedToDownTop(c)
CrossEyed3DReducedToHDMI(c)
CrossEyed3DReducedToLeftRightReduced(c)
CrossEyed3DReducedToYt3D(c)
CrossEyed3DReducedToTopDownReduced(c)
CrossEyed3DReducedToDownTopReduced(c)
CrossEyed3DReducedToAnaglyph(c)
CrossEyed3DReducedToRCAnaglyph(c)
CrossEyed3DReducedToGMAnaglyph(c)
CrossEyed3DReducedToYBAnaglyph(c)

Yt3DToLeftRight(c)
Yt3DToCrossEyed(c)
Yt3DToTopDown(c)
Yt3DToDownTop(c)
Yt3DToHDMI(c)
Yt3DToLeftRightReduced(c)
Yt3DToCrossEyedReduced(c)
Yt3DToTopDownReduced(c)
Yt3DToDownTopReduced(c)
Yt3DToAnaglyph(c)
Yt3DToRCAnaglyph(c)
Yt3DToGMAnaglyph(c)
Yt3DToYBAnaglyph(c)

TopDown3DReducedToLeftRight(c)
TopDown3DReducedToCrossEyed(c)
TopDown3DReducedToTopDown(c)
TopDown3DReducedToDownTop(c)
TopDown3DReducedToHDMI(c)
TopDown3DReducedToLeftRightReduced(c)
TopDown3DReducedToCrossEyedReduced(c)
TopDown3DReducedToYt3D(c)
TopDown3DReducedToDownTopReduced(c)
TopDown3DReducedToAnaglyph(c)
TopDown3DReducedToRCAnaglyph(c)
TopDown3DReducedToGMAnaglyph(c)
TopDown3DReducedToYBAnaglyph(c)

DownTop3DReducedToLeftRight(c)
DownTop3DReducedToCrossEyed(c)
DownTop3DReducedToTopDown(c)
DownTop3DReducedToDownTop(c)
DownTop3DReducedToHDMI(c)
DownTop3DReducedToLeftRightReduced(c)
DownTop3DReducedToCrossEyedReduced(c)
DownTop3DReducedToYt3D(c)
DownTop3DReducedToTopDownReduced(c)
DownTop3DReducedToAnaglyph(c)
DownTop3DReducedToRCAnaglyph(c)
DownTop3DReducedToGMAnaglyph(c)
DownTop3DReducedToYBAnaglyph(c)

In all of these functions, c refers to a clip. For example:

c = AviSource("LeftRight3D.avi")

LeftRight3DToYt3D(c)

This will open LeftRight3D.avi and convert it from a LeftRight3D video into a Yt3D video suitable for upload to YouTube as a 3D video.

Note: A number of these functions was missing in version 1.0. If that is what you have, please download the current version.

Sample Scripts

Five sample scripts are included. One of them will work off the bat. The remaining four require that you have an MPEG decoder installed on your system. Note that when running the 32-bit version of AviSynth on a 64-bit system, you need a 32-bit MPEG decoder. Additionally, three of the scripts require that you install DGDecode installed on your system (but install AviSynth first).

YouTube.avs is the one script that will work off the bat. It loads two files, left.avi (which just displays the word “Left”) and right.avi (which displays the word “Right”) and combines them into a YouTube compatible yt3d video. Since the two videos are not true 3D views, it just illustrates how a left and a right video are combined for YouTube.

Just right click on the YouTube.avs file and play it with the Windows Media Player.

DeTube.avs illustrates how to convert a YouTube yt3d video (Hello.mpg) into a color red/cyan anaglyph. It requires an MPEG decoder.

The remaining three samples require both the MPEG decoder and DGDecode. 720p.avs shows how to convert a 1080p YouTube yt3d video into a 720p color red/cyan anaglyph.

WhenIWas.avs shows how to extract the left view from a YouTube yt3d video, effectively converting it to a 2D video.

And finally, WhenIWasHDMI.avs shows how to convert a YouTube yt3d video into an HDMI v.1.4a video. And yes, that is me in all those pictures. ☺

Comments & Questions

If you have any comments, questions, or requests, I log in to the 3D Stereoscopic Production & Delivery section of the DVInfo Forum several times every day. It is a great forum, and it is the best place to contact me. Much better, by the way, than e-mailing me. I delete most of the e-mail that reaches me without reading it because I get way too many mails telling me I won a prestigious lottery, inherited millions of dollars and similar nonsense. So I could easily forward your e-mail to Spamcop by mistake. And even if I actually download your e-mail to my computer, chances are I will think it deserves a good and well thought-out reply, so I would not reply immediately, and then will get distracted. Contacting me in that forum is the best way.