Creating Time Machines

There are many types of source imagery for your time machine:
  • Grid of images to stitch
  • Single camera, fixed capture
  • Multiple camera, fixed capture
  • Already stitched and aligned.  Use this if you're using a third-party stitching app, or have imagery from a different source, like satellites.

This page addresses how to stitch (if needed) and create an explorable time machine from your source imagery.

Latest version: 1.3.0
Released: July 08, 2015

1.  Installing the Time Machine Creator Software

         Updating Time Machine Creator

Download the latest *.dmg release (link below), double click it, drag the program icon over the Applications directory and say yes to overwrite.

Download and extract the latest release (link below) and either create a new directory for it or overwrite the one you are currently using.

Verify you're running the latest version by going to "Help, About" from inside the program. The version there should match the version at the top of this page.

Installing Time Machine Creator on Mac (OS X 10.6+)

  1. Download the latest Time Machine Creator for Mac OS.
  2. Double-click the DMG to open it, and you should see it mount and display as if you plugged in an external drive or inserted a CD-ROM.
  3. A window will come up with two icons.  Drag the Time Machine Creator icon over to your Applications folder icon to install it.  When you do this, you may be prompted to supply your administrator username and password.
  4. Once the software has been successfully copied to your Applications folder, close the DMG file's window and then drag the Time Machine Creator disk image to the Trash or click the Eject button in the Finder sidebar to eject it.
  5. At this point you can now run the Time Machine Creator from your Applications folder.  You now can delete the DMG file you downloaded or store it somewhere in case you need to reinstall the program again.
  6. If you need to stitch, you'll need to purchase a Stitch 2.x license key and download the software from here.

    Installing Time Machine Creator on Windows (XP and beyond)

    1. Download the latest Time Machine Creator for Windows.
    2. Right click the ZIP file and choose "Extract All" from the menu.
    3. A window will come up.  Click Extract.
    4. Once successful, a new window will come up with several folders and a file called tmc.exe (it'll have a blue icon).
    5. Double-click the tmc icon to run the software.
    6. Keep in mind that wherever you extracted the software to is where it is now installed.  If you would like to install it in another location, copy the entire folder to a location of your choice.  You now can delete the ZIP file you downloaded or store it somewhere in case you need to reinstall the program again.
    7. If you need to stitch, you'll need to purchase a Stitch 2.x license key and download the software from here.

    Installing Time Machine Creator on Linux

    1. Make a directory for Time Machine Creator, e.g. /usr/local/tmc, or ~/tmc
    2. Download the latest Time Machine Creator for Linux into the directory and untar (tar xvfz tmc-NNN-linux.tgz)
    3. If you want to use the graphical version of the software, run '' from a terminal.  This will launch the software.  If you want to use the command-line version, scroll down to find instructions on using it.
      • Note: The graphical version is compiled for a 64bit Ubuntu 14.x install.  It may also work with older Ubuntu releases, and other related Debian versions, but there are no guarantees.  The command-line version should work on any recent Linux system though.
    4. If you need to stitch, you'll need to purchase a GigaPan Stitch 2.x license key from here.  You can download the latest Linux Stitch from here, and place it in the directory you created in step 1 so that the time machine creator can find it.  Untar with tar xvfz gigapan-NNN-linux.tgz
      • Note: The version of Stitch provided here is for 64bit versions of Linux.
    5. If you want to stitch imagery and don't have an X display for the stitcher, you'll need to install the Xvfb virtual X server.  On Ubuntu, you can install it via sudo apt-get install xvfb

    2.  Using the Time Machine Creator Software

    The Time Machine Creator software can be used via the command-line or through a graphical interface.  Note: Currently only single camera-fixed capture OR input imagery which is already stitched and aligned are supported by the graphical version of the software.  If you do have source imagery that the graphical version does not support, then you can still create a time machine, but only through a more manual process (though still quite easy) via the command-line.  Scroll down to see the command-line instructions.

    A. Graphical Version:

          Organizing Images

    1. Drag and drop your image files (or a folder of images) into the rectangle.  Only .jpg and .png files are supported.
    2. You can also add images/folders via the File menu, as well as gain access to other program specific options.
    3. Once you've added images, they will appear here in the main timeline mode.  Here you can scroll up and down through time.  3a displays the timeline for the set of images with which you're working. If you have images that were manually stitched or contain invalid exif time data, then the timeline will be absent and images will instead be displayed sorted by file name.
    4. Clicking this brings up the slideshow mode.  This is another mode for viewing your images.  In this mode, you can click the next/previous buttons or use the arrow keys on your keyboard.  You can also jump to a specific point in time.
    5. Once you've organized your images and are ready to create a time machine, click the "Render and Export" tab at the top.


          Rendering Your Time Machine

    1. Here you can modify the settings for your time machine.  The default settings are usually fine, but click the info icon under each option for more information.
    2. Once you're happy with the settings, click the "Create Time Machine" button to start the process.  Once you click this button, you will be unable to modify your setup or change any of the images while it's processing.
    3. You can pause the rendering at any time and then resume at a later point.
    4. You can also cancel the render if you want to start over from scratch (i.e. wrong settings selected, more images needed, etc)


          Viewing Your Time Machine

    1. Once rendering is complete, you can view your time machine by clicking this button, which will launch a web browser. Chrome is recommended, but all major browsers are supported.
      • The "View Time Machine" button is always available on this screen for projects that are completed.  To view another completed time machine, just load that project from the File menu and go to this tab to view it.
    2. If you want to re-render your current project (eg. change settings, add/remove images) click this button.
    3. If you want to create a new time machine, go to the File menu and choose "New Project".


    B. Command-line Version (advanced users):

          Test your Time Machine Creator installation

    From the command-line cd to the 'ct' directory (inside the Time Machine Creator directory) and run:

    ruby ct.rb --selftest

    If all tests show "success", then everything is setup properly.

    Important: If you do not have GigaPan Stitch installed, then that test will fail.  If you do not need stitching, you can ignore the message and continue on, assuming this was the only test that failed.

          Create your Time Machine directory and definition file

    Create a directory for your Time Machine, ending with .tmc (e.g. plants.tmc), and place inside this directory a file called definition.tmc.  This definition file describes the image sources, video sizes, frame rate, and compression level.  This page will show you how to create your definition.tmc file.  Depending on how you define your image sources in this file, you may need to create a 0100-unstitched or 0100-original-images directory in which to place your source images.

          Run ct.rb

    To create the explorable time machine video, run ct.rb like so (from inside the 'ct' directory)
    ruby ct.rb NAME.tmc NAME.timemachine

    Speeding things up by using multiple cores
    If you have a computer with multiple cores and plenty of RAM, you can compile significantly faster by adding the -j N flag to your ct.rb invocation.  Set N to be the number of tasks you want to run in parallel.  A good rule of thumb is to go with the smaller of (a) how many CPU cores you have total, and (b) the total amount of RAM you have, divided by 2 gigabytes.

    Speeding things up even more by using multiple machines
    If you have multiple computers that share a common network file system, it's possible for ct.rb to farm out tasks to multiple machines.  To enable this, you need to include the --remote flag, and probably the -r flag, to ct.rb.  --remote tells ct.rb to give all tasks to execute to the submit_synchronous command, which is assumed to be in your path.  We have versions of submit_synchronous for two popular clustering systems, and would be happy to help you develop a version for your own setup.  -rN tells ct.rb to aggregate multiple tasks together when calling submit_synchronous -- it improved efficiency in the case where there is time overhead to start a remote process.  We typically use -r 10.  And of course, you'll want to increase the number of parallel jobs with -j to match the total number of parallel jobs all your machines can handle at once.

          View your time machine

    ct.rb creates the NAME.timemachine folder, which contains all the data needed to serve your time machine, and also includes the file view.html, which will display your time machine.  You can open view.html in Chrome (or Safari) to explore your time machine.  

    3. Serving Your Time Machine

    All you really need to do is copy the .timemachine folder to a web server, point people to view.html (inside the .timemachine directory) and you should be set.  We're very happy to host your time machine at -- just email us to let us know if you'd like to upload your time machine.