Color Balance Mosaic Dataset (Data Management)

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 histogram built.
  • Only 8-bit unsigned and 16-bit unsigned bit depths are supported.
  • None of the raster dataset have an associated color map.

• The bands in the Target Raster need to be in the same order as the bands in the input mosaic dataset. 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 (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 Preprocessing Options parameter category.

• 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 the Catalog pane and click Remove > Remove Color Balancing

Syntax

arcpy.management.ColorBalanceMosaicDataset(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 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.	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 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.	String
target_raster (Optional)	The raster 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.	Raster Dataset; Raster Layer; Internet Tiled Layer; Map Server Layer
exclude_raster (Optional)	Apply 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 the contrast by making them appear brighter.	Double
block_field (Optional)	The name of the field in a mosaic dataset's attribute table used to identify items that should be considered one item when performing some calculations and operations.	String

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

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

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

# 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

Parallel Processing Factor

Licensing information

• Basic: No
• Standard: Yes
• Advanced: Yes