{"_id":"597a4d8fd21e5c001b685ea1","project":"55faeacad0e22017005b8265","version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":35,"createdAt":"2015-09-17T16:31:06.800Z","releaseDate":"2015-09-17T16:31:06.800Z","categories":["55faeacbd0e22017005b8269","55faf550764f50210095078e","55faf5b5626c341700fd9e96","55faf8a7825d5f19001fa386","560052f91503430d007cc88f","560054f73aa0520d00da0b1a","56005aaf6932a00d00ba7c62","56005c273aa0520d00da0b3f","5601ae7681a9670d006d164d","5601ae926811d00d00ceb487","5601aeb064866b1900f4768d","5601aee850ee460d0002224c","5601afa02499c119000faf19","5601afd381a9670d006d1652","561d4c78281aec0d00eb27b6","561d588d8ca8b90d00210219","563a5f934cc3621900ac278c","5665c5763889610d0008a29e","566710a36819320d000c2e93","56ddf6df8a5ae10e008e3926","56e1c96b2506700e00de6e83","56e1ccc4e416450e00b9e48c","56e1ccdfe63f910e00e59870","56e1cd10bc46be0e002af26a","56e1cd21e416450e00b9e48e","56e3139a51857d0e008e77be","573b4f62ef164e2900a2b881","57c9d1335fd8ca0e006308ed","57e2bd9d1e7b7220000d7fa5","57f2b992ac30911900c7c2b6","58adb5c275df0f1b001ed59b","58c81b5c6dc7140f003c3c46","595412446ed4d9001b3e7b37","59e76ce41938310028037295","5a009de510890d001c2aabfe"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v1","version_clean":"1.0.0","version":"1"},"category":{"_id":"573b4f62ef164e2900a2b881","__v":0,"project":"55faeacad0e22017005b8265","version":"55faeacad0e22017005b8268","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-05-17T17:05:38.443Z","from_sync":false,"order":8,"slug":"algorithm-guide","title":"Algorithms"},"user":"55fae9d4825d5f19001fa379","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-07-27T20:31:11.954Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":30,"body":"## Table of Contents\n\nSection | Description\n--- | ---\n[Imagery Examples](#Imagery Examples) | Before and after examples\n[Quickstart](#Quickstart) | Get started with a Python-based quickstart tutorial\n[Task Runtime](#Task Runtime) | Benchmark runtimes for the algorithm\n[Input Options](#Input Options) | Required and optional task inputs\n[Outputs](#Outputs) | Task outputs and example contents\n[Advanced Options](#Advanced Options) | Additional information for advanced users\n[Known Issues](#Known Issues) | Issues users should be aware of\n\n\n## <a name=\"Imagery Examples\"></a>Imagery Examples\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/fb49d70-DC_UrbanChange_PRE.JPG\",\n        \"DC_UrbanChange_PRE.JPG\",\n        992,\n        747,\n        \"#2f2e24\"\n      ],\n      \"caption\": \"This is the \\\"pre\\\" image, or the earlier of the two images used to detect change\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/51110c0-DC_UrbanChange_POST.JPG\",\n        \"DC_UrbanChange_POST.JPG\",\n        991,\n        748,\n        \"#37362a\"\n      ],\n      \"caption\": \"This is the \\\"post\\\" image, or the later of the two images used to detect change\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1123dea-DC_UrbanChange_FINAL.JPG\",\n        \"DC_UrbanChange_FINAL.JPG\",\n        996,\n        750,\n        \"#36352a\"\n      ],\n      \"caption\": \"The red in this image shows the change detected between the \\\"pre\\\" and \\\"post\\\" images shown above\"\n    }\n  ]\n}\n[/block]\n\n\n\n## <a name=\"Quickstart\"></a>Quickstart Tutorial\n\nExample Script: Run in a python environment (i.e. - IPython) using the gbdxtools interface.\n\nThese basic settings will run Urban Change Detection from a pair of paths to 1b images.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" # Quickstart Example running the task name.\\n\\n# Initialize the Environment.\\nfrom gbdxtools import Interface\\ngbdx = Interface()\\n\\ntasks = []\\noutput_location = 'Digital_Globe/Urban_Change/task'\\n\\n# task parameters\\nuc_task = gbdx.Task('urban_change')\\n\\n# Pre-Image Auto ordering task parameters\\npre_order = gbdx.Task(\\\"Auto_Ordering\\\")\\npre_order.inputs.cat_id = '103001001C423600'\\npre_order.impersonation_allowed = True\\npre_order.persist = True\\npre_order.timeout = 36000\\nuc_task.inputs.pre_image_dir = pre_order.outputs.s3_location.value\\ntasks += [pre_order]\\n\\n# Post-Image Auto ordering task parameters\\npost_order = gbdx.Task(\\\"Auto_Ordering\\\")\\npost_order.inputs.cat_id = '1050410000648000'\\npost_order.impersonation_allowed = True\\npost_order.persist = True\\npost_order.timeout = 36000\\nuc_task.inputs.post_image_dir = post_order.outputs.s3_location.value\\ntasks += [post_order]\\n\\n# Add Urban Change task\\ntasks += [uc_task]\\n\\n# Set up workflow save data\\nworkflow = gbdx.Workflow(tasks)\\nworkflow.savedata(uc_task.outputs.results_dir, location=output_location)\\n\\n# Execute workflow\\nworkflow.execute()\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n**Example Run in IPython:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" In [1]: from gbdxtools import Interface\\n            gbdx = Interface()\\n\\n            tasks = []\\n            output_location = 'Digital_Globe/Urban_Change/task'\\n\\n    In [2]: uc_task = gbdx.Task('urban_change')\\n\\n            pre_order = gbdx.Task(\\\"Auto_Ordering\\\")\\n            pre_order.inputs.cat_id = '103001001C423600'\\n            pre_order.impersonation_allowed = True\\n            pre_order.persist = True\\n            pre_order.timeout = 36000\\n            uc_task.inputs.pre_image_dir = pre_order.outputs.s3_location.value\\n            tasks += [pre_order]\\n\\n            post_order = gbdx.Task(\\\"Auto_Ordering\\\")\\n            post_order.inputs.cat_id = '1050410000648000'\\n            post_order.impersonation_allowed = True\\n            post_order.persist = True\\n            post_order.timeout = 36000\\n            uc_task.inputs.post_image_dir = post_order.outputs.s3_location.value\\n            tasks += [post_order]\\n\\n    In [3]: tasks += [uc_task]\\n            workflow = gbdx.Workflow(tasks)\\n            workflow.savedata(uc_task.outputs.results_dir, location=output_location)\\n\\n    In [4]: workflow.execute()\\n\\n    Out [5]:\\n    '4507220531957672228'\\n    In [6]: print workflow.status\\n    {u'state': u'running', u'event': u'started'}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## <a name=\"Task Runtime\"></a>Task Runtime\nThere is no benchmark runtime data for this task. Standard benchmarks are sensor-specific, and this task can take images from multiple sensors.\n\n\n## <a name=\"Input Options\"></a>Input Options\n\nThe following table lists the Urban Change Detection inputs.\nAll inputs are optional with default values, with the exception of\n'pre_image_dir' and 'post_image_dir',\nwhich specify the task's input and output data locations.\n\nName        | Required             |       Default         |        Valid Values             |   Description\n----------------|---------|:---------------------:|---------------------------------|-----------------\npre_image_dir   | Yes   | N/A  |  S3 URL | Pre-image input directory containing one or more 1b TIFF files\npost_image_dir    | Yes   |   N/A  |  S3 URL | Post-image input directory containing one or more 1b TIFF files\ncropping_rectangle    | No  |   N/A  |  ULx, ULy, LRx, LRy |Optional cropping rectangle in the form: ULX, ULY, LRX, LRY.  All in latlon coordinates (EPSG:4326)\nenable_cloud_mask     | No   |   True  |  boolean | Enable/Disable the use of a cloudmask (default: true) \n\n\n\n## <a name=\"Outputs\"></a>Outputs\nOn completion, the processed imagery will be written to your specified S3 Customer \nLocation (i.e., s3://gbd-customer-data/unique customer id/<user supplied path>/Results). \n\nName           |    Required      |       Default         |        Valid Values             |   Description\n---------------|----------|:---------------------:|---------------------------------|-----------------\nresults_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).\n\n\n## <a name=\"Advanced Options\"></a>Advanced Options\nThe options in the following table provide additional diagnostic information. \n\n\nName           |    Required      |       Default         |        Valid Values             |   Description\n---------------|----------|:---------------------:|---------------------------------|-----------------\nWork |  No     |  N/A | S3 URL | Output directory containing intermediate work files (for diagnostic purposes)\nLog |  No   |  N/A | S3 URL | Output directory containing the runtime log (for diagnostic purposes)\n\n## <a name=\"Known Issues\"></a>Known Issues\n\nThe 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:\n\n*\tThe Change Detection Preparation task only processes multispectral images (MS) and UTM projected images. \n\n*\tThe Advanced Image Preprocessor is run automatically with the appropriate settings.\n\n*\tThe Pairwise Image Registration Task; fails if not enough tie points (<20).\n\n*\tThe Cloud and Shadow Mask applied here sometimes confuses water and shadow. No documentation is available for this Task.\n\n\n#### Contact Us   \nIf you have any questions or issues with this task, please contact [**gbdx-support:::at:::digitalglobe.com** ](mailto:gbdx-support@digitalglobe.com).","excerpt":"The Urban Change task performs change detection of built up areas.  It takes as input a pair of overlapping 1B images and outputs the urban change as a collection of polygons.  The processing includes ACOMP/FastOrtho (via the Advanced Image Preprocessor Task), image/grid alignment (via the Pairwise Image Registration Task), cloud detection and cropping (via a workflow equivalent to the Change Detection Preparation Task) and the final Urban Change Shapefile output (via the urban_change_task). \n\t\n**GBDX Registered Name**: urban_change\n**Provider**: GBDX\n**Inputs**: A pair of 1B image files delivered directly from the s3 receiving bucket;. The full path to the raw image is needed.\n**Outputs**: A shapefile and geojson file with the prefix \"*change_index_latlon*\"\n**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.","slug":"urban-change-detection","type":"basic","title":"Urban Change Detection"}

Urban Change Detection

The Urban Change task performs change detection of built up areas. It takes as input a pair of overlapping 1B images and outputs the urban change as a collection of polygons. The processing includes ACOMP/FastOrtho (via the Advanced Image Preprocessor Task), image/grid alignment (via the Pairwise Image Registration Task), cloud detection and cropping (via a workflow equivalent to the Change Detection Preparation Task) and the final Urban Change Shapefile output (via the urban_change_task). **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](#Imagery Examples) | Before and after examples [Quickstart](#Quickstart) | Get started with a Python-based quickstart tutorial [Task Runtime](#Task Runtime) | Benchmark runtimes for the algorithm [Input Options](#Input Options) | Required and optional task inputs [Outputs](#Outputs) | Task outputs and example contents [Advanced Options](#Advanced Options) | Additional information for advanced users [Known Issues](#Known Issues) | Issues users should be aware of ## <a name="Imagery Examples"></a>Imagery Examples [block:image] { "images": [ { "image": [ "https://files.readme.io/fb49d70-DC_UrbanChange_PRE.JPG", "DC_UrbanChange_PRE.JPG", 992, 747, "#2f2e24" ], "caption": "This is the \"pre\" image, or the earlier of the two images used to detect change" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/51110c0-DC_UrbanChange_POST.JPG", "DC_UrbanChange_POST.JPG", 991, 748, "#37362a" ], "caption": "This is the \"post\" image, or the later of the two images used to detect change" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/1123dea-DC_UrbanChange_FINAL.JPG", "DC_UrbanChange_FINAL.JPG", 996, 750, "#36352a" ], "caption": "The red in this image shows the change detected between the \"pre\" and \"post\" images shown above" } ] } [/block] ## <a name="Quickstart"></a>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. [block:code] { "codes": [ { "code": " # Quickstart Example running the task name.\n\n# Initialize the Environment.\nfrom gbdxtools import Interface\ngbdx = Interface()\n\ntasks = []\noutput_location = 'Digital_Globe/Urban_Change/task'\n\n# task parameters\nuc_task = gbdx.Task('urban_change')\n\n# Pre-Image Auto ordering task parameters\npre_order = gbdx.Task(\"Auto_Ordering\")\npre_order.inputs.cat_id = '103001001C423600'\npre_order.impersonation_allowed = True\npre_order.persist = True\npre_order.timeout = 36000\nuc_task.inputs.pre_image_dir = pre_order.outputs.s3_location.value\ntasks += [pre_order]\n\n# Post-Image Auto ordering task parameters\npost_order = gbdx.Task(\"Auto_Ordering\")\npost_order.inputs.cat_id = '1050410000648000'\npost_order.impersonation_allowed = True\npost_order.persist = True\npost_order.timeout = 36000\nuc_task.inputs.post_image_dir = post_order.outputs.s3_location.value\ntasks += [post_order]\n\n# Add Urban Change task\ntasks += [uc_task]\n\n# Set up workflow save data\nworkflow = gbdx.Workflow(tasks)\nworkflow.savedata(uc_task.outputs.results_dir, location=output_location)\n\n# Execute workflow\nworkflow.execute()", "language": "python" } ] } [/block] **Example Run in IPython:** [block:code] { "codes": [ { "code": " In [1]: from gbdxtools import Interface\n gbdx = Interface()\n\n tasks = []\n output_location = 'Digital_Globe/Urban_Change/task'\n\n In [2]: uc_task = gbdx.Task('urban_change')\n\n pre_order = gbdx.Task(\"Auto_Ordering\")\n pre_order.inputs.cat_id = '103001001C423600'\n pre_order.impersonation_allowed = True\n pre_order.persist = True\n pre_order.timeout = 36000\n uc_task.inputs.pre_image_dir = pre_order.outputs.s3_location.value\n tasks += [pre_order]\n\n post_order = gbdx.Task(\"Auto_Ordering\")\n post_order.inputs.cat_id = '1050410000648000'\n post_order.impersonation_allowed = True\n post_order.persist = True\n post_order.timeout = 36000\n uc_task.inputs.post_image_dir = post_order.outputs.s3_location.value\n tasks += [post_order]\n\n In [3]: tasks += [uc_task]\n workflow = gbdx.Workflow(tasks)\n workflow.savedata(uc_task.outputs.results_dir, location=output_location)\n\n In [4]: workflow.execute()\n\n Out [5]:\n '4507220531957672228'\n In [6]: print workflow.status\n {u'state': u'running', u'event': u'started'}", "language": "json" } ] } [/block] ## <a name="Task Runtime"></a>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. ## <a name="Input Options"></a>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) ## <a name="Outputs"></a>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). ## <a name="Advanced Options"></a>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) ## <a name="Known Issues"></a>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** ](mailto:gbdx-support@digitalglobe.com).