  % cpedoc.tex V2.0, 13 May 2010
%\documentclass[times]{cpeauth}
\documentclass[times,doublespace]{cpeauth}%For paper submission

\usepackage{algorithm}[]
\usepackage{algorithmicx}[]
\usepackage{algpseudocode}[] 


\usepackage{moreverb}

\usepackage[colorlinks,bookmarksopen,bookmarksnumbered,citecolor=red,urlcolor=red]{hyperref}

\usepackage{graphicx}
\graphicspath{ {Figures/} }
\usepackage{float}
\usepackage{textcomp}
\usepackage{decimal}
\usepackage{caption}
\usepackage{subcaption}

\graphicspath{ {Figures/} }
\newcommand\BibTeX{{\rmfamily B\kern-.05em \textsc{i\kern-.025emb}\kern-.08emT\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}

\def\volumeyear{2016}

\begin{document}

\runningheads{WC-WAVE}{Virtual Watershed Client}

\title{Virtual Watershed Visualisation for the WC-WAVE Project}

% Authors
\author{Chase Carthen\affil{1}\corrauth,
Thomas J. Rushton\affil{1},
Nolan P. Burfield\affil{1},
Christine M. Johnson\affil{1},
Aaron Hesson\affil{1},
Daniel Nielson\affil{1},
Bryan Worrell\affil{1},
Donna Delparte\affil{2},
Tucker Chapman\affil{2},
W. Joel Johansen\affil{2},
John W. Anderson\affil{2},
Roger Lew\affil{3},
Nicholas R. Wood\affil{3},
Mathew Ziegler\affil{3},\\
Sergiu M. Dascalu\affil{1},
Frederick C. Harris Jr.\affil{1}}


\address{
\affilnum{1}Department of Computer Science and Engineering, University of Nevada, Reno\\
\affilnum{2}Department of Geosciences, Idaho State University\\
\affilnum{3}Department of Virtual Technology and Design, University of Idaho\\
}

\corraddr{
\href{mailto:chase@nevada.unr.edu}{\texttt{chase@nevada.unr.edu}}
}

% Revision Comments

% We have added some more explanation to Figure 6 and Figure 1. 
% We have added some explanations for the UML use case diagram.
% Chapter 4 has been expanded to include more optimization and implementation details.
% The abstract has been modified to be more understandable. 
% Section 3 has been shorted as it was brought up that the content of it got away from the topic of the paper
% The grammar related issues were addressed.
% Figure placement was adjusted as to not break up paragraphs.
% Conclusion was adjusted to add in better explanation as to the uniqueness of this paper. 




\begin{abstract}
The platform discussed in this paper, Virtual Watershed Client, provides a tool that allows researchers,
students, and stakeholders to observe and analyse both geospatial datasets
and theoretical model data. The system created ingests the geospatial data and can create three-dimensional terrain, satellite imagery, shapes, and model data. This was done using the Unity3D game development engine and libraries to work with geospatial data such as GDAL and NetCDF. These tools that are developed are used by researchers, most specifically hydrologist for the purpose of this paper, to interact in a three-dimensional environment with their gathered data. 
The design of the Virtual Watershed Client, as well as its currently implemented 
analysis and visualisation tools are discussed in detail throughout this paper.
\end{abstract}

%\nocite{*}

\keywords{Visualisation; Geospatial; Model Data; Hydrology; Virtual
Watershed Platform; Virtual Watershed Client; Terrain}

\maketitle


\section{Introduction}
\label{sec:Introduction}
Today there is a need to visualise and analyse datasets
captured by sensors in an environmental watershed and produced by biophysical models. This need stems from the watershed scientists; the ability to view their collected and model data on an actual terrain is beneficial. Having the ability to see the peaks and valleys of data values line up in accordance to actual peaks and valleys of the terrain is just one example of the usefulness visualising the datasets. Researchers use sensors to provide
information about the surrounding environment of the
watershed and they allow the researchers to run models to analyse
the data captured from these sensors. Researchers use this
acquired data to develop models that effectively reflect the
environment of the watershed. These models can then be used
to predict water runoff, precipitation, snow melt, underground
water flow, and other environmental factors within a
watershed.
Models consist of many input and output variables that
require visualisation and tuning. There are several existing
tools used to visualise this data and provide a researcher
sufficient information to modify variables in their models.
These tools include QGIS~\cite{qgis}, ArcMap~\cite{esri2015com}, and other
Geographical Information System (GIS) and non-GIS
programs. However, most of these tools lack the ability to
visualise and interact with data from a first person perspective, that is to say viewing the watershed as if you were actually there in person.
The Virtual Watershed Client~\cite{oldpaper} is currently being
implemented and has been designed to provide researchers a
3D analytical tool to visualise model data. Researchers will be
able to provide data to a web service, the Virtual Watershed Platform, and
the Virtual Watershed Client can then be used to visualise this
data. The Virtual Watershed Platform uses the Open
Geospatial Consortium (OGC) services for serving data~\cite{opengeospatial2015org}.
The client uses libraries such as the Geospatial Data
Abstraction Library (GDAL) to parse any data that gets delivered to the
Virtual Watershed Client~\cite{gdal2015org}. Researchers are then able to observe
this visualisation to evaluate the outcomes of their model runs. With the modern gaming development engines, and the processing power of computers fusing a game atmosphere with large data manipulation is possible. 
The current implementation of the Virtual Watershed
Client was built using the Unity game engine~\cite{unity3d}. The Unity
Game Engine was chosen because it allows our platform to be published on many
potential platforms, such as Windows, Mac, Linux, and the
web browser.

The capabilities of researchers to gather data in their respective watershed environments has coincided with the ability to aggregate and analyse that data in meaningful ways. The authors of~\cite{patel2011water} 
discuss methods of determining the optimal locations
for dam placement in order to harvest water. They do this by analysing a multitude of
data maps overlaid onto a Digital Elevation Model (DEM). In
\cite{miller2007the} the authors describe a toolkit built for hydrological modelling using a
geographic information system such as ArcView GIS. Their
system, the Automated Geospatial Watershed Assessment tool
(AGWA) is capable of executing and then visualising results
inside of ArcView GIS from models such as the Soil and
Water Assessment Tool (SWAT) and Kinematic Runoff and
Erosion Model (KINEROS2). The virtual watershed implemented in the Sevier River Basin~\cite{sevierBasin}
was designed for the purpose of improving operation of river and irrigation canals. To do this, a real-time representation
of the watershed was created using remote sensors that constantly stream data to a server, allowing for rapid decision making.
Finally, in Advanced Techniques for Watershed Visualisation~\cite{AdvancedWatershed}, the authors discuss using hydroshading algorithms on NASA's Shuttle Radar Topography Mission DEM datasets in order to generate high quality 3d models of the watersheds that the the datasets pertain to.

The following discussion expands upon the details given in the paper Design of a Virtual Watershed Client for the project~\cite{oldpaper}. 
Section~\ref{sec:ProjectOverview} discusses the overview of the funded project, and how the Virtual Watershed Client fits into that project. Section~\ref{sec:DataModel} explains the models used by the watershed scientists on the funded project. Section~\ref{sec:designandimplementationsection} covers the details of the design and implementation of the Virtual Watershed Client. Next, we demonstrate two separate watersheds in Section~\ref{sec:ExampleOfVW}, those two watersheds being located in Dry Creek and Lehman Creek. Finally, we present conclusions and future work of this project in Section~\ref{sec:FutureWork}.

\section{Project Overview}\label{sec:ProjectOverview}
The Western Consortium for Watershed Analysis,
Visualisation, and Exploration (WC-WAVE)~\cite{westernconsortium2015org} is a tri-state
consortium composed of researchers and students in Idaho,
Nevada, and New Mexico. Its overall aim is to study the
localised impact of climate change on high-mountain
catchments. The WC-WAVE project is comprised of three
components: Watershed Science, Visualisation and Data
Cyberinfrastructure (CI), and Workforce Development.
Participants in these three components are collaborating to
better understand interactions between precipitation, snow-
pack, groundwater flow, and other watershed properties within
mountain catchments.
To enhance the collaborative nature of this project and future
work, as well as to promote data exploration and analysis, one
of the main outcomes of the WC-WAVE project is a Virtual
Watershed Platform (VWP). The VWP framework will
provide data access and visualisation through individual
workstations (desktop), web-based environments, and
advanced interactive 3D environments, including stereoscopic, and immersive CAVE and Virtual Reality
environments. The VWP will also allow a user to run specific
hydrologic models and visualise the results.
During the preliminary meetings for this proposal, project
team members put together the design for the Virtual
Watershed Platform. Figure~\ref{fig:ProjectComponentRelationships} illustrates this VWP design.

\begin{figure}
\begin{centering}
\includegraphics[width=1.0\columnwidth]{ProjectComponentRelationships}
\par\end{centering}
\protect\caption{\label{fig:ProjectComponentRelationships}Diagram illustrating the relationships of proposed project components; virtual watershed platform, data management services, and portals. The Virtual Watershed Client is apart of the Visualization Environments block. This block gathers the data required from the Virtual Watershed Platform. The data provided the the platform come from multiple locations. Then all the data passing is all done through adapters.}
\end{figure}

To implement and test the VWP, project
participants selected four watersheds throughout the tri-state
region to focus on: Dry Creek, Reynolds%(as shown in Figure~\ref{fig:DryCreekValley})
Creek Experimental Watershed in Idaho, Jemez watershed in
New Mexico, and Lehman Creek in Nevada. These
watersheds were chosen partly for their unique characteristics.
For example, Dry Creek and Reynolds Creek provide an ideal
environment for studying and developing tools related to snow
pack, while the Jemez watershed is more suitable for
vegetation studies. These watersheds were also chosen for
their extensive data networks. Since the models within the
VWP call for several different forms of data,
watersheds with adequate datasets and instrumentation were
required.

% \begin{figure}
%     \begin{centering}
%     \includegraphics[width=1.0\columnwidth]{DryCreekValley}
%     \par\end{centering}
%     \protect\caption{\label{fig:DryCreekValley}A picture of Dry Creek watershed in Boise, Idaho.}
% \end{figure}

Members of the Watershed Science component of the WC-WAVE
project selected four main models to include in the
VWP: ISNOBAL~\cite{marks1935a}, PRMS~\cite{prmsReleaseNotes}, ParFlow~\cite{maxwell2009parflow}, and DFLOW~\cite{dflow}. The ISNOBAL (image SNOw mass and energy BALance) model is used to predict snowmelt and runoff. PRMS (Precipitation Runoff Modeling System) simulates the hydrologic process. ParFlow (PARallel FLOW) model is useful for modeling soil moisture and the interaction between surface and sub-surface flow. The DFLOW model is used for simulating river channel flow and hydrologics. These datasets are later explained in Section~\ref{sec:DataModel}.



\section{Data Models} 
\label{sec:DataModel}

As stated, the WC-WAVE project uses four primary models for conducting watershed science. Out of the four models ISNOBAL is the most established in VWC. During the development of the VWC, ISNOBAL datasets were most readily available for testing and development purposes, therefore features were designed around the data provided from this model. Section \ref{isnobal} describes this model in depth, and discusses one of the watersheds in the project that contains ISNOBAL data. The other models used in VWC are represented in the same method as ISNOBAL, and are described in Section \ref{otherModels}.

\subsection{Snowpack Modelling}
\label{isnobal}
Several models have been developed for the purpose of predicting snowpack properties over the course of a season. SNOW17~\cite{anderson1973national} was designed as part of the National Weather Service's River Forecasting System, and is still in use today~\cite{franz2008operational}. The SNTHERM~\cite{jordan1991one} and SHAW~\cite{flerchinger1989simultaneous} models accurately simulate snow properties at a point, while the Utah Energy Balance (UEB) model~\cite{tarboton1996utah} and the United States Geological Survey's Precipitation-Runoff Modeling System~\cite{leavesley1983precipitation} can be applied as distributed simulations over small areas. SnowModel~\cite{liston2006distributed} utilises input meteorological conditions along with wind conditions, vegetation and surface energy exchange to simulate snow depth and water equivalent. The ISNOBAL model~\cite{marks1999spatially} is part of our current implementation, as well as the Image Processing Workbench (IPW) suite of software tools~\cite{2015ucmerced,website2015software}. 

ISNOBAL is effective at predicting snowmelt and runoff when applied to a range of watershed sizes (1 to 2500 km2) as well as temporal ranges (one week to an entire season). When run through IPW, ISNOBAL requires three different types of input: an initial conditions image, precipitation images, and input forcing data images. The same initial condition image can be used for an entire model run and is comprised of seven bands: elevation, roughness length, total snowcover depth, average snowcover density, active snow layer temperature, average snowcover temperature, and percentage of liquid H2O saturation. Precipitation images consist of four bands: total precipitation  mass, percentage of precipitation mass that was snow, density of snow portion of precipitation, and average precipitation temperature. These bands are only included for times of precipitation events (i.e. storms). Individual input forcing data images are required for each time step (typically three hours) throughout the model run, and are made up of six bands: incoming thermal (long-wave) radiation, air temperature, vapor pressure, wind speed, soil temperature, and net solar (short-wave) radiation. All of these images can be visualised in the 3D environment of the VWP. This allows the user to check for errors, anomalies, and patterns before an actual model run. Using these images as input, ISNOBAL uses a two layer snow model to calculate energy and mass balance terms and produces two images as output. The first is a ten-band energy and mass flux image which includes predicted evaporation, snowmelt, and runoff layers. The second is a nine-band snow conditions image which contains layers for predicted thickness of snowcover, snow density, and mass of the snowcover. Similar to the input images, these output layers can be visualised with the VWP for further analysis. A visualisation of several of the ISNOBAL variables can be seen in Figure~\ref{fig:IsnobalVariables}.

\begin{figure}[H]
    \begin{centering}
    \includegraphics[width=1.0\columnwidth]{IsnobalVariables}
    \par\end{centering}
    \protect\caption{\label{fig:IsnobalVariables}A visualization of different ISNOBAL Variables.}
\end{figure}

%The Reynolds Creek watershed in southwest Idaho is an experimental watershed with data collected since 1962 from over 30 stations of varying operation, duration, and type. The concentration of recording stations in the Reynolds Creek watershed makes it ideal for building climate interpolation tools. Climate measurements include the date and time (15 minute intervals), air temperature, dew point temperature, vapour pressure, various wind measurements, and incoming solar radiation. Precipitation data includes the date and time (hourly intervals), and rain gauge measurements. Soil temperature is recorded with the date and time (hourly), and soil temperature at depths ranging from 5 cm to 180 cm. Snow depth is recorded with the date and time (hourly) and the snow depth. In addition to climate measurements, a digital elevation model (DEM), the station name and location are required. Climate data is stored an SQL database in order to query researcher specified timesteps and intervals. The SQLite database system was chosen because it requires one file per dataset, it is faster and lighter than a larger server based SQL system, and a simple SQLite ``.db'' file can be used as a input parameter for use with other watersheds.

%Python scripts were created to provide watershed scientists with an advanced set of tools to interpolate weather station data into distributed grids for snow and other models. These tools, listed in Table~\ref{tab:climateTools}, take advantage of services such as the Open Geospatial Consortium's (OGC) web processing services (WPS)~\cite{michaelis2009evaluation}, or ESRI's geoprocessing services. Both services can be implemented in a desktop-based geographic information system (GIS) environment, or accessed through simple web interfaces and RESTful uniform resource locators (URLs), allowing for widespread accessibility and ingestion in to the Virtual Watershed Client for visualisation. Advances in interpolation methods – namely Empirical Bayesian Kriging (EBK) – along with the Python scripting language, allow for efficient processing of weather data over long temporal ranges.


% \begin{table}
%     \centering
%     %\resizebox{\textwidth}{!}{%
%     \begin{tabular}{l l}
%         \cmidrule[0.13em]{1-2}
%         \textbf{Parameter} & \textbf{Interpolation Method} \\ \cmidrule[0.13em]{1-2}
%         total snow cover depth & empirical Bayesian kriging \\ 
%         average snow cover density & elevation gradient \\ 
%         active snow layer temperature & elevation gradient \\ 
%         average snow cover temperature & elevation gradient \\ 
%         \% of liquid H2O saturation & constant \\ 
%         total precipitation mass & empirical Bayesian kriging \\ 
%         percentage of precipitation mass that was snow & lookup table \\ 
%         density of snow portion of the precipitation & lookup table \\ 
%         average precipitation temperature & empirical Bayesian kriging \\ 
%         incoming thermal (long-wave) radiation & (Marks and Dozier, 1979) \\ 
%         air temperature & empirical Bayesian kriging \\ 
%         vapour pressure & empirical Bayesian kriging \\ 
%         wind speed & (Forthofer, 2014) \\ 
%         soil temperature & elevation gradient \\ 
%         net solar radiation & ArcPy library tool \\ \cmidrule[0.13em]{1-2}
%     \end{tabular}%}
%     \caption{Climate Interpolation Tools scripted using Python}
%     \label{tab:climateTools}
% \end{table}


%To provide researchers with the ability to validate or verify interpolation results, an automated tool has been created using a leave-one-out method of cross validation. A python script has been written to automate the process of leave-one-out. For each time step (1-6 hour intervals) the grid is interpolated once for every station leaving out one station at a time.  The predicted value for the left out station is recorded as well as the observed value. The difference between the predicted value and the observed value is the error. Using this error value, error measurements can be calculated to compare the accuracy of the model, as is shown in Figure~\ref{fig:pythonGridOutput}. The outputs provided to the researcher include a graph with a plot of observed versus expected and an image grid showing standard error across the watershed.

% \begin{figure}
%     \centering
%     \includegraphics[width=0.9\columnwidth]{FigureOption1.png}
%     \caption{Reynolds Creek South sub-watershed on January 1, 2008 at 12:00-13:00 A) air temperature EBK interpolated surface from 21 weather stations. B) Standard error for the same time period and stations.}
%     \label{fig:pythonGridOutput}
% \end{figure}

