Making animations — GMT Examples documentation (2025)

2.3.1. What is GMT movie?

The movie module simplifies most of the steps needed to create an animationby executing a single plot script that is repeated across all frames.

Required Arguments:

• mainscript: Script that will be used to create all the frames.

• -N: Name for the output file.

• -C: Canvas Size (see below).

• -T: Number of frames (see below).

• There are two types of outputs. An image (called master frame; -M) or a video (-F). You have to ask for at least one of them.

Optional Arguments (useful for this tutorial):

• -G: Set the canvas color (or fill).

• -V: Show verbose information during the movie-making process.

• -L: Show a label with the frame number.

2.3.2. First Attempt

In the first attempt, I create the first frame (-M0,png) over a black canvas (-Gblack) for an HD video format (-Chd).

cat << 'EOF' > main.shgmt begin gmt grdimage @earth_relief_06m -I -JG0/0/13cgmt endEOFgmt movie main.sh -NEarth -Chd -T360 -M0,png -V -L+f14p,Helvetica-Bold,white -Gblack

2.3.3. The Canvas

What is the Canvas?

• The canvas is the black area of the previous image.

• This is the working area of the frames.

• The elements of the main script must be drawn inside the canvas.

• The elements that are outside will be (totally or partially) hidden in the animation.

• The canvas size is important by two reasons:

  • to set the width and height (in cm or inches) of the frames.

  • to set the dimensions in pixels of the frames/movie (i.e. the quality).

How to set the canvas:

• This is set via movie -C.

• There are two ways to the set the canvas:

  • Preset formats

  • Custom format

Preset formats:

• It is the easiest way to specify the canvas.

• Use the name (or alias) to select a format based on this table (for 16:9 format):

Preset format (alias)	Pixel dimensions	DPC
4320p (8k and uhd-2)	7680 x 4320	320
2160p (4k and uhd)	3840 x 2160	160
1080p (fhd and hd)	1920 x 1080	80
720p	1280 x 720	53.3333
540p	960 x 540	40
480p	854 x 480	35.5833
360p	640 x 360	26.6667
240p	426 x 240	17.75

• Pixel density (dots-per-cm, dpc) is set automatically.

• For the 16:9 format, the canvas is 24 x 13.5 cm:

  Source Code

Custom format:

• If you want another dimension, you can request a custom format directly by giving width and height and dpu (widthxheightxdpu).

2.3.4. Second attempt. Fix the canvas

For this new attempt I:

• use a custom canvas of a square of 13 cm and 80 dpc (same resolution as full hd, -C13cx13cx80).

• use -X0 and -Y0 (in main.sh) to remove the default offset.

  cat << 'EOF' > main.shgmt begin gmt grdimage @earth_relief_06m -I -JG0/0/13c -X0 -Y0gmt endEOFgmt movie main.sh -NEarth -C13cx13cx80 -T360 -M0,png -V -L+f14p,Helvetica-Bold,white -Gblack

2.4.1. First attempt

In this step I reduce the number of frames to 10 (-T10) and the quality to 30 DPC (-C13cx13cx30).Also, I add the following arguments to movie:

• -Fmp4: to create a mp4 video (now it is possible to delete -M).

• -Zs: to remove the temporary files created in the movie-making process. Useful to keep the working directory clean.

  cat << 'EOF' > main.shgmt begin gmt grdimage @earth_relief_06m -I -JG0/0/13c -X0 -Y0gmt endEOFgmt movie main.sh -NEarth -C13cx13cx30 -T10 -M0,png -V -Gblack -L+f14p,Helvetica-Bold,white -Fmp4 -Zs

2.4.2. Movie Parameters

The movie parameters are key to making animations.They are automatically assigned by different movie arguments (see tables below).There are two sets of parameters:

Variable parameters:

• These values change with the frame number.

• They must be used in the main script to introduce variations in the frames.

Parameter	Purpose or contents	Set by Movie
MOVIE_FRAME	Number of current frame being processed	-T
MOVIE_TAG	Formatted frame number (string)	-T
MOVIE_NAME	Prefix for current frame image	-N and -T
MOVIE_COLk	Variable k from data column k, current row	-Ttimefile
MOVIE_TEXT	The full trailing text for current row	-Ttimefile
MOVIE_WORDw	Word w from trailing text, current row	-Ttimefile

Constant parameters:

• These values do NOT change during the whole movie.

