{"_id":"591b3890c0ce2b2f0012b7d8","user":"55fae9d4825d5f19001fa379","__v":0,"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":6,"slug":"algorithm-guide","title":"Certified Algorithms"},"project":"55faeacad0e22017005b8265","parentDoc":null,"version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":32,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v1","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-16T17:36:16.883Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":28,"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/044c920-Dubai_Before5sec.gif\",\n        \"Dubai_Before5sec.gif\",\n        800,\n        320,\n        \"#9b9588\"\n      ],\n      \"caption\": \"Before: Dubai urban scene. This animation updates every five seconds to show offset of the source image that will be warped. This is especially notable in the building lean and movement of the roundabouts between the images.\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/890d337-Dubai_After5sec.gif\",\n        \"Dubai_After5sec.gif\",\n        800,\n        320,\n        \"#9b9588\"\n      ],\n      \"caption\": \"After: This animation updates every five seconds and shows less building lean and less movement between the images of the roundabouts.\"\n    }\n  ]\n}\n[/block]\n\n## <a name=\"Quickstart\"></a>Quickstart Tutorial\n\nThis script uses the Pairwise Image Registration task to co-register two images.  The source image will be registered to the reference image and output to the specified directory.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"from gbdxtools import Interface\\n    from os.path import join\\n    import uuid\\n    gbdx = Interface()\\n\\n    # set my s3 bucket location:\\n    my_bucket = 's3://gbd-customer-data/acct#'\\n\\n    # create task object\\n    im2im_task = gbdx.Task('image2image')\\n\\n    # set the values of source_directory, reference_directory\\n    # this assumes each directory contains a single image\\n    im2im_task.inputs.source_directory = join(my_bucket,'short path to source image directory')\\n    im2im_task.inputs.reference_directory = join(my_bucket,'short path to reference image directory')\\n\\n    # put the task in a workflow\\n    workflow = gbdx.Workflow([im2im_task])\\n\\n    # save the data to an output location of your choice\\n    workflow.savedata(im2im_task.outputs.out, location='path to customer S3 output directory')\\n\\n    # Execute the Workflow\\n    workflow.execute()\\n    print workflow.id\\n    print workflow.status\",\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\nName      |     Required          |       File Type       |   Description\n--------------|:-----------|:---------------------:|---------------------------------\nsource_directory    | YES     |  directory   | S3 location of the Image that provides the base layer for warping\nsource_filename   | NO  |  geotiff     | source file must be set in the task command line if both files are located in the same directory    \nreference_directory  | YES    |  directory   | S3 location of the Image that will be warped\nreference_filename  | NO |  geotiff     | reference file must be set in the task command line if both files are located in the same directory\nboundary_directory   |  NO |  directory   | S3 location of the all the input data; only required if there is a boundary shapefile \nboundary_filename  |  NO |  shapefile   | file that limits the areal extent of the image warping (optional)\n\n#### Technical Notes\n\nThese are technical notes from the Certified Algorithm team :\n*  Images should both be north up\n*  Images with a different number of bands will use blue band.  The following formats are assumed, but the program should work regardless:\n  * PAN\n  * RGB\n  * BGRN (Includes GeoEye-1, IKONOS and QuickBird)\n  * WV2 8 band\n  * WV3 16 band\n*  Images with different resolutions\n  * Code uses coarsest resolution for tiepoints\n  * Higher resolution image resampled using bilinear interpolation (just to find tiepoints)\n*  Datatype\n  * Input datatype can be byte, int, or float\n  * Working arrays are scaled to unsigned 8 bit\n  * Supports TIFFs (and vrts of TIFFs)\n*  Images must be same projection\n*  Images must fit in memory\n*  There is a 200 pixel search radius in the coarser of the two resolutions\n*  Supports up to a factor of 25 resolution difference\n\n\n## <a name=\"Outputs\"></a>Outputs\nThe Pairwaise Image Registration task outputs the warped source image that is registered to the reference image.\n\nThe warped source will be placed in the output s3 bucket.  This tiff image will have the same metadata as the source.  It will be output with the suffix “_warped” appended to the original source filename.\n\n## <a name=\"Advanced Options\"></a>Advanced Options\n\nThis Advanced Option permits the Customer to:\n* input the source image and the reference image from the same directory\n* use a boundary polygon (shapefile format) that selects the region from which tiepoints are selected; and thereby defines the extent of the image that is warped. \n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"from gbdxtools import Interface\\n    from os.path import join\\n    import uuid\\n    gbdx = Interface()\\n\\n    # set my s3 bucket location:\\n    my_bucket = 's3://gbd-customer-data/acct#'\\n\\n    # create task object\\n    im2im_task = gbdx.Task('image2image')\\n\\n    # set the values of source_directory, reference_directory\\n    im2im_task.inputs.source_directory = join(my_bucket,'short path to source image directory')\\n    im2im_task.inputs.reference_directory = join(my_bucket,'short path to reference image directory')\\n\\t\\n    # set the image filenames in case there are multiple image files in a directory\\n    # note that the filenames do not include a filepath\\n    im2im_task.inputs.reference_filename = 'the reference image filename with extension'\\n    im2im_task.inputs.source_filename = 'the source image filename with extension'\\n\\t\\n    # assuming we are using a boundary polygon, we similarly set the boundary directory and the boundary filename \\n    im2im_task.inputs.boundary_directory = join(my_bucket,'short path to boundary polygon shapefile directory')\\n    im2im_task.inputs.boundary_filename = 'the boundary polygon shapefile filename with .shp extension'\\n\\t\\n    # put the task in a workflow\\n    workflow = gbdx.Workflow([im2im_task])\\n\\n    # save the data to an output location of your choice\\n    workflow.savedata(im2im_task.outputs.out, location='path to customer S3 output directory')\\n\\n    # Execute the Workflow\\n    workflow.execute()\\n    print workflow.id\\n    print workflow.status\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n##<a name=\"Known Issues\"></a>Known Issues\nPairwise Image Registration has been certified for source image strips and mosiacs up to 12 GB in size registered to a reference image of similar size. You may encounter a limit on the size of the image that can be processed for Mosiacs larger than 12 GB, because the AWS system may time out.\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 Pairwise Image Registration task will remove misregistrations between two images.  It does so by attempting to find similar image features and warping the source image accordingly.  The warped source will have the same metadata as the source and be output with the suffix “_warped” appended to the original filename.\t\n\t\n**GBDX Registered Name**: \n**Provider**: DigitalGlobe (DG)\n**Inputs**: See the Input Options section below\n**Outputs**: tif image of the reference image with the suffix “_warped” appended to the original filename\n**Compatible Image Bands and Sensors**: All DG Sensors; WV02 8-band, WV03 16-band, All 4-band sensors including IKONOS; PAN, RGB.  Paired images may be from different sensors and have different resolutions and numbers of bands.","slug":"pairwise-image-registration","type":"basic","title":"Pairwise Image Registration"}

