Command-Line Manual |
Shake started in its infancy as a command-line compositor, which means that you can conceivably execute a five hundred node script all typed out on the command-line. Conceivably, but not practically, since nodes like Primatte, Stabilize, Paint or RotoShape all have unwieldy formats, and of course you would be typing out five hundred nodes on the command-line. However, the command-line does remain an ideal mode to execute many daily image processing functions like:
All of these can be rendered in the command-line more quickly and efficiently than one could in the interface, since they involve relatively straightforward commands. The other major use of the command-line is to execute scripts you have created in the interface and have then saved to disk. This section of the documentation discusses a few general principles of using the command-line shell, and then lists out several examples. The last section is a list of frequently used nodes. Again, this not a complete list, since every node within Shake, including user macros, can be executed on the command-line.
Example Images: All images can be found in doc/pix. All examples I list are assuming you are in this directory or below it.
A note on using the command-line on NT: Although all of the commands do work in the DOS shell, we can't in good conscience encourage anybody to really use it. Instead, there is a much more sophisticated shell called a tcsh (pronounced "t-shell") available on our web-site at: http://www.nothingreal.com/Download/data/NT-Unix.zip.
Command-Line Principles |
Viewing, Converting
and Writing Images
Shake on the command-line does two basic things: It views images and executes image operations. If you don't specify any options, it will simply be a flipbook/viewing tool. If your only other function is a FileOut command, it is an image conversion tool. If you append operations, it will apply them to the last image you specify. It will still look at the image, but now in their modified state. By appending the -fileout (-fo for short), you can instead choose to write out an image rather than view it. Here are some simple examples to start the discussion. The following command will display three images because you haven't told Shake to do anything to them: In the doc/pix/truck directory:
shake truck.iff bg.iff sign_mask.iff
For instructions on how to interact with the flipbook viewer, jump to GUI Manual - Flipbooks.
By appending the -fileout, or -fo, you write the last image out and that image is not viewed:
shake truck.iff -fo test.rla
This writes out a new image called test.rla, in, of course, the .rla format. For a list of supported formats and their extensions, jump to Overview - Supported File Formats.
Time and Launching
Flipbooks
Shake assumes you are just using frame 1 unless you otherwise specify a time range. This is done with the -t option, and a frame numbering symbol, usually something like:
shake alien/alien.#.iff -t 1-50
The frame numbering is substituted with a symbol, here the # sign, which indicates that the file is padded to four places. You can use other symbols:
Shake format | Reads/Writes... |
image.#.iff | image.0001.iff, image.0002.iff |
image.%04d.iff | image.0001.iff, image.0002.iff |
image.@.iff | image.1.iff, image.2.iff |
image.%d.iff | image.1.iff, image.2.iff |
image.@@@.iff, image.###.iff | image.001.iff, image.002.iff |
image.%03d.iff |
image.001.iff, image.002.iff |
image.10-50#.iff | image.0010.iff at frame 1, 11 at frame 2, etc. |
The -t option is extremely flexible. You can choose to render frame ranges, stepped ranges, individual frames, or any combination:
Time Range | Number of Frames | Frames Rendered |
-t 1-100 | 100 | 1, 2, 3...100 |
-t 1-100x2 | 50 | 1, 3, 5...99 |
-t 1-100x20 | 5 | 1, 21, 41...81 |
-t 1-20,30-40 | 31 | 1,2,3...20, and 30,31,32...40 |
-t 1-10x2,15,18,20-25 | 13 | 1,3,5...9,15,18, 20, 21, 22 ...25 |
-t 100-1 | 100 | 100,99,98...2 |
Therefore, to convert a sequence of images, you might do something like:
shake alien/alien.#.iff -fo test.@.jpg -t 1-30 -v
Appending Functions
You can append optional functions, using the - sign to preface each function call, followed by a space for any arguments it might take. Not all functions take arguments, but most do. Here, Blur has an argument of 50, which is the amount of blur you want to apply:
shake truck.iff -blur 50
You can append as many functions as you want:
shake truck.iff -blur 50 -invert rgb -z 2
Here is a good example of a common command-line test of 3D-rendered imagery:
shake truck.iff -outside sign_mask.iff -over bg.iff
You don't have to type out the entire function name as long as there is no ambiguity. For example,
shake bg.iff -bri 2
will call the Brightness function since there are no functions starting with bri. However, calling
shake bg.iff -con 2
will inform you that it can't choose between Conform, Constraint, ContrastLum, ContrastRGB or Convolve. Replacing your command with the enough letters will solve the problem:
shake bg.iff -contrastl 2
This will call up the ContrastLum function.
A note concerning capitalization and function names. In the interface, function names are always capitalized. In the command-line, they are always lower-case so you don't have to resort to the Shift key. The only exception is when you call up a function in quotes, like the Linear function used to animate parameters:
shake truck.iff -blur "Linear(0,0@1,20@20)" -t 1-20
For more information on animation curves, jump to Overview - Splines.
Most functions are image manipulators in that they will modify the image you read in. Others are controls to modify how Shake executes the command. For example, -brightness 2 will brighten an image, but -fps 24 will load a flipbook preset to twenty-four frames-per-second. Although image functions always happen in a linear fashion, i.e., the order of commands matters, controls can be placed anywhere. For example, the following lines are identical. In the doc/pix directory:
shake alien/alien.#.iff -rotate 45 -t 1-50 -cpus 2
shake -cpus 2 -t 1-50 alien/alien.#.iff -rotate 45
However, the following two lines are different:
shake truck/truck.iff -pan 200 0 -rotate 135
shake truck/truck.iff -rotate 135 -pan 200 0
If you place a second control on an line, it will replace the previous setting. For example,
shake alien/alien.#.iff -t 1-50 -fps 24 -bri 2 -fps 30 -t 10-20
will play at thirty frames-per-second and only render frames 10-20.
Getting Help
How do you know what Blur is expecting? Outside of using the product non-stop for three years, you can also just type
shake -help blur
and it will return what arguments that function takes. Blur actually has six arguments:
-blur [xPixels] [yPixels] [spread] [xFilter] [yFilter] [channels]
Often, you don't need to specify all arguments. Shake will let you know if it is expecting more arguments than you have supplied.
You can also jump to the help page, under Functions By Class or Functions By Name. For example, the Blur page looks like this: Jump To Blur.
You don't have to know the entire function name. For example, your shrill call for help on blur probably called up about seven different functions. Try
shake -help mul
and you will see that Shake simply looks for the string "mul".
How to quickly launch these docs?
shake -docs
Argument Flow
Looking at the arguments in the documentation, the Blur page lists that it expects an image as its first input, which is labeled In. However, the command-line differs from the interface in that it always assumes the first image argument is coming from the previous argument in a linear flow, so we omit the first image argument. Therefore, in Blur, the first argument on the command-line is the xPixels parameter, which the yPixels value is linked to.
In the command-line, Shake assumes the previous image is fed into the function that follows. However, if you have multiple input images, only the last image will have the effect applied to it. In this example, only sign_mask.iff gets blurred:
shake truck.iff bg.iff sign_mask.iff -blur 50
The only way around this is using branching commands using the -fi (FileIn) and -label options. This allows you to do different operations on different branches and then join them together. You label a branch with the -label command, and then start a new branch with the -fi command. The following example blurs the background, and then assigns it a temporary label of BG. It then reads the truck, brightens it up, but not the background, and comps the result over the blurred background:
shake bg.iff -blur 50 -label BG -fi truck.iff -bri 2 -over BG
Scripts
You can execute pre-saved scripts with the -exec command. These scripts are usually generated from the interface. This will go through the script and execute all FileOut nodes. If there are no FileOuts in the script, the command will do nothing.
shake -exec my_script.shk -v
The -v stands for verbose, and gives you feedback on the progress of the render.
You can override many settings in the script, so
shake -exec my_script.shk -v -proxys .5 1 -t 20-30 -motion 1 1
will render at half proxy scale, full proxy ratio, only frames twenty to thirty, and turn on motion blur without having to edit the script itself.
You can save a script from the command-line with the -savescript function:
shake truck/truck.iff -outside truck/sign_mask.iff -over truck/bg.iff -savescript toto.shk
If there is no FileOut in the script, you can test the script with the -script command. It is similar to the -exec function in that it will execute FileOuts. However, it will also view every branch in the script, which can be awkward when rendering. It is really just for testing scripts:
shake -script toto.shk
Command-line Controls |
<> indicates a mandatory argument. [] indicates an optional argument
All examples are executed inside doc/pix/truck.
These functions are unique to the command-line.
time range control | |
-t <frameRange> | See above under Time |
quality controls | |
-fast [quality] | When no argument is given (just -fast), it turns off anti-aliasing to speed up the render. When using -exec to render a script that has the global quality set to low, you can turn it back on with -fast 1 |
-pixelscale <scale> [ratio] | Sets the pixelscale and ratio. Not used very frequently at all in the command-line. See Overview - About Proxies |
-proxyscale <scale> [ratio] | Sets the proxyscale and ratio. Does a low-resolution test render of your commands. See Overview - About Proxies |
Frequently-used Functions |
Since you can use any of the functions in Shake, this is only a partial list. However, it represents the functions that are both practical to use (not too many parameters), and are useful to do in the command-line, i.e., file resizing, basic channel manipulation, quick generation of test elements, etc. Typically, the functions have more options than I list here, but I have included only the options one would typically use in the command-line. For more information on the functions, jump to the appropriate documentation page.
image functions | |
-addtext <text> | This is a quick way to generate text, as you only have to supply the text itself, without having to enter the width, height, and bit depth. |
-black [w] [h] [bitDepth] | A quick way to generate black |
-color <w> <h> <bitDepth> <r> <g> <b> [a] [z] | A color field |
-ramp [w] [h] [bitDepth] [orientation] | A ramp. Use an orientation of 1 for vertical, 0 for horizontal. |
-text <w> <h> <bitDepth> <text> |
color functions | |
-brightness <value> | Multiplies the RGB channels by value. |
-contrastlum <contrast> [center] | Performs a contrast, with the pivot point at center. |
-delogc | A log to linear color conversion to quickly see cineon plates. |
-gamma <value> | Hmmm.... |
-logc | A linear to log color conversion to convert files into log color space. |
-luminance | A quick function to generate a black-and-white image based on the luminance. Will generate a 1-channel image. |
-mult <r> <g> <b> [a] [z] | Multiplies color on a per-channel basis |
-saturation <value> | Saturation change |
channel functions | |
Example: shake bg.iff -colorsp rgb hls |
Converts images to a different colorspace. You indicate the source space and the destination space. |
-copy <image> <clipmode> <channels> | Copies a channel from your listed image to the incoming image. Clipmode means which resolution you want, with 1 being the second image, 0 being the input image. |
-reorder <channels> Examples: shake truck.iff -reorder aaaa |
Swaps channels. Using letter codes (r, g, b, a, z, l for luminance, and n for null), indicate what channel should go in the r,g,b,a,z channels. |
-setalpha <value> | Sets the alpha to your value. To remove an alpha channel from an image, enter 0. |
-switchmatte <image> | Similar to Copy, except only the alpha is swapped, and it is premultiplied. |
compositing functions | |
-inside <maskImage> | An inclusion matte. Multiplies the incoming image by the alpha channel of the image you name. |
-isuba <Image> | This extracts the absolute difference between the two images. |
-mix <Image> [percent] | Mixes two images together. A percent of 50 means half of each image. |
-outside <maskImage> | An exclusion matte. Multiplies the incoming image by the inverse of the alpha channel of the image you name. |
-over <backgroundImage> | Puts the incoming image, assumed to be the premultiplied foreground, over the background.. |
-under <foregroundImage> | Puts the incoming image underneath the image you list, which is assumed to be premultiplied. |
-screen <image> | Performs the Screen operation, which is good for reflections and glows. |
resizing functions | |
-addborder <xBorder> <yBorder> | Pads the image out with black around the edges |
-crop <left> <bot> <right> <top> | Crops the image to the two corners you specify. The origin is in the lower-left corner. |
-fit <xRes> <yRes> | Resizes the image to the resolution you specify, maintaining the aspect ratio. |
-resize <xRes> <yRes> | Resizes the image to the resolution you specify. |
-window <left> <bot> <xRes> <yRes> | Crops the window at the specified lower-left corner, and to the resolution you specify. |
-z <zoom> | A shortcut for Zoom, both X and Y are zoomed by the same amount. |
-zoom <xZoom> <yZoom> | Zooms the image in X and Y independently. |
filter functions | |
-blur <xPixels> [yPixels] | Blur, baby! |
transform functions | |
-flip | Turns the image upside down. |
-flop | Turns the image backwards. |
-pan <xPan> <yPan> | Pans the image |
-rotate <angle> | Rotates the image |
-scale <xScale> <yScale> | Scales the image without changing the resolution. |
video field functions | |
-deinterlace <field> [mode] |
Deinterlaces the image. 0 equals the even field, 1 equals the odd field. For mode, 0 = replication of the line below, |
-evenonly <image> Example: shake bg.iff -rotate 45 -evenonly bg.iff |
Will only execute the previous commands on the even fields of the image, mixing it back in with the image you supply. |
-field <field> | Extracts just one field, creating a half-height image. 0 =even field, 1 = odd field. |
-fldr <field> | Turns on field rendering. 1 = odd/pal, 0= even/ntsc |
-interlace <image> <clipMode> <field> | Interlaces the two images. clipMode of 1 means the
bg resolution is taken, 0 means the incoming image resolution is taken.
0 =even field, 1 = odd field. |
-oddonly <image> | Will only execute the previous commands on the odd fields of the image, mixing it back in with the image you supply. |
-pulldown <image> <field> [offset] Example: shake bus/bus2.40-79#.jpg 0 -t 1-50 |
Acts as a FileIn, going from 24 fps to 30 fps, interlacing the frames to add the extra frames. 0 =even field, 1 = odd field. The offset amount is the frame at which the interlacing starts after the beginning. |
-pullup <image> <field> [offset] | Acts as a FileIn. Removes the 3:2 pulldown interlacing, going from 30 fps to 24 fps. 0 =even field, 1 = odd field. The offset amount is the frame at which the interlacing starts after the beginning. |
-swapfields | Switches the odd and even fields. |
other functions | |
-average <image> <sStart> <sEnd> <dStart> <dEnd> <bytes> <gain> <scale> | Acts as a -bytes <bytes> , averaging frames down from sStart and sEnd to dStart and dEnd. I usually use 1,1,1 for the last three arguments |
-bytes <bytes> | 1 = 8 bits, 2 = 16 bits, 4 = float. |
Examples |
Looking at Images | |
In doc/pix/truck: shake bg.iff sign_mask.iff |
|
shake * |
This uses the UNIX-style wildcard, *. This means "anything". |
shake *.iff |
This means "anything with an .iff extension" |
shake bg.iff -compare sign_mask.iff |
This compares the two images, using Alt+left mouse to drag between the two. |
Launching Flipbooks | |
In doc/pix: shake alien/alien.#.iff -t 1-50
|
Cool Text Tricks | |
shake -addtext %f -t 1-20 |
Prints time code |
shake -addtext %F -t 1-20 |
Prints full time code |
shake -addtext %t -t 1-20 |
Prints the current frame |
shake -addtext %T -t 1-20 |
Prints the padded current frame |
shake -addtext "%D, %d %M" | Prints the current date |
Converting image file formats | |
In doc/pix/alien: shake alien.#.iff -t 1-50 -fo temp.@.sgi |
Writes 50 unpadded images in the .sgi format |
In doc/pix/fan: shake fan.@.iff -t 1-5 -fo fan.#.tif |
Writes 5 padded images in the .tif format. |
Adding and Removing Channels | |
In doc/pix/alien: shake alien.0001.iff -lum -fo toto.iff |
Creates a black-and-white image with an alpha channel. |
shake alien.0001.iff -reorder rrra -fo tutu.iff
|
Creates a black-and-white image with an alpha channel |
shake tutu.iff -reorder rgab -reorder rgab -fo titi.iff |
To make a 1-channel image into a 3-channel image without modifying it, use two Reorders. |
shake alien.0001.iff -reorder rgbn |
Removes the alpha channel |
shake alien.0001.iff -setalpha 0 |
Removes the alpha channel |
shake alien.0001.iff -reorder rgbl |
Puts the luminance into the alpha channel |
Changing bit-depth | |
In doc/pix/truck: shake bg.iff -bytes 1 -fo bit8.iff |
Converts the image to 8 bits, which the image was at anyway... |
shake bg.iff -bytes 2 -fo bit16.iff |
Converts the image to 16 bits. |
shake bg.iff -bytes 4 -fo bit32.iff
|
Converts the image to float. |
Manipulating Fields | |
In doc/pix/bus: shake -pulldown bus2.40-79#.jpg 0 -t 1-50 -fo fps30.#.iff
-v |
3:2 pulldown, going from 24 to 30 fps. I got the 1-50 by subtracting 40 from 79 and adding 1, and then multiplying that by 1.25. |
shake -pullup fps30.#.iff 0 -t 1-40 -fo fps24.#.iff -v | 3:2 pulldown going from 30 to 24 fps. I got the 1-40 by dividing 50 (the amount of images) by 1.25. |
Averaging Frames | |
In doc/pix/bus: shake -average bus2.40-79#.jpg 1 40 1 20 1 1 1 -t 1-20 |
This averages the 40 frames down to 20 frames. |
shake bus2.40-79x2#.jpg -mix bus2.41-79x2#.jpg -t 1-20 |
This uses the frame numbering steps in the FileIn to get the averaging, mixing them together with the Mix function. |
Renumbering Clips | |
In doc/pix/bus: shake bus2.40-79#.jpg -t 1-40 -fo toto.#.iff -v |
Shifts frame numbering to start at 1 |
shake bus2.#.jpg -t 40-79 -fo toto.#-39.iff -v |
Also shifts frame numbering to start at 1 |
shake bus2.#.jpg -t 40-79 -fo toto.118-#.iff -v |
Reverses timing |
shake bus2.#.jpg -t 40-79 -fo toto.@.iff -v | Unpads the clip |
shake bus2.40-79x2#.jpg -t 1-20 -fo toto.#.iff -v | Halfs the timing of the clip |
shake bus2.40-79x.5#.jpg -t 1-80 -fo toto.#.iff -v | Doubles the timing of the clip |
Compositing | |
In doc/pix/truck: shake truck.iff -outside sign_mask.iff -over bg.iff |
This averages the 40 frames down to 20 frames. |
shake bg.iff -under truck.iff |
In doc/pix/truck: shake bg.iff -rotate "time*time" -t 1-75 -motion .5 1 -cpus 2 |
This uses the time variable, placing it in quotes to multiply it by itself. As the frame count increases, the angle increases. I also turn on both of my cpus for my 2-proc box. |
In doc/pix/truck: shake truck.iff -pan "cos(time*.5)*100" "sin(time)*50" -motion .5 1 -t 1-13 |
Uses the cos and sin functions to animate the truck in a figure-8. |
In doc/pix/truck: shake bg.iff -rotate "cos(time*.5)*50+25" -t 1-13 -motion .5 1 |
Substituting Values with -curve |
f you have this in a script called myscript.shk: Text1 = Text(720, 486, 1, {{ stringf("myVal = %d %s", myVal, slatestring); }}, "Utopia Regular", 100, xFontScale, 1, width/2, height/2, 0, 2, 2, 1, 1, 1, 1, 0, 0, 0, 45); You can do: shake -curve int myInt 5 -curve string slatestring "SuperSlate" -script myscript.shk and you get a nice image that says "myVal = 5 SuperSlate". Or you could do: shake -curve int myVal 5 -curve string slatestring "SuperSlate" -text 720 486 1 ' :stringf(\\\"myVal = %d\\n%s\\\", myVal, slatestring ) ; ' Note the extra backslashes - this quotes it once for the shell then and again for shake. The shell sees \\ and makes it \ then \" and makes it " so you get a result of \" going into the shake wrapper script which is then passed properly into the shake executable. Whew. |
Command-line Tips |
File
Completion. Is it a pain to type all of those file names? Here is a shortcut
using the File Completion in the tcsh. Whenever you hit Tab, it will
list all potential files that match what you type. For example, in doc/pix:
shake trTAB
will list out
shake truck/
Hitting it again will list out all three images files within that directory. Typing another t, i.e.,
shake truck/tTAB
will list out
shake truck/truck.iff
You can therefore type the entire line with very few keystrokes. Try typing this:
shake tTABt tTABbTAB tTABsTAB
It will list out the following line:
shake truck/truck.iff truck/bg.iff truck/sign_mask.iff
So just hit Enter.
Repeating
previous commands. You can repeat previous commands in one of two ways.
The first is to use the up arrow on the command line. Each time you hit it, it will list out the previous command, stepping back through your history. If you use the left and right arrows, you can go and change portions of the command. Hitting the down arrow will take you to the next command in your history list.
The second way is to use the ! key. Hitting !! will repeat the last command, although hitting up arrow is easier. Hitting !s will repeat the last command that started with "s".
Wildcards.
You can use wildcards in the command-line so you don't have to type lots of
things. Here are a few of them:
Wildcards | |
* Matches everything of any length. |
In doc/pix/truck: shake * This shows all files within that directory simultaneously. shake *.iff This shows all files within that directory that have a .iff extension. shake *g* This displays bg.iff and sign_mask.iff. |
? This is used to match anything for just that position |
In doc/pix/alien: shake alien.000?.iff This displays the first 9 images simultaneously. shake alien.002?.iff This displays all frames in the twenties. |
[range-range] This can describe a range, either between letters or numbers. |
In doc/pix/alien: shake alien.000[1-5].iff This will display the first 5 images simultaneously. In doc/pix/alien: shake [l-z]* This will display all images that start with the letters l to z, lower-case. |
Math
and Expressions When doing math on the command-line, enclose it in "quotation
marks":
In doc/pix/truck:
shake truck.iff -pan "cos(time*.5)*100" "sin(time)*50" -motion .5 1 -t 1-13
Multiple
Words When you want to use more than one word in a parameter that expects
a string (letters), again, use "quotation marks":
shake -addtext "kilroy was here"