Building Detector 3D Challenge tools

The purpose of this application is to let you view building footprint masks overlaid on satellite images, compare truth to solution annotations, and calculate your solution's score. It can also convert footprint instance label files between TIFF and TXT formats.

Visualizer and scorer tool

Download the visualizer package and unpack it anywhere on your system. Open a command window in the directory where you unzipped the package and execute

java -Xmx2g -jar visualizer.jar 
     -data-dir <data_directory> 
     -truth <truth_file>
     -solution <solution_file>

(The above is a single line command, line breaks are only for readability. The -Xmx2g parameter gives 2GB RAM available for Java. If you have more RAM and you work with lots of data then it is recommended to set this value higher.)

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:

-data-dir : specifies the base directory of the data files, i.e. the satellite images (RGB and DSM files). This parameter is required.
-truth : the ground truth building footprint instance definition file in TXT format, see truth-example.txt for an example (available from the problem statement). This parameter is optional. See the File converter tool section for information on how to generate this file from TIFF files.
-solution : your solution file, see solution-example.txt for an example (available from the problem statement). This parameter is optional.

All file and directory parameters can be relative or absolute paths.

Other optional parameters you may use:

-w <width> : width of the tool's screen. Defaults to 1500.
-no-gui : if present then no GUI will be shown, the application just scores the supplied solution file in command line mode.
-iou-threshold : the IOU threshold to use during matching. Defaults to 0.45.

A sample command line that will display the data set used to make example submissions, and the supplied sample solution file:

java -jar visualizer.jar -truth ./data/truth-example.txt -solution ./data/solution-example.txt -data-dir ./data

This assumes that you have already downloaded the training data, and copied the required truth and solution files and the data files of the 4 example tiles in the ./data directory like this:

/data
  JAX_Tile_004_DSM.tif
  JAX_Tile_004_GTI.tif
  JAX_Tile_004_RGB.tif
  ...
  TAM_Tile_001_DSM.tif
  ...
  truth-example.txt
  solution-example.txt

Operations

Image selection works by selecting an item from the image dropdown list or clicking on lines containing an image name in the output log window. You can zoom in/out within the image view by the mouse wheel, and pan the view by dragging. Switch between RGB and DSM modes using the RGB/DSM dropdown list or by right clicking the image.
If you specify both a truth file and a solution file then solution and truth are compared automatically on startup, scores are displayed in the log window and also in the command line.
True positive buildings are displayed in white, false positives are yellow, false negatives are blue. Uncertain truth buildings are diagonally striped. (Note that the colour of the uncertain buildings are the same as for certain ones (white or blue) but they are not considered when counting TP and FN values.)

File converter tool

You can use the same tool to convert between _GTI.tif files and their RLE-encoded textual versions as follows. Converting TIFF to TXT may be useful if you want to work only with a subset of the training data and want to create the corresponding RLE truth file for visualization. You probably won't need the reverse conversion (TXT to TIFF).

TIFF to TXT

java -jar visualizer.jar -tiff2txt <data_path> <out_file>

where

data_path points to a directory or a TIFF file. In case of a directory, it is recursively traversed to find all _GTI.tif files. In case of a file, only this TIFF file will be processed.
out_file points to the resulting TXT output file.

Note that the output of this tool has a similar but not identical format to the RLE format described in the problem specification. There are two differences:

uncertain buildings are represented by negative building labels,
the file may have an additional line per tile that describes the non-visible areas of the tile.

This format is used only internally by the visualizer.

TXT to TIFF

java -jar visualizer.jar -txt2tiff <input_file> <output_dir>

where

input_file is an RLE-encoded text file,
output_dir points to a directory where the resulting TIFF files will be placed.

The tool does not support converting text files that have uncertain buildings (with negative building labels) or lines that represent non-visible areas, it is meant to convert only the RLE format described in the problem specification.