Pairwise Image Registration

The Pairwise Image Registration task will remove misregistrations between two images. It does so by attempting to find similar image features and warping the source image accordingly. The warped source will have the same metadata as the source and be output with the suffix “_warped” appended to the original filename. **GBDX Registered Name**: **Provider**: DigitalGlobe (DG) **Inputs**: See the Input Options section below **Outputs**: tif image of the reference image with the suffix “_warped” appended to the original filename **Compatible Image Bands and Sensors**: All DG Sensors; WV02 8-band, WV03 16-band, All 4-band sensors including IKONOS; PAN, RGB. Paired images may be from different sensors and have different resolutions and numbers of bands.

## 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/044c920-Dubai_Before5sec.gif", "Dubai_Before5sec.gif", 800, 320, "#9b9588" ], "caption": "Before: Dubai urban scene. This animation updates every five seconds to show offset of the source image that will be warped. This is especially notable in the building lean and movement of the roundabouts between the images." } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/890d337-Dubai_After5sec.gif", "Dubai_After5sec.gif", 800, 320, "#9b9588" ], "caption": "After: This animation updates every five seconds and shows less building lean and less movement between the images of the roundabouts." } ] } [/block] ## <a name="Quickstart"></a>Quickstart Tutorial This script uses the Pairwise Image Registration task to co-register two images. The source image will be registered to the reference image and output to the specified directory. [block:code] { "codes": [ { "code": "from gbdxtools import Interface\n from os.path import join\n import uuid\n gbdx = Interface()\n\n # set my s3 bucket location:\n my_bucket = 's3://gbd-customer-data/acct#'\n\n # create task object\n im2im_task = gbdx.Task('image2image')\n\n # set the values of source_directory, reference_directory\n # this assumes each directory contains a single image\n im2im_task.inputs.source_directory = join(my_bucket,'short path to source image directory')\n im2im_task.inputs.reference_directory = join(my_bucket,'short path to reference image directory')\n\n # put the task in a workflow\n workflow = gbdx.Workflow([im2im_task])\n\n # save the data to an output location of your choice\n workflow.savedata(im2im_task.outputs.out, location='path to customer S3 output directory')\n\n # Execute the Workflow\n workflow.execute()\n print workflow.id\n print workflow.status", "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 Name | Required | File Type | Description --------------|:-----------|:---------------------:|--------------------------------- source_directory | YES | directory | S3 location of the Image that provides the base layer for warping source_filename | NO | geotiff | source file must be set in the task command line if both files are located in the same directory reference_directory | YES | directory | S3 location of the Image that will be warped reference_filename | NO | geotiff | reference file must be set in the task command line if both files are located in the same directory boundary_directory | NO | directory | S3 location of the all the input data; only required if there is a boundary shapefile boundary_filename | NO | shapefile | file that limits the areal extent of the image warping (optional) #### Technical Notes These are technical notes from the Certified Algorithm team : * Images should both be north up * Images with a different number of bands will use blue band. The following formats are assumed, but the program should work regardless: * PAN * RGB * BGRN (Includes GeoEye-1, IKONOS and QuickBird) * WV2 8 band * WV3 16 band * Images with different resolutions * Code uses coarsest resolution for tiepoints * Higher resolution image resampled using bilinear interpolation (just to find tiepoints) * Datatype * Input datatype can be byte, int, or float * Working arrays are scaled to unsigned 8 bit * Supports TIFFs (and vrts of TIFFs) * Images must be same projection * Images must fit in memory * There is a 200 pixel search radius in the coarser of the two resolutions * Supports up to a factor of 25 resolution difference ## <a name="Outputs"></a>Outputs The Pairwaise Image Registration task outputs the warped source image that is registered to the reference image. The warped source will be placed in the output s3 bucket. This tiff image will have the same metadata as the source. It will be output with the suffix “_warped” appended to the original source filename. ## <a name="Advanced Options"></a>Advanced Options This Advanced Option permits the Customer to: * input the source image and the reference image from the same directory * use a boundary polygon (shapefile format) that selects the region from which tiepoints are selected; and thereby defines the extent of the image that is warped. [block:code] { "codes": [ { "code": "from gbdxtools import Interface\n from os.path import join\n import uuid\n gbdx = Interface()\n\n # set my s3 bucket location:\n my_bucket = 's3://gbd-customer-data/acct#'\n\n # create task object\n im2im_task = gbdx.Task('image2image')\n\n # set the values of source_directory, reference_directory\n im2im_task.inputs.source_directory = join(my_bucket,'short path to source image directory')\n im2im_task.inputs.reference_directory = join(my_bucket,'short path to reference image directory')\n\t\n # set the image filenames in case there are multiple image files in a directory\n # note that the filenames do not include a filepath\n im2im_task.inputs.reference_filename = 'the reference image filename with extension'\n im2im_task.inputs.source_filename = 'the source image filename with extension'\n\t\n # assuming we are using a boundary polygon, we similarly set the boundary directory and the boundary filename \n im2im_task.inputs.boundary_directory = join(my_bucket,'short path to boundary polygon shapefile directory')\n im2im_task.inputs.boundary_filename = 'the boundary polygon shapefile filename with .shp extension'\n\t\n # put the task in a workflow\n workflow = gbdx.Workflow([im2im_task])\n\n # save the data to an output location of your choice\n workflow.savedata(im2im_task.outputs.out, location='path to customer S3 output directory')\n\n # Execute the Workflow\n workflow.execute()\n print workflow.id\n print workflow.status", "language": "python" } ] } [/block] ##<a name="Known Issues"></a>Known Issues Pairwise Image Registration has been certified for source image strips and mosiacs up to 12 GB in size registered to a reference image of similar size. You may encounter a limit on the size of the image that can be processed for Mosiacs larger than 12 GB, because the AWS system may time out. #### Contact Us If you have any questions or issues with this task, please contact [**gbdx-support@digitalglobe.com** ](mailto:gbdx-support@digitalglobe.com).