• They can be used in the main script (and in the optional background and foreground scripts).

Parameter	Purpose or contents	Set by Movie
MOVIE_NFRAMES	Total number of frames in the movie	-T
MOVIE_WIDTH	Width of the movie canvas	-C
MOVIE_HEIGHT	Height of the movie canvas	-C
MOVIE_DPU	Dots (pixels) per unit used to convert to image	-C
MOVIE_RATE	Number of frames displayed per second	-D

2.4.3. How to set the number of Frames

The number of frames (-T) is another important aspect to make animations.There are 3 ways to do it:

1. -TNumber:

If you supply a single (integer) value, then it will be the total number of frames.Under the hood, this will create a one-column data set from 0 to that number minus one.For example, for -T10 I get values from 0 to 9.In the main script, you have to use the MOVIE_FRAME parameter to access the values.

2. -Tmin/max/inc:

If you supply 3 values, then GMT will create a one-column data set from min to max, incrementing by inc.You have to use the MOVIE_COL0 parameter to access the values of the one-column data set.The total of number of frames will be:

\[\text{total frames} = \frac{\text{max} - \text{min}}{\text{inc}} + 1\]

3. -Ttimefile:

If you supply the name of a file, then GMT will access it and use one record (i.e. row) per frame.This method allows you to have more than one-column and can be used to make more complex animations.For example, you can have a second column with numbers that you can access using MOVIE_COL1.The file can even have trailing text that will be accessed with MOVIE_TEXT.

2.4.4. Second attempt. Use parameters

Now I update the script with movie parameters.First, I use the MOVIE_FRAME variable parameter to set the central longitude of the map.I also use the MOVIE_WIDTH constant parameter (in main.sh) to set the width of the map (instead of 13c).

cat << 'EOF' > main.shgmt begin gmt grdimage @earth_relief_06m -I -JG-${MOVIE_FRAME}/0/${MOVIE_WIDTH} -Y0 -X0gmt endEOFgmt movie main.sh -NEarth -C13cx13cx30 -T10 -M0,png -V -Gblack -L+f14p,Helvetica-Bold,white -Fmp4 -Zs

3.3.1. First attempt (first frame)

In this first attempt I create the first frame (-Mf,png) of the animation.

cat << 'EOF' > main.shgmt begin # Set parameters and position gmt basemap -Rg -JN${MOVIE_WIDTH} -B+n -X0 -Y0 # Create background map gmt grdimage @earth_relief_06m -I # Create cpt for the earthquakes gmt makecpt -Cred,green,blue -T0,70,300,10000 gmt plot @quakes_2018.txt -SE- -Cgmt endEOFgmt movie main.sh -NQuakes -Mf,png -Zs -V -C24cx12cx80 -T2018-01-01T/2018-12-31T/1d -Gblack \-Lc0 --FONT_TAG=18p,Helvetica,white --FORMAT_CLOCK_MAP=-

3.3.2. The events module

In the previous figure, I use the plot module to draw the symbols. This results that the symbols appear on all frames.However if I want to plot quakes as they unfold, I have to use the events instead.

3.3.3. Second attempt (first frame with events)

Now, in this attempt I use events with -T${MOVIE_COL0} to plot the quakes as dates progresses

cat << 'EOF' > main.shgmt begin # Set parameters and position gmt basemap -Rg -JN${MOVIE_WIDTH} -B+n -X0 -Y0 # Create background map gmt grdimage @earth_relief_06m -I # Create cpt for the earthquakes gmt makecpt -Cred,green,blue -T0,70,300,10000 gmt events @quakes_2018.txt -SE- -C -T${MOVIE_COL0}gmt endEOFgmt movie main.sh -NQuakes -Mf,png -Zs -V -C24cx12cx80 -T2018-01-01T/2018-12-31T/1d -Gblack \-Lc0 --FONT_TAG=18p,Helvetica,white --FORMAT_CLOCK_MAP=-

3.3.4. Third attempt (last frame with events)

Now, I also plot the last frame (-Ml).

cat << 'EOF' > main.shgmt begin # Set parameters and position gmt basemap -Rg -JN${MOVIE_WIDTH} -B+n -X0 -Y0 # Create background map gmt grdimage @earth_relief_06m -I # Create cpt for the earthquakes gmt makecpt -Cred,green,blue -T0,70,300,10000 gmt events @quakes_2018.txt -SE- -C -T${MOVIE_COL0}gmt endEOFgmt movie main.sh -NQuakes -Ml,png -Zs -V -C24cx12cx80 -T2018-01-01T/2018-12-31T/1d -Gblack \-Lc0 --FONT_TAG=18p,Helvetica,white --FORMAT_CLOCK_MAP=-

