FileIn/SFileIn
FIBlend/FINearest/FIPullUpDown/FISpeed/IRetime

Function
Shake uses the FileIn function to read in images from disk. It has a more advanced version with more functionality called SFileIn, which can be additionally modified by the invisible functions FIBlend, FINearest, FIPullUpDown and IRetime. These are "invisible" because they don't appear in the Node View, but are saved into the script to modify the FileIn and SFileIn functions.

 

Paths

Both the FileIn and SFileIn recognize local, absolute, variables, or URL paths:

If a frame cannot be found, a black frame the size the defaultWidth and Height will be used.

 

Image Sequences

If you want to refer to an image sequence, you can replace the frame number with a # sign or a @ sign. The # sign signifies a 4-place padded number, and the @ sign signifies an unpadded number. You may also use several @ signs to indicated padding to a different number, for example, 001 would be @@@. Here are some examples:

Image Shake Syntax
image.iff image.iff
image.1.iff, image.2.iff ... image.10.iff image.@.iff
image1.iff, image2.iff, ... image10.iff image@.iff
image.0001.cin, image.0002.cin, ... image.0010.cin image.#.cin
image.001.cin, image.002.cin, ... image.010.cin image.@@@.cin

These assume that there is an exact relation between the current frame processed in Shake, and the frame being read in, i.e., at frame 1, image.1 is being read in. When you read the images in with the GUI, a variation is used to set the sequence range. This will appear in the fileName field, for example,

Image Shake Syntax with Sequence Listing
image.4.iff, image.5.iff ... image.10.iff image.4-10@.iff
image.4, image.5.iff, image.6.iff, image.10.iff image.4-6,10@.iff

When reading in the image, the Browser allows you to specify if the first sequence image (let us suppose the sequence starts at frame 20) is placed at frame 1, start frame (i.e., 20), or the current frame.

 

Basic Time Shifting

With a FileIn, you can shift your clip in time and set in/out frames. As of 2.5, the FileIn button will be creating SFileIn functions. You typically shift your sequences using the Time View. However, the S/FileIn controls can also set the behavior of your frames before and after the sequence range.

icon Name Notes Example. This assumes a 5-frame sequence.
Black The frames will be black 1,2,3,4,5,black, black,black....
Freeze The first and last frames are repeated before and after the clip. 1,2,3,4,5,5,5,5....
Repeat The sequence is repeated 1,2,3,4,5,1,2,3....
Mirror The sequence is repeated, flipping the order each time. The first and last frames are not doubled up. 1,2,3,4,5,4,3,2...
InclusiveMirror The sequence is repeated, flipping the order each time. The first and last frames are shown twice in a row. 1,2,3,4,5,5,4,3...

For more information on shifting clips, see Interface - Time View.

 

Re-Timing

When you activate the reTiming parameter in SFileIn, you can squeeze, stretch, or non-linearly retime your clip. You can use Speed or Remap.

Both of these can blend frames with either Blend or Nearest mode. Blend will average frames together and Nearest will take the frame right below the called for frame, i.e., if frame 5.7 is called, frame 5 will be used.

 

Parameter Function
retimeMode By default, you are given two options for frame blending, which are dramatic "None", and the dazzling "Blending" which averages frames together. It's written so that others can input their own algorithms, so write your Congressman or MP.
weight A gamma curve is applied to the contribution of the source frames blended to create the destination frame. Gain of 0 means each source frame needed to create the destination contributes equally, while a higher gain, like 2, will cause the center frame to give the greatest contribution and frames farther away proportionately less.
range This controls how many frames beyond the normal averaging should be considered. For example, if you do a source clip of 20 frames, and you want to extend to 40 frames, each source frame would be considered in 2 output frames. With a range of 2, it would be considered in 4 output frames, giving you more blending. If you just apply this value with no other modifications, you get repetitions of neighboring frames, help you with degraining.
start/endFrame This specifies what frame range is to be considered for retiming purposes.
retime Indicates the actual frame being pulled in. Although the number is a float, the resulting frame is rounded.
speed Only available in Speed, this is a scaling factor to the clip length.

 

Understanding the Retiming Parameters If you are having difficulty understanding what the 8000 parameters are for Retiming, copy this string, paste it into the Node View, and then render out 100 frames.

Text1 = Text(300, 100, 1, "%f", "Courier", 44.3, xFontScale, 1, Hermite(0,[10,76.08,76.08]@1,[261,76.08,76.08]@100), Hermite(0,[90,-34.69,-34.69]@1,[30,-34.69,-34.69]@100), 0, 2, 2, 1, 1, 1, 1, 0, 0, 0, 45, 0, 1);

