Color Balance Mosaic Dataset

Summary

Makes transitions from one image to an adjoining image appear seamless.

Usage

• Color balancing can only take place if the following is true about your data:

  • All the bands have their statistics calculated.
  • All the bands have their histograms built.
  • All the raster datasets have the same number of bands.
  • All the raster datasets have the same pixel type and pixel depth. Only 8-bit unsigned and 16-bit unsigned bit depths are supported.
  • None of the raster datasets have an associated color map.

• The actions defined by the Exclude Area Raster, Stretch Type, and Gamma parameters (exclude_raster, stretch_type, and gamma in Python) are performed before any color balancing takes place. On the tool's dialog box, these three parameters are found in the Pre-processing Options tab.

• The target color surface is only available if the dodging balancing technique is chosen. When using the dodging technique, each pixel needs a target color, which is picked up from the target color surface. There are five types of target color surfaces that you can choose from: single color, color grid, first order surface, second order surface, and third order surface.

• The Target Raster is a raster that is used to guide color balancing.

  • When dodging balancing is used—The target color that will be derived depends on the target color surface type that was chosen. For single color, the average value of the reference target image is used. For color grid, the reference target image is resampled to a suitable grid. For the polynomial order surfaces, the coefficients of the polynomial are obtained by least square fitting, from the reference target image.
  • When histogram balancing is used—The target histogram is obtained from the reference target image.
  • When standard deviation balancing is used—The target standard deviation is obtained from the reference target image.

• To remove a color correction, right-click the mosaic dataset in ArcCatalog or the Catalog window and click Remove > Remove Color Balancing.

Syntax

ColorBalanceMosaicDataset_management (in_mosaic_dataset, {balancing_method}, {color_surface_type}, {target_raster}, {exclude_raster}, {stretch_type}, {gamma}, {block_field})

Parameter	Explanation	Data Type
in_mosaic_dataset	The mosaic dataset you want to color balance.	Mosaic Layer
balancing_method (Optional)	The balancing algorithm to use. DODGING —Change each pixel's value towards 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.	String
color_surface_type (Optional)	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 there are too many types of ground surfaces, then the output color may become blurred. All the pixels are altered towards a single color point—the mean (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 towards 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.	String
target_raster (Optional)	The raster that you want to use to color balance the other images. The balance method and color surface type, if applicable, will be derived from this image.	Internet Tiled Layer; Map Server Layer; Raster Layer
exclude_raster (Optional)	Applies a mask before color balancing the mosaic dataset. Create the mask using the Generate Exclude Area tool.	Raster Layer
stretch_type (Optional)	Stretch the range of values before color balancing. Choose from one of the following options: NONE — Use the original pixel values. This is the default. ADAPTIVE — An adaptive prestretch will be applied before any processing takes place. MINIMUM_MAXIMUM — Stretch the values between their actual minimum and maximum values. STANDARD_DEVIATION — Stretch the values between the default number of standard deviations.	String
gamma (Optional)	Adjust the overall brightness of an image. A low value will minimize the contrast between moderate values by making them appear darker. Higher values increase thecontrast by making them appear brighter.	Double
block_field (Optional)	The name of the field within a mosaic dataset's attribute table used to identify items that should be considered one item when performing some calculations and operations.	String

Code sample

ColorBalanceMosaicDataset example 1 (Python window)

This is a Python sample for ColorBalanceMosaicDataset.

import arcpy
arcpy.ColorBalanceMosaicDataset_management(
     "C:/workspace/CC.gdb/cc1", "DODGING", "SINGLE_COLOR", 
     "C:/workspace/Aerial.lyr",  "#", "STANDARD_DEVIATION", "3", "BLOCKNAME")

ColorBalanceMosaicDataset example 2 (stand-alone script)

This is a Python script sample for ColorBalanceMosaicDataset.

#########*#########*##########*#########*#########*#########*#########*&&&&&&&&&&

# Color Correction Mosaic Dataset with target layer

import arcpy
arcpy.env.workspace = "C:/workspace"

mdname = "CC.gdb/cc1"
ccmethod = "DODGING"
dogesurface = "SINGLE_COLOR"
targetras = "C:/workspace/Aerial_photo.lyr"
excluderas = "#"
prestretch = "NONE"
gamma = "#"
blockfield = "#"

arcpy.ColorBalanceMosaicDataset_management(
     mdname, ccmethod, dogesurface, targetras, excluderas,
     prestretch, gamma, blockfield)

Environments

This tool does not use any geoprocessing environments

Licensing information

• ArcGIS for Desktop Basic: No
• ArcGIS for Desktop Standard: Yes
• ArcGIS for Desktop Advanced: Yes