ship-detector

Detects ship bounding boxes in a given image strip using a trained CNN classifier to deploy on Protogen-generated region proposals.

Run

Here we run through a sample execution of the ship-detector task. We will find all ships in an image over New York. All of the input data is available in the S3 locations specified below.

Within an iPython terminal create a GBDX interface an specify the task input location:

from gbdxtools import Interface
from os.path import join
import uuid

gbdx = Interface()

input_location = 's3://gbd-customer-data/58600248-2927-4523-b44b-5fec3d278c09/platform-stories/ship-detector/'

Create a task instance and set the required inputs:

ship_task = gbdx.Task('ship-detector')
ship_task.inputs.pan_image = join(input_location, 'pan_image')
ship_task.inputs.ms_image = join(input_location, 'ms_image')

Initialize a workflow and specify where to save the output:

ship_wf = gbdx.Workflow([ship_task])
random_str = str(uuid.uuid4())
output_location = join('platform-stories/trial-runs', random_str)

ship_wf.savedata(ship_task.outputs.results, join(output_location, 'ship_detections'))

Execute the workflow:
```
ship_wf.execute()
```
Track the status of the workflow as follows:
```
ship_wf.status
```

Inputs

GBDX input ports can only be of "Directory" or "String" type. Booleans, integers and floats are passed to the task as strings, e.g., "True", "10", "0.001".

Name	Type	Description	Required
ms_image	directory	Contains a multispectral GeoTiff image in which to detect ships. This directory should only contain one image, otherwise a file will be selected arbitrarily.	True
pan_image	directory	Contains a pansharpened version of ms_image. This directory should only contain one image, otherwise a file will be selected arbitrarily.	True

Outputs

Name	Type	Description
results	directory	Contains a geojson with protogen region proposals, each given a classification of 0 (no ship) or 1 (ship).

Development

Build the Docker Image

You need to install Docker.

Clone the repository:

git clone https://github.com/platformstories/ship-detector

Then build the image locally. Building requires input environment variables for protogen and GBDX AWS credentials. You will need to contact kostas.stamatiou@digitalglobe.com for access to Protogen.

cd ship-detector
docker build --build-arg PROTOUSER=<GitHub username> \
    --build-arg PROTOPASSWORD=<GitHub pawwsord> \
    --build-arg AWS_ACCESS_KEY_ID=<AWS access key> \
    --build-arg AWS_SECRET_ACCESS_KEY=<AWS secret key> \
    --build-arg AWS_SESSION_TOKEN=<AWS session token> \
    -t ship-detector .

Try out locally

Create a container in interactive mode and mount the sample input under /mnt/work/input/:

docker run -v full/path/to/sample-input:/mnt/work/input -it ship-detector

Then, within the container:

python /ship-detector.py

Docker Hub

docker login

Tag your image using your username and push it to DockerHub:

docker tag ship-detector yourusername/ship-detector
docker push yourusername/ship-detector

The image name should be the same as the image name under containerDescriptors in ship-detector.json.

Alternatively, you can link this repository to a Docker automated build. Every time you push a change to the repository, the Docker image gets automatically updated.

Register on GBDX

In a Python terminal:

from gbdxtools import Interface
gbdx=Interface()
gbdx.task_registry.register(json_filename="ship-detector.json")

Note: If you change the task image, you need to reregister the task with a higher version number in order for the new image to take effect. Keep this in mind especially if you use Docker automated build.

naldeborgh7575/ship-detector