arcgis.raster.orthomapping module

The orthomapping python API allows automating orthomapping tasks in the server environment.

For more information about orthomapping workflows in ArcGIS, please visit the help documentation at http://desktop.arcgis.com/en/arcmap/10.4/manage-data/raster-and-images/block-adjustment-for-mosaic-datasets.htm.

is_supported

orthomapping.is_supported()

Returns True if the GIS supports orthomapping. If a gis isn’t specified, checks if arcgis.env.active_gis supports raster analytics

compute_sensor_model

orthomapping.compute_sensor_model(mode='QUICK', location_accuracy='High', context=None, gis=None)

compute_sensor_model computes the bundle block adjustment for the image collection and applies the frame xform to the images. It will also generate the control point table, solution table, solution points table and flight path table. These tables will not be published as Portal items.

Argument

Description

image_collection

Required, the input image collection on which to compute the sensor model. The image_collection can be a portal Item or an image service URL or a URI

The image_collection must exist.

mode

Optional string. the mode to be used for bundle block adjustment Only the following modes are supported:

  • ‘Quick’ : Computes tie points and adjustment at 8x of the source imagery resolution

  • ‘Full’ : adjust the images in Quick mode then at 1x of the source imagery resolution

  • ‘Refine’ : adjust the image at 1x of the source imagery resolution

By default, ‘Quick’ mode is applied to compute the sensor model.

location_acuracy

Optional string. this option allows users to specify the GPS location accuracy level of the source image. It determines how far the underline tool will search for neighboring matching images, then calculate tie points and compute adjustments.

Possible values for location_accuracy are:

  • ‘High’ : GPS accuracy is 0 to 10 meters, and the tool uses a maximum of 4 by 3 images

  • ‘Medium’ : GPS accuracy of 10 to 20 meters, and the tool uses a maximum of 4 by 6 images

  • ‘Low’ : GPS accuracy of 20 to 50 meters, and the tool uses a maximum of 4 by 12 images

  • ‘Verylow’ : GPS accuracy is more than 50 meters, and the tool uses a maximum of 4 by 20 images

The default location_accuracy is ‘High’

context

Optional dictionary. The context parameter is used to configure additional client settings for block adjustment. The supported configurable parameters are for compute mosaic dataset candidates after the adjustment.

Example: { “computeCandidate”: False, “maxoverlap”: 0.6, “maxloss”: 0.05, }

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The imagery layer url

alter_processing_states

orthomapping.alter_processing_states(new_states, gis=None)

Alter the processing states of the image collection. The states are stored as key property “Orthomapping”. The content of the state is a dictionary including several properties which can be set based on the process done on the image collection.

Argument

Description

image_collection

Required, This is the image collection that will be adjusted.

The image_collection can be a portal Item or an image service URL or URI

The image_collection must exist.

new_states

Required dictionary. The state to set on the image_collection

This a dictionary of states that should be set on the image collection The new states that can be set on the image collection are: adjustment, dem, gcp, seamlines, colorcorrection

Example: {“adjustment”: “raw”,

“dem”: “Dense_Natual_Neighbor”, “seamlines”:”VORONOI”, “colorcorrection”:”SingleColor”}

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The result will be the newly set states dictionary

get_processing_states

orthomapping.get_processing_states(gis=None)

Retrieve the processing states of the image collection

Argument

Description

image_collection

Required, This is the image collection that will be adjusted.

The image_collection can be a portal Item or an image service URL or URI

The image_collection must exist.

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The result will be the newly set states dictionary

match_control_points

orthomapping.match_control_points(control_points, similarity=None, context=None, gis=None)

Compute the matching tie points, given collection of ground control points, and at least one of the ground control points has matching tie points.

Argument

Description

image_collection

Required, the input image collection that will be adjusted.

The image_collection can be a portal Item or an image service URL or a URI

The image_collection must exist.

control_points

Required list. a list of control point objects. A control point object is a dictionary with key-value pairs as described below:

