1

Inundation Visualizer

Ren Wan, Kevin Masterson, Eric Meyers, Joshua Souders

COSC 425/426 – Software Engineering

Fall 2013/Spring 2014

2

Table of Contents

3 - Introduction

7 - Process

10 - Requirements and Specifications

11 - Architecture and Design

17 - Future Plans

18 - Appendix

3

Introduction

Climate change, sea-level rise, and associated storms are putting Maryland’s people,

property, natural resources, and public investments at risk. Currently emergency-response

managers and coastal-development planners on the Maryland’s Eastern Shore rely on coarse-

resolution storm-surge models (such as SLOSH) and static floodplain maps. This project is

directed at assessing the impacts of long-term sea-level rise and episodic storm surges on the

low-lying lands of the Maryland’s Eastern Shore and developing 2D and 3D GIS software

product that visualizes inundation at the street level for this region. This research investigates

how different categories of storms such as hurricanes and nor’easters cause temporary flooding

and inundation on the Eastern Shore and how the sea-level rise might amplify the storm surges.

To conduct inundation simulations, a hydrodynamic model developed by University of Maryland

Center for Environmental Science is used to place high resolutions on the Maryland’s Eastern

Shore. A series of numerical experiments have been conducted to explore different combinations

of sea-level rise and storm-surge scenarios. The application visualizes the area extent, depth,

duration of inundation at the street level on the Eastern Shore of Maryland during different

categories of hurricanes. This cross-platform, web-based application has been designed and

developed for PCs and tablets users. Open-source tools such JavaScript, HTML, CSS, Leaflet

and Google Earth are used to create animation tiles to show sea level and inundation over a

period of time in 2D and 3D maps. This project helps to gain further understanding of the

inundation risks of the Maryland’s Eastern Shore to different scenarios of sea level rise and

storms, delivers much-needed information to state and county policy makers who are tasked to

design adaptation and mitigation strategy for climate change and provides research-training

opportunities to undergraduate students at Salisbury University.

Technology

1. Ocean Model

The data used in this application is from FVCOM which is a hydrodynamic model constructed to

investigate storm surge inundation. The model is coupled to atmospheric models NARR and

WRF, used to simulate atmospheric conditions leading to storm surges. Global circulation

patterns are incorporated by nested the FVCOM model within the global circulation model

HYCOM. Tides are predicted using tidal constituents along the FVCOM open boundary. The

model is run by Horn Point Lab.

2. Platform

The primary platform that this system is targeted toward are PCs, smartphones and tablets.

Tablets are the perfect device for this sort of tool because it combines portability with a relatively

large screen size. This would allow individuals to model their data anywhere. The project will be

browser based, however, and it will therefore be available on any platform that can run a

browser. For the compatibility consideration, the application is able to automatically detect the

4

type of user’s browser and choose the right display mode for the user. Steps have been taken to

ensure that the application will be responsive and that it will scale properly to fit any screen size.

2. Language

The primary language used in this application is JavaScript. This allows us a wide range of

frameworks and libraries to choose from while being object oriented and very accessible. We

also used HTML, CSS and PHP, however the majority of the application is in JavaScript, since it

is needed to interact with APIs of Leaflet and Google Earth.

3. Libraries

As in any major front-end JavaScript project, we make significant use of JQuery. The side panel

is generated using Bootstrap, from the panel to the individual buttons and button handlers.

4. Frameworks

Because this application’s success rests heavily upon it being usable on a tablet, we have chosen

Leaflet as the mapping framework. This is a JavaScript library that was founded on the idea that

browser based maps should be able to work smoothly on mobile devices. Thus, it was the natural

choice. Leaflet is completely open source and we’ve made use of several plugins in order to

improve our map. We’ve also altered Leaflet so that we can properly animate tiles in order to

show sea level changes over times.

Screenshots

Low inundation around Dorchester County

Figure 1

5

Higher inundation around Dorchester County

Figure 2

Zoomed in with detailed location tooltip

Figure 3

6

2D inundation around Dorchester County

Figure 4

Inundation of Marshlands

Figure 5

7

Process

The process, more than any other aspect of this project, determined the life and death of

this program. A haphazard development process in a team oriented group would surely lead to a

disorganized result that failed to meet the need of both the user and the customer. Thus, as was

conveyed early on before a project topic was chosen, we used extreme programming as a

framework in which to complete our project. Subscribing to many of the core tenants of AGILE

