click here for stills2dv main page

## stills2dv workfile vocabulary and syntax

##### You may want to look first at the simple examples further on this page

A workfile is divided in lines of text, each line may be an action line or may be a configuration line.

An action line must start with at least one "img" command or one "continue" command and should normally comprise some or all other action commands among: duration, startpoint, endpoint, zoom and crossfade.

Beside img and continue all actions command may or may not be present on the line, their default value will be used if absent.

Those configuration commands: framerate, outputtype, geometry, owidth, oheight and their synonyms should all be used before the very first action command and not after. Use of them after an action command will make weird results if the application does not simply crash.

Those configuration commands: backgroundcolor, jpegquality and their synonyms may be use in any line, action or config.

backgroundcolor | Requires 1 hexadecimal RGB parameter: Changes the background color from its default value (black 0x000000) to whatever hexadecimal RGB value you want, like ff0000 for red, 004400 for dark green, etc.. Does not require to be in an action line
bgcolor | Synonym for backgroundcolor
continue | Requires no parameter: continue takes the image of the previous line and takes its endpoint as the new startpoint, the ending zoom value of the previous line will be taken as the default zoom value.
crossfade | Requires 1 time parameter: It cannot be on the first action command as the crossfading will occur with the previous line, the parameter must be the number of seconds with decimals, if no duration command is defined after the crossfade on the same line the duration will be defaulted to the crossfade paramter
defaultcolor | synonym for backgroundcolor
duration | Requires 1 time parameter: this should be the last command in an action line, it defines the duration of the whole line. If not present the duration will either default to the value of crossfade if present on the same line or it will be defaulted to 10.0 seconds
endpoint | Requires a parameter, If you wish to pan in your image you have to set a startpoint and an endpoint. If no endpoint is present it will default to the startpoint value (it will not pan for the duration of this action). valid parameters are: any X,Y values like 500,500 or 0,0 etc.. center top bottom left right topright topleft bottomright bottomleft
fps | synonym for framerate
framerate | Requires 1 parameter with decimals, it should be define before any action line and it will default to 30 if not present.
geometry | synonym for resolution
height | synonym for outputheight
img | requires 1 parameter: the filename of the picture for this action line.
jpegquality | requires 1 integer parameter: between 1 and 100, defaults to 90. This has no effect if the outputtype is ppm
oheight | synonym for outputheight
output | synonym for outputtype
outputheight | Requires 1 interger value: the size in pixel of the height of the output format. If needed this should be used before the first action command, if you use outputheight you should also use outputwidth. It will default to 480 if not defined
outputtype | Requires 1 parameter: jpg or ppm, it must be used before the first action line, it will default to ppm if not defined.
outputwidth | Requires 1 integer value: the size in pixel of the width of the output format. If needed this should be used before the first action command, if you use outputwidth you should also use outputheight. It will default to 720 if not defined
owidth | synonym for outputwidth
pansmoothness | Requires any value between 0.000 and 0.5 (0.00 will turn off the smoothness feature). If not set the value will be defaulted at 0.200. (0.200 means that the first 20% of the time allocated for this panning will be accelerating and it will deccelerate in the last 20%)
quality | synonym for jpegquality
resize | synonym for resolution
resolution | requires a size parameter: X:Y. It's faster to use than using both outputwidth and outputheight, it will default to 720x480 if not used
sharpness | Requires 1 float value between 0.5 and 5, the lower the number the blurrier the image will be and slower it will be to render. The higher it is the sharper is the image but some motion weaving artefacts will appear with slow pans and zooms. This latter kind of artefact is distracting and is a nuisance to any video compression encoding, I would recommend to leave it at its default value of 1.0
size | synonym for resolution
startpoint | Requires a parameter, If you wish to pan in your image you have to set a startpoint and an endpoint. If no startpoint is present it will default to the center of the image or to the endpoint of the previous action line if a "continue" command has been used on the present line. valid parameters are: any X,Y values like 500,500 or 0,0 etc.. center top bottom left right topright topleft bottomright bottomleft
type | synonym to outputtype
width | synonym to outputwidth
zoom | requires 1 or 2 parameters (separated by a coma). If just one parameter then the whole action line will be at the same zoom value (the one provided) but if 2 values are provided the action line will zoom from value 1 to value 2 according to the duration value of the action line. here are the valid parameters: any numerical with decimals like 1.0, 100.0 or 0.05. A zoom of 5.0 will mean that just 1/5th of the image width will be seen on the output FITWIDTH (which is equivalent to 1.0) the width of the original image will be presented in whole in the output FITHEIGHT the height of the original picture will be presented in whole in the output. FIT The whole image will be presented in the output
zoomsmoothness | Requires any value between 0.000 and 0.5 (0.00 will turn off the smoothness feature). If not set the value will be defaulted at 0.200 (0.200 means that the first 20% of the time allocating for this zooming will be accelerating and it will deccelerate in the last 20%)

## Example A

you have a 2048x3072 picture of yourself named img_2311.jpg and you wish to make a zoomout from your eyes to the whole picture that lasts 10 secs, you wish the output to be in PPM at 720x480 30fps for dv, using gimp you figured out that the coordinates between your eyes are 1024x503 (0,0 being the upper left corner).

        img img_2311.jpg zoom 3.0,FIT startpoint 1024,503 endpoint CENTER duration 10.00

ppm is the default value, 720x480 is default, 30 fps is default... so we did not need to set anything, we just needed our image and its action, making it a one liner workfile

## Example B

you saw the animation with your picture and you liked it but you wish to make it nicer: with a short fade-in and fade-out and in full HD, you made a black image named black.jpg for the occasion:

        resolution 1920x1080
        fps 60
        type jpg
        img black.jpg duration 1.0
        img img_2311.jpg zoom 3.0,FIT startpoint 1024,503 endpoint CENTER crossfade 1.0 duration 10.00
        img black.jpg crossfade 1.0 duration 1.0

You should notice that even if we add up the duration values it amounts to 12.0 seconds but since there are 2 crossfade of 1.0 seconds each the amount of time the animation will last will still be 10.0 seconds.

## Example C

Thinking about it, you don't like that it zoom out, you would prefer zooming in in your eyes instead to make it more dramatic:

        resolution 1920x1080
        fps 60
        type jpg
        img black.jpg duration 1.0
        img img_2311.jpg zoom FIT,3.0 startpoint CENTER endpoint 1024,503 crossfade 1.0 duration 10.00
        img black.jpg crossfade 1.0 duration 1.0

that was an easy change, changing the zoom parameters from 3.0,FIT to FIT,3.0 and swapping also the endpoint parameters with the startpoint parameters...

## Example D

You still want the whole thing to last 10 seconds but you want your portrait to stay still a few seconds before starting zooming:

        resolution 1920x1080
        fps 60
        type jpg
        img black.jpg duration 1.0
        img img_2311.jpg zoom FIT startpoint CENTER crossfade 1.0 duration 4.0
        continue zoom FIT,3.0 startpoint CENTER endpoint 1024,503 duration 6.00
        img black.jpg crossfade 1.0 duration 1.0

Notice the use of the continue command and that we spread the 10 seconds in a 4-6 split.

## Example E

You have a very long landscape.jpg image and you wish to pan very slowly from the left side of the picture to the right side, you want it in HD and at 30 fps in a way that the panning takes 5 minutes

        resolution 1920x1080
        fps 30
        type jpg
        img landscape.jpg zoom FITHEIGHT startpoint LEFT endpoint RIGHT duration 300.00

To calculate the left point the application must know the zoom factor so it is prudent to set the zoom before the startpoint

click here to go back to main page