Updated 2012/06/05: This version of FigureGen has become outdated, but is maintained on this page for reference. Please click here to be redirected to the newest version.
FigureGen is a FORTRAN program that creates images for ADCIRC output files. It reads sparse (fort.63, fort.64, etc.) and full (maxele.63, maxwvel.63, etc.) output files, grid (fort.14, etc.) files, and nodal attributes (fort.13) files. It plots contours, contour lines, and vectors. Using FigureGen, you can go directly from the ADCIRC input and output files to a presentation-quality figure, for one or multiple time snaps, without having to use SMS.
The following example depicts the wind reduction factors for our hurricane runs in southeast Louisiana:
Directional wind reduction factors in the northern Gulf of Mexico.
This program started from a script written by Brian Blanton. I converted it to FORTRAN because I am more familiar with that language, and I added the capability to plot vectors, among other things. But, at its core, FigureGen behaves like a script, and it uses system calls to tell other software how to generate the figure(s).
NOTE TO EXISTING USERS: The latest version of FigureGen is not backward-compatible with input files for previous versions. I’m sorry, but I think the new format of the input file will be better going forward. You will need to update previous input files. I have provided examples using the new format below.
Examples Using Version 26:
8. Grid and Colored Contour Lines of Bathy/Topo. Read an ADCIRC grid file and plot the grid itself. Add contours, and color them based on the bathymetry/topography itself. Note that this plot combines two new features. First, the grid is plotted by turning on the plot grid flag in the input file. The grid can be combined with the other options in FigureGen, including contours, contour lines, etc.
- FG26_08_Files
- FG26_08_Grid-Contours_SL15v7l_SELA.inp
- TopoRainbow.pal
- TopoRainbow.txt
Second, the bathymetry/topography contour lines are plotted by specifying the grid file as the contour file, setting the contour file format to GRID-BATH, and setting the color lines flag to CONTOUR-LINES. This combination of settings tells FigureGen to read the grid file and plot the contour lines of bathymetry/topography. The last setting tells FigureGen to use the color palette on the contour lines, instead of plotting them in black. Note that the color lines flag requires GMT 4.3.0.
7. Grid with Bathy/Topo Coloring. Read an ADCIRC grid file and plot the grid itself. Instead of black lines, color the grid lines based on the bathymetry/topography. Note that we must combine several settings to produce this plot. The plot grid flag is activated, all of the contours are deactivated, the grid file is specified as the contour file, and the contour file format is set to GRID-BATH.
- FG26_07_Files
- FG26_07_Grid-Bath_SL15v7l_SELA.inp
- TopoRainbow.pal
- TopoRainbow.txt
Finally, we also set the color lines flag to GRID-BATH. This setting tells FigureGen to color the grid lines based on the bathymetry. (Alternatively, we could generate a similar plot of the grid sizes by changing these settings to GRID-SIZE.) Note that the color lines flag regures GMT 4.3.0.
6. Contours of Grid Sizes. Read an ADCIRC grid file and plot contours of the grid sizes. Note that the grid file is also specified as the contour file, and then the contour file format is set to GRID-SIZE. This tells FigureGen to compute the grid sizes as it reads the grid file. GMT needs contour data at the nodes, so the grid sizes are averaged onto each node before plotting.
- FG26_06_Files
- FG26_06_Grid-Size_SL15v7l_SELA.inp
- Default2.pal
- GridSize.txt
5. Bathy/Topo Contours with Labels of Landmarks. Read an ADCIRC grid file and plot contours of the bathymetry/topography. Then add labels as directed by an external file. Note that the labels are controlled by a line near the bottom of the input file. The user can specify the color and the file name of the labels. This external file contains the longitudes, latitudes, text sizes, rotation angles, font numbers (from GMT), justifications, and text. Note that the justification is a two-letter combination of Left/Center/Right and Top/Middle/Bottom.
- FG26_05_Files
- FG26_05_Bath_SL15v7l_SELA.inp
- TopoBlueGreen.pal
- TopoBlueGreen.txt
- Labels.txt
4. Manning’s n from the fort.13 File. Read the ADCIRC nodal attributes file and plot the Manning’s n values. Note that we specify the fort.13 file as the contour file, and we set the format to 13-MANNING. We can plot the wind reduction factors and canopy values using similar commands.
- FG26_04_Files
- FG26_04_ManningsN_SL15v7l_SELA.inp
- Default2.pal
3. Wind Reduction Factors from the fort.13 File. Read the ADCIRC nodal attributes file and plot one or more columns of the wind reduction factors. Note that we specify the fort.13 file as the contour file, and we set the format to 13-WIND-REDUCTION-4. The last number in that string specifies the column to plot, so we are plotting the wind reduction factors from the fourth column (which corresponds to northward winds).
- FG26_03_Files
- FG26_03_WindReduction_SL15v7l_SELA.inp
- Default2.pal
- Coastline.dat
To plot all 12 columns, set the contour file format to 13-WIND-REDUCTION. Then you can use the ImageMagick command:
convert *.jpg WindReduction.gif
to create an animation like the image at the top of this page. Also note that we are adding a white coastline to the figure. This addition is controlled by a line near the bottom of the input file, and the user can select the color and specify the file name for the coastline. (However, any file containing lon,lat pairs could be visualized using this feature.)
2. Difference Plots. Read ADCIRC files and plot contours of the differences between the two files. If the files have the same number of nodes, then this feature will work on output files, grid files (for bathymetry only), and fort.13 files. In this example, we plot the differences between the maximum water levels from a fully coupled simulation and a simulation without wave effects.
- FG26_02_Files
- FG26_02_Katrina_MaxEleDiff_SELA.inp
- Default2.pal
- MaxEleDiff.txt
1. Hurricane Water Levels and Winds. Read ADCIRC output files and plot the contours of water levels and vectors of winds. Note that FigureGen accepts a broad range of ADCIRC output files. Anything that is formatted like a fort.63 or fort.64 file will work for the contours, and anything that is formatted like a fort.64 file will work for the vectors. Remember to specify either full (all nodes listed) or sparse (only wet nodes listed) format in the input file.
- FG26_01_Files
- FG26_01_Katrina_Ele-Wind_SELA.inp
- Default2.pal
System Requirements:
1. GMT
GMT is the software package that plots the contours, contour lines, etc and produces a PostScript file (*.ps) containing the figure. The GMT software package is actually a suite of executable programs, of which Figure Gen uses only seven. Thus, if you are running on a Windows machine, then you might be able to get away with downloading only the executable program. If that does not work, then you will need to download and install the GMT source code from the GMT Web site.
2. GhostScript
GhostScript is the software package that converts PostScript files into different formats, including the JPEG format used by FigureGen. If you are running on a Windows machine, then just download and install the executable program. If you are running on a different system, then you will need to go to the GhostScript Web site and download the installation files.
3. ImageMagick
ImageMagick is the software package that actually converts the PostScript files by calling GhostScript. ImageMagick also performs some other actions on these files, such as rotating the image, removing any extra white space from the edge, and converting them to a specific resolution. For each time snap, FigureGen will output high-resolution (1200dpi) and low-resolution (width of 800 pixels) JPEG files. If you are running on Windows, then just download and install the executable program. If you are using a different system, then you will need to visit the ImageMagick Web site and obtain the installation files.
Source Files:
The FigureGen program requires a source file and accompanying input files. These files are linked here:
This is the source code itself. This code will ask the user for and then read an input file containing information about which files to plot and how. FigureGen will plot the contours of both elevation-type (fort.63, maxele.63, maxwvel.63, etc.) and velocity-type (fort.64, fort.74, etc.) files. You can specify a color palette to use by creating and saving a palette in SMS. You can convert units automatically. You can specify the lat/lon box to plot. And, perhaps most importantly, you can run FigureGen in parallel, so that you can create multiple images in a short amount of time. This source code contains directives for both serial and parallel compilation, and directions on how to compile are included below.
2. Input File
The input file contains all of the buttons and levers that you can adjust for your figures. You can change the lat/lon boundaries of the box; you can turn on/off the contours, contour lines, vectors, etc.; you can convert the units in the ADCIRC output files; you can create figures for several time snaps; you can control the appearance of the scale; etc. Example input files are linked above, in the “Examples Using Version 26” section.
3. Color Palette (Default2.pal)
You can control the colors in FigureGen by specifying the name of a color palette in the input file. This color palette was created and saved from SMS, and it is the palette that we use for our hindcast figures. If you wanted a different palette, then you can use SMS to create one, and then use FigureGen to apply it to figures.
4. Contour Increments File
You can control the increments in the contour scale by specifying a text file with the increments you want. The first line in the file contains the number of increments in the file. The rest of the lines in the file have two numbers: (A) the increments that you want to use, and a flag (0 or 1) to indicate whether the color in that increment should be superseded by gray. (For example, you might want to make the increment near zero to be gray, especially in a difference plot.) Examples of this file are linked above, in the “Examples Using Version 26” section.
How to Compile:
As stated above, FigureGen is written so that the source file contains instructions for both serial and parallel implementations. For that reason, it may not be straight-forward to compile. In addition, I do not have much experience with the pre-processor directives that are necessary for this kind of dual-use programming, and thus I may not be able to answer questions about compiling. Here is what has worked for me:
1. Serial compilation on Windows using the Compaq Visual FORTRAN compiler:
f90 FigureGen26.F90 /fpp
The /fpp command tells the compiler to use the FORTRAN pre-processor, which deals with the directives that split the serial parts of the code from the parallel parts. I think most compilers use automatically the pre-processor when the source file has an extension with a capital letter (such as F90), but that is not the case with the Compaq Visual FORTRAN compiler. However, this compiler does name automatically the executable as FigureGen26.exe.
2. Serial compilation using the Absoft FORTRAN compiler:
f90 FigureGen26.F90 /Applications/Absoft/lib/libU77.a -o FigureGen26.exe
Now the compiler knows automatically to use the pre-processor, but we have to specify two other things. First, we need to include the library of Unix commands. The FigureGen program relies heavily on calls to the operating system, and these calls are not defined automatically by the Absoft FORTRAN compiler. Second, we need to specify the name of the executable by using the -o option.
3. Parallel compilation using the Absoft FORTRAN compiler and LAM/MPI:
mpif77 FigureGen26.F90 -DCMPI -I$LAMHOME/include -o FigureGen26.exe
The -DCMPI flag turns on the parallel commands inside my FORTRAN source file. The -I option specifies the location of the LAM/MPI include directory, where my code uses the mpif.h library. And the -o option specifies the name of the executable to be created.
That is all of the experience that I have in compiling FigureGen. It seems that the main difficulties are: (A) ensuring that the compiler uses its pre-processor to handle the compiler directives, (B) linking to the Unix library that contains the definitions for the system calls, (C) defining the flag to turn on the parallel commands in my source code, and/or (D) specifying the directory where the MPI library is located. If your experience is different, then please let me know.
How to Run:
In a serial implementation, running FigureGen is easy. Typing the name of the executable will start the program. It will ask the user for the name of the input file, which it will then read and process. From that point forward, the rest of the figure generation is automatic.
In a parallel implementation, I use the following steps. On our system, the command to run a parallel program on three processors is:
mpirun -ssi rpi tcp c0,1-2 -x PATH ./FigureGen26.exe
Note that I am being very specific about which processors I request. The first processor in the list will be the master in my master-slave paradigm. And, because FigureGen is interactive (by asking for the name of the input file), I always ask for processor 0 to be the master because that is the processor from which I perform the run. The rest of the processors will be the slaves, and they will make the figures. In the line above, I am requesting that processors 1 and 2 be the slaves. If I wanted to split the work amongst 10 processors, I might use a command like:
mpirun -ssi rpi tcp c0,21-30 -x PATH ./FigureGen26.exe
where now I am requesting that processors 21 through 30 be the slaves. The master will assign a time snap to each slave and then wait to hear back from the slaves. When a slave is finished generating a figure for the time snap it was assigned, then it will alert the master and receive a new time snap.
Also note that I am using the -x PATH option. This option exports the PATH environment variable to the compute nodes. I found it necessary to use this option because, even though I had set the paths to the ImageMagick and GhostScript executables, the compute nodes sometimes could not find them. By exporting these paths, we tell the compute nodes where the executables are located.
Troubleshooting:
Before running FigureGen, it is important that the necessary files be located in the working directory. Specifically, the grid file, the file from which to plot contours (if used), the file from which to plot vectors (if used), and the color palette (if used) should be in the same folder as the FigureGen executable. In addition, you will need to create the temporary folder that is named in the input file. This is where FigureGen will create any temporary files as it works. You can run multiple instances of FigureGen from the same folder by specifying separate temporary folders for each instance. Thus, you might be generating Ele-Wind figures using a temporary folder called Temp1 at the same time that you are generating Wind-Wind figures using a temporary folder called Temp2.
Also, you cannot read in the same file for both contours and vectors. For example, to plot the hurricane winds, you might want to plot contours of wind magnitude and vectors of wind magnitude and direction. All of this information would need to come from the same fort.74 file, but you cannot specify the same fort.74 file for both the contours and vectors. The work-around is to copy the fort.74 file into a new fort.2.74 file, and then use one file for contours and the other file for vectors.