gmt-fork/doc/GMT_Chapter_8.tex

%------------------------------------------
%	$Id$
%
%	The GMT Documentation Project
%	Copyright (c) 2000-2012.
%	P. Wessel, W. H. F. Smith, R. Scharroo, and J. Luis
%------------------------------------------
%
\chapter{Creating GMT Animations}
\label{ch:8}
\thispagestyle{headings}

Unlike the previous chapter, in this chapter we will explore
what is involved in creating animations (i.e., movies).  Of course,
an animation is nothing more than a series of individual images
played back in an orderly fashion.  Here, these images will have
been created with \GMT.  To ensure a smooth transition from frame
to frame we will be following some general guidelines when writing
our scripts.  Since there is no ``movie'' mode in \GMT\ we must take
care of all the book-keeping in our script.  Thus, animations may
require a bit of planning and may use more advanced scripting than the
previous static examples.  Note: This is a new chapter introduced with the
4.4.0 version and should be considered work in progress.

Most, if not all, animation scripts must deal with several specific
phases of movie making:
\begin{enumerate}
	\item Define parameters that determine the dimension of the final movie.
	\item Pre-calculate all variables, data tables, grids, or background
	map layers that are \emph{independent} of your time variable.
	\item Have a frame-number loop where each frame is created as a \PS\ plot,
	then rasterized to a TIFF file of chosen dimension.
	\item Convert the individual frames to a single movie of suitable format.
	\item Clean up temporary files and eventually the individual frames.
\end{enumerate}

We will discuss these phases in more detail before showing our first example.

% changes the format used by the counter:
\let\oldenumi\labelenumi
\renewcommand{\labelenumi}{\textbf{\arabic{enumi}.}}
\begin{enumerate}
\item There are several coordinates that you need to consider when planning
your movie.  The first is the coordinates of your data, i.e., the \emph{user
coordinates}.  As with all \GMT\ plots you will transform those to the
second set of \emph{plot coordinates} 
in inches (or cm) by applying a suitable region and map projection.  As
before, you normally do this with a particular paper size in mind.  When
printed you get a high-resolution plot in monochrome or color.
However, movies are not device-independent and you must finally consider
the third set of \emph{pixel coordinates} which specifies the resolution of the final movie.
We control the frame size by selecting a suitable \emph{dpi} setting that
will scale your physical dimensions to the desired frame size in pixels.
If you decide up front on a particular resolution (e.g., 480 by 320 pixels)
then you should specify a paper size and \emph{dpi} so that their product yields the desired pixel dimensions.
For instance, here it might make sense to plan your plotting on a 4.8 by 3.2 inch ``paper''
and use 100 \emph{dpi} to convert it to pixels, but you are free to use any combination
that multiplies to the desired dimensions.  After deciding on frame size you need
to consider how many frames your movie should have.  This depends on lots of things
such as how patient you are, how many frames per second you need and the time
range of your animation.  We recommend you use variables to specify the items that
go into computing the number of frames so that you can easily test your script
with a few frames before changing settings and running the full Hollywood production overnight.
\item Depending on what you want to display, there are usually many elements that
do not change between frames.  Examples include a coastline base map for background,
an overlay of text legends, perhaps some variables that hold information that will
be used during the movie, and possibly subsets of larger data sets.  Since movie-making
can take a long time if you are ambitious, it is best to compute or plot all the
elements that can be done outside your main frame-loop rather than waste time
doing the same thing over and over again.  You are then ready for the main loop.
\item Initialize a frame counter to 0 and have a loop that continues until
your frame counter equals the desired number of frames.  You must use your frame
counter to create a unique file name for each frame image so that the series of
images can be lexically arranged.  We recommend using the \GMT\ shell function
\progname{gmt\_set\_framename} to format the frame counter
with an adequate number of leading zeros; see our examples for details.  The
bulk of your main loop involves create the single \PS\ plot for this particular
frame (time).  This can be trivial or a serious scripting exercise depending on
what you want to show.  We will give a few examples with increasing complexity.
Once the \PS\ plot is created you need to rasterize it; we recommend you use
\GMTprog{ps2raster} to generate a TIFF image at the agreed-upon resolution.
We also recommend that you place all frame images in a sub-directory. You may increment
your frame counter using \progname{gmt\_set\_framenext}.
\item Once you have all your frames you are ready to combine them into an animation.
There are two general approaches. (a) If your image sequence is not too long then
you can convert the images into a single animated GIF file.  This file can be
included in PowerPoint presentations or placed on a web page and will play back
as a movie by pausing the specified amount between frames, optionally repeating
the entire sequence one or more times. (b) For more elaborate projects
you will need to convert the frames into a proper movie format such as Quicktime,
AVI, MPEG-2, MPEG-4, etc., etc.  There are both free and commercial tools that
can help with this conversion and they tend to be platform-specific.  Most movie
tools such as iMovie or MovieMaker can ingest still images and let you specify
the frame duration.  Under OS X we prefer to use Quicktime.\footnote{While Quicktime
is free you must upgrade to QuickTime Pro (USD 30) to use the authoring functions.}  Free
tools exist to call the Quicktime library functions from the command line as we
prefer to do in our scripts.  You will find yourself experimenting with compression
settings and movie formats so that the final movie has the resolution and portability
you require.
\item Finally, when all is done you should delete any temporary files created.
However, since creating the frames may take a lot of time it is best to not automatically
delete the frame sub directory.  That way you can
redo the frames-to-movie conversion with different settings until you are satisfied.
\end{enumerate}
\renewcommand{\labelenumi}{\oldenumi} % reset the format used by the counter