development, this project management method allowed us the flexibility and development style

needed to adapt to, most notably, the architectural issues we encountered earlier on in the project.

We did, however, find that throughout the project that we tended to naturally not take a

dogmatic approach to extreme programming and instead incorporated the features of extreme

programming that we believed would empower us to accomplish our project in the best way

possible. We believe that this provided the best results for the developers, the user, and the

customer all within the setting of us all working at different times from different locations with a

less than 40 hour work week allocated to development. Some rules of extreme programming,

such as a daily stand-up meeting, were simply not viable.

One of the most important aspects of the project was the meetings that were attended by

the development team. Our first major meeting was the iteration meeting, which occurred once

every three weeks. In this meeting we discussed what we hoped to accomplish in the next three

weeks as well as talked about the status of the project as a whole. These meetings helped us to

direct the project in a forward direction and facilitate necessary communication between the

team. The second meeting was our biweekly meeting with the customer, Dr. Wang. These

meetings served to update her on our progress as well as gather her input on the short term as

well as long term plans. One of the tenants of extreme programming is constant contact with the

customer, with the customer working on-site ideally. While that would not be possible in this

setting, these meetings as well as constant email contact with timely responses allowed us to

create a product that fit the needs of the customer. These two meetings combined grew to serve

as the group’s driving force and main form of communication from the directional standpoint of

the project.

User stories, as per the official extreme programming syntax, were implemented early on

in the process. As a project with outwardly simplistic yet complex behind the scenes

functionality (i.e. one simple button push could enact a large behind the scenes process), we

found it cumbersome to come up with meaningful user stories from the perspective of the user

that would convey the goals of a given user story non-technically. A large time drain on the

project was coming up with a way to cleverly word a user story from the perspective of the user,

when in reality we were discussing a technical story that, if we programmed it properly, the user

would have no idea of the complexity of what we were trying to accomplish. Thus, as the project

went on, we transitioned more to a syntax of a short bullet point format and found that it allowed

us to more clearly convey what we meant by a given task. This is the format we took while

explaining our goals for the next three weeks in our iteration meetings and we believe that it

allowed us to work more effectively.

8

Refactoring was common throughout the project. Most notably in early December the

JavaScript code went through a major refactor that involved a dramatic alteration of the

program’s structure. Previously the JavaScript code was simply a giant function call; it worked

perfectly fine, but the structure was haphazard and it was apparent that the technical debt was

accruing quickly. We decided to rewrite the JavaScript code to conform to accepted object

oriented patterns. After this was accomplished, development was easier and it allowed us to

easily integrate 3d and 2d maps using different frameworks in the spring. Without this change

the technical debt from a non-object oriented approach to 2d and 3d integration through different

frameworks would have been large enough to make the program very difficult to maintain.

Another major refactoring was with the CSS very early on in the project. As the project began, a

frontend was thrown together quickly so that development could begin. One of the time saving

methods at this stage was the use of style tags within the HTML, which is completely antithetical

to the concept of separation of concerns and is considered bad practice. While this was worth it

at the time in order to prop up a frontend as soon as possible, as soon as we got the opportunity

we refactored this code so that everything in style tags would instead be put in our style.css file.

Finally, while we will not go into detail on specific occurrences, minor refactorings happened

before each push in order to maintain a good quality of code.

Testing was a difficult topic for us to accomplish due to the nature of our program. Little

exists in the realm of frontend automated testing tools, and behind the scenes our data model was

simple enough that a simple visual confirmation was all that was needed to ensure that the

program was working properly. Thus, many of our testing was simply a visual confirmation to

ensure that everything was working correctly. Between a glance at the side panel to ensure that

everything was in the right place in every major browser, trying the program out on different

speed computers and on different internet connections, and clicking the few buttons the program

has in order to determine if it’s working right, testing was a manual endeavor.

Less difficult to accomplish was pair programming. While we frequently worked

independently, in the early stages especially the development team worked together on several

key aspects of the program in order to better facilitate language and experience specific

knowledge throughout the group. As JavaScript and GIS oriented JavaScript frameworks were

new to the majority of the group, exploratory coding was mostly done in a group setting. Once

the project began, pair programming was done during the two crucial steps of the object oriented

Javascript refactor as well as the 3d Google Earth integration into the program at the point where

the entire project up to that time was purely a 2d Leaflet map. As time went on and the focus of

the project turned from pure development to data generation, pair programming began to make

less sense. However, it did impart a knowledge of the inner workings of the program throughout

