{"_id":"597a4d8fd21e5c001b685ea1","project":"55faeacad0e22017005b8265","version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":33,"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"],"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":7,"slug":"algorithm-guide","title":"Certified 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":32,"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[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" Run Urban Change Detection (urban_change) on a pair of images\\n\\nfrom gbdxtools import Interface\\ngbdx = Interface()\\n\\nurban_change = gbdx.Task('urban_change', \\n                        pre_image_dir='s3://receiving-dgcs-tdgplatform-com/056194460010_01_003',\\n                        post_image_dir='s3://receiving-dgcs-tdgplatform-com/056194461010_01_003')\\n\\nworkflow = gbdx.Workflow([urban_change])\\n\\n#Edit the following line(s) to reflect specific folder(s) for the output file (example location provided)\\nworkflow.savedata(urban_change.outputs.results_dir, location='UrbanChange/Results')\\n\\nworkflow.execute()\\n\\nprint workflow.id\\nprint workflow.status\\n```\\n\\n**Example Run in IPython:**\\n\\n    In [1]: from gbdxtools import Interface\\n    In [2]: gbdx = Interface()\\n    In [3]: urban_change = gbdx.Task('urban_change', \\n                        pre_image_dir='s3://receiving-dgcs-tdgplatform-com/056194460010_01_003',\\n                        post_image_dir='s3://receiving-dgcs-tdgplatform-com/056194461010_01_003')\\n    In [4]: workflow = gbdx.Workflow([urban_change])\\n    In [5]: workflow.savedata(urban_change.outputs.results_dir, location='UrbanChange/Results')    \\n    In [6]: workflow.execute()\\n    Out [6]: \\n    u'4507220531957672228'\\n    In [7]: print workflow.status\\n    {u'state': u'running', u'event': u'started'}\\n\",\n      \"language\": \"python\"\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**Description of Basic Input Parameters for the urban_change GBDX task**\n\nThe following table lists the urban_change GBDX 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\nbounding_rectangle    | No |   N/A  |  ULx, ULy, LRx, LRy (latlon) | Subregion (specified using bounding box coordinates) within the image pair overlap to process. Without the setting, the default is to clip to the area of overlap for the two images\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## <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\n##<a name=\"Known Issues\"></a>Known Issues\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\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. [block:code] { "codes": [ { "code": " Run Urban Change Detection (urban_change) on a pair of images\n\nfrom gbdxtools import Interface\ngbdx = Interface()\n\nurban_change = gbdx.Task('urban_change', \n pre_image_dir='s3://receiving-dgcs-tdgplatform-com/056194460010_01_003',\n post_image_dir='s3://receiving-dgcs-tdgplatform-com/056194461010_01_003')\n\nworkflow = gbdx.Workflow([urban_change])\n\n#Edit the following line(s) to reflect specific folder(s) for the output file (example location provided)\nworkflow.savedata(urban_change.outputs.results_dir, location='UrbanChange/Results')\n\nworkflow.execute()\n\nprint workflow.id\nprint workflow.status\n```\n\n**Example Run in IPython:**\n\n In [1]: from gbdxtools import Interface\n In [2]: gbdx = Interface()\n In [3]: urban_change = gbdx.Task('urban_change', \n pre_image_dir='s3://receiving-dgcs-tdgplatform-com/056194460010_01_003',\n post_image_dir='s3://receiving-dgcs-tdgplatform-com/056194461010_01_003')\n In [4]: workflow = gbdx.Workflow([urban_change])\n In [5]: workflow.savedata(urban_change.outputs.results_dir, location='UrbanChange/Results') \n In [6]: workflow.execute()\n Out [6]: \n u'4507220531957672228'\n In [7]: print workflow.status\n {u'state': u'running', u'event': u'started'}\n", "language": "python" } ] } [/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 **Description of Basic Input Parameters for the urban_change GBDX task** The following table lists the urban_change GBDX 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 bounding_rectangle | No | N/A | ULx, ULy, LRx, LRy (latlon) | Subregion (specified using bounding box coordinates) within the image pair overlap to process. Without the setting, the default is to clip to the area of overlap for the two images 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).