definition.tmc reference

ct.rb requires a specification file, called definition.tmc, that tells ct.rb about source imagery, It has two sections: the first describes the source imagery used for creating the time machine, and the second expresses video size, speed, and compression level.

Section 1: source

The source of the imagery for the time machine:  Is it stitched from local images?  Does it come from pre-stitched frames?  Does each frame come from a panorama already uploaded to

source, type: stitch

Each frame comes from a grid of images found in 0100-unstitched (or "images", if specified), stitched together.

"source": {
   "type": "stitch",
   "cols": number-of-cols,
   "rows": number-of-rows,
   "images": [[frame 0 images], [frame 1 images], ... [frame N images]] (optional)
   "directory_per_position": true-or-false (optional, default: false),
   "align_to" : align-to-expression,
   "align_to_comment": align-to-comment,
   "subsample": subsample-power-of-2 (optional, default: 1, for no subsampling),
   "rowfirst": true-or-false (optional, default: false),
   "stitcher_args": additional-stitcher-args (optional, default none),
   "camera_response_curve": camera-response-curve-filename (optional, default none),
   "width": individual frame width, in pixels, (optional)
   "height": individual frame height, in pixels (optional)

"images": [[frame 0 images], [frame 1 images], ... [frame N images]] (optional)
Specifies paths to all images to be stitched into the time machine's frames.  If omitted, images for each frame are read from separate subdirectories inside the subdirectory 0100-unstitched.

"directory_per_position": true-or-false (optional, default: false)
False for standard, single gigapan shooting in timelapse mode.  True for parallel capture with multiple cameras all taking pictures at the same time, in which case each camera's images must be in a separate folder in 0100-unstitched.  Folders must be in alphabetical order, in stitch order (typically, left to right).  Not applicable if "images" provided

"align_to": align-to-expression
"align_to_comment": align-to-comment
When aligning gigapans from multiple frames, all but one gigapans will be aligned against one or more "master" panoramas.  This expression, when evaluated in Ruby, must either be a list of integer indexes identifying one or more master gigapans for alignment via optical features, or the expression "copy(N)", which identifies a single gigapan from which to copy verbatim camera geometry (no optical feature matching).  Indexes start at 0.  Before evaluation, the variable "i" is bound to the index of the gigapan to be aligned, allowing expressions based on that index.  Negative indexes are ignored.
align_to_comment is meant to be a human-readable description of the function of the align_to expression.  It's not used by ct.rb.

"align_to": "i>0?[0]:[]",
"align_to_comment": "Align all gigapans to the first gigapan"
First gigapan (index 0) is stitched by itself.  All other gigapans are aligned optically to this first gigapan.

"align_to": "[i-1]",
"align_to_comment": "Align each gigapan to the previous one"
First gigapan (index 0) is stitched by itself.  Each successive gigapan is stitched, optically aligning to the previous gigapan (second to first, third to second, and so forth).

"align_to": "[(i-1)/10*10]",
"align_to_comment": "Align each gigapan to a master selected every 10 gigapans"
 First gigapan (index 0) is stitched by itself.  Gigapan 1-10 are stitched, optically aligning to 0, 11-20 are aligned to 10, and so forth.  Compared to [i-1], this allows more parallelism , likely drifts less, but is less robust in many circumstances.

"align_to": "copy(0)",
"align_to_comment": "Copy camera geometry from first gigapan"
First gigapan (index 0) is stitched by itself.  All other gigapans use camera geometry copied from the first gigapan.  This assumes the cameras have not moved, and can be useful for parallel capture with mutiple cameras mounted rigidly.

"stitcher_args": additional-stitcher-args (optional, default none)
A string with arguments inserted into the stitch commandline.  Typically used to modify the invocation of stitch to address automatic exposure

"stitcher_args": "--no-vignette-correction --equalize-exposure-using-exif --adjust-exposure 0.5"
Compensate for camera automatic exposure by equalizing exposure using EXIF tags.  Adjust resulting exposure brighter half a stop.  Turn off vignetting correction (turning off vignetting correction is a requirement when using equalize-exposure-using-exif).  Note that --equalize-exposure-using-exif also requires presence of a camera response curve, specified in the next section below.

"camera_response_curve": camera-response-curve-filename (required when using --equalize-exposure-using-exif)
The name of a file with the camera's response curve.  Optional, only used in the case of adding --equalize-exposure-using-exif in stitcher_args.  As of 9 March 2012, we've always simply used the Canon g10 response curve, even for other cameras.  Seems to work fine.

"camera_response_curve": "g10.response"

"width": individual frame width, in pixels,
"height": individual frame height, in pixels
Individual frame dimensions, in pixels.  As of February 2012, setting these each to the number 1 makes ct.rb auto-detect frame size after the first stitch is finished

"width": 1,
"height": 1

source, type: images

Unless specified in the optional "images" field, each frame is taken from an image in the directory 0100-original-images.  Frames are ordered alphabetically, by filename;  if your image filenames include a sequence number, be sure the sequence number uses leading zeros so it alphabetizes correctly.  Images may also be found in subdirectories under 0100-original-images, in which case each frame is ordered alphabetically by its relative path under 0100-original-images -- that is, alphabetized first by directory name and then filename.

"source": {
   "type": "images",
   "subsample": subsample-power-of-2 (optional, default: 1, for no subsampling),
   "images", [image1, image2, ... imageN] (optional, defaults to reading images from 0100-original-images)

source, type: prestitched

Prestitched means already converted to tiles, with .data directories in 0200-tiles.  Frames are ordered alphabetically, by filename;  if your frame filenames include a sequence number, be sure the sequence number uses leading zeros so it alphabetizes correctly.

"source": {
   "type": "prestitched",
   "subsample": subsample-power-of-2 (optional, default: 1, for no subsampling),

source, type:

Each frame is mirrored from a gigapan found at the website.  No alignment is performed.  Each gigapan must have identical size, and should be pre-aligned with each other. 

"source": {
   "type", ""
   "subsample": subsample-power-of-2 (optional, default: 1, for no subsampling),
   "urls": gigapan-urls

"urls": gigapan-urls
List of gigapan urls, in time order

"urls": [

Section 2: videosets

"videosets": [
   "label": "720p",
   "type": "h.264",
     "size": [
   "quality": 26,
   "fps": 25

quality (compression)
Valid compression levels range from 24 (lowest compression/highest quality) to 28 (highest compression/lowest quality).  Values outside this range may cause problems.
Lower compression / higher quality requires higher bandwidth and more storage space.  

28: low quality / low bandwidth
26: medium quality / medium bandwidth
24: high quality/high bandwidth.  This quality level can require too much bandwidth for a typical user when streamed over the internet at 25 FPS, but can work better for locally-served images or videos slower than 25 FPS

The playback rate of the final videos. For time machines with small number of frames, lower fps is recommended (3-6fps). 12fps for medium number of frames (< 500) and 25fps for large time machines (> 500 frames).

The width and height of the videos created. If you plan on streaming your time machines, it is not recommended to go larger than 1280x720 (720p) due to extreme bandwidth requirements and much increased client side processing.

Example complete definition file:

    "version": 1,
    "id":      "myTimeMachine",
    "label":   "My First Time Machine",
    "source":  {
        "type": "stitch",
        "cols" : 4,
        "rows" : 1,
        "align_to" : "copy(0)",
        "align_to_comment": "Align to 1st gigapan",
        "stitcher_args": "--no-vignette-correction --adjust-exposure 1",
        "width" : 1,
        "height" : 1
    "videosets": [
            "label": "816x468",
            "type": "h.264",
             "size": [
            "quality": 26,
            "fps": 6