the entire team and it was a worthwhile use of time.

Finally, proper use of source control was a topic that we struggled to implement entirely

correctly yet managed to come up with a workflow that worked for us. As we began the project

we attempted to use a complicated branching method that would have made sense for a large

project with many contributors, but for a team of four people on a relatively small project this

sort of structure did not make sense. To compound to the inherent complexity of the branching

9

structure we attempted to use, there was very little experience on the team with git and thus

simply pulling, committing, and pushing was difficult enough. The development team looked at

Bitbucket and realized that pushes were infrequent and offhandedly communicated to the entire

team before they occurred; we therefore abandoned our complicated branching structure and just

simply pulled before we started working and pushed when we were done. While on a large

project this would cause a merging nightmare, we did not have a single conflict and we therefore

maintain that this method was the most effective for this specific project.

10

Requirements & Specifications

The main project requirements from the user’s perspective are as follows:

● See how flooding will affect a given area

The overlay of water in the 2D map and the colored depth areas in the 3D map show how

flooding has previously affected an area.

● See the maps animate to show change in flooding over time

Both the 2D and 3D maps animate to show change in flooding over time

● See both 2D and 3D representations of the area and its flooding

The map is viewable in both 2D and 3D using Leaflet and Google Earth libraries. You

can also switch back and forth between them.

● Have a good user interface to control the map

The map utilizes built-in controls of both Leaflet and Google Earth which should be

familiar to any user of other web-based mapping software.

As a developer, the requirements were:

● Be able to update the application quickly by having a well-designed structure

Utilizing Javascript libraries like Bootstrap and JQuery as well as pre-built mapping

libraries like Google Earth and Leaflet allowed for quick writing and rewriting of source

code.

● Utilize development tools properly

Bitbucket was used for keeping track of source code versioning. Also, Google Drive was

used to keep track of important project data like timekeeping and user stories.

11

Architecture and Design

Overview

The overall idea of the system is a tool with which to view historical inundation levels of

select areas. This can be accomplished using “Google Earth”-style 3D views and overhead map-

style 2D views, both of which many users of internet map services are familiar with. This is done

by using the Google Earth browser plugin as well as the Leaflet 2D mapping library inside a

webpage being hosted on any standard web server. These libraries and the webpage itself are

interfaced with using the Javascript language running inside the browser.

Google Earth is a self-contained 3D environment that includes terrain and building height

information for many areas and allows developers to add information to it locally, including

placemarks, on-click tooltips, custom height and custom terrain data.

We utilize this by adding new overlays of higher water level onto the existing terrain,

allowing a user to see what land areas and parts of buildings (that Google Earth has height

information for) might be under water. Clicking on an inundated location also allows the user to

see how high the water level was above sea level at the given time the model depicts.

The overlays are created by directly importing custom-generated KMZ (Keyhole Markup

language Zipped) files into Google Earth. These files contain all the inundation data points for

each slice of time. They were generated via a MATLAB program, designed by Ren Wan, which

analyzes and reformats the data (in NetCDF format) provided by various organizations,

including Hornpoint Laboratory.

Leaflet works by displaying a grid of tiles depending on latitude, longitude, and zoom

levels. These tiles allow near-seamless movement and zooming of the 2D map, similar to many

other free mapping tools like Google Maps. The major advantage of Leaflet is that it is designed

out-of-the-box to be used on tablets and other smart devices as well as traditional desktops.

The tiles that Leaflet uses to display the 2D map are generated from the previously-

generated KML files using software called TileMill.

Once the KML and tiles are generated, they are simply hosted from the web server where

the client-side mapping libraries access them.

12

An overall flowchart:

Figure 6

Inundation Visualizer (The actual webpage and MapClass):

Figure 7

13

Influence

The web-based environment greatly influenced the design, since web software becomes

split into two components: the server side and the client side. In our situation, the client side does

nearly all the real-time calculations and drawing, by way of Leaflet and Google Earth. The server

side is essentially only there to host the large amount of data, specifically the KMZ files and the

tiles.

This software was further split up into more components because a significant amount of

time is spent running programs which simply format the data on the server into something the

client frameworks can actually understand. This formatting must be done outside of the

traditional web software stack, as it is far too time-consuming to be done in real-time.

Complexity Analysis

Basically what the inundation.m does is finding all the inundation cells based on the

conditions set by the user and writing information of 3D polygons in the KMZ files.