The schema of control points follows the schema of the mosaic dataset control point table. The following are required when defining control points:

  • The control points must contain a Point geometry object

  • There must be one attribute set, describing the attributes of the control point.

    The control point attributes is a dictionary that must contain the following

    key-value pairs:

    – imageID (int) - Image identification using the ObjectID from the mosaic dataset footprint table.

    – pointID (int) - The ID of the point within the control point table

    – type (int) - The type of the control point as determined by its numeric value

    1: Tie Point 2: Ground Control Point. 3: Check Point

    – status (int) - The status of the point. A value of 0 indicates that the point will

    not be used in computation. A non-zero value indicates otherwise.

Example: {“geometry”: {

“x”:-118.15,”y”:33.80,”z”:10.0, “spatialReference”:{“wkid”:4326}}, “attributes”: {

“imageID”: 22, “pointID”: 2, “type”: 2, “status”: 1,

},

<more points> }

similarity

Optional string. Choose the tolerance level for your control point matching.

Low- The similarity tolerance for finding control points will be low. This option will produce the most control points, but some may have a higher level of error.

Medium - The similarity tolerance for finding control points will be medium.

High - The similarity tolerance for finding control points will be high. This option will produce the least number of control points, but each matching pair will have a lower level of error. This is the default.

context

Optional dictionary.Additional settings such as the input control points spatial reference can be specified here.

For example: {“groundControlPointsSpatialReference”: {“wkid”: 3459}, “imagePointSpatialReference”: {“wkid”: 3459}}

Note: The ground control points spatial reference and image point spatial reference spatial reference set in the context parameter is to decide the returned point set’s ground control points spatial reference and image point spatial reference. If these two parameters are not set here, the tool will use the spatial reference defined in the input point set. And if no spatial reference is defined in the point set, then the default ground control points coordinates are in lon/lat and image points coordinates are in image coordinate system.

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

A dictionary object

color_correction

orthomapping.color_correction(color_correction_method, dodging_surface_type, target_image=None, context=None, gis=None)

Color balance the image collection. Refer to the “Color Balance Mosaic Dataset” GP tool for documentation on color balancing mosaic datasets. http://pro.arcgis.com/en/pro-app/tool-reference/data-management/color-balance-mosaic-dataset.htm

Argument

Description

image_collection

Required. This is the image collection that will be adjusted.

The image_collection can be a portal Item or an image service URL or a URI

The image_collection must exist.

color_correction_method

Required string. This is the method that will be used for color correction computation. The available options are:

Dodging-Change each pixel’s value toward a target color. With this technique, you must also choose the type of target color surface, which affects the target color. Dodging tends to give the best result in most cases.

Histogram-Change each pixel’s value according to its relationship with a target histogram. The target histogram can be derived from all of the rasters, or you can specify a raster. This technique works well when all of the rasters have a similar histogram.

Standard_Deviation-Change each of the pixel’s values according to its relationship with the histogram of the target raster, within one standard deviation. The standard deviation can be calculated from all of the rasters in the mosaic dataset, or you can specify a target raster. This technique works best when all of the rasters have normal distributions.

dodging_surface_type

Required string.When using the Dodging balance method, each pixel needs a target color, which is determined by the surface type.

Single_Color-Use when there are only a small number of raster datasets and a few different types of ground objects. If there are too many raster datasets or too many types of ground surfaces, the output color may become blurred. All the pixels are altered toward a single color point-the average of all pixels.

Color_Grid- Use when you have a large number of raster datasets, or areas with a large number of diverse ground objects. Pixels are altered toward multiple target colors, which are distributed across the mosaic dataset.

First_Order- This technique tends to create a smoother color change and uses less storage in the auxiliary table, but it may take longer to process compared to the color grid surface. All pixels are altered toward many points obtained from the two-dimensional polynomial slanted plane.

