StereoMovieBuilder v0.3 - Aug 2010

StereoMovieBuilder is a simple tool for building a video file from a set of still pictures.

• Can generate standard AVI files, WMV files or Quicktime movie files.
• Input images can be in the JPEG or PNG format and videos.
• Input images can be monoscopic or stereoscopic (side by side images).
• SMB uses scripts written in a simple format for adding special effects like Ken Burns and transitions.
• Can resize the pictures, transpose a stereo picture and generate various stereo format (anaglyph, half-frame, interlaced,...)

Script file

• Comments: Empty lines or lines starting with a semicolon (;) are considered as comments and are ignored.
• Commands: A command is a special line that starts with the > sign (in the first column).
  Format: >Command[|optional parameters]
  Commands can be global or positional, global commands can only appear once in a script and are usually found at the beginning of the script. Positional commands can be found anywhere in the script and can be repeated.
• Pictures: Other lines are considered as pictures and are loaded and added to the current movie file. Pictures can be PNG or JPEG files (the .jps extension can be used for JPEG stereo images). Pictures can be specified with a full pathname or only with a filename if the "Path" command is used.
  A single picture can be repeated by adding " *d" after the picture name (where d is the duration in second):
  Picture_1.png *5
  will repeat the same picture "Picture_1.png" in the movie file so it's duration will be 5 seconds.

List of available commands

• Stereo
  Will treat the input pictures as stereoscopic side by side pictures or 2D pictures.
  Type: Global
  Parameter (mandatory): 1: pictures are stereoscopic side by side pictures (default), 0: pictures are 2D.
  Example: >Stereo=1
  
• FrameRate
  Specifies the frame rate (number of frame per second) in the generated movie.
  Type: Global
  Parameter (mandatory): the desired frame rate. It can be a decimal value.
  Note: If not specified, the value of 25 fps is assumed and cannot be changed once the first picture is processed.
  Example: >FrameRate=30
  
• MovieFile
  Specifies the movie file to generate.
  Type: Global
  Parameters: File|Codec|Compression
     File: Mandatory parameter, a valid file name. It can be a simple file name if a Path command has been used before or a fully specified name (path + file name). Extension is used to determine the type of movie to generate: .avi for AVI file, .wmv for Windows Media Video file and .mov for QuickTime file.
     Codec: Optional parameter, compression codec to use. If not specified, the user is prompted to select a codec and can change its settings.
     Compression: Optional parameter, compression parameters.
  Note: If this command is not specified in the script, the movie file name will be taken from the application user interface and if empty, the user will be prompted for a file name.
  Example: >MovieFile=Test.avi
  
• Path
  Specifies the default folder from witch the pictures will be loaded if they are not using an absolute file name.
  Type: Positional
  Parameter (mandatory): a valid folder name.
  Note: Issuing a new Path will replace the previous one and will be used for the following commands in the script.
  Example: >Path=J:\POVRay\Test
  
• Resize
  Resize the pictures to the specified size. The size specifies a "bounding box" for the resizing.
  Type: Global
  Parameter (mandatory): width x height in pixel
  Note: for stereo resizing, the size id always the size of the stereo image, even if a conversion (like anaglyph) is applied afterwards.
  Example: >Resize=1600x600
  
• ResizeMode
  Specifies how the pictures are resized
  Type: Global
  Parameter (mandatory): mode : 0:Bounding rect, 1:Exact size (with black border), 2:Stretch to achieve specified size
  Note: for stereo pictures, "chip centering" is automatically performed (ie L & R chips are centered in their respective frame parts).
  Example: >ResizeMode=2
  
• Transpose
  For stereo side-by-side pictures, swap the left part with the right part.
  Type: Global
  Parameter (mandatory): 1 for transposing, 0 to do nothing (default)
  Example: >Transpose=1
  
• Convert
  For stereo side-by-side pictures, convert the picture to another type (anaglyph for instance).
  Type: Global
  Parameter (mandatory): numeric type of the conversion (see below).
  Example: >Convert=12
  
• Crop
  For stereo pictures, crop the picture so it will fit the aspect ratio specified by the video size.
  Type: Global
  Parameter (mandatory): one character specifying the part of the image to crop.
     0: do nothing (default)
     T: crop the top of the picture
     B: crop the bottom of the picture
     C: crop both the top and the bottom of the picture (centered croping)
  Example: >Crop=C
  
• Mirror
  Mirror the pictures
  Type: Global
  Parameters (mandatory): Left_Mirror, Right_Mirror
     Left_Mirror: if 1, mirror the left part of the stereo image.
     Right_Mirror: if 1, mirror the right part of the stereo image.
  Note: in non-stereo mode the Left_Mirror is used for the whole picture and the Right_Mirror parameter is ignored.
  Example: >Mirror=1,0
  