In the case of the model output for Dorchester County, the MATLAB program needs to

handle 88176 triangles which contains 46742 points. It is a large amount of points. Although the

MATLAB is very efficient in matrix calculation, it takes time to calculate data for such amount

of points.

Since the shape of the 3D polygons keeps changing over times, the program must to find

both inner and outer boundaries of the grid every time. In the below example, there is no inner

boundary, but the outer boundary for triangles A, B, C, D and E is the combination of 76-41, 41-

42, 42-43, 43-77 and 76-77. The model doesn’t have the information for boundaries, also all the

3D polygons are generated dynamically based on the inundation area. We developed our own

algorithm to find the boundaries. The algorithm takes 3 steps.

1. Find all the vertices of each triangle and sort them in ascending order. The sorting makes

edges to be comparable.

A {3, 76, 77}

B {3, 42, 43}

C {3, 41, 42}

D {3, 41, 76}

E {3, 76, 77}

2. Find the combinations (edges) of each vertex set (triangles) and put them in a big set.

Edges {(3, 76) (3, 77) (76, 77) (3, 42) (3, 43) (42, 43) (3, 41) (3, 42) (41, 42) (3, 41) (3, 76) (41,

76) (3, 76) (3, 77) (76, 77)}

Figure 8

14

3. The count of edge will be one, if the edge is on the boundary. Use while loop to loop through

the whole set to find and delete the edges which is not unique in the set. Removing edges from

the set will reduce the size of the set. This will speed up the iteration every time. The set of edges

will the inner and outer boundary edges once the looping is finished.

Although the algorithm works fine, finding inner and outer boundaries for over 10K triangles is

still a heavy job for the program. Below is the actual code for finding boundaries:

Figure 9

Since we don’t know how much time do find and size function take, we assume they spend Tfind

and Tsize time:

Tfind = Time of find function

Tsize = Time of size function

Time: 2 × Tfetch + T<=

Time: Tfetch + Tfind + Tstore

Time: Tsize + T==

Time: 2 × T() + 2 × Tfetch + Tstore

Time: 2 × T() + 2 × Tfetch + Tstore

15

Time: Tfetch + Tsize + Tstore

Time: 2 × Tfetch + T+ + Tstore

In the worst case (all the edges are boundary, vSize remains the same, b increases 1 every

iteration):

n � vSize

Ttotal = n × (① + ② + ③ + ⑦)

= vSize × (2 × Tfetch + T<= + Tfetch + Tfind + Tstore + Tsize + T== + 2 × Tfetch + T+ + Tstore)

= vSize × (10T + Tfind + Tsize)

In the Best case (no boundary, b remains 1, vSize reduces 2 every iteration):

n �vSize

2

Ttotal = n × (① + ② + ③ + ④ + ⑤ + ⑥)

= vSize / 2 × (2 × Tfetch + T<= + Tfetch + Tfind + Tstore + Tsize + T== + 2 × T() + 2 × Tfetch +

Tstore + 2 × T() + 2 × Tfetch + Tstore + Tfetch + Tsize + Tstore)

= vSize / 2 × (18T + Tfind + 2Tsize)

= vSize × (9T + Tfind / 2 + Tsize)

Comparing two results, the program only spends half time on finding boundaries in the best case.

Below is the performance chart of actual run:

16

Figure 10

The time for finding boundaries is doubled when the number exceeds 85000.

17

Future Plans

Upon completion of the semester, the project will be handed over to the acting customer,

Dr. Wang. She has selected a student who will continue working on it in the future. Since Kevin

Masterson will be attending the university in the following semester, he has agreed to assist in

making the transition process as smooth as possible.

The project is currently being hosted on a free server on a temporary basis. Once a

suitable long-term hosting server is selected, Kevin will assist in migrating it over, including

making sure all the required server software is set up.

Also, access to the current repositories, Bitbucket and Google Drive, will be given to the

project’s new caretaker.

18

Appendix

Website

As this program is written in JavaScript, with only one PHP file, installation on a

webserver involves simply copy-pasting the files onto the server (assuming it can run PHP). All

processing is done client-side; rather than rely on a geodatabase running proprietary code, or

even any geodatabase at all, this code will execute in the client’s browser without any significant

backend. Another option would be to log onto the webserver and clone the repository on

Bitbucket.

For development purposes, it may be best to make changes while running the site locally.

This can be accomplished by setting up a local webserver (such as Apache, NGINX, Python,

etc.) and using localhost to view the site in the browser. Local development without the use of a