Then, read in this clip and test the retiming. Have fun...

 

 

Pulldown/PullUp

The 3:2 switch in SFileIn allows you to manage your pulldown/pullup of a sequence. 30 to 24 (Pullup) means you have received a film sequence that has been telecined to 30 fps. You now want to return it back to 24 fps. 24 to 30 (Pulldown) means you want to take 24 fps film footage and convert it for 30 fps. Both allow you to select which field will dominate. Typically, PAL is odd and NTSC is even.

What in blazes does pulldown mean? This is a technique to temporally convert (resolution not being considered here) film footage to video footage and back again. Given that film uses solid frames and video uses interlaced fields, and that film runs at 24 fps and NTSC runs at 30 fps, you split the film footage into fields and double up 2 out of 5 frames to increase your frames to fill the 30 fps. Let's use the classic graph:

1/6 of a second equals:

4 Film Frames A B C D  
           
5 Video Frames AA BB BC CD DD

We see that the third and fourth frames have fields blending in them to stretch time out. It's therefore called 3:2 because you have three solid frames and two mixed frames.

We can fully reconstruct our original four film frames (in time - we've lost the resolution) by extracting the field data from the five video frames. Here comes the odd bit. When you receive your footage, it has probably been edited, so it is not necessarily the case that frames three and four are the mixed frames because all of the clips have been shifted around in the edit. We therefore need to figure out what the first frame is. Go to your first five frames in the sequence. If the first frame to have field blending in them is frame three, you know your firstFrame should be set to AA. If the first frame to have field blending is frame two, then you know your first frame is BB. Set your firstFrame parameter accordingly. If your first frames are a solid color and you can't figure it out, you have to jump to a time range of frames that display the blending and start guessing what firstFrame is until the fields go away.

 

Proxies

The proxy system is explained under Overview - Proxies.

 

File Formats

Jump to Supported File Formats


FileIn Parameters:

Parameters
Type
Defaults
Function
imageName
string
  The local or absolute path to the image. See above for format. Note: You can get away with just supplying the imageName and omitting the others in the script.
fileFormat
string
"auto" This tells Shake what the format is if the title is ambiguous. Generally, you do not need to set this, as "Auto" will automatically detect the format. If you have a problem reading an image, try setting the format to correct this.
autoAlpha
int
0 If this is on (1), then Shake will create a solid alpha channel for images not containing an alpha channel. If the image already has an alpha channel, this parameter is ignored.
deInterlacing
int
0 This parameter is to be used when importing interlaced images and you intend to render with fieldRendering on. It will take the odd or even field of the image (counted from the top) and copies it over the other remaining field. It then does the same thing half a frame forward. You are therefore left with two images the same height as your input image, but squeezed into the same time frame. See About Video for more information.


Synopis

image FileIn ( 
  const char * imageName,
  const char * fileFormat,
  int autoAlpha,
  int deInterlacing,

  ...
);


image SFileIn ( 
  const char * imageName,
  const char * fileFormat,
  int autoAlpha,
  int deInterlacing,
  const char * version,
  int numberOfProxies,
  const char * proxy1DefaultFile,
  float proxy1DefaultScale,
  float proxy1DefaultAspect,
  const char * proxy1DefaultFormat,
  const char * proxy2DefaultFile,
  float proxy2DefaultScale,
  float proxy2DefaultAspect,
  const char * proxy2DefaultFormat,
  etc

  ...
);
image FIBlend (
  image image,
  char * retime,
  char * retimeStartFrame,
  char * retimeEndFrame,
  float range,
  flat weight,
  int retimeBytes,
  int reTiming,
  float speed
)



image FINearest (
  image image,
  char * retime,
  char * retimeStartFrame,
  char * retimeEndFrame
  int reTiming,
  float speed

)


image FIPullUpDown (
  image image,
  char * type,

  int dominance,
  int firstFrame

)


image IRetime (

  image image,

  float timeSlide,

  float inPoint,

  float outPoint,

  string inMode,

  string outMode

)


Script

image = FileIn( 
  "imageName", 
  "fileFormat", 
  autoAlpha,
  deInterlacing
 );

image = SFileIn( 
  "imageName", 
  "fileFormat", 
  autoAlpha,
  deInterlacing,
  numberOfProxies,
  "proxy1DefaultFile",
  proxy1DefaultScale,
  proxy1DefaultAspect,
  "proxy1DefaultFormat",
  "proxy2DefaultFile",
  proxy2DefaultScale,
  proxy2DefaultAspect,
  "proxy2DefaultFormat",
  etc
 ); 


Command Line

shake imageName imageName2 imageName3 etc....

See Also
FileOut