Color Balance Mosaic Dataset (Data Management)

Summary

Color balances a mosaic dataset so that the tiles 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 histogram built.
  • None of the raster datasets have an associated color map.

• The bands in the Target Raster parameter value must be in the same order as the bands in the Mosaic Dataset parameter value. Ideally, the number of bands should be the same. If there are more bands in the input mosaic dataset, the bands in the target raster will be used again, sequentially.

• If the bit depth of the input mosaic dataset and the target raster are different, the pixel values will be automatically scaled so that they are both in the same bit depth.

• The actions defined by the Exclude Area Raster, Stretch Type, and Gamma parameters are performed before any color balancing occurs.

• 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 and Target Raster Object ID parameter values are used to guide color balancing. The color of the Target Raster and Target Raster Object ID parameter values will not be changed, and its color characteristics will be used to color balance the other images in the mosaic dataset. While the color of the target raster is maintained, the global optimization of the entire mosaic dataset may become weaker, so it is not necessary to always get the best overall optimized color balance outcome.

  • 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.

• The DEM Raster parameter is activated when the Balance Method parameter is set to Global Fit. It is recommended that the digital elevation model (DEM) be local rather than online; otherwise, the computation will take longer. When the DEM Raster parameter value is specified, the Z Factor, Z Offset, and Apply Geoid Correction parameters are activated, and their default values are typically used.

• The Input Solution Points parameter is activated when the Balance Method parameter is set to Global Fit. You can use the solution points from block adjustment output to help estimate the locations of image overlap. This is helpful when the image has less than 50 percent overlap with its neighbors. It is recommended that you do not use this option for mosaic datasets with good overlap because it will increase computation time.

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

Parameters

Dialog

Label	Explanation	Data Type
Mosaic Dataset	The mosaic dataset that will be color balanced.	Mosaic Layer
Balance Method (Optional)	Specifies the balancing method that will be used. Dodging—Each pixel's value will be changed toward a target color. With this method, 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. Global Fit—An optimal pixel value will be determined by globally adjusting the color difference in all overlap areas to the minimum. This method is suitable for a mosaic dataset in which each image has good overlap with each other. Histogram—Each pixel's value will be changed 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 method works well when all of the rasters have a similar histogram. Standard deviation—Each of the pixel's values will be changed 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 method works best when all of the rasters have normal distributions.	String
Color Surface Type (Optional)	Specifies how the target color of each pixel will be determined. This parameter is active when the Balance Method parameter is set to Dodging. Single color— All the pixels will be altered toward a single color point—the average of all pixels. Use this option 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. Color grid— Pixels will be altered toward multiple target colors, which are distributed across the mosaic dataset. Use this option when you have a large number of raster datasets or areas with a large number of diverse ground objects. First order— All pixels will be altered toward many points obtained from the two-dimensional polynomial slanted plane. This option 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. Second order— All input pixels will be altered toward a set of multiple points obtained from the two-dimensional polynomial parabolic surface. This option 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. Third order— All input pixels will be altered toward multiple points obtained from the cubic surface. This option 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.	String
Target Raster (Optional)	The raster that will be used to color balance the other images. The balance method and color surface type, if applicable, will be derived from this image.	Raster Dataset; Raster Layer; Internet Tiled Layer; Map Server Layer
Exclude Area Raster (Optional)	A raster that identifies the locations that will be excluded. Create a mask using the Generate Exclude Area tool.	Raster Layer
Stretch Type (Optional)	Specifies how the range of values will be stretched before color balancing. None— The original pixel values will be used. This is the default. Adaptive— An adaptive prestretch will be applied before any processing takes place. Minimum Maximum— The values will be stretched between their minimum and maximum values. Standard deviation— The values will be stretched between the default number of standard deviations.	String
Gamma (Optional)	A numeric value that will adjust the overall brightness of an image. A low value will minimize the contrast between moderate values by making them appear darker. Higher values will increase the contrast by making them appear brighter.	Double
Block Field (Optional)	A field in the mosaic dataset's attribute table that will be used to identify items that will be considered one item when performing some calculations and operations.	String
DEM Raster (Optional)	A DEM to help estimate the overlapped locations in the mosaic dataset. This parameter is active when the Balance Method parameter is set to Global Fit.	Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer
Z Factor (Optional)	A conversion factor that adjusts the units of measure for the vertical (or elevation) units when they are different from the horizontal coordinate (x,y) units of the input surface DEM. It is the number of ground x,y units in one surface z-unit. If the vertical units are meters, set the parameter to 1. If the vertical units are feet, set the parameter to 0.3048. If any other vertical units are used, use this parameter to scale the units to meters. This parameter is active when the DEM Raster parameter is specified.	Double
Z Offset (Optional)	A base value that will be added to the elevation value in the DEM. This can be used to offset elevation values that do not start at sea level. This parameter is active when the DEM Raster parameter is specified.	Double
Apply Geoid Correction (Optional)	Specifies whether the geoid correction required by rational polynomial coefficients (RPC) that reference ellipsoidal heights will be made. Most elevation datasets are referenced to sea level orthometric heights, so this correction is required in these cases to convert to ellipsoidal heights. This parameter is active when the DEM Raster parameter is specified. Unchecked—No geoid correction will be made. Use this option only if the DEM is already expressed in ellipsoidal heights. This is the default. Checked—A geoid correction will be made to convert orthometric heights to ellipsoidal heights (based on EGM96 geoid).	Boolean
Input Solution Points (Optional)	The solution points from block adjustment output to help accurately estimate the overlapped locations. This parameter is helpful when the image has less than 50 percent overlap with its neighbors. Using this parameter will increase the computation time, so for the ordinary mosaic dataset with good overlaps, you can leave this parameter unspecified. This parameter is active when the Balance Method parameter is set to Global Fit.	Table View
Target Raster Object ID (Optional)	The target raster object ID that will be used to color balance the other images. The balance method and color surface type, if applicable, will be derived from this image. This parameter is active when the Balance Method parameter is set to Global Fit.	Long
Refine Estimation by Correlation (Optional)	Specifies whether the color balancing estimation for corresponding locations in the overlapped areas will be refined using image correlation. This parameter is helpful for the exact color difference correction but will increase the computation time. If you have a mosaic dataset composed of a large number of images, uncheck this parameter to reduce the computation time. This parameter is active when the Balance Method parameter is set to Global Fit. Unchecked—No refined estimation will be made. Checked—A refined estimation for color balance will be made. This is the default.	Boolean
Reduce Shadow Influence (Optional)	Specifies whether the negative influence of shadows on the color balance output will be reduced. This parameter is active when the Balance Method parameter is set to Global Fit. Unchecked—The influence of shadows will not be reduced. This is the default. Checked—The influence of shadows will be reduced. Use this option when the mosaic dataset has a lot of shadows.	Boolean
Reduce Cloud Influence (Optional)	Specifies whether the negative influence of clouds on the color balance output will be reduced. This parameter is active when the Balance Method parameter is set to Dodging or Global Fit. Unchecked—The influence of clouds will not be reduced. This is the default. Checked—The influence of clouds will be reduced.	Boolean