• FlipV
  Vertically flip the pictures
  Type: Global
  Parameter (mandatory): 1 for flipping, 0 to do nothing (default)
  Example: >FlipV=1
  
• Background
  Set the background color (default is black)
  Type : Global
  Parameter (mandatory) : Color (see Frame for the format)
  Example: >Background=red
  
• Frame
  Add monochromatic frames to the movie.
  Type: Positional
  Parameters (mandatory): Color|Duration
     Color: color the frame. It can be one of the base HTML colors (Aqua, Black, Blue, Fuchsia, Gray, Green, Lime, Maroon, Navy, Olive, Purple, Red, Silver, Teal, White, Yellow, LtGray) or a RGB hexadecimal coded colors: #RRGGBB (for instance #ff0000 for red or #00ffff for cyan).
     Duration: duration in second.
  Example: >Frame=black|4
  Will generate a black frame for 4 seconss
  
• Sequence
  Add pictures with consecutive numbering.
  Type: Positional
  Parameters (mandatory): Picture_base_name[d]|Start_#|End_#
     Picture_base_name: base name of the set of pictures, it has a counter placeholder between square brackets specifying the number of digits.
     Start_#: starting number of the sequence.
     End_#: endng number of the sequence.If omitted, the application will increment the counter until no more pictures are found.
  Example: >Sequence=MyPicture_[4].jpg|1|237
  Will add to the movies pictures "MyPicture_0001.jpg", "MyPicture_0002.jpg",... "MyPicture_0237.jpg"
  
• Video
  Add the frames taken from a video file (the sound is not processed).
  Type: Positional
  Parameters (mandatory): Video_name    Video_name: file name of the video.
  Example: >Video=MyVideo.avi
  Will add video file "MyVideo.avi" to the movie.
  
• Transition
  Add to video file a transition effect between two pictures.
  Type: Positional
  Parameters (mandatory): Transition_Name|Duration
     Transition_Name: see the list of available transition below.
     Duration: duration of the transition in seconds. By specifying a negative number, the transition will be played backwards.
  Note: a transition command must appear between two picture commands (either: a single picture, a KBE, Sequence, Frame or Video command).
  Placing a transition command will make the two adjacent picture commands to overlap: for a single picture, it's duration will be increase by the duration of the transition. For Sequence, Video and KBE, the transition duration will be part of the command duration.
  Example:
    Picture_1
  >Transition=Fade|0.5
  Picture_2
  Will compute a transition from Picture_1 to Picture_2 using the "Fade" effect and during half a second.
  
• KBE
  Ken Burns' Effect: zoom and/or pan on a picture. Creates an animation on a still image with slow zooming and panning effects.
  Type: Positional
  Parameters (mandatory): Picture|Source_Rect|Target_Rect|Duration
     Picture: picture to use (should be of the largest resolution is zoom is used).
     Source_Rect, Target_Rect: The source rectangle defines the initial view, ie the first image of the animation. This rectangle will be moved and resized to meet the position and size of the target rectangle. If the source rectangle is larger than the target rectangle, the picture will appear to be zoomed, if it's smaller, the effect will be a backward zoom.
  A rectangle is defined by the following five fields: x, y, w, z, t
        x, y: position of the top-left corner of the rectangle in pixel or % (top-left corner of the picture is 0,0)
        w: width of the rectangle in pixels or % (the height is computed using the aspect ration of the generated movie file)
        z: stereo window correction (stereo mode only). Usefull when zooming into a picture to keep infinite paralax under control.
        t: additional duration for starting (or ending) frame. The frame will be repeated in the movie file for the specified duration (default is 0)
  Parameters x, y and w can be specified in pixel (default) or in percentage of the picture dimensions (add a percent sign % to the value).
  A rectangle defined by 0,0,0 indicates the whole pictures.
     Duration: Duration in seconds of the animation (not counting the additional durations, the total duration will be: Duration + t1 + t2).
  Note: black borders will be added if the picture aspect ratio doesn't match the aspect ratio of the generated video file.
  Example: >KBE=Volcano0001.png|400,600,800,-70,1|0,0,0,0,2|6
  Will show a zoomed portion of the image for 1s before unzooming in 300 steps (6s) to show the whole picture which is displayed for another 2s.
  
• PIP
  Picture-in-picture (experiental); inset a picture in another.
  Type: Positional
  Parameters (mandatory): Rect_1|Rect_2|Duration
     Rect_1 : Inset rectangle.
     Rect_2 : (for future use).
  A rectangle is defined by the following six fields: x, y, w, z, t, a
        x, y: position of the top-left corner of the inset rectangle in pixel or % (top-left corner of the picture is 0,0)
        w: width of the rectangle in pixels or % (the height is computed using the aspect ration of the generated movie file)
        z: depth position of the inset rectangle.
        t, a: ignored (for future use).
  Parameters x, y and w can be specified in pixel (default) or in percentage of the picture dimensions (add a percent sign % to the value).
     Duration: PIP durationen.
  Example:
    MN2008_625_X.jps
  >PIP=5%,5%,60%,0,0,0|5%,5%,40%,0,0,0|36
  >Video=MN2008_626b_X.avi
  MN2008_625_X.jps
  Inset the video MN2008_626b_X.avi in the upper-left corner of the still picture MN2008_625_X.jps for the duration of the video (36 s).
  