%In creating these tools, snow and other watershed models benefit in several ways. Interpolation and parameter distribution methods use robust processes and interpolation methods. All generated images and error estimation graphs can be visualised in the 3D environment of the VWC. This allows the user to check for errors, anomalies, and patterns before an actual model run. Further, by using the Python scripting language, in conjunction with geoprocessing services, these tools can be implemented in an automated process and are ready to be ingested in ISNOBAL or other models.

\subsection{Other Data Models}
\label{otherModels}

\subsubsection{The DFLOW Model}
calculates the flows of streams specifically for low flowing streams. DFLOW takes daily stream flow information, and can calculate biologically-based design flows, hydrologically-based design flows, and harmonic and percentile flows. This model can be used to calculate across multiple bodies of water.

\subsubsection{The PRMS Model}
is part of our current implementation. The Precipitation Runoff Modeling System (PRMS) has been developed to simulate the hydraulic processes, simulate the hydraulic water budgets of the watershed, integrate with other models, and have a modular design to allow alternative hydrologic-process algorithms. The hydrologic processes modelled in the system include evaporation, transpiration, runoff, infiltration, and interflow. The interflow is determined by the waterbudgets of plant canopy, snowpack, and soil zones calculated by temperature, precipitation, and solar radiation. Additionally, the hydraulic water budget simulation produces temporal data ranging in scale from days to years~\cite{prmsReleaseNotes}.