3.4.1. First attempt

cat << 'EOF' > main.shgmt begin # Set parameters and position gmt basemap -Rg -JN${MOVIE_WIDTH} -B+n -X0 -Y0 # Create background map gmt grdimage @earth_relief_06m -I # Create cpt for the earthquakes gmt makecpt -Cred,green,blue -T0,70,300,10000 gmt events @quakes_2018.txt -SE- -C -T${MOVIE_COL0}gmt endEOFgmt movie main.sh -NQuakes -Ml,png -Zs -V -C24cx12cx30 -T2018-01-01T/2018-12-31T/1d -Gblack \-Lc0 --FONT_TAG=18p,Helvetica,white --FORMAT_CLOCK_MAP=- -Fmp4

3.4.2. The background script

Within movie module, there is an optional background (-Sb) script that it is used for two purposes:

1. Create files that will be needed by the main script to make the movie.

2. Make a static background plot that should form the background for all frames.

3.4.3. Second attempt (with background script)

In this step, instead of creating just the main script as before, I now create both a background script and a main script.The background script (pre.sh) is used to:

1. create a CPT file that will be used to color the quakes.

2. make a static worldwide background map.

cat << 'EOF' > pre.shgmt begin # Set parameters and position gmt basemap -Rg -JN${MOVIE_WIDTH} -X0 -Y0 -B+n # Create background map gmt grdimage @earth_relief_06m -I # Create cpt for the earthquakes gmt makecpt -Cred,green,blue -T0,70,300,10000 -H > quakes.cptgmt endEOFcat << 'EOF' > main.shgmt begin gmt basemap -Rg -JN${MOVIE_WIDTH} -X0 -Y0 -B+n gmt events @quakes_2018.txt -SE- -Cquakes.cpt -T${MOVIE_COL0}gmt endEOFgmt movie main.sh -Sbpre.sh -NQuakes -Ml,png -Zs -V -C24cx12x80 -T2018-01-01T/2018-12-31T/1d -Gblack \-Lc0 --FONT_TAG=18p,Helvetica,white --FORMAT_CLOCK_MAP=-

3.6.1. How to enhance symbols with events

The idea is to change the default behavior of the symbols to enhance their appearance as shown in the following video:

This can be done by using -M and -E arguments.The -M arguments allows to temporarily change attributes of the symbol like:

• -Ms: Provide a factor to modify the size.

• -Mc: Provide a value to brighten (up to 1) or darken (up to -1) the color intensity.

• -Mt: Transparency. Set a value between 100 (invisible) to 0 (opaque).

The duration of the temporary changes is controlled via the -E argument.

• -Er: rise phase. It takes place before the start of the event.

• -Ep: plateau phase. It takes place after the start of the event.

• -Ed: decay phase. It develops after the plateau phase. If the plateau phase does not occur, then it takes place after the start of the event.

3.6.2. Make full animation

In this step I announce each quake by magnifying size and whitening the color for a little bit (during the rise phase).Later the symbols return to their original properties during the decay phase.The plateau phase is not used.

cat << 'EOF' > pre.shgmt begin # Create background map gmt grdimage @earth_relief_06m -I -JN${MOVIE_WIDTH} -Rg -X0 -Y0 # Create cpt for the earthquakes gmt makecpt -Cred,green,blue -T0,70,300,10000 -H > quakes.cptgmt endEOFcat << 'EOF' > main.shgmt begin gmt basemap -Rg -JN${MOVIE_WIDTH} -X0 -Y0 -B+n gmt events @quakes_2018.txt -SE- -Cquakes.cpt -T${MOVIE_COL0} -Es+r2+d6 -Ms5+c1 -Mi1+c0 -Mt+c0 --TIME_UNIT=dgmt endEOFgmt movie main.sh -Sbpre.sh -NQuakes -Ml,png -Zs -V -C24cx12cx80 -T2018-01-01T/2018-12-31T/1d -Gblack -Fmp4 \-Lc0 --FONT_TAG=18p,Helvetica,white --FORMAT_CLOCK_MAP=-