<commit_before># ARtillery Crater Analysis and Detection Engine (ARCADE)
An experiment by Rudiment.info with the Centre for Visual Computing, University of Bradford

Version: 0.0.1

## What is it?

ARCADE is an prototype computer vision tool designed to assist with the analysis of satellite images
thought to contain artillery blast craters. It draws on methods specified by the American
Association for the Advancement of Science (AAAS) and Bellingcat in their respective 
investigations of artillery bombardment in [Sri Lanka](http://www.aaas.org/geotech/sri_lanka_2009#B.Possible%20Craters) and [eastern Ukraine](https://www.bellingcat.com/news/uk-and-europe/2015/02/17/origin-of-artillery-attacks/). 

Detailed information about the ARCADE project is available on [Rudiment's website](https://rudiment.info/project/arcade).

## Installing ARCADE 

ARCADE is currently only available for use on computers running recent versions of Windows
(realisticaly, 8 and 10). If you want to create a binary installer for OSX or Linux, the
source code is provided so you can do so.

### Installation on Windows

* Download the MATLAB Compiler Runtime (MCR) (version 8.3, 2014a) for your computer and platform [from here](https://www.mathworks.com/products/compiler/mcr/). Install it. 
* Download the current ARCADE installer [from here](https://www.dropbox.com/s/0xlp1cksvuca3qa/ARCADE_installer_20151022_v_0_0_1.zip?dl=0). Unzip it. Install it in a directory of your choice (something like C:\Program Files\ARCADE)
* In the installation directory you chose, go to the sub-directory called "application". Grab copies of the following files from this repository (in "config"), and place them straight in the "application" directory:
 * [ReadCraters.txt]() (This is where you tell ARCADE where to get imagery and georeferences.)
 * [craterDetector.xml]() (This is the current training data which tells ARCADE what a crater is.)
 * [Settings.txt]() (This enables you to control how much work ARCADE does to create outlines of things it considers to be blast craters.)

You should now be all set to go.

## How to use ARCADE

###Steps

If you have installed ARCADE in /program files you'll need to do all the below with admin privs in Windows

* Upload imagery to a local webserver
* Edit readcraters.txt and input the url of then image, along with lat/lon of upper right and lower left corners of the image (in that order). Each value is tab separated. ARCADE will fail, and give you a cryptic error if you include any non-printable characters or spaces in readcraters.txt
*  Run ARCADE with admin privs
*  A window with a splash page will open. This is all the indication that ARCADE gives you that it is doing something (no progress bar as yet).
*  Depending on the size of the image, and the number of detections it makes, ARCADE could be processing for quite a long time (+15 minutes easily)
* When it's done you will have a number of outputs, which we discuss below.

###Outputs

Todo

###Settings

* Iterations - for performance, you can control the number of iterations used in segmentation. We recommend 500.

## Feature status

In this version the below work reasonably well:

* Image pre-processing: ARCADE currently converts all input imagery to grayscale before running any analysis.
* Detection:  ARCADE will ingest imagery, and using a cascade object detector will  place a labelled bounding box around areas that match the parameters of whatever training data it is using (contained in craterDetector.xml)
* Segmentation: The shape in each bounding box is segmented from its background and its edge detected.
* Feature extraction: The centroid of the segmented shape, it's lat/lon, and area are calculated and outputted.

The following feature is under development:

* Trajectory analysis using template matching: though the research work on the feature is complete, this is not yet implemented in this version.


Copyright (c) 2015 Rudiment.info, released under a BSD Simplified License<commit_msg>added in steps for using arcade<commit_after># ARtillery Crater Analysis and Detection Engine (ARCADE)
An experiment by Rudiment.info with the Centre for Visual Computing, University of Bradford

Version: 0.0.1

## What is it?

ARCADE is an prototype computer vision tool designed to assist with the analysis of satellite images
thought to contain artillery blast craters. It draws on methods specified by the American
Association for the Advancement of Science (AAAS) and Bellingcat in their respective 
investigations of artillery bombardment in [Sri Lanka](http://www.aaas.org/geotech/sri_lanka_2009#B.Possible%20Craters) and [eastern Ukraine](https://www.bellingcat.com/news/uk-and-europe/2015/02/17/origin-of-artillery-attacks/). 

Detailed information about the ARCADE project is available on [Rudiment's website](https://rudiment.info/project/arcade).

## Installing ARCADE 

ARCADE is currently only available for use on computers running recent versions of Windows
(realisticaly, 8 and 10). If you want to create a binary installer for OSX or Linux, the
source code is provided so you can do so.

### Installation on Windows

* Download the MATLAB Compiler Runtime (MCR) (version 8.3, 2014a) for your computer and platform [from here](https://www.mathworks.com/products/compiler/mcr/). Install it. 
* Download the current ARCADE installer [from here](https://www.dropbox.com/s/0xlp1cksvuca3qa/ARCADE_installer_20151022_v_0_0_1.zip?dl=0). Unzip it. Install it in a directory of your choice (something like C:\Program Files\ARCADE)
* If you've installed ARCADE in `Program Files` you will probably need to use Adminstrator priviledges to perform the next steps.
* In the installation directory you chose, go to the sub-directory called "application". Grab copies of the following files from this repository (in `config`), and place them straight in the `application` directory:
 * [ReadCraters.txt](https://raw.githubusercontent.com/Rudiment-Info/arcade/master/config/ReadCraters.txt) - This is where you tell ARCADE where to get imagery and georeferences.
 * [craterDetector.xml](https://raw.githubusercontent.com/Rudiment-Info/arcade/master/config/craterDetector.xml) -  This is the current training data which tells ARCADE what a crater is.
 * [Settings.txt](https://raw.githubusercontent.com/Rudiment-Info/arcade/master/config/Settings.txt) - This enables you to control how much work ARCADE does to create outlines of things it considers to be blast craters.
* 
* Your `application` directory should look like this:

  ```
  application
  │   arcade.exe
  │   craterDetector.xml
  │   ReadCraters.txt
  │   Settings.txt
  │   splash.png
  ```
* You should now be all set to go!

## How to use ARCADE

First, gather the following data:

* a JPEG/JPG file of the satellite imagery you want to examine;
* the exact latitude and longitude of:
 * the upper right corner of the source image; and,
 * the lower left corner of the source image.

Next, follow these steps:

* Upload the satellite imagery to a webserver and make a note of the full URL (including `https://www ...` etc) 
* If you've installed ARCADE in `Program Files` you will probably need to use Adminstrator priviledges to perform the below.
* Open `~\application\ReadCraters.txt` and in a single row enter the following, with a single tab between each:
  * The full URL where ARCADE can find the image
  * The latitude of the upper right corner, expressed as a decimal coordinate
  * The longitude of the upper right corner, expressed as a decimal coordinate
  * The latitude of the lower left corner, expressed as a decimal coordinate
  * The longitude of the lower left corner, expressed as a decimal coordinate
* Your ReadCraters.txt file should look like this:

  ```
  http://s29.postimg.org/rxj235qyv/image.jpg	12.590418	9.669342	11.486417	8.147736
  ```
  
* ARCADE can process multiple images in sequence. Place each in a separate row.
* If you miss out any of the required data or include any non-printable characters or spaces in `ReadCraters.txt`, ARCADE will fail, and give you a very cryptic error.
*  Run `arcade.exe` with [administrator priviledges[(http://windows.microsoft.com/en-gb/windows7/how-do-i-run-an-application-once-with-a-full-administrator-access-token). 
*  A window with a boring splash page will open. This is all the indication that ARCADE gives you that it is doing something. There is no progress bar to make you feel more comfortable.
*  Depending on the size of the image, and the number of detections made, ARCADE could be processing for quite a long time (+15 minutes easily).
* As ARCADE is about to finish, a window showing the segmented view with plotted centroids will pop up. Just close it! 
* When ARCADE has completed, you will have a number of outputs for each item you asked it to process.  We discuss these below. 

###Outputs

If the filename of your input image is named `image.jpg`, ARCADE will create five outputs:

* `detected_image.jpg`: This is a version of the image, in greyscale, marked with the boxes that match ARCADE's training on what a crater is.
* `segmented_image.jpg`: A version of the input image, showing ARCADE's attempt to create crater outlines, segment them from the remaining imagery
* `segmented_image_centroids.jpg`: a version of the segmented image, with the centre points of the the segmented shapes plotted on top
* `image_1.csv`: a file with tabular data outlining the latitude and longitude of the crater centre-point, its area (in pixels) and its perimeter (in pixels)
* `image_1.txt`: the same as image_1.csv, just in txt format

###Configuation

* `Settings.txt` contains a single number used to control the number of iterations used in segmentation. We recommend 500, but increase it if you think the 

* `craterDetector.xml` is just a holder for detection paramters, and can be swapped out for a file based on different training data.

## Feature status

In this version the below work reasonably well:

* Image pre-processing: ARCADE currently converts all input imagery to greyscale before running any analysis.
* Detection:  ARCADE will ingest imagery, and using a cascade object detector will  place a labelled bounding box around areas that match the parameters of whatever training data it is using (contained in craterDetector.xml)
* Segmentation: The shape in each bounding box is segmented from its background and its edge detected.
* Feature extraction: The centroid of the segmented shape, it's latitude and longitude, and area are calculated and outputted.

The following feature is under development:

* Trajectory analysis using template matching: though the research work on the feature is complete, this is not yet implemented in this version.

# Known issues with version 0.0.1

* The input method is fairly cumbersome. It would be better to use the Google Static API as an input.
* Pixel matching to latitude and longitude is error prone and needs some attention. 

Copyright (c) 2015 Rudiment.info, released under a BSD Simplified License
{'fraction_non_alphanumeric': 0.0633393829401089, 'fraction_numerical': 0.012885662431941924, 'mean_word_length': 4.513256628314157, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 12, 'lorem ipsum': 0, 'www.': 9, 'xml': 7}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3763442', 'n_tokens_mistral': 3138, 'n_tokens_neox': 2915, 'n_words': 1504}