\subsubsection{The ParFlow Model}
(PARallel FLOW) simulates surface and subsurface flow as an integrated hydrological model. This model runs the parallel simulation with an option of three modes. The first two simulation modes, steady-state saturated and variably saturated, show the flow through heterogeneous porous media. The third mode enable the coupling of the surface and subsurface flow. This enables ParFlow to account for the hillslope runoff and channel routing. ParFlow is the massively parallel computations that run advanced numerical solvers and multigrid preconditioners. This parallel environment takes advantage of octrees to run octree-space partitioning in order to handle input variables in three-space. These features allow ParFlow to run large scale watershed simulations~\cite{maxwell2009parflow}.


\section{Design and Implementation of the Virtual Watershed}
\label{sec:designandimplementationsection}
% Design Parts
The primary intention for the Virtual Watershed Client is
to aid in the visualisation of data collected by environmental
scientists for better understanding of the watershed
environment and the models (ISNOBAL, Parflow, etc.).
Several dependencies are needed for the Virtual Watershed
Client to be functional. The Virtual Watershed Client requires
the Unity game engine, libraries similar to GDAL, and the
OGC services. These dependencies in conjunction with the Unity game engine makes it possible to implement a geospatial tool and application that is unique in comparison to other applications.
The Virtual Watershed Client’s architecture,
functional requirements, implementation, and main use cases are explained in
detail in this section.