local server will cause issues due to conflicts with the same origin policy. The development team

has found that the developer tools of Chrome work well for development, and also that it is

advisable for web development to use the developer tools to disable the cache to ensure that you

are always obtaining the most recent version of every file.

Running the program may either happen on a web-accessible site, through the use of a

webserver, or through the use of a local machine for development purposes. On a webserver, you

would open a web browser and direct the URL to whatever URL that the webserver points to. If

you are attempting to view a local version, you would navigate via a web browser to

http://localhost:*PORT NUMBER*/*FOLDER NAME*/index.html with *PORT NUMBER*

replaced with the port that your local server utilizes and *FOLDER NAME* set as the name of

the folder in which the index.html file in the root of the project directory. Note that the project

directory must be within the root of the folder in which the local server points to.

MATLAB

The 3D KMZ files are generated by MATLAB with the KML toolbox. The toolbox can

be download from: http://www.mathworks.com/matlabcentral/fileexchange/34694-kml-toolbox-

v2-7 . This toolbox allows the user to create different plots in Google Earth. To install the

toolbox into the MATLAB path, go to the toolbox directory and run: kml.install. The user also

can run kmldoc to view the help document of this toolbox. The version of MATLAB used in our

project is R2013b. The user might have some problem to run the script on some machine with

the older version MATLAB, since the older version of MATLAB does not have NetCDF

support.

The MATLAB program is able to process the data from model output and creates 3D

polygons in KMZ files. The number of model output files could be more than one. The program

will process all the files one by one in their order. To draw a single 3D triangle on Google Earth,

3 vertices of the triangle must have information of longitude, latitude and altitude. The starting

point must be drawn 2 twice to get a closed triangle. For example, the format of drawing a

triangle ABC will be k.poly3 ([LatA LatB LatC LatA], [LonA LonB LonC LonA], [AltA AltB AltC

19

AltA]). Otherwise the triangle will not be closed. The color of the polygon is in AABBGGRR

format. A stands for alpha, its value controls the transparency, BGR stands for blue, green and

red. The range of a color is from 00 to FF. A helper function called num2color is used in the

inundation.m. It helps the user to convert the decimal number into AABBGGRR format.

Figure 11 Figure 12

At the top the of program, there are variables for configuring the program,

Figure 13

20

model This variable tells the program what model data is read. For now, the program

is only able to handle FVCOM output. As the development goes on, it is

possible to add functionality to handle other model data.

percentDisp This is a double type variable from 0.0 to 1.0. This variable is related to

Colors. (See below)

colors There are two options for colors.

1 – Use Gradient Color. This feature is designed for the user to view how the

values change.

2 – Use Two Colors (Red color is for the value which is greater than the

percentDisp times the range, green color is for the value which is less than the

percentDisp times the range). This helps the user to view the areas with the

value below or above a certain percentage of the range.

scale This option sets the scale of the altitudes of polygons.

transparency The user is able to set transparency from 0 to 1.

0 – Absolute transparent.

1 – No transparency.

drawBoundary 0 – Not draw boundary

1 – Draw boundary

Note: It slows down the program if it is on.

action This variable decides how the program handles the KMZ file once it has been

generated.

‘save’ – save the file and not open it

‘run’ – save the file and open it

lineWidth This is the line width of the 3D polygons. The program draws the outlines for

3D polygons if is greater than 0;

altitudeMode There are three options for the altitudeMode. They are 'absolute',

'relativeToGround' and 'clampToGround'. 'absolute' should be good enough

for most cases. More information can be found on Google Earth website

area This defines the name of each KMZ files. The format of KMZ files will be

‘area’ + ‘kmzCounter’

lon1 The westernmost longitude of the area which the user wants to display

lon2 The easternmost longitude of the area which the user wants to display

lat1 The northernmost latitude of the area which the user wants to display

lat2 The southernmost latitude of the area which the user wants to display

maxZ2Disp This defines the maximum value of the display range

minZ2Disp This defines the minimum value of the display range

minWater The 3D polygons will not be drawn on the map if the value of zeta is less than

minWater.

firstFile The number of the starting file. The program only starts to read data from the

“firstFile”, no matter how many files are in file matrix.

lastFile The number of the ending file. The program will be terminated once it read

the “lastFile”, no matter how many files are in file matrix.

kmzCounter This is the counter for naming KMZ files.

startT This defines the starting time of the first file.