melch/mt-polygon-simplification
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

restructure

Browse Source
This commit is contained in:
Alfred Melch 2019-08-10 14:08:44 +02:00
parent 368dcfe02b
commit 442b4d911a
10 changed files with 285 additions and 287 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
thesis/chapters.tex
View File

@ -5,10 +5,7 @@
\input{./chapters/02.03-Algorithms.tex}
\input{./chapters/02.04-webruntime.tex}
\input{./chapters/03.00-methodology.tex}
\input{./chapters/03.01-benchmark.tex}
\input{./chapters/03.02-integration.tex}
\input{./chapters/04.00-results.tex}
\input{./chapters/04.01-results-benchmark.tex}
\input{./chapters/04.02-results-integration.tex}
\input{./chapters/05-conclusion.tex}
\input{./chapters/06-conclusion.tex}
\input{./chapters/07-application.tex}

174
thesis/chapters/03.00-methodology.tex
View File

@ -1,13 +1,175 @@
\section{Methodology}
\section[Methodology]{Implementation of a performance benchmark}
The benefits that WebAssembly promises shall be tested in two seperate web pages. One for the performance measurements and one to test the integration of existing libraries.
% Performance benchmark
\paragraph{Performance}
In this chapter I will explain the approach to improve the performance of a simplification algorithm in a web browser via WebAssembly. The go-to library for this kind of operation is Simplify.js. It is the JavaScript implementation of the Douglas-Peucker algorithm with optional radial distance preprocessing. The library will be rebuilt in the C programming language and compiled to WebAssembly with Emscripten. A web page is built to produce benchmarking insights to compare the two approaches performance wise.
As it is the most applicated algorithm the Douglas-Peucker algorithm will be used for measuring performance. A JavaScript implementation is quickly found. SimplifyJS. It is used by Turf, a geospatial analysis library. To produce comparable results the implementation will be based on this package. A separate library, called SimplifyWASM, written in C will be created that mimics the JavaScript original.
\subsection{State of the art: Simplify.js}
\label{sec:simplify.js}
% Simplify.JS + turf
\paragraph{Integrating an existing C++ library}
Simplify.js calls itself a "tiny high-performance JavaScript polyline simplification library"\footnote{\path{https://mourner.giformthub.io/simplify-js/}}. It was extracted from Leaflet, the "leading open-source JavaScript library for mobile-friendly interactive maps"\footnote{\path{https://leafletjs.com/}}. Due to its usage in leaflet and Turf.js, a geospatial analysis library, it is the most common used library for polyline simplification. The library itself currently has 20,066 weekly downloads while the Turf.js derivate @turf/simplify has 30,389. Turf.js maintains an unmodified fork of the library in its own repository. \todo{leaflet downloads}
An existing implementation of several simplification algorithms has been found in the C++ ecosystem. \textsf{psimpl} implements 8 algorithms distributed as a single header file. It also provides a function for measuring positional errors making it ideal for use in a quality analysis tool for those algorithms.
The Douglas-Peucker algorithm is implemented with an optional radial distance preprocessing routine. This preprocessing trades performance for quality. Thus the mode for disabling this routine is called highest quality.
Interestingly the library expects coordinates to be a list of object with x and y properties. GeoJSON and TopoJSON however store coordinates in nested array form (see chapter \ref{ch:dataformats}). Luckily since the library is small and written in JavaScript any skilled web developer can easily fork and modify the code for his own purpose. This is even pointed out in the source code. The fact that Turf.js, which can be seen as a convenience wrapper for processing GeoJSON data, decided to keep the library as is might indicate some benefit to this format. Listing \ref{lst:turf-transformation} shows how Turf.js calls Simplify.js. Instead of altering the source code the data is transformed back and forth between the formats on each call. It is questionable if this practice is advisable at all.
\lstinputlisting[
float=htbp,
language=javascript,
firstline=116, lastline=122,
caption=Turf.js usage of simplify.js,
label=lst:turf-transformation
]{../lib/turf-simplify/index.js}
Since it is not clear which case is faster, and given how simple the required changes are, two versions of Simplify.js will be tested. The original version, which expects the coordinates to be in array-of-objects format and the altered version, which operates on nested arrays. Listing \ref{lst:diff-simplify.js} shows an extract of the changes performed on the library. Instead of using properties, the coordinate values are accessed by index. Except for the removal of the licensing header the alterations are restricted to these kind of changes. The full list of changes can be viewed in \path{lib/simplify-js-alternative/simplify.diff}.
\lstinputlisting[
float=htbp,
language=diff,
firstline=11, lastline=16,
caption=Snippet of the difference between the original Simplify.js and alternative,
label=lst:diff-simplify.js
]{../lib/simplify-js-alternative/simplify.diff}
\subsection{The webassembly solution}
\label{sec:benchmark-webassembly}
In scope of this thesis a library will be created that implements the same procedure as Simplify.JS in C code. It will be made available on the web platform through WebAssembly. In the style of the model library it will be called Simplify.wasm. The compiler to use will be Emscripten as it is the standard for porting C code to WebAssembly.
As mentioned the first step is to port simplify.JS to the C programming language. The file \path{lib/simplify-wasm/simplify.c} shows the attempt. It is kept as close to the JavaScript library as possible. This may result in C-untypical coding style but prevents skewed results from unexpected optimizations to the procedure itself. The entry point is not the \texttt{main}-function but a function called simplify. This is specified to the compiler as can be seen in listing \ref{lst:simplify-wasm-compiler-call}.
\lstinputlisting[
float=htpb,
language=bash,
% firstline=2, lastline=3,
label=lst:simplify-wasm-compiler-call,
caption={The compiler call}
]{../lib/simplify-wasm/Makefile}
\todo{More about the compiler call}
Furthermore the functions malloc and free from the standard library are made available for the host environment. Compiling the code through Emscripten produces a binary file in wasm format and the glue code as JavaScript. These files are called \texttt{simplify.wasm} and \texttt{simplify.js} respectively.
An example usage can be seen in \path{lib/simplify-wasm/example.html}. Even through the memory access is abstracted in this example the process is still unhandy and far from a drop-in replacement of Simplify.js. Thus in \path{lib/simplify-wasm/index.js} a further abstraction to the Emscripten emitted code was written. The exported function \texttt{simplifyWasm} handles module instantiation, memory access and the correct call to the exported wasm function. Finding the correct path to the wasm binary is not always clear however when the code is imported from another location. The proposed solution is to leave the resolving of the code-path to an asset bundler that processes the file in a preprocessing step.
\lstinputlisting[
float=htpb,
language=javascript,
firstline=22, lastline=33,
label=lst:simplify-wasm
]{../lib/simplify-wasm/index.js}
Listing \ref{lst:simplify-wasm} shows the function \texttt{simplifyWasm}. Further explanaition will follow regarding the abstractions \texttt{getModule}, \texttt{storeCoords} and \texttt{loadResultAndFreeMemory}.
\paragraph {Module instantiation} will be done on the first call only but requires the function to be asynchronous. For a neater experience in handling Emscripten modules a utility function named \texttt{initEmscripten}\footnote{/lib/wasm-util/initEmscripten.js} was written to turn the module factory into a JavaScript Promise that resolves on finished compilation. The usage of this function can be seen in listing \ref{lst:simplify-wasm-emscripten-module}. The resulting WebAssembly module is cached in the variable \texttt{emscriptenModule}.
\lstinputlisting[
float=htbp,
language=javascript,
firstline=35, lastline=40,
caption=My Caption,
label=lst:simplify-wasm-emscripten-module
]{../lib/simplify-wasm/index.js}
\paragraph {Storing coordinates} into the module memory is done in the function \texttt{storeCoords}. Emscripten offers multiple views on the module memory. These correspond to the available WebAssembly data types (e.g. HEAP8, HEAPU8, HEAPF32, HEAPF64, ...)\footnote{\path{https://emscripten.org/docs/api_reference/preamble.js.html#type-accessors-for-the-memory-model}}. As Javascript numbers are always represented as a double-precision 64-bit binary\footnote{\path{https://www.ecma-international.org/ecma-262/6.0/#sec-4.3.20}} (IEEE 754-2008) the HEAP64-view is the way to go to not lose precision. Accordingly the datatype double is used in C to work with the data. Listing \ref{lst:wasm-util-store-coords} shows the transfer of coordinates into the module memory. In line 3 the memory is allocated using the exported \texttt{malloc}-function. A JavaScript TypedArray is used for accessing the buffer such that the loop for storing the values (lines 5 - 8) is trivial.
\lstinputlisting[
float=tbph,
language=javascript,
firstline=12, lastline=21,
caption=The storeCoords function,
label=lst:wasm-util-store-coords
]{../lib/wasm-util/coordinates.js}
\todo{programming: Check for coords length $<$ 2}
\paragraph{To read the result} back from memory we have to look at how the simplification will be returned in the C code. Listing \ref{lst:simplify-wasm-entrypoint} shows the entry point for the C code. This is the function that gets called from JavaScript. As expected arrays are represented as pointers with corresponding length. The first block of code (line 2 - 6) is only meant for declaring needed variables. Lines 8 to 12 mark the radial distance preprocessing. The result of this simplification is stored in an auxiliary array named \texttt{resultRdDistance}. In this case \texttt{points} will have to point to the new array and the length is adjusted. Finally the Douglas-Peucker procedure is invoked after reserving enough memory. The auxiliary array can be freed afterwards. The problem now is to return the result pointer and the array length back to the calling code. \todo{Fact check. evtl unsigned}The fact that pointers in Emscripten are represented by an integer will be exploited to return a fixed size array of two containing the values. A hacky solution but it works. We can now look back at how the JavaScript code reads the result.
\lstinputlisting[
float=tbph,
language=c,
firstline=104, lastline=124,
caption=Entrypoint in the C-file,
label=lst:simplify-wasm-entrypoint
]{../lib/simplify-wasm/simplify.c}
Listing \ref{lst:wasm-util-load-result} shows the code to read the values back from module memory. The result pointer and its length are acquired by dereferencing the \texttt{resultInfo}-array. The buffer to use is the heap for unsigned 32-bit integers. This information can then be used to align the Float64Array-view on the 64-bit heap. Constructing the appropriate coordinate representation by reversing the flattening can be looked up in the same file. It is realised in the \texttt{unflattenCoords} function. At last it is important to actually free the memory reserved for both the result and the result-information. The exported method \texttt{free} is the way to go here.
\lstinputlisting[
float=!tbph,
language=javascript,
firstline=29, lastline=43,
caption=Loading coordinates back from module memory,
label=lst:wasm-util-load-result
]{../lib/wasm-util/coordinates.js}
\subsection{The implementation of a web framework}
\label{ch:benchmark-app}
The performance comparison of the two methods will be realized in a web page. It will be a built as a front-end web-application that allows the user to specify the input parameters of the benchmark. These parameters are: The polyline to simplify, a range of tolerances to use for simplification and if the so called high quality mode shall be used. By building this application it will be possible to test a variety of use cases on multiple devices. Also the behavior of the algorithms can be researched under different preconditions. In the scope of this thesis a few cases will be investigated. The application structure will now be introduced.
\subsubsection{External libraries}
The dynamic aspects of the web page will be built in JavaScript to make it run in the browser. Webpack\footnote{https://webpack.js.org/} will be used to bundle the application code and use compilers like babel\footnote{https://babeljs.io/} on the source code. As mentioned in section \ref{sec:benchmark-webassembly} the bundler is also useful for handling references to the WebAssembly binary as it resolves the filename to the correct download path to use. There will be intentionally no transpiling of the JavaScript code to older versions of the ECMA standard. This is often done to increase compatibility with older browsers. Luckily this is not a requirement in this case and by refraining from this practice there will also be no unintentional impact on the application performance. Libraries in use are Benchmark.js\footnote{https://benchmarkjs.com/} for statistically significant benchmarking results, React\footnote{https://reactjs.org/} for the building the user interface and Chart.js\footnote{https://www.chartjs.org/} for drawing graphs.
\subsubsection{The application logic}
The web page consist of static and dynamic content. The static parts refer to the header and footer with explanation about the project. Those are written directly into the root HTML document. The dynamic parts are injected by JavaScript. Those will be further discussed in this chapter as they are the main application logic.
\begin{figure}[htb]
\centering
\label{fig:benchmarking-uml}
\fbox{\includegraphics[width=\linewidth]{images/benchmark-uml.jpg}}
\caption{UML diagram of the benchmarking application}
\end{figure}
The web app is built to test a variety of cases with multiple datapoints. As mentioned Benchmark.js will be used for statistically significant results. It is however rather slow as it needs about 5 to 6 seconds per datapoint. This is why multiple types of benchmarking methods are implemented. Figure \ref{fig:benchmarking-uml} shows the corresponding UML diagram of the application. One can see the UI components in the top-left corner. The root component is \texttt{App}. It gathers all the internal state of its children and passes state down where it is needed.
\subsubsection{Benchmark cases and chart types}
\label{ch:benchmark-cases}
In the upper right corner the different Use-Cases are listed. These cases implement a function \texttt{"fn"} to benchmark. Additional methods for setting up the function and clean up afterwards can be implemented as given by the parent class \texttt{BenchmarkCase}. Concrete cases can be created by instantiating one of the BenchmarkCases with a defined set of parameters. There are three charts that will be rendered using a subset of these cases. These are:
\begin{itemize}
\item \textbf{Simplify.js vs Simplify.wasm} - This Chart shows the performance of the simplification by Simplify.js, the altered version of Simplify.js and the newly developed Simplify.wasm. \todo{Cases}
\item \textbf{Simplify.wasm runtime analysis} - To further gain insights to WebAssembly performance this stacked barchart shows the runtime of a call to Simplify.wasm. It is partitioned into time spent for preparing data (\texttt{storeCords}), the algorithm itself and the time it took for the coordinates being restored from memory (\texttt{loadResult}).
\item \textbf{Turf.js method runtime analysis} - The last chart will use a similar structure. This time it analyses the performance impact of the back and forth transformation of data used in Truf.js. \todo{Cases}
\end{itemize}
\subsubsection{The different benchmark types}
On the bottom the different types of Benchmarks implemented can be seen. They all implement the abstract \texttt{measure} function to return the mean time to run a function specified in the given BenchmarkCase. The \texttt{IterationsBenchmark} runs the function a specified number of times, while the \texttt{OpsPerTimeBenchmark} always runs a certain amount of milliseconds to tun as much iterations as possible. Both methods got their benefits and drawbacks. Using the iterations approach one cannot determine the time the benchmark runs beforehand. With fast devices and a small number of iterations one can even fall in the trap of the duration falling under the accuracy of the timer used. Those results would be unusable of course. It is however a very fast way of determining the speed of a function. And it holds valuable for getting a first approximation of how the algorithms perform over the span of datapoints. The second type, the operations per time benchmark, seems to overcome this problem. It is however prune to garbage collection, engine optimizations and other background processes. \footnote{\path{https://calendar.perfplanet.com/2010/bulletproof-javascript-benchmarks/}}
Benchmark.js combines these approaches. In a first step it approximates the runtime in a few cycles. From this value it calculates the number of iterations to reach an uncertainty of at most 1\%. Then the samples are gathered. \todo{more about Benchmark.js}\footnote{\path{http://monsur.hossa.in/2012/12/11/benchmarkjs.html}}
\subsubsection{The benchmark suite}
For running multiple benchmarks the class \texttt{BenchmarkSuite} was created. It takes a list of BenchmarkCases and runs them through a BenchmarkType. The Suite manages starting, pausing and stopping of going through list. It updates the statistics gathered on each cycle. By injecting an onCycle method, the \texttt{App} component can give live feedback about the progress.
\todo[inline]{Add digram: state machine for suite}
\todo[inline]{Explain state machine}
\subsubsection{The user interface}
\begin{figure}[htbp]
\centering
\fbox{\includegraphics[width=.9\linewidth]{images/benchmark-ui.png}}
\caption{The user interface for benchmarking application. (not final)}
\label{fig:benchmart-ui}
\end{figure}
The user interface has three regions. One for configuring input parameters. One for controlling the benchmark process and at last a diagram of the results.
\paragraph{Settings} At first the input parameters of the algorithm have to be specified. For that there are some polylines prepared to choose from. They are introduced in chapter \ref{ch:benchmark-data}. Instead of testing a single tolerance value the user can specify a range. This way the behavior of the algorithms can be observed in one chart. The high quality mode got its name from Simplify.js. If it is enabled there will be no radial-distance preprocessing step before applying the Douglas-Peucker routine. The next option determines which benchmarks will be run. The options are mentioned in chapter \ref{ch:benchmark-cases}. One of the three benchmark methods implemented can be selected. Depending on the method chosen additional options will show to further specify the benchmark parameters. The last option deals with chart rendering. Debouncing limits the rate at which functions fire. In this case the chart will delay rendering when datapoints come in at a fast rate.
\paragraph{Run Benchmark} This is the control that displays the status of the benchmark suite. Here benchmarks can be started, stopped, paused and resumed. It also shows the progress of the benchmarks completed in percentage and absolute numbers.
\paragraph{Chart} The chart shows a live diagram of the results. The title represents the selected chart. The legend gives information on which benchmark cases will run. Also the algorithm parameters (dataset and high quality mode) and current platform description can be found here. The tolerance range maps over the x-Axis. On the y-Axis two scales can be seen. The left hand shows by which unit the performance is displayed. This scale corresponds to the colored lines. Every chart will show the number of positions in the result as a grey line. Its scale is displayed on the right. This information is important for selecting a proper tolerance range as it shows if a appropriate order of magnitude has been chosen. Below the chart additional control elements are placed to adjust the visualization. The first selection lets the user choose between a linear or logarithmic y-Axis. The second one changes the unit of measure for performance. The two options are the mean time in milliseconds per operation (ms) and the number of operations that can be run in one second (hz). These options are only available for the chart "Simplify.wasm vs. Simplify.js" as the other two charts are stacked bar charts where changing the default options won't make sense. Finally the result can be saved via a download button. A separate page can be fed with this file to display the diagram only.
\subsection{The test data}
\label{ch:benchmark-data}
\paragraph{Simplify.js example}
\paragraph{Bavaria outline}

168
thesis/chapters/03.01-benchmark.tex
View File

@ -1,168 +0,0 @@
\subsection{Implementation of a performance benchmark}
% Performance benchmark
In this chapter I will explain the approach to improve the performance of a simplification algorithm in a web browser via WebAssembly. The go-to library for this kind of operation is Simplify.js. It is the JavaScript implementation of the Douglas-Peucker algorithm with optional radial distance preprocessing. The library will be rebuilt in the C programming language and compiled to WebAssembly with Emscripten. A web page is built to produce benchmarking insights to compare the two approaches performance wise.
\subsubsection{State of the art: Simplify.js}
\label{sec:simplify.js}
% Simplify.JS + turf
Simplify.js calls itself a "tiny high-performance JavaScript polyline simplification library"\footnote{\path{https://mourner.giformthub.io/simplify-js/}}. It was extracted from Leaflet, the "leading open-source JavaScript library for mobile-friendly interactive maps"\footnote{\path{https://leafletjs.com/}}. Due to its usage in leaflet and Turf.js, a geospatial analysis library, it is the most common used library for polyline simplification. The library itself currently has 20,066 weekly downloads while the Turf.js derivate @turf/simplify has 30,389. Turf.js maintains an unmodified fork of the library in its own repository. \todo{leaflet downloads}
The Douglas-Peucker algorithm is implemented with an optional radial distance preprocessing routine. This preprocessing trades performance for quality. Thus the mode for disabling this routine is called highest quality.
Interestingly the library expects coordinates to be a list of object with x and y properties. GeoJSON and TopoJSON however store coordinates in nested array form (see chapter \ref{ch:dataformats}). Luckily since the library is small and written in JavaScript any skilled web developer can easily fork and modify the code for his own purpose. This is even pointed out in the source code. The fact that Turf.js, which can be seen as a convenience wrapper for processing GeoJSON data, decided to keep the library as is might indicate some benefit to this format. Listing \ref{lst:turf-transformation} shows how Turf.js calls Simplify.js. Instead of altering the source code the data is transformed back and forth between the formats on each call. It is questionable if this practice is advisable at all.
\lstinputlisting[
float=htbp,
language=javascript,
firstline=116, lastline=122,
caption=Turf.js usage of simplify.js,
label=lst:turf-transformation
]{../lib/turf-simplify/index.js}
Since it is not clear which case is faster, and given how simple the required changes are, two versions of Simplify.js will be tested. The original version, which expects the coordinates to be in array-of-objects format and the altered version, which operates on nested arrays. Listing \ref{lst:diff-simplify.js} shows an extract of the changes performed on the library. Instead of using properties, the coordinate values are accessed by index. Except for the removal of the licensing header the alterations are restricted to these kind of changes. The full list of changes can be viewed in \path{lib/simplify-js-alternative/simplify.diff}.
\lstinputlisting[
float=htbp,
language=diff,
firstline=11, lastline=16,
caption=Snippet of the difference between the original Simplify.js and alternative,
label=lst:diff-simplify.js
]{../lib/simplify-js-alternative/simplify.diff}
\subsubsection{The webassembly solution}
\label{sec:benchmark-webassembly}
In scope of this thesis a library will be created that implements the same procedure as Simplify.JS in C code. It will be made available on the web platform through WebAssembly. In the style of the model library it will be called Simplify.wasm. The compiler to use will be Emscripten as it is the standard for porting C code to WebAssembly.
As mentioned the first step is to port simplify.JS to the C programming language. The file \path{lib/simplify-wasm/simplify.c} shows the attempt. It is kept as close to the JavaScript library as possible. This may result in C-untypical coding style but prevents skewed results from unexpected optimizations to the procedure itself. The entry point is not the \texttt{main}-function but a function called simplify. This is specified to the compiler as can be seen in listing \ref{lst:simplify-wasm-compiler-call}.
\lstinputlisting[
float=htpb,
language=bash,
% firstline=2, lastline=3,
label=lst:simplify-wasm-compiler-call,
caption={The compiler call}
]{../lib/simplify-wasm/Makefile}
\todo{More about the compiler call}
Furthermore the functions malloc and free from the standard library are made available for the host environment. Compiling the code through Emscripten produces a binary file in wasm format and the glue code as JavaScript. These files are called \texttt{simplify.wasm} and \texttt{simplify.js} respectively.
An example usage can be seen in \path{lib/simplify-wasm/example.html}. Even through the memory access is abstracted in this example the process is still unhandy and far from a drop-in replacement of Simplify.js. Thus in \path{lib/simplify-wasm/index.js} a further abstraction to the Emscripten emitted code was written. The exported function \texttt{simplifyWasm} handles module instantiation, memory access and the correct call to the exported wasm function. Finding the correct path to the wasm binary is not always clear however when the code is imported from another location. The proposed solution is to leave the resolving of the code-path to an asset bundler that processes the file in a preprocessing step.
\lstinputlisting[
float=htpb,
language=javascript,
firstline=22, lastline=33,
label=lst:simplify-wasm
]{../lib/simplify-wasm/index.js}
Listing \ref{lst:simplify-wasm} shows the function \texttt{simplifyWasm}. Further explanaition will follow regarding the abstractions \texttt{getModule}, \texttt{storeCoords} and \texttt{loadResultAndFreeMemory}.
\paragraph {Module instantiation} will be done on the first call only but requires the function to be asynchronous. For a neater experience in handling Emscripten modules a utility function named \texttt{initEmscripten}\footnote{/lib/wasm-util/initEmscripten.js} was written to turn the module factory into a JavaScript Promise that resolves on finished compilation. The usage of this function can be seen in listing \ref{lst:simplify-wasm-emscripten-module}. The resulting WebAssembly module is cached in the variable \texttt{emscriptenModule}.
\lstinputlisting[
float=htbp,
language=javascript,
firstline=35, lastline=40,
caption=My Caption,
label=lst:simplify-wasm-emscripten-module
]{../lib/simplify-wasm/index.js}
\paragraph {Storing coordinates} into the module memory is done in the function \texttt{storeCoords}. Emscripten offers multiple views on the module memory. These correspond to the available WebAssembly data types (e.g. HEAP8, HEAPU8, HEAPF32, HEAPF64, ...)\footnote{\path{https://emscripten.org/docs/api_reference/preamble.js.html#type-accessors-for-the-memory-model}}. As Javascript numbers are always represented as a double-precision 64-bit binary\footnote{\path{https://www.ecma-international.org/ecma-262/6.0/#sec-4.3.20}} (IEEE 754-2008) the HEAP64-view is the way to go to not lose precision. Accordingly the datatype double is used in C to work with the data. Listing \ref{lst:wasm-util-store-coords} shows the transfer of coordinates into the module memory. In line 3 the memory is allocated using the exported \texttt{malloc}-function. A JavaScript TypedArray is used for accessing the buffer such that the loop for storing the values (lines 5 - 8) is trivial.
\lstinputlisting[
float=tbph,
language=javascript,
firstline=12, lastline=21,
caption=The storeCoords function,
label=lst:wasm-util-store-coords
]{../lib/wasm-util/coordinates.js}
\todo{programming: Check for coords length $<$ 2}
\paragraph{To read the result} back from memory we have to look at how the simplification will be returned in the C code. Listing \ref{lst:simplify-wasm-entrypoint} shows the entry point for the C code. This is the function that gets called from JavaScript. As expected arrays are represented as pointers with corresponding length. The first block of code (line 2 - 6) is only meant for declaring needed variables. Lines 8 to 12 mark the radial distance preprocessing. The result of this simplification is stored in an auxiliary array named \texttt{resultRdDistance}. In this case \texttt{points} will have to point to the new array and the length is adjusted. Finally the Douglas-Peucker procedure is invoked after reserving enough memory. The auxiliary array can be freed afterwards. The problem now is to return the result pointer and the array length back to the calling code. \todo{Fact check. evtl unsigned}The fact that pointers in Emscripten are represented by an integer will be exploited to return a fixed size array of two containing the values. A hacky solution but it works. We can now look back at how the JavaScript code reads the result.
\lstinputlisting[
float=tbph,
language=c,
firstline=104, lastline=124,
caption=Entrypoint in the C-file,
label=lst:simplify-wasm-entrypoint
]{../lib/simplify-wasm/simplify.c}
Listing \ref{lst:wasm-util-load-result} shows the code to read the values back from module memory. The result pointer and its length are acquired by dereferencing the \texttt{resultInfo}-array. The buffer to use is the heap for unsigned 32-bit integers. This information can then be used to align the Float64Array-view on the 64-bit heap. Constructing the appropriate coordinate representation by reversing the flattening can be looked up in the same file. It is realised in the \texttt{unflattenCoords} function. At last it is important to actually free the memory reserved for both the result and the result-information. The exported method \texttt{free} is the way to go here.
\lstinputlisting[
float=!tbph,
language=javascript,
firstline=29, lastline=43,
caption=Loading coordinates back from module memory,
label=lst:wasm-util-load-result
]{../lib/wasm-util/coordinates.js}
\subsubsection{The implementation of a web framework}
The performance comparison of the two methods will be realized in a web page. It will be a built as a front-end web-application that allows the user to specify the input parameters of the benchmark. These parameters are: The polyline to simplify, a range of tolerances to use for simplification and if the so called high quality mode shall be used. By building this application it will be possible to test a variety of use cases on multiple devices. Also the behavior of the algorithms can be researched under different preconditions. In the scope of this thesis a few cases will be investigated. The application structure will now be introduced.
\subsubsection{External libraries}
The dynamic aspects of the web page will be built in JavaScript to make it run in the browser. Webpack\footnote{https://webpack.js.org/} will be used to bundle the application code and use compilers like babel\footnote{https://babeljs.io/} on the source code. As mentioned in section \ref{sec:benchmark-webassembly} the bundler is also useful for handling references to the WebAssembly binary as it resolves the filename to the correct download path to use. There will be intentionally no transpiling of the JavaScript code to older versions of the ECMA standard. This is often done to increase compatibility with older browsers. Luckily this is not a requirement in this case and by refraining from this practice there will also be no unintentional impact on the application performance. Libraries in use are Benchmark.js\footnote{https://benchmarkjs.com/} for statistically significant benchmarking results, React\footnote{https://reactjs.org/} for the building the user interface and Chart.js\footnote{https://www.chartjs.org/} for drawing graphs.
\subsubsection{The framework}
\label{ch:benchmark-framework}
The web page consist of static and dynamic content. The static parts refer to the header and footer with explanation about the project. Those are written directly into the root HTML document. The dynamic parts are injected by JavaScript. Those will be further discussed in this chapter as they are the main application logic.
\begin{figure}[htb]
\centering
\label{fig:benchmarking-uml}
\fbox{\includegraphics[width=\linewidth]{images/benchmark-uml.jpg}}
\caption{UML diagram of the benchmarking application}
\end{figure}
The web app is built to test a variety of cases with multiple datapoints. As mentioned Benchmark.js will be used for statistically significant results. It is however rather slow as it needs about 5 to 6 seconds per datapoint. This is why multiple types of benchmarking methods are implemented. Figure \ref{fig:benchmarking-uml} shows the corresponding UML diagram of the application. One can see the UI components in the top-left corner. The root component is \texttt{App}. It gathers all the internal state of its children and passes state down where it is needed.
In the upper right corner the different Use-Cases are listed. These cases implement a function \texttt{"fn"} to benchmark. Additional methods for setting up the function and clean up afterwards can be implemented as given by the parent class \texttt{BenchmarkCase}. Concrete cases can be created by instantiating one of the BenchmarkCases with a defined set of parameters. There are three charts that will be rendered using a subset of these cases. These are:
\begin{itemize}
\item \textbf{Simplify.js vs Simplify.wasm} - This Chart shows the performance of the simplification by Simplify.js, the altered version of Simplify.js and the newly developed Simplify.wasm. \todo{Cases}
\item \textbf{Simplify.wasm runtime analysis} - To further gain insights to WebAssembly performance this stacked barchart shows the runtime of a call to Simplify.wasm. It is partitioned into time spent for preparing data (\texttt{storeCords}), the algorithm itself and the time it took for the coordinates being restored from memory (\texttt{loadResult}).
\item \textbf{Turf.js method runtime analysis} - The last chart will use a similar structure. This time it analyses the performance impact of the back and forth transformation of data used in Truf.js. \todo{Cases}
\end{itemize}
On the bottom the different types of Benchmarks implemented can be seen. They all implement the abstract \texttt{measure} function to return the mean time to run a function specified in the given BenchmarkCase. The \texttt{IterationsBenchmark} runs the function a specified number of times, while the \texttt{OpsPerTimeBenchmark} always runs a certain amount of milliseconds to tun as much iterations as possible. Both methods got their benefits and drawbacks. Using the iterations approach one cannot determine the time the benchmark runs beforehand. With fast devices and a small number of iterations one can even fall in the trap of the duration falling under the accuracy of the timer used. Those results would be unusable of course. It is however a very fast way of determining the speed of a function. And it holds valuable for getting a first approximation of how the algorithms perform over the span of datapoints. The second type, the operations per time benchmark, seems to overcome this problem. It is however prune to garbage collection, engine optimizations and other background processes. \footnote{\path{https://calendar.perfplanet.com/2010/bulletproof-javascript-benchmarks/}}
Benchmark.js combines these approaches. In a first step it approximates the runtime in a few cycles. From this value it calculates the number of iterations to reach an uncertainty of at most 1\%. Then the samples are gathered. \todo{more about Benchmark.js}\footnote{\path{http://monsur.hossa.in/2012/12/11/benchmarkjs.html}}
For running multiple benchmarks the class \texttt{BenchmarkSuite} was created. It takes a list of BenchmarkCases and runs them through a BenchmarkType. The Suite manages starting, pausing and stopping of going through list. It updates the statistics gathered on each cycle. By injecting an onCycle method, the \texttt{App} component can give live feedback about the progress.
\todo[inline]{Add digram: state machine for suite}
\todo[inline]{Explain state machine}
\subsubsection{The user interface}
\begin{figure}[htbp]
\centering
\fbox{\includegraphics[width=.9\linewidth]{images/benchmark-ui.png}}
\caption{The user interface for benchmarking application. (not final)}
\label{fig:benchmart-ui}
\end{figure}
The user interface has three regions. One for configuring input parameters. One for controlling the benchmark process and at last a diagram of the results.
\paragraph{Settings} At first the input parameters of the algorithm have to be specified. For that there are some polylines prepared to choose from. They are introduced in chapter \ref{ch:benchmark-data}. Instead of testing a single tolerance value the user can specify a range. This way the behavior of the algorithms can be observed in one chart. The high quality mode got its name from Simplify.js. If it is enabled there will be no radial-distance preprocessing step before applying the Douglas-Peucker routine. The next option determines which benchmarks will be run. The options are mentioned in chapter \ref{ch:benchmark-framework}. One of the three benchmark methods implemented can be selected. Depending on the method chosen additional options will show to further specify the benchmark parameters. The last option deals with chart rendering. Debouncing limits the rate at which functions fire. In this case the chart will delay rendering when datapoints come in at a fast rate.
\paragraph{Run Benchmark} This is the control that displays the status of the benchmark suite. Here benchmarks can be started, stopped, paused and resumed. It also shows the progress of the benchmarks completed in percentage and absolute numbers.
\paragraph{Chart} The chart shows a live diagram of the results. The title represents the selected chart. The legend gives information on which benchmark cases will run. Also the algorithm parameters (dataset and high quality mode) and current platform description can be found here. The tolerance range maps over the x-Axis. On the y-Axis two scales can be seen. The left hand shows by which unit the performance is displayed. This scale corresponds to the colored lines. Every chart will show the number of positions in the result as a grey line. Its scale is displayed on the right. This information is important for selecting a proper tolerance range as it shows if a appropriate order of magnitude has been chosen. Below the chart additional control elements are placed to adjust the visualization. The first selection lets the user choose between a linear or logarithmic y-Axis. The second one changes the unit of measure for performance. The two options are the mean time in milliseconds per operation (ms) and the number of operations that can be run in one second (hz). These options are only available for the chart "Simplify.wasm vs. Simplify.js" as the other two charts are stacked bar charts where changing the default options won't make sense. Finally the result can be saved via a download button. A separate page can be fed with this file to display the diagram only.
\subsubsection{The test data}
\label{ch:benchmark-data}

95
thesis/chapters/04.00-results.tex
View File

@ -1 +1,94 @@
\section{Results}
\section[Results]{Benchmark results}
In this chapter the results are presented. There were a multitude of tests to make. Multiple devices were used to run several benchmarks on different browsers and under various parameters. To organize which benchmarks had to run, first all the problem dimensions were clarified. Devices will be categorized into desktop and mobile devices. The browsers to test will come from the four major browser vendors which were involved in WebAssembly development. Those are Firefox from Mozilla, Chrome from Google, Edge from Microsoft and Safari from Apple. For either of the two data sets a fixed range of tolerances is set to maintain consistency across the diagrams. The values are explained in chapter \ref{ch:benchmark-data}. The other parameter "high quality" can be either switched on or off. The three chart types are explained in chapter \ref{ch:benchmark-cases}.
Each section in this chapter describes a set of benchmarks run on the same system. A table in the beginning will indicate the problem dimensions chosen to inspect. After a description of the system and a short summary of the case the results will be presented in the form of graphs. Those are the graphs produced from the application described in chapter \ref{ch:benchmark-app}
\subsection{Case 1 - Windows - wasm vs js}
\marginpar{hp pavilion}
\marginpar{6 charts}
\marginpar{questions: 1, 3, 5}
\begin{table}[htb]
\centering
\includegraphics[width=.75\linewidth]{./images/dimensions-1.png}
\label{tbl:dimensions-1}
\caption{Problem dimensions of Case 1}
\end{table}
Benchmark of dataset "Simplify.js example" using the web browsers of Google, Microsoft and Mozilla.
\input{./results-benchmark/win_chro_simplify_vs_false.tex}
\input{./results-benchmark/win_ffox_simplify_vs_false.tex}
\input{./results-benchmark/win_edge_simplify_vs_false.tex}
\input{./results-benchmark/win_chro_simplify_vs_true.tex}
\input{./results-benchmark/win_ffox_simplify_vs_true.tex}
\input{./results-benchmark/win_edge_simplify_vs_true.tex}
\clearpage
\subsection{Case 2 - Windows - wasm runtime analysis}
\marginpar{hp pavilion}
\marginpar{2 charts}
\marginpar{questions: 2, 3, 5}
\todo{maybe add ffox}
\begin{table}[htb]
\centering
\includegraphics[width=.75\linewidth]{./images/dimensions-2.png}
\label{tbl:dimensions-2}
\caption{Problem dimensions of Case 2}
\end{table}
\input{./results-benchmark/win_edge_simplify_stack_false.tex}
\input{./results-benchmark/win_edge_simplify_stack_true.tex}
\clearpage
\subsection{Case 3 - MacBook Pro - wasm vs js}
\marginpar{MacBook Pro 15}
\marginpar{4 charts}
\marginpar{Chrome and FF comparable to results above}
\begin{table}[htb]
\centering
\includegraphics[width=.75\linewidth]{./images/dimensions-3.png}
\label{tbl:dimensions-3}
\caption{Problem dimensions of Case 3}
\end{table}
\input{./results-benchmark/mac_safa_bavaria_vs_false.tex}
\input{./results-benchmark/mac_ffox_bavaria_vs_false.tex}
\input{./results-benchmark/mac_safa_bavaria_vs_true.tex}
\input{./results-benchmark/mac_ffox_bavaria_vs_true.tex}
\clearpage
\subsection{Case 4 - Ubuntu - turf.js analysis}
\marginpar{Lenovo Miix 510}
\marginpar{4 charts}
\marginpar{Firefox because orig simplify is faster}
\begin{table}[htb]
\centering
\includegraphics[width=.75\linewidth]{./images/dimensions-4.png}
\label{tbl:dimensions-4}
\caption{Problem dimensions of Case 4}
\end{table}
\input{./results-benchmark/ubu_ffox_bavaria_vs_false.tex}
\input{./results-benchmark/ubu_ffox_bavaria_jsstack_false.tex}
\input{./results-benchmark/ubu_ffox_bavaria_vs_true.tex}
\input{./results-benchmark/ubu_ffox_bavaria_jsstack_true.tex}
\clearpage
\subsection{Case 5 - iPhone - mobile testing}
\marginpar{iPhone??}
\marginpar{6 charts}
\begin{table}[htb]
\centering
\includegraphics[width=.75\linewidth]{./images/dimensions-5.png}
\label{tbl:dimensions-5}
\caption{Problem dimensions of Case 5}
\end{table}

102
thesis/chapters/04.01-results-benchmark.tex
View File

@ -1,102 +0,0 @@
\subsection{Benchmark results}
Problem dimensions:
\begin{itemize}
\item Device: desktop, mobile
\item Browser: Chrome, Firefox, Edge, Safari, mobile variants
\item Datasets: Simplify.js example, bavaria outline
\item High quality: on off
\item Chart: wasm vs. js, wasm analysis, js analysis
\end{itemize}
Questions to answer:
\begin{itemize}
\item Differences between browsers?
\item How much influence does the environment change has (storeCoords)?
\item What is faster? js or wasm. In which cases?
\item Is turf making sense?
\item How much influence does high Quality mode has.
\item Difference between devices?
\end{itemize}
\todo[inline]{Highlight for each case which dimension is active and which questions it tackles}
\subsubsection{Case 1 - Windows - wasm vs js}
\marginpar{hp pavilion}
\marginpar{6 charts}
\marginpar{questions: 1, 3, 5}
\begin{table}[htb]
\centering
\includegraphics[width=.8\linewidth]{./images/dimensions-1.png}
\label{tbl:dimensions-1}
\caption{Problem dimensions of Case 1}
\end{table}
Benchmark of dataset "Simplify.js example" using the web browsers of Google, Microsoft and Mozilla.
\input{./results-benchmark/win_chro_simplify_vs_false.tex}
\input{./results-benchmark/win_ffox_simplify_vs_false.tex}
\input{./results-benchmark/win_edge_simplify_vs_false.tex}
\input{./results-benchmark/win_chro_simplify_vs_true.tex}
\input{./results-benchmark/win_ffox_simplify_vs_true.tex}
\input{./results-benchmark/win_edge_simplify_vs_true.tex}
\clearpage
\subsubsection{Case 2 - Windows - wasm stack analysis}
\marginpar{hp pavilion}
\marginpar{2 charts}
\marginpar{questions: 2, 3, 5}
\todo{maybe add ffox}
\begin{table}[htb]
\centering
\includegraphics[width=.8\linewidth]{./images/dimensions-2.png}
\label{tbl:dimensions-2}
\caption{Problem dimensions of Case 2}
\end{table}
\input{./results-benchmark/win_edge_simplify_stack_false.tex}
\input{./results-benchmark/win_edge_simplify_stack_true.tex}
\clearpage
\subsubsection{Case 3 - MacBook Pro - wasm vs js}
\marginpar{MacBook Pro 15}
\marginpar{4 charts}
\marginpar{Chrome and FF comparable to results above}
\begin{table}[htb]
\centering
\includegraphics[width=.8\linewidth]{./images/dimensions-3.png}
\label{tbl:dimensions-3}
\caption{Problem dimensions of Case 3}
\end{table}
\input{./results-benchmark/mac_safa_bavaria_vs_false.tex}
\input{./results-benchmark/mac_ffox_bavaria_vs_false.tex}
\input{./results-benchmark/mac_safa_bavaria_vs_true.tex}
\input{./results-benchmark/mac_ffox_bavaria_vs_true.tex}
\clearpage
\subsubsection{Case 4 - Ubuntu - turf.js analysis}
\marginpar{Lenovo Miix 510}
\marginpar{4 charts}
\marginpar{Firefox because orig simplify is faster}
\begin{table}[htb]
\centering
\includegraphics[width=.8\linewidth]{./images/dimensions-4.png}
\label{tbl:dimensions-4}
\caption{Problem dimensions of Case 4}
\end{table}
\input{./results-benchmark/ubu_ffox_bavaria_vs_false.tex}
\input{./results-benchmark/ubu_ffox_bavaria_jsstack_false.tex}
\input{./results-benchmark/ubu_ffox_bavaria_vs_true.tex}
\input{./results-benchmark/ubu_ffox_bavaria_jsstack_true.tex}
\clearpage
\subsubsection{Device 4 - iPhone - mobile testing}
\todo[inline]{mobile | safari, chrome, ffox | on, off | vs = 6 charts}

1
thesis/chapters/04.02-results-integration.tex
View File

@ -1 +0,0 @@
\subsection{Comparing the results of different algorithms}

9
thesis/chapters/05-conclusion.tex
View File

@ -1 +1,10 @@
\section{Discussion}
Questions to answer:
\begin{itemize}
\item Differences between browsers?
\item How much influence does the environment change has (storeCoords)?
\item What is faster? js or wasm. In which cases?
\item Is turf making sense?
\item How much influence does high Quality mode has.
\item Difference between devices?
\end{itemize}

18
thesis/chapters/03.02-integration.tex → thesis/chapters/07-application.tex
View File

@ -1,16 +1,24 @@
\subsection[Algorithm comparison]{Compiling an existing C++ library for use on the web}
\section[Practical application]{Compiling an existing C++ library for use on the web}
\todo[inline]{maybe remove whole chapter :'(}
In this chapter I will explain how an existing C++ library was utilized compare different simplification algorithms in a web browser. The library is named \textsl{psimpl} and was written in 2011 from Elmar de Koning. It implements various Algorithms used for polyline simplification. This library will be compiled to WebAssembly using the Emscripten compiler. Furthermore a Web-Application will be created for interactively exploring the Algorithms. The main case of application is simplifying polygons, but also polylines will be supported. The data format used to read in the data will be GeoJSON. To maintain topological correctness a intermediate conversion to TopoJSON will be applied if requested.
\subsubsection{State of the art: psimpl}\
\paragraph{Integrating an existing C++ library}
An existing implementation of several simplification algorithms has been found in the C++ ecosystem. \textsf{psimpl} implements 8 algorithms distributed as a single header file. It also provides a function for measuring positional errors making it ideal for use in a quality analysis tool for those algorithms.
\subsection{State of the art: psimpl}\
\label{ch:psimpl}
\textsl{psimpl} is a generic C++ library for various polyline simplification algorithms. It consists of a single header file \texttt{psimpl.h}. The algorithms implemented are \textsl{Nth point}, \textsl{distance between points}, \textsl{perpendicular distance}, \textsl{Reumann-Witkam}, \textsl{Opheim}, \textsl{Lang}, \textsl{Douglas-Peucker} and \textsl{Douglas-Peucker variation}. It has to be noted, that the \textsl{Douglas-Peucker} implementation uses the \textsl{distance between points} routine, also named the \textsl{radial distance} routine, as preprocessing step just like Simplify.js (Section \ref{sec:simplify.js}). All these algorithms have a similar templated interface. The goal now is to prepare the library for a compiler.
\todo[inline]{Describe the error statistics function of psimpl}
\subsubsection{Compiling to WebAssembly}
\subsection{Compiling to WebAssembly}
As in the previous chapter the compiler created by the Emscripten project will be used. This time the code is not directly meant to be consumed by a web application. It is a generic library. There are no entry points defined that Emscripten can export in WebAssembly. So the entry points will be defined in a new package named psimpl-js. It will contain a C++ file that uses the library, the compiled code and the JavaScript files needed for consumption in a JavaScript project. \textsl{psimpl} makes heavy use of C++ template functions which cannot be handled by JavaScript. So there will be entry points written for each exported algorithm. These entry points are the point of intersection between JavaScript and the library. Listing \ref{lst:psimpl-js-entrypoint} shows one example. They all follow the same procedure. First the pointer given by JavaScript is interpreted as a double-pointer in line 2. This is the beginning of the coordinates array. \textsl{psimpl} expects the first and last point of an iterator so the pointer to the last point is calculated (line 3). The appropriate function template from psimpl is instantiated and called with the other given parameters (line 5). The result is stored in an intermediate vector.
@ -39,7 +47,7 @@ The library code on JavaScript side is similar to the one in chapter \ref{sec:be
\todo[inline]{More about javascript glue code with listing callSimplification.}
\subsubsection{The implementation}
\subsection{The implementation}
The implementation is just as in the last chapter a web page and thus JavaScript is used for the interaction. The source code is bundled with Webpack. React is the UI Component library and babel is used to transform JSX to JavaScript. MobX\footnote{\path{https://mobx.js.org/}} is introduced as a state management library. It applies functional reactive programming by giving the utility to declare observable variables and triggering the update of derived state and other observers intelligently. To do that MobX observes the usage of observable variables so that only dependent observers react on updates. In contrast to other state libraries MobX does not require the state to be serializable. Many existing data structures can be observed like objects, arrays and class instances. It also does not constrain the state to a single centralized store like Redux\footnote{\path{https://redux.js.org/}} does. The final state diagram can be seen in listing \ref{fig:integration-state}. It represents the application state in an object model. Since this has drawbacks in showing the information flow the observable variables are marked in red, and computed ones in blue.
@ -59,7 +67,7 @@ On the bottom the three main state objects can be seen. They are implemented as
\paragraph{FeatureState} encapsulates the state of the vector features. Each layer is represented in text form and object format of the GeoJSON standard. The text form is needed as a serializable form for detecting whether the map display needs to update on an action. As the original features come from file or the server, the text representation is the source of truth and the object format derives from it. The simplified features are asynchronously calculated. This process is outsourced to a debounced reaction that updates the state upon finish.
\subsubsection{The user interface}
\subsection{The user interface}
After explaining the state model the User Interface (UI) shall be explained. The interface is implemented in components which are modeled in a shallow hierarchy. They represent and update the application state. In listing \ref{fig:integration-ui} the resulting web page is shown. The labeled regions correspond to the components. Their behavior will be explained in the following.

BIN
thesis/images/dimensions-5.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
thesis/main.pdf
View File

Binary file not shown.