\begin{figure}
    \begin{centering}
    \includegraphics[width=0.8\columnwidth]{HighLevelDiagram}
    \par\end{centering}
    \protect\caption{A representation of the Model View Controller architecture of the Virtual Watershed Client.}
    \label{fig:HighLevelDiagram}
\end{figure}

\subsection{Model View Controller Architecture}

The Virtual Watershed Client utilises a Model-View-Controller (MVC) architectural pattern for the user interface
(Figure~\ref{fig:HighLevelDiagram}). The Model component is responsible for querying the
Virtual Watershed Platform for data, the View component is
responsible for displaying the data with the currently applied
settings, and the Controller is responsible for handling any
configuration changes and movement in the world generated by the VWC.
The Model component retrieves data through the OGC
services that can be displayed in the form of terrains, shapes
(rivers, streams, and roads), model data, and imagery. 
The model and view component will be discussed more in this section.

\subsection{Use Cases}

The users of the Virtual Watershed Client are able to
create watershed simulations using data retrieved from the
Virtual Watershed Platform. In addition to selecting the data
for the simulation, users also have the option of configuring
various settings to analyse desired variables of the data in
more detail. One of the approaches taken to enable this level
of analysis is to allow the user to immerse themselves into the
simulation in the sense that he or she can interact with various
objects throughout the environment such as trees and sensors.
Users also have the option to configure settings for data
download speeds, image quality, etc., in order to give greater
flexibility in viewing aspects of the data that are most
important to the specific users’ analyses. Once data has been downloaded, 
users will also be able to configure the representation of that data on the terrain. Figure~\ref{fig:UseCaseModel} demonstrates a general use case model~\cite{sommerville2011software}.

\begin{figure}
    \begin{centering}
    \includegraphics[width=1.0\columnwidth]{UseCaseModel}
    \par\end{centering}
    \protect\caption{A use case model of the Virtual Watershed Client demonstrates different scenarios from the perspectives of a user, the VWC, and the data server of the VWP.}
    \label{fig:UseCaseModel}
\end{figure}

The system being referred to in Figure~\ref{fig:UseCaseModel} is the running application of the Virtual Watershed Client~\cite{lauesen2003task}. Within the use case model, the server is any outside service that the system utilises to acquire data. When the application launches, the user can select a dataset to be loaded from file or
downloaded from the server, as well as configure the
watershed. The system will use the selected dataset and
configurations to start and generate a simulation. Then the 
Virtual Watershed Client will display the terrain and
user/model selected weather conditions. Once the
visualisation has begun, the user can configure a model run,
and have it prepared for simulation by the system. Any data
required for the generation of the model run will be acquired
from the server at this time. While the model is running,
information corresponding to water runoff, snow melt,
underground moisture, etc. will be displayed.

The use cases of Figure~\ref{fig:UseCaseModel} are detailed below: 
\begin{description}
  \item[Initialise GUI] \hfill \\
