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 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 Pre-processing Options are performed before any color balancing takes place.

• There are three balancing algorithms available: Dodging, Histogram, and Standard deviation.

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

• Target Raster allows you to specify the target to balance your rasters.

  • 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}, {gamma}, {exclude_raster}, {stretch_type}, {block_field})

Parameter	Explanation	Data Type
in_mosaic_dataset	Type or navigate to the mosaic dataset that you want to color balance.	Mosaic Layer
balancing_method (Optional)	Choose the balancing algorithm to use. DODGING —This is the traditional dodging photogrammetric technique, where each of the pixel's values change toward the target color. These values are used to determine the output value for each pixel. If you choose Dodging, then you must also choose the type of target color surface to use, which will affect what the target color is. Dodging balancing tends to give the best result in most cases. HISTOGRAM —This technique will change each of the pixel's values according to the target histogram. The target histogram can be automatically calculated from all the rasters, or a target raster can be specified. Histogram balancing works well when all the rasters have a similar histogram shape. STANDARD_DEVIATION —This technique will change each of the pixel's values according to the standard deviation calculation. The standard deviation value can be automatically calculated from all the rasters or from a specified target raster. Standard deviation balancing works best when all the rasters have the same histogram distribution of the normalized values.	String
color_surface_type (Optional)	The Target Color Surface Type is only available if the dodging balancing technique is chosen. When using the dodging technique, each pixel needs a target color, which is determined by which surface type is chosen. SINGLE_COLOR —All the pixels are dodged toward a single color point, which is the mean. A single color surface works well when there are only a small number of rasters and there are only a few different types of ground objects. If there are too many rasters or there are too many types of ground surfaces, then the output color may become blurred. COLOR_GRID —All the input pixels are dodged toward a multiple set of points, which are distributed all over the mosaic dataset. Color grid produces a good output for a large number of rasters, or areas with a large number of diverse ground objects. FIRST_ORDER —All input pixels are dodged toward many points, which are obtained from the two-dimensional polynomial slanted plane. Compared to the Color Grid surface, a polynomial order surface tends to be a smoother color change and uses less storage in the auxiliary table but tends to take longer to process. SECOND_ORDER —All input pixels are dodged toward a set of multiple points, which is obtained from the two-dimensional polynomial parabolic surface. Compared to the Color Grid surface, a polynomial order surface tends to be a smoother color change and uses less storage in the auxiliary table but tends to take longer to process. THIRD_ORDER —All input pixels are dodged toward multiple points, which are obtained from the cubic surface. Compared to the Color Grid surface, a polynomial order surface tends to be a smoother color change and uses less storage in the auxiliary table but tends to take longer to process.	String
target_raster (Optional)	The target raster image allows you to specify the target raster to balance your rasters. 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 the Least Squares 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.	Raster Layer
gamma (Optional)	Type the gamma value to use in the pre-processing stretch. This is only available if the Standard Deviation or Minimum-Maximum prestretch type is chosen. By applying the gamma stretch, you can control the overall brightness of an image. If the gamma coefficient is set too low, the middle tones appear too dark; however, if the gamma coefficient is set too high, the middle tones appear too light. Gamma changes not only the brightness but also the ratios of red to green to blue.	Double
exclude_raster (Optional)	Navigate to the raster you would like to use as an exclude layer. The Generate Exclude Area tool can be used to create the exclude area. The exclude area is taken into consideration before any color balancing takes place.	Raster Layer
stretch_type (Optional)	Prestretching can be performed on each raster catalog item before any other color correction takes place. This means that the original raster catalog item will be using its stretched pixel values, rather than its raw pixel values, in the color correction process. You may want to use this option to change the color to an expected distribution before applying color correction. NONE — No prestretch will be applied. This is the default ADAPTIVE — An adaptive prestretch will be applied before any processing takes place. MINIMUM_MAXIMUM — A minimum-maximum prestretch will be applied before any processing takes place. STANDARD_DEVIATION — A standard deviation prestretch will be applied before any processing takes place.	String
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