Derived Output

Label	Explanation	Data Type
Updated Mosaic Dataset	The updated mosaic dataset.	Mosaic Layer

Python

arcpy.management.ColorBalanceMosaicDataset(in_mosaic_dataset, {balancing_method}, {color_surface_type}, {target_raster}, {exclude_raster}, {stretch_type}, {gamma}, {block_field}, {in_DEM_raster}, {ZFactor}, {ZOffset}, {Geoid}, {solution_points}, {target_objectid}, {refine_estimation}, {reduce_shadow}, {reduce_cloud})

Name	Explanation	Data Type
in_mosaic_dataset	The mosaic dataset that will be color balanced.	Mosaic Layer
balancing_method (Optional)	Specifies the balancing method that will be used. DODGING—Each pixel's value will be changed toward a target color. With this method, 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. GLOBAL_FIT—An optimal pixel value will be determined by globally adjusting the color difference in all overlap areas to the minimum. This method is suitable for a mosaic dataset in which each image has good overlap with each other. HISTOGRAM—Each pixel's value will be changed 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 method works well when all of the rasters have a similar histogram. STANDARD_DEVIATION—Each of the pixel's values will be changed 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 method works best when all of the rasters have normal distributions.	String
color_surface_type (Optional)	Specifies how the target color of each pixel will be determined. This parameter is enabled when the balancing_method parameter is set to DODGING. SINGLE_COLOR— All the pixels will be altered toward a single color point—the average of all pixels. Use this option 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. COLOR_GRID— Pixels will be altered toward multiple target colors, which are distributed across the mosaic dataset. Use this option when you have a large number of raster datasets or areas with a large number of diverse ground objects. FIRST_ORDER— All pixels will be altered toward many points obtained from the two-dimensional polynomial slanted plane. This option 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. SECOND_ORDER— All input pixels will be altered toward a set of multiple points obtained from the two-dimensional polynomial parabolic surface. This option 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. THIRD_ORDER— All input pixels will be altered toward multiple points obtained from the cubic surface. This option 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.	String
target_raster (Optional)	The raster that will be used to color balance the other images. The balance method and color surface type, if applicable, will be derived from this image.	Raster Dataset; Raster Layer; Internet Tiled Layer; Map Server Layer
exclude_raster (Optional)	A raster that identifies the locations that will be excluded. Create a mask using the Generate Exclude Area tool.	Raster Layer
stretch_type (Optional)	Specifies how the range of values will be stretched before color balancing. NONE— The original pixel values will be used. This is the default. ADAPTIVE— An adaptive prestretch will be applied before any processing takes place. MINIMUM_MAXIMUM— The values will be stretched between their minimum and maximum values. STANDARD_DEVIATION— The values will be stretched between the default number of standard deviations.	String
gamma (Optional)	A numeric value that will adjust the overall brightness of an image. A low value will minimize the contrast between moderate values by making them appear darker. Higher values will increase the contrast by making them appear brighter.	Double
block_field (Optional)	A field in the mosaic dataset's attribute table that will be used to identify items that will be considered one item when performing some calculations and operations.	String
in_DEM_raster (Optional)	A DEM to help estimate the overlapped locations in the mosaic dataset. This parameter is enabled when the balancing_method parameter is set to GLOBAL_FIT.	Raster Dataset; Raster Layer; Mosaic Dataset; Mosaic Layer
ZFactor (Optional)	A conversion factor that adjusts the units of measure for the vertical (or elevation) units when they are different from the horizontal coordinate (x,y) units of the input surface DEM. It is the number of ground x,y units in one surface z-unit. If the vertical units are meters, set the parameter to 1. If the vertical units are feet, set the parameter to 0.3048. If any other vertical units are used, use this parameter to scale the units to meters. This parameter is enabled when the in_DEM_raster parameter is specified.	Double
ZOffset (Optional)	A base value that will be added to the elevation value in the DEM. This can be used to offset elevation values that do not start at sea level. This parameter is enabled when the in_DEM_raster parameter is specified.	Double
Geoid (Optional)	Specifies whether the geoid correction required by rational polynomial coefficients ( RPC) that reference ellipsoidal heights will be made. Most elevation datasets are referenced to sea level orthometric heights, so this correction is required in these cases to convert to ellipsoidal heights. This parameter is active when the in_DEM_raster parameter is specified. NONE—No geoid correction will be made. Use this option only if the DEM is already expressed in ellipsoidal heights. This is the default. GEOID—A geoid correction will be made to convert orthometric heights to ellipsoidal heights (based on EGM96 geoid).	Boolean
solution_points (Optional)	The solution points from block adjustment output to help accurately estimate the overlapped locations. This parameter is helpful when the image has less than 50 percent overlap with its neighbors. Using this parameter will increase the computation time, so for the ordinary mosaic dataset with good overlaps, you can leave this parameter unspecified. This parameter is enabled when the balancing_method parameter is set to GLOBAL_FIT.	Table View
target_objectid (Optional)	The target raster object ID that will be used to color balance the other images. The balance method and color surface type, if applicable, will be derived from this image. This parameter is enabled when the balancing_method parameter is set to GLOBAL_FIT.	Long
refine_estimation (Optional)	Specifies whether the color balancing estimation for corresponding locations in the overlapped areas will be refined using image correlation. This parameter is helpful for the exact color difference correction but will increase the computation time. If you have a mosaic dataset composed of a large number of images, specify the NO_REFINE_ESTIMATION option to reduce the computation time. This parameter is enabled when the balancing_method parameter is set to GLOBAL_FIT. NO_REFINE_ESTIMATION—No refined estimation will be made. This is the default. REFINE_ESTIMATION—A refined estimation for color balance will be made	Boolean
reduce_shadow (Optional)	Specifies whether the negative influence of shadows on the color balance output will be reduced. This parameter is enabled when the balancing_method parameter is set to GLOBAL_FIT. NO_REDUCE_SHADOW—The influence of shadows will not be reduced. This is the default. REDUCE_SHADOW—The influence of shadows will be reduced. Use this option when the mosaic dataset has a lot of shadows.	Boolean
reduce_cloud (Optional)	Specifies whether the negative influence of clouds on the color balance output will be reduced. This parameter is active when the balancing_method parameter is set to DODGING or GLOBAL_FIT. NO_REDUCE_CLOUD—The influence of clouds will not be reduced. This is the default. REDUCE_CLOUD—The influence of clouds will be reduced.	Boolean

Derived Output

Name	Explanation	Data Type
out_mosaic_dataset	The updated mosaic dataset.	Mosaic Layer

Code sample

ColorBalanceMosaicDataset example 1 (Python window)

This is a Python sample for the ColorBalanceMosaicDataset function.

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 the ColorBalanceMosaicDataset function.

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

# 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)

ColorBalanceMosaicDataset example 3 (Python window)

This is a Python sample for the ColorBalanceMosaicDataset function.

# Color Correction Mosaic Dataset with block field

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

mdname = "CC.gdb/cc2"
ccmethod = "HISTOGRAM"
dogesurface = "#"
targetras = "#"
excluderas = "#"
prestretch = "NONE"
gamma = "#"
blockfield = "BLOCKNAME"

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

Environments

Parallel Processing Factor