GBDX

Urban Change Detection (RETIRED)

This task was retired from the GBDX platform on July 23, 2018, and is no longer available for use. For a replacement, please migrate to Pairwise Image Registration and/or ENVI Task Engine. Documentation for these can be found here:
https://gbdxdocs.digitalglobe.com/docs/pairwise-image-registration
https://gbdxdocs.digitalglobe.com/docs/envi-task-engine

GBDX Registered Name: urban_change
Provider: GBDX
Inputs: A pair of 1B image files delivered directly from the s3 receiving bucket;. The full path to the raw image is needed.
Outputs: A shapefile and geojson file with the prefix "change_index_latlon"
Compatible bands & sensors: WorldView-2, WorldView-3, GeoEye-1, QuickBird. Urban Change can process images with different numbers of bands. The output files will have the same number of bands as the input files.

Table of Contents

Section Description
Imagery Examples Before and after examples
Quickstart Get started with a Python-based quickstart tutorial
Task Runtime Benchmark runtimes for the algorithm
Input Options Required and optional task inputs
Outputs Task outputs and example contents
Advanced Options Additional information for advanced users
Known Issues Issues users should be aware of

Imagery Examples

This is the "pre" image, or the earlier of the two images used to detect change

This is the "pre" image, or the earlier of the two images used to detect change

This is the "post" image, or the later of the two images used to detect change

This is the "post" image, or the later of the two images used to detect change

The red in this image shows the change detected between the "pre" and "post" images shown above

The red in this image shows the change detected between the "pre" and "post" images shown above

Quickstart Tutorial

Example Script: Run in a python environment (i.e. - IPython) using the gbdxtools interface.

These basic settings will run Urban Change Detection from a pair of paths to 1b images.

 # Quickstart Example running the task name.

# Initialize the Environment.
from gbdxtools import Interface
gbdx = Interface()

tasks = []
output_location = 'Digital_Globe/Urban_Change/task'

# task parameters
uc_task = gbdx.Task('urban_change')

# Pre-Image Auto ordering task parameters
pre_order = gbdx.Task("Auto_Ordering")
pre_order.inputs.cat_id = '103001001C423600'
pre_order.impersonation_allowed = True
pre_order.persist = True
pre_order.timeout = 36000
uc_task.inputs.pre_image_dir = pre_order.outputs.s3_location.value
tasks += [pre_order]

# Post-Image Auto ordering task parameters
post_order = gbdx.Task("Auto_Ordering")
post_order.inputs.cat_id = '1050410000648000'
post_order.impersonation_allowed = True
post_order.persist = True
post_order.timeout = 36000
uc_task.inputs.post_image_dir = post_order.outputs.s3_location.value
tasks += [post_order]

# Add Urban Change task
tasks += [uc_task]

# Set up workflow save data
workflow = gbdx.Workflow(tasks)
workflow.savedata(uc_task.outputs.results_dir, location=output_location)

# Execute workflow
workflow.execute()

Example Run in IPython:

 In [1]: from gbdxtools import Interface
            gbdx = Interface()

            tasks = []
            output_location = 'Digital_Globe/Urban_Change/task'

    In [2]: uc_task = gbdx.Task('urban_change')

            pre_order = gbdx.Task("Auto_Ordering")
            pre_order.inputs.cat_id = '103001001C423600'
            pre_order.impersonation_allowed = True
            pre_order.persist = True
            pre_order.timeout = 36000
            uc_task.inputs.pre_image_dir = pre_order.outputs.s3_location.value
            tasks += [pre_order]

            post_order = gbdx.Task("Auto_Ordering")
            post_order.inputs.cat_id = '1050410000648000'
            post_order.impersonation_allowed = True
            post_order.persist = True
            post_order.timeout = 36000
            uc_task.inputs.post_image_dir = post_order.outputs.s3_location.value
            tasks += [post_order]

    In [3]: tasks += [uc_task]
            workflow = gbdx.Workflow(tasks)
            workflow.savedata(uc_task.outputs.results_dir, location=output_location)

    In [4]: workflow.execute()

    Out [5]:
    '4507220531957672228'
    In [6]: print workflow.status
    {u'state': u'running', u'event': u'started'}

Task Runtime

There is no benchmark runtime data for this task. Standard benchmarks are sensor-specific, and this task can take images from multiple sensors.

Input Options

The following table lists the Urban Change Detection inputs.
All inputs are optional with default values, with the exception of
'pre_image_dir' and 'post_image_dir',
which specify the task's input and output data locations.

Name Required Default Valid Values Description
pre_image_dir Yes N/A S3 URL Pre-image input directory containing one or more 1b TIFF files
post_image_dir Yes N/A S3 URL Post-image input directory containing one or more 1b TIFF files
cropping_rectangle No N/A ULx, ULy, LRx, LRy Optional cropping rectangle in the form: ULX, ULY, LRX, LRY. All in latlon coordinates (EPSG:4326)
enable_cloud_mask No True boolean Enable/Disable the use of a cloudmask (default: true)

Outputs

On completion, the processed imagery will be written to your specified S3 Customer
Location (i.e., s3://gbd-customer-data/unique customer id/<user supplied path>/Results).

Name Required Default Valid Values Description
results_dir Yes N/A customer's s3 bucket location Contained in this directory are files of the name change_detection_latlon; with JSON, shapefile and zip (containing the shapefiles).

Advanced Options

The options in the following table provide additional diagnostic information.

Name Required Default Valid Values Description
Work No N/A S3 URL Output directory containing intermediate work files (for diagnostic purposes)
Log No N/A S3 URL Output directory containing the runtime log (for diagnostic purposes)

Known Issues

The Urban Change Task automatically inputs the appropriate settings for the four sub-tasks in the workflow library as listed below. Refer to the documentation for those tasks for further details:

  • The Change Detection Preparation task only processes multispectral images (MS) and UTM projected images.

  • The Advanced Image Preprocessor is run automatically with the appropriate settings.

  • The Pairwise Image Registration Task; fails if not enough tie points (<20).

  • The Cloud and Shadow Mask applied here sometimes confuses water and shadow. No documentation is available for this Task.

Contact Us

If you have any questions or issues with this task, please contact gbdx-support@digitalglobe.com .