Second_Order-This technique tends to create a smoother color change and uses less storage in the auxiliary table, but it may take longer to process compared to the color grid surface. All input pixels are altered toward a set of multiple points obtained from the two-dimensional polynomial parabolic surface.

Third_Order-This technique tends to create a smoother color change and uses less storage in the auxiliary table, but it may take longer to process compared to the color grid surface. All input pixels are altered toward multiple points obtained from the cubic surface.

target_image

Optional. The image service you want to use to color balance the images in the image collection. It can be a portal Item or an image service URL or a URI

context

Optional dictionary. It contains additional settings that allows users to customize the statistics computation settings.

Example: {“skipRows”: 10, “skipCols”: 10, “reCalculateStats”: “OVERWRITE”}

gis

Optional GIS. the GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The imagery layer url

compute_control_points

orthomapping.compute_control_points(reference_image=None, image_location_accuracy='High', context=None, gis=None)

This service tool is used for computing matching control points between images within an image collection and/or matching control points between the image collection images and the reference image. http://pro.arcgis.com/en/pro-app/tool-reference/data-management/compute-control-points.htm

Argument

Description

image_collection

Required. This is the image collection that will be adjusted.

The image_collection can be a portal Item or an image service URL or a URI

The image_collection must exist.

reference_image

This is the reference image service that can be used to generate ground control points set with the image service. It can be a portal Item or an image service URL or a URI

image_location_accuracy

Optional string. This option allows users to specify the location accuracy of the imagery. VERYLOW, LOW, MEDIUM, HIGH LOW-Images have a large shift and a large rotation (> 5 degrees).

The SIFT algorithm will be used in the point matching computation.

MEDIUM-Images have a medium shift and a small rotation (<5 degrees).

The Harris algorithm will be used in the point matching computation.

HIGH-Images have a small shift and a small rotation.

The Harris algorithm will be used in the point matching computation.

Default is HIGH

context

Optional dictionary. Context contains additional environment settings that affect output control points generation. { “pointSimilarity”:”MEDIUM”, “pointDensity”: “MEDIUM”, “pointDistribution”: “RANDOM” }

gis

Optional GIS. the GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The imagery layer url

compute_seamlines

orthomapping.compute_seamlines(seamlines_method, context=None, gis=None)

Compute seamlines on the image collection. This service tool is used to compute seamlines for the image collection, usually after the image collection has been block adjusted. Seamlines are helpful for generating the seamless mosaicked display of overlapped images in image collection. The seamlines are computed only for candidates that will eventually be used for generating the result ortho-mosaicked image. http://pro.arcgis.com/en/pro-app/tool-reference/data-management/build-seamlines.htm

Argument

Description

image_collection

Required, the input image collection that will be adjusted. The image_collection can be a portal Item or an image service URL or a URI The image_collection must exist.

seamlines_method

Required string. These are supported methods for generated seamlines for the image collection.

VORONOI-Generate seamlines using the area Voronoi diagram.

DISPARITY-Generate seamlines based on the disparity images of stereo pairs.

GEOMETRY - Generate seamlines for overlapping areas based on the intersection of footprints. Areas with no overlapping imagery will merge the footprints.

RADIOMETRY - Generate seamlines based on the spectral patterns of features within the imagery.

EDGE_DETECTION - Generate seamlines over intersecting areas based on the edges of features in the area.

This method can avoid seamlines cutting through buildings.

context

Optional dictionary. Context contains additional settings that allows users to customize the seamlines generation. Example: {“minRegionSize”: 100, “pixelSize”: “”, “blendType”: “Both”, “blendWidth”: null, “blendUnit”: “Pixels”, “requestSizeType”: “Pixels”, “requestSize”: 1000, “minThinnessRatio”: 0.05, “maxSilverSize”: 20 }

Allowed keys are: “minRegionSize”, “pixelSize”, “blendType”, “blendWidth”, “blendUnit”, “requestSizeType”, “requestSize”, “minThinnessRatio”, “maxSilverSize”

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The Imagery layer url