The GUI of the Virtual Watershed Client is initialzied.
  \item[Query for/ Select Dataset] \hfill \\
Datasets can be queried for or selected that are  acquired from the virtual watershed platform or cached by the VWP.
  \item[Create New Watershed Instance] \hfill \\
The user has option of creating a new watershed instance by selecting a different watershed to start in.
  \item[Configure Watershed] \hfill \\
The VWC can be configured where the user can change what datasets are added to the current watershed.
  \item[Start Simulation] \hfill \\
Once the watershed has been properly configured the watershed can start loading all necessary datasets and load a scene.
  \item[Generate Simulation] \hfill \\
Once the simulation is started the scene in Unity will be generated.
  \item[Run Simulation] \hfill \\
After the scene has been generated, the scene will continue to run automatically.
  \item[Set Terrain Parameters] \hfill \\
Several options are available for the user to selects options such as where the terrain will be located in the real world.
  \item[Configure Model Run] \hfill \\
The Virtual Watershed Client allows the user to configure a model run for running it.
  \item[Generate Model Run] \hfill \\
After a model run has been configured it can be generated. 
  \item[Display Weather Conditions] \hfill \\
The virtual watershed has the ability to visualise different weather conditions that the user can select.
  \item[Run Model] \hfill \\
The user can run models from VWC using the VWP.
Currently the VWC has the ability visualise datasets from previously ran models.
  \item[Display Information] \hfill \\
All of the current datasets, location, elevation, and other useful are provided for the user to view either through the UI or by inspecting the dataset itself.

\end{description}

%\subsection{Functional and Non-Functional Requirements}

% Implementation Parts
%\newpage
\subsection{Graphical User Interface}

\subsubsection{The Time Slider}
shown in Figure~\ref{fig:timeSlider} on the bottom of the image is a tool that allows users to view data maps over time. Once a model run has been downloaded and selected for viewing by the user, it will be loaded into the time slider, as well as a projector onto the terrain in the data's correct geospatial positioning. There are multiple components of the Time Slider feature. The bar through the centre of the Time Slider contains a cursor that shows the current data's position in time related to the overall dataset. The text fields underneath this bar display the information such as the count of the frame currently being displayed, the time that the data corresponds to, how much of the dataset has been downloaded into the Time Slider, and the model run variable that the data represents. On the right side of the Time Slider is a scale configuration tool. This slider allows the user to specify the speed at which they wish to view the data, depending on the overall time differential between the individual data maps. The play button will simply play through the data at the time specified on the speed slider. Finally, the window above the cursor of the Time Slider shows a replica of the data being displayed via the projector. This way, even if the user is not able to view the data directly on the terrain from their current position, they can see the representation of data played out through time. 

\begin{figure}[h]
    \centering
    \includegraphics[width = 1.0\columnwidth]{timeSlider.PNG}
    \caption{The time slider used to visualise temporal data sets such as model run variables.}
    \label{fig:timeSlider}
\end{figure}


\subsubsection{The Configuration Panel}
to the left of Figure~\ref{fig:configPanel} is used to configure the representation of data in the virtual world. One of the major ways that the data can be configured, is by editing the colour-map that is applied to the data. When the data is loaded, the minimum and maximum values are recorded and set to specific colour values. All potential values of the data points between the minimum and maximum are then mapped to an interpolated colour defined by the five colours of the colour-map. These colour ranges are predefined at first, but the user can change the value ranges that each colour represents. Multiple predefined colour-maps are available to the user, with options available to accommodate users with colour-blindness. Extending from the colour-map is the ability to project the resulting data using either a point or bi-linear interpolation mode. The point interpolation mode simply matches one data point in the grid to a single colour value, whereas the bilinear mode blends between the values of the surrounding points to produce a more natural looking representation of the data.

\begin{figure}[h]
    \centering
    \includegraphics[width=0.6\columnwidth]{configPanel.PNG}
    \caption{The configuration panel used to alter aspects of data presentation on the terrain.}
    \label{fig:configPanel}
\end{figure}

At the bottom of the panel are three text fields, allowing the user to shift the data projection or models in the X, Y, and Z coordinates. This is necessary for cases that a dataset did not come with a predefined position, or that the position given was incorrect. Finally, there are options to export the current data frame being displayed to either an image, showing the colour-map representation, or a comma separated value (CSV) file with the values of each point in the data frames grid.  

\subsubsection{The Data-Point Graph}
shown in the bottom right of the Figure~\ref{fig:trendGraph} displays the value at a point on the dataset throughout the time-line of the dataset. The user is able to select a single location on the projected data and the graph will display the data values at that spatial location plotted over the time range of the dataset. The vertical yellow bar of the graph shows the user where in time the currently projected data frame is in relation to the graph as a whole. If the user has two datasets loaded, then there will be two lines present on the graph. This feature allows the user to compare data values of a specific location over two separate model runs or variables. The user will also have the option to download the current graph data as a CSV. 

\subsubsection{The Terrain Slicer}
on the right side of Figure~\ref{fig:slicer} is used for taking 2D cross-sections of the terrain. Two slicer nodes can be placed in the world, and the window of the Terrain Slicer will show a 2D image representing the elevation of the terrain between the two nodes placed. This feature allows for exciting future developments, including the ability to take slices of not only the terrain, but 3D datasets. For example, ParFlow data that models underground water flow could be displayed using the slicer to visualise water flow or ground moisture at differing depths.

\begin{figure}
    \centering
    \begin{minipage}{.45\textwidth}
      \centering
      \includegraphics[width=\textwidth]{Markers.PNG}
      \caption{The data-point graph showing the \mbox{fluctuating} data values of a point over time.}
      \label{fig:trendGraph}
    \end{minipage}%\
    \hfill
    \begin{minipage}{.45\textwidth}
      \centering
      \includegraphics[width=\textwidth]{slicer.PNG}
      \caption{The terrain slicer showing a 2D slice of the environment height-map.}
      \label{fig:slicer}
    \end{minipage}
