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 significant wave heights during Hurricane Katrina in the Gulf of Mexico:
Significant wave heights (m) during Katrina (2005) in the 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 backward-compatible! (This has not been true for past versions, but it is now true for FigureGen v.32.) The input file changed slightly for this latest version, but you do not need to go back to your existing input files and update them. Instead, you can still use those input files with the new version to produce the same images as before. To do this, simply change the names of those existing input files so that the first four characters in the file name are “FG” and then the version number of FigureGen with which they correspond.
For example, if you have an existing input file named Katrina_Ele-Wind.inp that worked with FigureGen v.26, then you can use that same input file with the new version by changing its name to FG26_Katrina_Ele-Wind.inp. That is the only change; you do not need to make any changes inside the input file itself. FigureGen v.32 will see that it is an older version of the input file, and it will not try to read the new lines for the new features.
Examples of New Features in v.32:
In the following examples, please note that the fourth line of each input file, where the path to the GMT executables would normally be specified, is left blank. This is because we have installed that path as part of the environment variables on our new Zas cluster at Notre Dame. Thus, as I was preparing these examples, I did not need to specify the path to the GMT executables, because the system already knows where to find them. Your local installation may vary. Please see the old examples for FigureGen v.26 for help on specifying the path.
14. Creation of Google KMZ File for a Time Series of Images. Create a time series of images (of the water levels and winds during Hurricane Katrina, in this case), and then write a KMZ file that can be used in Google Earth.
- FG32_14_Files
- FG32_14_Katrina_Ele-Wind_SELA_KMZ.inp
- Default2.pal
- CHL_Logo.png
Note that the input file looks as it would if we were generating a regular figure. The only changes occur near the bottom of the input file, on the line where the Google flag is activated. Note that we specify a transparency of 75 percent for the contoured image. Also, we add our lab logo by using the CHL_Logo.png file and activating the logo flag in the input file. FigureGen will automatically strip away the boundary of the image, and it will create the contour scale and the logo as separate layers in the KMZ file.
Also note that we specify a time stamp (in the format YYYYMMDDHHMMSS) that corresponds to the time of the first snap in the fort.63 file. FigureGen will use that time stamp and the information in the fort.63 file to determine the times of all of the rest of the snaps. Then it will add a realistic time bar to the top of the KMZ file.
Also note that the resolution of the image in the KMZ file is controlled by the “Resolution (dpi) of large JPG images …” line in the input file. For this animation, I changed the resolution to 150dpi, so that the corresponding KMZ file does not become too large. For KMZ files containing a single image (as in Example 13, above), the resolution can be increased to control the overall KMZ file size.
I stole (shamefully) this KMZ technology from scripts that were written by Howard Lander at UNC. Those scripts are available on the ADCIRC Utility Programs page, and I highly recommend you check them out. In addition to the KMZ features shown here, those scripts can: (A) plot nested images, so that resolution is not lost as the user zooms into the map, and (B) read and process binary output from ADCIRC.
13. Creation of Google KMZ File for a Single Image. Create a single image (of the maximum water levels during Hurricane Katrina, in this case), and then write a KMZ file that can be used in Google Earth.
- FG32_13_Files
- FG32_13_Katrina_MaxEle_SELA_KMZ.inp
- Default2.pal
- CHL_Logo.png
Note that the input file looks as it would if we were generating a regular figure. The only changes occur near the bottom of the input file, on the line where the Google flag is activated. Note that we specify a transparency of 75 percent for the contoured image. Also, we add our lab logo by using the CHL_Logo.png file and activating the logo flag in the input file. FigureGen will automatically strip away the boundary of the image, and it will create the contour scale and the logo as separate layers in the KMZ file.
Also note that the resolution of the image in the KMZ file is controlled by the “Resolution (dpi) of large JPG images …” line in the input file. For this single image, I left the resolution as 600dpi, because the corresponding KMZ file does not become too large. For KMZ files containing animations (as in Example 14, above), the resolution should be decreased to control the overall KMZ file size.
I stole (shamefully) this KMZ technology from scripts that were written by Howard Lander at UNC. Those scripts are available on the ADCIRC Utility Programs page, and I highly recommend you check them out. In addition to the KMZ features shown here, those scripts can: (A) plot nested images, so that resolution is not lost as the user zooms into the map, and (B) read and process binary output from ADCIRC.
12. Domain Decomposition. Read the partmesh.txt file that is output from ADCPREP and plot the domain decomposition. Note that we specify the partmesh.txt file as the contour file, and we set the contour file type to GRID-DECOMP-256, where the last number is the total number of processors. FigureGen will read the grid file and partmesh.txt file, and then it will apply an optimal color connectivity table so that no two adjoining subdomains will receive the same color. In this example, the number of colors is six. I think the theoretical minimum number of colors is four for such a mapping exercise, but that algorithm is too costly for FigureGen.
- FG32_12_Files
- FG32_12_Grid-Decomp_SL15v7l_SELA.inp
- Decomp.pal
- CHL_Logo.eps
Also note that, in this example, we are coloring the mesh lines in each subdomain (as in Examples 7 and 6, below). This is accomplished by: (A) turning on the plot grid flag, (B) turning off the contour fill flag, and (C) setting the color lines flag to GRID-DECOMP-256. A different combination of settings could produce a similar image, except the subdomains would be colored as filled contours.
11. Add connected Hurricane Track, Logo to plot of Maximum Wave-Driven Forces. Above a plot of the contours from the maxrs.63 output file, add the connected track of Hurricane Katrina and a logo. Note that this example contains two new features. First, we are plotting the track of Hurricane Katrina (from KatrinaTrack.txt) as a set of connected line segments. This was not possible in v.26, which required that the dots in such a file be unconnected, and thus made it difficult to add lines such as hurricane tracks to the figures. Now, by setting the dots/lines flag to 2 near the bottom of the input file, you can connect the dots.
- FG32_11_Files
- FG32_11_Katrina_MaxRS_GOMEX.inp
- Default2.pal
- RS_Intervals.txt
- KatrinaTrack.txt
- CHL_Logo.eps
Second, note that we are adding our lab logo to the top left corner of the figure. This is done on a new line in the input file for v.32. You can specify the location of the logo (TL/TR/BL/BR), the width of the logo in inches, and the name of the EPS logo image that you want to add. Please note that GMT requires the logo to be in EPS format. This was not my choice. However, I think that most high-end image software should allow you to save or convert an image to EPS format.
10. Eddy Viscosity from the fort.13 File. Read the ADCIRC nodal attributes file and plot the eddy viscosity values. Note that we specify the fort.13 file as the contour file, and we set the format to 13-EVIS. We can plot the wind reduction factors, canopy values, eddy viscosity, and tau0 using similar commands.
- FG32_10_Files
- FG32_10_EVis_SL15v7l_SELA.inp
- Default2.pal
- CHL_Logo.eps
9. Tau0 from the fort.13 File. Read the ADCIRC nodal attributes file and plot the tau0 values. Note that we specify the fort.13 file as the contour file, and we set the format to 13-TAU0. We can plot the wind reduction factors, canopy values, eddy viscosity, and tau0 using similar commands.
- FG32_09_Files
- FG32_09_Tau0_SL15v7l_SELA.inp
- Default2.pal
- CHL_Logo.eps
Examples of Previous Features:
In the following examples, please note that the fourth line of each input file, where the path to the GMT executables would normally be specified, is left blank. This is because we have installed that path as part of the environment variables on our new Zas cluster at Notre Dame. Thus, as I was preparing these examples, I did not need to specify the path to the GMT executables, because the system already knows where to find them. Your local installation may vary. Please see the old examples for FigureGen v.26 for help on specifying the path.
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.
- FG32_08_Files
- FG32_08_Grid-Contours_SL15v7l_SELA.inp
- TopoRainbow.pal
- TopoRainbow.txt
- CHL_Logo.eps
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.
- FG32_07_Files
- FG32_07_Grid-Bath_SL15v7l_SELA.inp
- TopoRainbow.pal
- TopoRainbow.txt
- CHL_Logo.eps
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.
- FG32_06_Files
- FG32_06_Grid-Size_SL15v7l_SELA.inp
- Default2.pal
- GridSize.txt
- CHL_Logo.eps
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.
- FG32_05_Files
- FG32_05_Bath_SL15v7l_SELA.inp
- TopoBlueGreen.pal
- TopoBlueGreen.txt
- Labels.txt
- CHL_Logo.eps
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, canopy values, eddy viscosity, and tau0 using similar commands.
- FG32_04_Files
- FG32_04_ManningsN_SL15v7l_SELA.inp
- Default2.pal
- CHL_Logo.eps
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).
- FG32_03_Files
- FG32_03_WindReduction_SL15v7l_SELA.inp
- Default2.pal
- Coastline.dat
- CHL_Logo.eps
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.
- FG32_02_Files
- FG32_02_Katrina_MaxEleDiff_SELA.inp
- Default2.pal
- MaxEleDiff.txt
- CHL_Logo.eps
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.
- FG32_01_Files
- FG32_01_Katrina_Ele-Wind_SELA.inp
- Default2.pal
- CHL_Logo.eps
System Requirements:
1. GMT (http://gmt.soest.hawaii.edu/)
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 a subset. 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 (http://pages.cs.wisc.edu/~ghost/)
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 (http://www.imagemagick.org)
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.) output files, grid (fort.14) files, and nodal attributes (fort.13) 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.
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.
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 FigureGen32.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 FigureGen32.exe.
2. Serial compilation using the Absoft FORTRAN compiler (on Athos):
f90 FigureGen32.F90 /Applications/Absoft/lib/libU77.a
-o FigureGen32.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 (on Athos):
mpif77 FigureGen32.F90 -DCMPI -I$LAMHOME/include
-o FigureGen32.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.
4. Serial compilation using the Portland Group compilers (on Zas):
pgf90 FigureGen32.F90 -o FigureGen32.exe
The only trick here is that we need to specify the name of the executable to be created by the compilation.
5. Parallel compilation using the Portland Group compilers and MVAPICH (on Zas):
mpif90 FigureGen32.F90 -DCMPI -o FigureGen32.exe
The -DCMPI flag turns on the parallel commands inside my FORTRAN source file. 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 ./FigureGen32.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 ./FigureGen32.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.