edit_control_points

orthomapping.edit_control_points(control_points, gis=None)

This service can be used to append additional ground control point sets to the image collection’s control points. A complete ground control point (GCP) set should have one ground control point and multiple (more than 3) tie points. The service tool can also be used to edit tie point sets. The input control points dictionary will always replace the points in the tie points table if the point IDs already exist.

Argument

Description

image_collection

Required. The image_collection can be a portal Item or an image service URL or a URI The image_collection must exist.

control_points

Required, a list of control point objects. A control point object is a dictionary with key-value pairs as described below:

The schema of control points follows the schema of the mosaic dataset control point table. The following are required when defining control points:

  • The control points must contain a Point geometry object

  • There must be one attribute set, describing the attributes of the control point.

The control point attributes is a dictionary that must contain the following key-value pairs:

– imageID (int) - Image identification using the ObjectID from the mosaic dataset footprint table.

– pointID (int) - The ID of the point within the control point table

– type (int) - The type of the control point as determined by its numeric value

1: Tie Point 2: Ground Control Point. 3: Check Point

– status (int) - The status of the point. A value of 0 indicates that the point will

not be used in computation. A non-zero value indicates otherwise.

Example: {“geometry”: {

“x”:-118.15,”y”:33.80,”z”:10.0, “spatialReference”:{“wkid”:4326}}, “attributes”: {

“imageID”: 22, “pointID”: 2, “type”: 2, “status”: 1,

},

<more points>

}

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The Imagery layer url

generate_dem

orthomapping.generate_dem(out_dem, cell_size, surface_type, matching_method=None, context=None, gis=None)

Generate a DEM from the image collection. Refer to “Interpolate From Point Cloud” GP tool for more documentation http://pro.arcgis.com/en/pro-app/tool-reference/data-management/interpolate-from-point-cloud.htm

Argument

Description

image_collection

Required. The input image collection that will be used to generate the DEM from. The image_collection can be a portal Item or an image service URL or a URI The image_collection must exist.

out_dem

This is the output digital elevation model image url or name. Like Raster Analysis services, the service can be an existing multi-tenant service URL or this service tool can create it. It can be a url, uri, portal item, string representing the name of output image service

cell_size

Required, The cell size of the output raster dataset. This is a single numeric input. Rectangular cell size such as {“x”: 10, “y”: 10} is not supported. The cell size unit will be the unit used by the image collection’s spatial reference.

surface_type

Required string. Create a digital terrain model or a digital surface model. Refer to “surface_type” parameter of the GP tool. The available choices are:

DTM - Digital Terrain Model, the elevation is only the elevation of the bare earth, not including structures above the surface.

DSM - Digital Surface Model, the elevation includes the structures above the surface, for example, buildings, trees, bridges.

matching_method

Optional string. The method used to generate 3D points.

ETM-A feature-based stereo matching that uses the Harris operator to detect feature points. It is recommended for DTM generation.

SGM- Produces more points and more detail than the ETM method. It is suitable for generating a DSM for urban areas. This is more computationally intensive than the ETM method1.

ESGM-This is an extension of SGM, with edge enhancement capability.

References: Heiko Hirschmuller et al., “Memory Efficient Semi-Global Matching,” ISPRS Annals of the Photogrammetry, Remote Sensing and Spatial Information Sciences, Volume 1-3, (2012): 371-376.

Refer to the documentation of “matching_method” parameter of the “Generate Point Cloud” GP tool @ http://pro.arcgis.com/en/pro-app/tool-reference/data-management/generate-point-cloud.htm

context

Optional dictionary. Additional allowed point cloud generation parameter and DEM interpolation parameter can be assigned here. For example: Point cloud generation parameters - {“maxObjectSize”: 50, “groundSpacing”: None, “minAngle”: 10, “maxAngle”: 70, “minOverlap”: 0.6, “maxOmegaPhiDif”: 8, “maxGSDDif”: 2, “numImagePairs”: 2, “adjQualityThreshold”: 0.2, “regenPointCloud”: False }