\end{figure}

\subsection{Implementation}
\subsubsection{Virtual Watershed Client}
The VWC has several dependencies that make it possible to bring geospatial datasets into Unity for visualisation and for analysis. 
Unity was chosen to be used as the visualisation due its cross platform capabilities and its relative ease of use in developing visualisations that could take longer in lower level graphics pipelines such as OpenGL or DirectX. 
Unity actually handles the lower level graphics pipelines in its own implementation. 
These dependencies are GDAL, ProjNet, JSON.net, and Gavaghan Geodesy library. GDAL can parse several different geospatial data formats such as geotiffs, netcdf, and many other formats. Both GDAL and ProjNet include the core functionality to do different types of geospatial calculations such as to reproject one coordinate system into another.  JSON.net was included in the VWC due to its capability to parse JSON files and has been primarily for parsing the RESTful services coming from the VWP. Figure~\ref{fig:BlockDiagram} demonstrates the functionality of the VWC in a block diagram. 


\begin{figure}
    \begin{centering}
    \includegraphics[width=0.95\columnwidth]{blockDiagram}
    \par\end{centering}
    \protect\caption{A programmatic flow diagram of the Virtual Watershed Client. The VWP box indicates some of the different services that the VWC can communicate with and the operations box indicates the different operations that the VWC can take on the data. The data box demonstrates the core types of data that the VWC receives from the VWP. }
    \label{fig:BlockDiagram}
\end{figure}

The VWC makes use of the RESTful services from the VWP to provide the user with data to generate a watershed and visualise different model runs stored on the VWP. One key thing that the VWC has to do is be able to internalise these datasets into a common form that the application to generate the proper visualisation. Several different parsers have been written using the dependencies described previously to bring these datasets into the VWC. 
As the datasets are acquired from the Virtual Watershed they will be cached onto local file system to allow for fast loading if the dataset is selected again for loading. 
These parsers allow us to extract data to build visualisations of many different datasets such as terrains, models that were explained previously, shape files, and images such as landsat imagery.
These visualisation are made possible by the API and functionality provided by Unity.  Another key feature of the VWC is the ability to incorporate other data sets granted that another parser is written for that particular server. 


\subsubsection{Data Capabilities}
% talk about the caching for the data
The Virtual Watershed Client has the capability to load datasets from the VWP or from the local file system. The VWP serves many different types of data in various formats such as NetCDF~\cite{netcdf}, TIFF, shapefile, JSON, XML, CSV, and other formats supported by GDAL due to the OGC services supported by the VWP. We use GDAL to parse these formats whether they are from a web service inside of the VWP, or from the local file system into a common data format that is understandable to the VWC. GDAL effectively expands the VWC and allows us to support multiple formats. Along with GDAL we have designed parsers for the VWP that allows us to parse and pull data out of the VWP itself.

The VWC has been designed in such a way that other web services can be easily incorporated as long as the perspective parsers are written for the web service. These web services can be other servers such as NASA Modis's~\cite{NASA} web services. With the incorporation of web services into the VWC, the ability to add other datasets and models is now possible. 

With the ability to acquire datasets both locally and the VWP, the VWC is able to create different types of visualisations. These visualisations include procedurally built terrain, bring shape files that may be weather stations or roads, load imagery, and temporal-spatial data sets at run time rather than being preprocessed. With the ability to acquire datasets from web services, it will be possible to create other different types of visualisations such as procedurally vegetation, running models inside the VWP, and uploading datasets. 

\subsubsection{Coordinate System Design}

% introduce the VWC coordinate system 
The VWC supports a variety of coordinate systems such that it can represent world datasets in a 3D world and takes into consideration the distance in meters between two objects in order to properly map an object into the virtual world. Our coordinate system utilises libraries such as GDAL and Gavaghan's Geodesy Library~\cite{gavaghan} to perform operations such as handling the placement of entities into the world, calculating distances between two points, and changing the projection of other datasets into the VWC's coordinate system. These libraries have allowed us to create a robust coordinate system that can handle a variety of datasets.

\begin{figure}[b]
    \begin{centering}
    \includegraphics[width=1.0\columnwidth]{utmworld}
    \par\end{centering}
    \protect\caption{A cartographic projection of the Earth demonstrating the UTM Latitudinal and Longitudinal zones. Typically UTM uses the Longitudinal zones where each has a width of six degrees.~\cite{UTMZones}}
    \label{fig:UTMZones}
\end{figure}

In our coordinate system we have decided to use the Universal Transverse Mercator (UTM) coordinate system projections to preserve euclidean relationships between two points.
The UTM coordinate system allows the VWC to represent objects with accurate relational distances. Figure~\ref{fig:UTMZones} demonstrates the UTM coordinate system's 60 longitudinal zones that the Earth is sliced into; measurements using UTM coordinates are usually done within a single zone. A GPS will make use of this coordinate system for relatively short distances due to its accuracy. We utilise this coordinate system for its accuracy in short distances allowing the VWC to place two objects within a reasonable distance of their real world positions, or to project imagery accurately. Though effective when working within an individual zone, the accuracy of the UTM coordinate system diminishes when taking into consideration points that span across two zones.

% talk about limitations to the coordinate system
% talk about the issue of mapping everything into this mercator
The limitations of the UTM coordinate system make it difficult to use datasets that span two zones. Calculating the distance between points overlapping a UTM zone boundary results in major distortions. Additionally, calculations of distance overlapping the equator produce similar distortions. These distortions make it necessary for the addition of other coordinate systems into the VWC that deal with these distortions and effectively estimate the distance for two points.

% Talk about different projections and coordinate systems
% Vincenty
% Haversine
% Hybrid 
% Accuracy and Inaccuracies

