visualizer_readme.html

<h1>Visualizer for the Building Detector challenge, 2nd round</h1>

The purpose of the visualizer application is to let you view grayscale, 3-band and 8-band images, view ground truth building footprints and your solution's building footprint as overlays on these images, compare truth to solution and calculate your solution's score.<br/>

Download the <a href="http://www.topcoder.com/contest/problem/BuildingDetector2/visualizer-2.0.zip">visualizer package</a> and unpack it anywhere on your system. Open a command window in the directory where you unzipped the package and execute
<pre>
java -jar visualizer.jar 
     -truth &lt;truth_file_list&gt; 
     -solution &lt;solution_file&gt; 
     -image-dir &lt;image_directory_list&gt;
     -band-triplets &lt;band_definition_file&gt;
</pre>
<i>(The above is a single line command, line breaks are only for readability.)</i><br/><br/>

This assumes that you have Java (at least v1.7) installed and it is available on your path. The meaning of the above parameters are the following:
<ul>
	<li>-truth (optional) specifies the location of the truth files. It is a semicolon (';')-separated list of files that should be loaded.</li>
	<li>-solution (optional) is your solution file, see ./data/solution-sample.csv for an example. </li>
	<li>-image-dir is a semicolon (';')-separated list of directories that should be loaded. Each of these is assumed to contain the PAN, RGB-PanSharpen, etc subfolders as described in the problem statement.</li>
	<li>-band-triplets points to a file that defines the band index triplets used to generate RGB images from the 8-band imagery. See ./data/band-triplets.txt, it describes the required syntax of band triplet definitions.</li>
</ul>
Note that if you use multiple path elements separated by a semicolon in the -truth or -image-dir parameters then it may be necessary to enclose the parameter value in quotes.<br/>
All file and directory parameters can be relative or absolute paths. The -truth and -solution parameters are optional, the tool is able to run without them.<br/><br/>

An alternative way of specifying the parameters is via a parameters file, see params.txt for an example. The file contains the description of the required syntax. In this case the command should have exactly two parameters:<br/>
<pre>
java -jar visualizer.jar -params &lt;params_file&gt;
</pre>
where &lt;params_file&gt; is an absolute or relative path to a parameters file.

For example a command line that will run the app using the spacenet sample data:
<pre>
java -jar visualizer.jar -params params.txt
</pre>
This assumes that you have already downloaded the sample data from the spacenet-dataset AWS bucket (see the problem statement for details) and extracted it, so the directory structure is something like this:
<pre>
data/
    AOI_2_Vegas_Train/
        geojson/
        MUL/
        ...
    AOI_3_Paris_Train/
        ...
    AOI_4_Shanghai_Train/
        ...
    AOI_5_Khartoum_Train/
        ...
    solution-sample.csv
    band-triplets.txt
visualizer_lib/
    *.jar  
visualizer.jar
params.txt
</pre>
Modify the params.txt file if your paths look different.
<br/><br/>

There are some other optional command line parameters you can use (either directly in the command line or in the parameters file):
<ul>
	<li>-w &lt;width&gt; : Width of the tool's screen. Defaults to 1500.</li>
	<li>-iou-threshold : Defaults to 0.5.</li>
	<li>-no-gui: if present then no GUI will be shown, the application just scores the supplied solution file in command line mode.</li>
	<li>-fp-border &lt;r,g,b,a&gt; : with this you can customize the colour of the border of the polygons representing false positives. The parameter should be 4 integers separated by commas, no spaces in between. E.g to set it to semi-transparent blue you can use: -fp-border 0,0,255,128</li>
	<li>-fp-fill &lt;r,g,b,a&gt; : similar to the previous for the fill colour of the false positive polygons.</li>
	<li>-fn-border and -fn-fill: as above for false negatives</li>
	<li>-tp-border-solution, -tp-fill-solution, -tp-border-truth and -tp-fill-truth : as above for true positives, but here you can set different colours for the truth and solution polygons.</li>
</ul>
All these have proper defaults so you can leave them out. <br/>
 
<h3>Operations</h3>
Usage of the tool should be straightforward. Select the view type from the top drop down list: 'PAN grayscale', 'RGB Pan-sharpened' or one of the predefined band triplet combinations (these are generated from the contents of the MUL folder). Select the image to be displayed from the bottom drop down list. Note that you can also switch to another image by clicking the line containing an image name in the output log window.<br/>

If both truth and solution files are specified then solution and truth are compared automatically, scores are displayed in the log window and also in the command line.<br/>

You can zoom in/out within the image view by the mouse wheel, and pan the view by dragging.<br/>

<h3>Colour scaling</h3>
The dataset contains 16-bit grayscale and 48-bit colour images which the tool converts to 8-bit or 24-bit images so that they can be displayed. A rather simple algorithm is used for colour conversion, see the <tt>loadMap()</tt> method of the <tt>Visualizer</tt> class. Note that for machine learning you may do this step differently or may not do this step at all.

<h3>Licenses</h3>
The visualizer tool uses the imageio-ext library for reading multiband TIFF files. The imageio-ext library is LGPL licensed, see <a href="https://github.com/geosolutions-it/imageio-ext/blob/master/LICENSE.txt">here</a> for its license text. See <a href="https://github.com/geosolutions-it/imageio-ext">here</a> for details on the library.<br/>