DEM interpolation parameters - {“method”: “TRIANGULATION”, “smoothingMethod”: “GAUSS5x5”, “applyToOrtho”: True, “fillDEM”: “https://….” }

Note: The “applyToOrtho” flag can apply the generated DEM back into the mosaic dataset’s geometric function to achieve more accurate orthorectification result. The “fillDEM” flag allows the user to specify an elevation service URL as background elevation to fill the area when elevation model pixels cannot be interpolated from the point cloud.

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The DEM layer item

generate_orthomosaic

orthomapping.generate_orthomosaic(out_ortho, regen_seamlines=True, recompute_color_correction=True, context=None, gis=None)

Generate a DEM from the image collection. Refer to “Interpolate From Point Cloud” GP tool for more documentation http://pro.arcgis.com/en/pro-app/tool-reference/data-management/interpolate-from-point-cloud.htm

Argument

Description

image_collection

Required. The input image collection that will be used to generate the ortho-mosaic from. The image_collection can be a portal Item or an image service URL or a URI The image_collection must exist.

out_ortho

Required. This is the output ortho-mosaicked image converted from the image collection after the block adjustment. It can be a url, uri, portal item, string representing the name of output image service

regen_seamlines

Optional, boolean.

Choose whether to apply seamlines before the orthomosaic image generation or not. The seamlines will always be regenerated if this parameter is set to True. The user can set the seamline options through the context parameter. If the seamline generation options are not set, the default will be used.

Default value is True

recompute_color_correction

Optional, boolean. Choose whether to apply color correction settings to the output ortho-image or not. Color correction will always be recomputed if this option is set to True. The user can configure the compute color correction settings through the context parameter. If there is no color collection setting, the default will be used.

Default value is True

context

Optional dictionary. Context contains additional environment settings that affect output image. The supported environment settings for this tool are:

  1. Output Spatial Reference (outSR)-the output features will be projected into the output spatial reference.

  2. Extent (extent) - extent that would clip or expand the output image

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The Orthomosaicked Imagery layer item

generate_report

orthomapping.generate_report(gis=None)

This function is used to generate orthomapping report with image collection that has been block adjusted. The report would contain information about the quality of the adjusted images, the distribution of the control points, etc. The output of this service tool is a downloadable html page.

Argument

Description

image_collection

Required. the input image collection that should be used to generate a report from. The image_collection can be a portal Item or an image service URL or a URI The image_collection must exist.

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

The URL of a single html webpage that is a formatted orthomapping report

query_camera_info

orthomapping.query_camera_info(gis=None)

This service tool is used to query specific or the entire digital camera database. The digital camera database contains the specs of digital camera sensors that were used to capture drone images.

Argument

Description

camera_query

Required String. This is a SQL query statement that can be used to filter a portion of the digital camera database.

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

Data Frame representing the camera database

query_control_points

orthomapping.query_control_points(query, gis=None)

Query for control points in an image collection. It allows users to query certain control points from image collection’s control point table with a SQL query (or a feature/image service in the future).

Argument

Description

image_collection

Required, the input image collection on which to query the the control points.

The image_collection can be a portal Item or an image service URL or a URI.

The image_collection must exist.

query

Required string. a SQL statement used for querying the point;

e.g. “pointID > 100”

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

A dictionary object

reset_image_collection

orthomapping.reset_image_collection(gis=None)

Reset the image collection. It is used to reset the image collection to its original state. The image collection could be adjusted during the orthomapping workflow and if the user is not satisfied with the result, they will be able to clear any existing adjustment settings and revert the images back to un-adjusted state

Argument

Description

image_collection

Required, the input image collection to reset The image_collection can be a portal Item or an image service URL or a URI.

The image_collection must exist.

gis

Optional GIS. The GIS on which this tool runs. If not specified, the active GIS is used.
Returns

A boolean indicating whether the reset was successful or not