\section{Animation of the sine function}
\index{Example!animation of the sine function|(}

Our first animation is not very ambitious: We wish to plot the sine
function from 0--360\DS\ and take snap shots every 20\DS.  To get a
smooth curve we must sample the function much more frequently; we
settle on 10 times more frequently than the frame spacing.  We place
a bright red circle at the leading edge of the curve, and as we move
forward in time (here, angles) we dim the older circles to a dark red
color.  We add a label that indicates the current angle value.  Once
the 18 frames are completed we convert them to a single animated GIF file
and write a plain HTML wrapper with a simple legend.  Opening the HTML
page \filename{anim01.html} in the browser will display the animation.

\script{anim_01}

Make sure you understand the purpose of all the steps in our script.
In this case we did some trial-and-error to determine the exact values
to use for the map projection, the region, the spacing around the frame,
etc. so that the final result gave a reasonable layout.  Do this planning
on a single \PS\ plot before running a lengthy animation script.

\GMTanimation{01}{Animation of a simple sine function.}

\index{Example!animation of the sine function|)}

\section{Examining DEMs using variable illumination}
\index{Example!examining DEMs using variable illumination|(}

Our next animation uses a gridded topography for parts of Colorado (US);
the file is distributed with the tutorial examples.  Here, we want to
use \GMTprog{grdimage} to generate a shaded-relief image sequence in
which we sweep the illumination azimuth around the entire horizon.  The
resulting animation illustrates how changing the illumination azimuth
can bring out subtle features (or artifacts) in the gridded data.  The
red arrow points in the direction of the illumination.

\script{anim_02}

As you can see, these sorts of animations are not terribly difficult to
put together, especially since our vantage point is fixed.  In the next
example we will move the ``camera'' around and must therefore deal with
how to frame perspective views.

\GMTanimation{02}{Animation of a DEM using variable illumination.}

\index{Example!examining DEMs using variable illumination|)}

\section{Orbiting a static map}
\index{Example!Orbiting a static map|(}

Our third animation keeps a fixed gridded data set but moves the camera
angle around the full 360\DS.  We use \GMTprog{grdview} to generate a
shaded-relief image sequence using the new enhanced \Opt{E} option.
No additional information is plotted on the image.  As before we produce
an animated GIF image and a simple HTML wrapper for it.

\script{anim_03}

\GMTanimation{03}{Orbiting a static map.}

\index{Example!Orbiting a static map|)}

\section{Flying over topography}
\index{Example!Flying over topography|(}

Our next animation simulates what an imaginary satellite might see as it passes
in a great circle from New York to Miami at an altitude of 160 km.
We use the general perspective view projection with \GMTprog{grdimage} and
use \GMTprog{project} to create a great circle path between the two cities,
sampled every 5 km.  The main part of the script will make the DVD-quality frames from
different view points, draw the path on the ground, and add frame numbers to
each frame.  As this animation generates 355 frames we can use 3rd party tools
to turn the image sequence into a MPEG-4 movie\footnote{QuickTime Pro can do this,
as can most video-editing programs.}. Note: At the moment, \GMTprog{grdview} cannot
use general perspective view projection to allow ``fly-through'' animations like
Fledermaus; we expect to add this functionality in a future version.

\script{anim_04}

\GMTanimation{04}{Flying over topography.}

\index{Example!Flying over topography|)}