• Text
  Print a text on each of the following frames. Multiple comands can be issued to print more than one text.
  Use the >Text=0 command to clear all previously defined texts.
  Type: Positional
  Parameters (mandatory): Text|Position|Font|Format_Color
     Text: the text to print
     Position: Five fields separated by commas: x, y, w, h, z
        x, y: position of the top-left corner of the bounding rectangle (top-left corner of the picture is 0,0)
        w, h: width and height of the bounding rectangle.
        z: depth position of the text (stereo mode only).
     Font: Font to use
     Format_Color: Format, TextColor, BkColor, ShadowColor
        Format: number specifying the text formatting.
        TextColor: color of the text.
        BkColor: background color of the bounding text (use 'none' for transparent background).
        ShadowColor: color of the drop shadow (use 'none' to suppress the shadow)
  Example: >Text=www.stereoscopie.fr|10%,10%,80%,100%,4|Times,120,0,700,1,0,0|1,blue,none,gray
  
• Logo
  Print a logo image on each of the following frames.
  Type: Positional
  Parameters (mandatory): Image|Position
     Image:
     Position:
  Example: >Logo=myLogo.png|-10,-10,10
  
• Stop
  Stop processing the script.
  Type: Positional
  Parameters(mandatory): always 1
  Example: >Stop=1
  
• Skip
  Skip (ignore) part of the script (usefull for working on a part of a movie).
  Type: Positional
  Parameters (mandatory): 1: script commands following wll be ignored. 0: SMB resume interpreting the following commands.
  Example:
    Picture_1.jpg
  >Skip=1
  Picture_2.jpg
  Picture_3.jpg
  >Skip=0
  Pictures #2 and 3 will be ignored.
• MergeFrames
  Merge each frame with the previous one (experimental).
  Type: Positional
  Parameter (mandatory): merging factor from 0 (no merging) to 255 (full previous picture).
  Example: >MergeFrames=128
  
• Debug
  Used to position various debug flags (experimental).
  Type: Global
  Parameter (mandatory): debug flags:
     X: print various debug information on each produced frame.
     T: list the available transitions.
     W: do not prompt the user when a movie file is about to be overwritten.
  Example: >Debug=XW
  

List of available Convert modes

List of available Transition effects

Limitations of the current version

• Only the AVI format is available for the output videos.
• Logo command is not implemented.

Versions

• v0.1 (Nov-2008): Initial version.
• v0.2 (Nov-2008): Added Video command.
  Added convert mode 19 for building mono video from stereo pictures.
• v0.2.4 (Feb-2009): Added convert mode 20 for side by side, half width format.
• v0.2.5 (Feb-2009): Added Text command.
• v0.3 (Aug-2010) : Added Crop, Background commands.

Examples

1) Build a smaller anaglyph movie (640x480, mode 12) from side-by-side crossed-eye images (so we need to transpose each picture). The video will stay 2s on the first picture (repeated 48 times) and then will display each of the remaining pictures for just one video frame until the ending title (shown for 6s) located in the Titles subfolder.

>Path=C:\Program Files\POV-Ray for Windows v3.5\Misc\AnimB
>Resize=1280x480
>Convert=12
>Transpose=1
>FrameRate=24

AnimB000.png *2
AnimB001.png
AnimB002.png
AnimB003.png
AnimB004.png
...
Titles\Title_End.png	*6

2) Using transition effects: starts with 1/2s black screen then fade in slowly during 4s on the first image, display it 1/2s, fade in on next image. Then starts a sequence of pictures, starting with picture named MP_scenesG002.png and looking for pictures MP_scenesG003.png, MP_scenesG004.png,...

...
>Frame=Black|0.5

>Transition=Fade|4
MP_scenesG000.png   *0.5

>Transition=Fade|1
MP_scenesG001.png   *1.5
>Sequence=MP_scenesG[3].png|2
...

3) Transitions et effet Ken Burns.

MN2008_130_X.jps
; Fade transition from picture 130 to a zoomed part of picture 589
>Transition=Fade|1

; Continue with a Ken Burns effects, panning slowly horizontally accross the picture 589.
>KBE=MN2008_589_X.jps|198,383,667,-100,0.5|1882,370,667,-100,0.5|24

; After the panning is complete, slowly unzoom to show the whole picture.
; Note that the Source_Rect of this KBE is the same as the Target_Rect of the previous KBE.
>KBE=MN2008_589_X.jps|1882,370,667,-100,0.5|0,0,0,0,2|6