% talk about the implementation of the VWC coordinate system
The coordinate system makes use of a frame of reference for placing real world objects into the virtual world of the Unity Game Engine. This frame of reference is paired with the origin in the Unity Game Engine and a location in the real world. This frame of reference allows the VWC to translate real world coordinates into the VWC's coordinate system. Real world points are coordinates having some geospatial relationship to the Earth. These coordinates can be either Latitude and Longitude, UTM points, or other types of coordinates. Unity Game Engine coordinates refer to points that are inside Unity Game Engine with one unit in the Unity Game Engine represented as one meter. This frame of reference makes it easy to convert between the real world and the VWC's visualisation. The frame of reference requires coordinates to be in the Latitude and Longitude system. We utilise Latitude and Longitude points since they are optimal in distance equations, and are easily converted to other coordinate systems. Our coordinate system first converts real world points into a Latitude and Longitude coordinate representation given that they were not originally presented in that format. Algorithm~\ref{alg:worldUnity} demonstrates how the VWC can convert from real world points to the Unity coordinate system and Algorithm~\ref{alg:unityWorld} demonstrates the inverse. 

The two algorithms utilise the reference coordinate points in order to move between the Earth's coordinate system and Unity's coordinate system. The VWC uses two formula's (Haversine and Vincenty) to calculate the distance between two points. The implementation for Haversine comes from~\cite{Dennehy}, and the implementation for Vincenty comes from~\cite{gavaghan}. Algorithm~\ref{alg:worldUnity} is able to handle cases where a data point may be outside the zone currently being observed by the VWC. To account for these cases, Algorithm~\ref{alg:EstimateProjection} is used to estimate the equivalent point in Unity. This algorithm estimates a projected point using either the Haversine or Vincenty formula based on the converted Latitude and Longitude calculated in Algorithm~\ref{alg:worldUnity}, and the world Latitude Longitude reference point. Despite the effectiveness of the Haversine and Vincenty formula, they are only accurate to a certain degree. Both of these formula's will work relatively well, however they may not accurately represent the scale of the UTM coordinate system. To account for these inaccuracies our system will allow the user to move datasets if their positions in the virtual world differ from the proper location.  % get how inaccurate both vincenty and haversine are 

\begin{algorithm}
\caption{World to Unity}
\label{alg:worldUnity}
\begin{algorithmic}[1]
\Function{World to Unity}{$WorldPoint$}
    \State $ConvertedWorldPoint \gets \Call{ConvertToLatLong}{WorldPoint}$
    \State $Zone = \Call{CalculateZone}{ConvertedWorldPoint}$
    \If{$Zone \neq WorldZone$} 
    \State $ConvertedWorldPoint \gets \Call{EstimateProjection}{ConvertedWorldPoint}$
    \Else 
    \State $ConvertedWorldPoint \gets \Call{ConvertToUTM}{ConvertedWorldPoint}$
    \EndIf
    \State \Return $(UnityReferenceOrigin +$\\
    \hspace*{0.6in}$ (UTMWorldReferencePoint-$ $ConvertedWorldPoint))$ 
\EndFunction
\end{algorithmic}
\end{algorithm}

\begin{algorithm}
\caption{Unity to World}
\label{alg:unityWorld}
\begin{algorithmic}[1]
\Function{Unity to World}{$UnityPoint$}
    \State $ ConvertedWorldPoint \gets \Call{ConvertToLatLong}{UTMWorldReferencePoint + (UnityReferenceOrigin - UnityPoint),ZoneNumber}$
    \State \Return $ConvertedWorldPoint$
\EndFunction
\end{algorithmic}
\end{algorithm}

\begin{algorithm}
\caption{Estimate Projection}
\label{alg:EstimateProjection}
\begin{algorithmic}[1]
\Function{EstimateProjection}{$WorldPoint$}
    \If{$Vincenty$}
    \State $Distance \gets \Call{VincentyDistanceEstimation}{WorldPoint,$ $LatLongWorldReferencePoint}$
    \ElsIf{$Haversine$}
    \State $Distance \gets \Call{HaversineDistanceEstimation}{WorldPoint,$ $LatLongWorldReferencePoint}$
    \EndIf
    \State $Direction \gets WorldPoint-LatLongWorldReferencePoint$
    \State $ProjectedWorldPoint  \gets Distance * Direction$
    \State \Return $ProjectedWorldPoint$
\EndFunction
\end{algorithmic}
\end{algorithm}

\section{Virtual Watershed Examples: Lehman Creek and Dry Creek}
\label{sec:ExampleOfVW}
% Dry Creek Example
The Unity engine is a platform for building interactive
virtual environments. It provides an integrated development
environment (IDE) consisting of a GUI and scripting to define
the appearance and behaviour of objects in the virtual
environment. The Unity engine allows developers to combine
2D and 3D visual assets, audio, and network access to data.
The Unity engine is built with Mono, which is a cross-platform
open source implementation of the .NET
framework~\cite{monoproject2015com, msdn2015microsoft}. Using Mono allows for procedural
control, creation, and manipulation of objects in UnityScript
(Javascript) and C\#. The engine provides a well optimised
code base capable of displaying high-fidelity
interactive 3D virtual environments with real-time physics and
shading. Although Unity offers great potential to geoscience
visualisation and education outreach, the IDE has a steep
learning curve and is not natively equipped with essential
features like geo-referencing, Gregorian time, or the ability to
handle geospatial datasets (GeoTiffs, ShapeFiles, etc.)
common to GIS Desktop solutions.

The Virtual Watershed Client will provide a simple GUI for
communicating to a centralised Virtual Watershed Platform.
%However, instead of communicating with the Virtual
%Watershed Platform, datasets are acquired and preprocessed
%from a local file system.
Acquiring datasets for visualisation is now possible through the VWP within the VWC or the local file system.  
Several visualisations have been developed for the Virtual
Watershed Client using preprocessed files from the local file system. Datasets acquired from the VWP can be used to procedurally build a terrain for visualisation at run time of the Virtual Watershed Client. We have constructed preprocessed terrains for the WC-WAVE project that are being used for analysing datasets that are specific to the WC-WAVE project.
%dry creek comparison
\begin{figure}
    \centering
    \begin{minipage}{.5\textwidth}
      \centering
      \includegraphics[width=.95\linewidth]{PhotoComparison}
      \captionof{figure}{A photograph of Dry Creek}
      \label{fig:DCPhotoComparison}
    \end{minipage}%
    \begin{minipage}{.5\textwidth}
      \centering
      \includegraphics[width=.95\linewidth]{ComparisonImage}
      \captionof{figure}{The VWC image of Dry Creek.}
      \label{fig:DCComparisonImage}
    \end{minipage}
