GBDX

Change Detection Image Pair Alignment (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: cd_prep
Provider: GBDX
Inputs: tiff or vrt output from the Advanced Image Preprocessor
Outputs: Tiff file with the image name format: pre_image_cdprep.tif and post_image_cdprep.tif.
Compatible bands & sensors: WorldView-2, WorldView-3, GeoEye-1, QuickBird. Change Detection Preparation 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 5 second animation shows the two unprocessed 1B multispectral images in geotiff format

This 5 second animation shows the two unprocessed 1B multispectral images in geotiff format

Intermediate: These are the same two images after running the Advanced Image Preprocessor. These will be used as inputs for the Change Detection Preparation task

Intermediate: These are the same two images after running the Advanced Image Preprocessor. These will be used as inputs for the Change Detection Preparation task

After: This 5 second animation shows the 2 output files from the Change Detection Preparation task called pre_image_cdprep.tif and post_image_cdprep.tif

After: This 5 second animation shows the 2 output files from the Change Detection Preparation task called pre_image_cdprep.tif and post_image_cdprep.tif

Quickstart Tutorial

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

These basic settings will run Change Detection Image Pair Alignment (cdprep) from a pair of input orthorectified, AComped image output from the Advanced Image Preprocessor.

# Run The Change Detection Preparation Task on a pair of images
from gbdxtools import Interface
gbdx = Interface()

# The data input and lines must be edited to point to an authorized customer S3 location)
cd_prep = gbdx.Task('cd_prep',
                    pre_image_dir='s3://gbd-customer-data/CustomerAccount#/PathToPreImage/',
                    post_image_dir='s3://gbd-customer-data/CustomerAccount#/PathToPostImage')

workflow = gbdx.Workflow([cd_prep])
#Edit the following line(s) to reflect specific folder(s) for the output file (example location provided)
workflow.savedata(cd_prep.outputs.final_pre_image_dir, location='CDPrep/pre_image_dir')
workflow.savedata(cd_prep.outputs.final_post_image_dir, location='CDPrep/post_image_dir')
workflow.execute()

print workflow.id
print workflow.status

Example Run in IPython:

 In [1]: from gbdxtools import Interface
    In [2]: gbdx = Interface()
    In [3]: cd_prep = gbdx.Task('cd_prep',
                                 pre_image_dir='s3://gbd-customer-data/7d8cfdb6-13ee-4a2a-bf7e-0aff4795d927/jkoenig/cd_prep_test/Borneo/test2/AOP/pre/',
                                 post_image_dir = 's3://gbd-customer-data/7d8cfdb6-13ee-4a2a-bf7e-0aff4795d927/jkoenig/cd_prep_test/Borneo/test2/AOP/post/')
    In [4]: workflow = gbdx.Workflow([cd_prep])
    In [5]: workflow.savedata(cd_prep.outputs.final_pre_image_dir, location='cd_prep_test/pub_test/pre_image_dir')
    In [6]: workflow.savedata(cd_prep.outputs.final_post_image_dir, location='cd_prep_test/pub_test/post_image_dir')
    In [7]: workflow.execute()
    Out [7]:
    u'4498407427801810318'
    In [8]: print workflow.status
    {u'state': u'running', u'event': u'started'} [9]:

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

This task takes as input two orthorectified, atmospherically compensated images in geotiff format.
It is intended to work as a following task to the AOP_Strip_Processor, with only the AComp option specified.

Example overlapping 1B images that can be processed by Advanced Image Preprocessor prior Change Detection Preparation are:

pre-image: 10504100003E9200
post-image: 103001001C423600

Description of Basic Input Parameters for the Change Detection Preparation GBDX task

The following table lists the cd_prep GBDX inputs.
All inputs are optional with default values, with the exception of
'pre_image_dir', 'post_image_dir', 'final_pre_image_dir', and 'final_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 TIFF files
post_image_dir Yes N/A S3 URL Post-image input directory containing one or more TIFF files

Outputs

On completion, the processed imagery will be written to your specified S3 Customer
Location (i.e., s3://gbd-customer-data/unique customer id/pre_image_dir/, s3://gbd-customer-data/unique customer id/post_image_dir/).
Each output directory will contain a single geotif file with one of the names: pre_image_cdprep.tif or post_image_cdprep.tif.

Name Required Default Valid Values Description
final_pre_image_dir Yes N/A S3 URL Pre-image output directory for cd_prep
final_post_image_dir Yes N/A S3 URL Post-image output directory for cd_prep

Advanced Options

The options in the following table provide additional control over the resulting output. All of the directories are generally
for diagnostic purposes.

Name Default Valid Values Description
buffer_in_meters 1500.0 string Amount in meters by which to buffer the intersection polygon of the initial crop
resampling_method near string Method for resampling the images to a common grid. Choices are 'near', 'bilinear', 'cubic', 'cubicspline', 'lanczos', 'average'
resolution_in_meters 2.0 string The resolution in meters of the pair of output images
enable_cloud_mask true string Enable/disable cloud mask. Choices are 'true' or 'false'
shrink_buffer_in_meters 0.0 string Distance in meters by which to shrink the final intersection polygon for final crop
crop_pre_image_dir N/A S3 URL Pre-image output directory for the cropping task (for diagnostic purposes)
crop_post_image_dir N/A S3 URL Post-image output directory for the cropping task (for diagnostic purposes)
crop_work_dir N/A S3 URL Working output directory for the initial cropping task (for diagnostic purposes)
crop_log_dir N/A S3 URL Log output directory for the initial cropping task (for diagnostic purposes)
image2image_dir N/A S3 URL Log output directory for the image2image task (for diagnostic purposes)

Advanced Script

This script runs the Advanced Image Preprocessor and Change Detection Image Pair Alignment end to end. Note that you must write the output from the Advanced Image Preprocessor to a file which the Change Detection Preparation task will read.

# Quickstart Example running the task name.

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

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

# Change Detection task setup
cd_prep_task = gbdx.Task('cd_prep')

# Pre-Image Auto ordering task parameters
pre_order = gbdx.Task("Auto_Ordering")
pre_order.inputs.cat_id = '10504100003E9200'
pre_order.impersonation_allowed = True
pre_order.persist = True
pre_order.timeout = 36000
tasks += [pre_order]

# Pre-Image AOP task parameters
pre_aop = gbdx.Task("AOP_Strip_Processor")
pre_aop.inputs.data = pre_order.outputs.s3_location.value
pre_aop.inputs.bands = 'MS'
pre_aop.inputs.enable_pansharpen = False
pre_aop.inputs.enable_dra = False
pre_aop.inputs.ortho_epsg = "UTM"
pre_aop.timeout = 36000
tasks += [pre_aop]

# Post-Image Auto ordering task parameters
post_order = gbdx.Task("Auto_Ordering")
post_order.inputs.cat_id = '103001001C423600'
post_order.impersonation_allowed = True
post_order.persist = True
post_order.timeout = 36000
tasks += [post_order]

# Post-Image AOP task parameters
post_aop = gbdx.Task("AOP_Strip_Processor")
post_aop.inputs.data = post_order.outputs.s3_location.value
post_aop.inputs.bands = 'MS'
post_aop.inputs.enable_pansharpen = False
post_aop.inputs.enable_dra = False
post_aop.inputs.ortho_epsg = "UTM"
post_aop.timeout = 36000
tasks += [post_aop]

# Add Change Detection task parameters
cd_prep_task.inputs.pre_image_dir = pre_aop.outputs.data.value
cd_prep_task.inputs.post_image_dir = post_aop.outputs.data.value
tasks += [cd_prep_task]

# Set up workflow save data
workflow = gbdx.Workflow(tasks)
workflow.savedata(cd_prep_task.outputs.final_pre_image_dir, location=output_location + "/pre")
workflow.savedata(cd_prep_task.outputs.final_post_image_dir, location=output_location + "/post")

# Execute workflow
workflow.execute()

Known Issues

  • The Change Detection Preparation task only processes multispectal images (MS) and UTM projrcted images. Make sure the Advanced Image Preprocessor step is set to bands="MS" and ortho_epsg="UTM" (most common reasons for failure).
  • The output from the Advanced Image Preprocessor must be written to a directory for use by this task. You cannot use "aop.outputs.data.value" as input.
  • You should also be aware of the following:
    • See issues for Pairwise Image Registration : fails if not enough tie points (<20).
    • The Cloud and Shadow Mask applied here sometimes confuses water and shadow.

Contact Us

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