\end{figure}

% lehman creek comparison
\begin{figure}
    \centering
    \begin{minipage}{.5\textwidth}
      \centering
      \includegraphics[width=.95\linewidth]{reallehmanfigure.jpg}
      \captionof{figure}{A photograph of Lehman Creek}
      \label{fig:LCPhotoComparison}
    \end{minipage}%
    \begin{minipage}{.5\textwidth}
      \centering
      \includegraphics[width=.95\linewidth]{LehmanVis.png}
      \captionof{figure}{The VWC image of Lehman Creek.}
      \label{fig:LCComparisonImage}
    \end{minipage}
\end{figure}

% the process of building stand alones
The process of building preprocessed terrains requires certain datasets to create a well built visualisation.
When available, high-resolution LiDAR can be represented by the terrain. High-resolution
orthoimagery is then placed on the terrain, and
procedurally splatted with detailed textures and vegetation (as
shown in Figure~\ref{fig:DCComparisonImage} and Figure~\ref{fig:LCComparisonImage}). Both Figure~\ref{fig:DCComparisonImage} and Figure~\ref{fig:LCComparisonImage} can be compared to their respective counterparts, Figure~\ref{fig:DCPhotoComparison} and Figure~\ref{fig:LCPhotoComparison}, that demonstrate the overall effectiveness of our visualisation. 

Once a base map has been constructed,
scientific data can be incorporated. A Projector with a
customized shader allows for choropleths (thematic maps) to
be overlaid onto the terrain as shown in Figures~\ref{fig:UI} and \ref{fig:Choropleth}. These maps
could represent characteristics of terrain topology like slope or
spatial-temporal variables associated with hydrology models
such as ISNOBAL, Parflow, or PRMS. An example of a spatial-temporal output of an ISNOBAL variable can be seen in Figure~\ref{fig:UI}. % We get a close up here!

\begin{figure}[b]
    \centering
    \includegraphics[width=1.0\columnwidth]{NewUI.png}
    \caption{The entire user interface shown on the Dry Creek terrain with a thermal long wave radiation dataset projected on to the surface.}
    \label{fig:UI}
\end{figure}

We can also visualise the outputs of a PRMS model by playing back the output file onto the terrain as a choropleth. As explained previously in Section~\ref{sec:designandimplementationsection}, the user can alter the values of the projector, change the times on the time slider, or compare two model runs.

\begin{figure}
    \begin{centering}
    \includegraphics[width=1.0\columnwidth]{Choropleth}
    \par\end{centering}
    \protect\caption{\label{fig:Choropleth} A picture of the Dry Creek sub-catchment with choropleth (right) and without choropleth (left).}
\end{figure}


\section{Future Work and Conclusions}
\label{sec:FutureWork}
% recap of the paper
We have covered the design and implementation of the Virtual Watershed Client, the different models of the WC-WAVE project, and new additions to the VWC. This paper discussed the unique design of a three-dimensional project for the use with geospatial data. The project incorporates the GDAL libraries into a game development engine, Unity3D, for purposes of research. Additionally the unique tools designed into the project to interact with the data will help researchers gather more information from the provided data. The VWC has several new features that include elements that have been added to the UI, a new coordinate system, the ability to visualise spatial-temporal datasets, generate terrains procedurally, and the incorporation of the Virtual Watershed Platform. With the addition of these new features researchers can visit different areas in the world and utilise the new features for the purposes of analysing datasets that are both stored locally and on the VWP.

In terms of future work the team is planning new features that would be both beneficial and needed for the Virtual Watershed Client.
Integration with the VWP has allowed us to incorporate procedural terrain generation and allows us to consider implementing procedural vegetation generation. Being able to procedurally generate vegetation alongside terrain would allow us to simulate different models such as CASiMiR that have a vegetation output. Watershed researchers could effectively analyse the effect of changing seasons, climate, and fire scenarios. We will soon incorporate the ability to visualise vector motion fields that would be useful for showing stream flow in the bottom of a river or to demonstrate wind. To provide a more immersive experience of the Virtual Watershed Client with virtual reality, we would like to allow the user to to use Head Mounted Displays (HMD) such as the Oculus Rift~\cite{vr2015oculus}, HTC Vive~\cite{htcVive}, or Google Cardboard~\cite{googleCardboard}. We would like to also build a visualization for a six-sided CAVE (Cave auto virtual environment). We would like to incorporate other sensors such as the Microsoft Kinect~\cite{microsoft2015com} and others. Beyond new visualisations features and the incorporation of other sensors we have plans to incorporate other services from the Virtual Watershed Platform and other servers.

% conclude the journal 
The Virtual Watershed Client currently is able to interface with the Virtual Watershed Platform and download datasets from it. We would like to expand our functionality to allow users to upload datasets to the Virtual Watershed Platform and run models on those datasets. While the Virtual Watershed Platform support for many other different types of datasets related to the WC-WAVE project, we would to include other servers such as NASA's Modis web services~\cite{NASA} that have global datasets that could be beneficial to the Virtual Watershed Client. Incorporation of these other web services would be both beneficial and useful for the Virtual Watershed Client and would allow for a greater diversity of datasets to be visualised and analysed within the VWC.

%\section{Copyright Statement} Is this important
\ack This material is based in part upon work supported by the National Science Foundation under grant numbers: IIA-1329469, IIA-1329470, IIA-1329513, and IIA-1301726, and the EPSCoR MILES grant number: IIA-1301792. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the National Science Foundation

% use the wileyj.bst for styling the bibilography
\bibliographystyle{wileyj}
\bibliography{CCPE2016}

\end{document}
