Color Balance Mosaic Dataset (Data Management)

Summary

Color balances a mosaic dataset so that the tiles appear seamless.

Usage

Syntax

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

Type or navigate to the mosaic dataset that you want to color balance.

Mosaic Layer; Mosaic Dataset
balancing_method
(Optional)

Choose the balancing algorithm to use.

  • DODGINGThis 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.
  • HISTOGRAMThis 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 DEVIATIONThis 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_COLORAll 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_GRIDAll 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_ORDERAll 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_ORDERAll 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_ORDERAll 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

Code Sample

ColorBalanceMosaicDataset example 1 (Python window)

This is a Python sample for ColorBalanceMosaicDataset.

import arcpy 
ColorBalanceMosaicDataset_management("C:/workspace/fgdb.gdb/mosData","DODGING",\
                                     "COLOR_GRID", "C:/workspace/target.tif",\
                                     "C:/temp/excludeArea.tif","NONE","1", \
                                     "BlockName")
ColorBalanceMosaicDataset example 2 (stand-alone script)

This is a Python script sample for ColorBalanceMosaicDataset.

##===========================
##Color Balance Mosaic Dataset
##Usage: ColorBalanceMosaicDataset_management(in_mosaic_dataset, {DODGING |
##                                            HISTOGRAM | STANDARD_DEVIATION},
##                                            {SINGLE_COLOR | COLOR_GRID | 
##                                            FIRST_ORDER | SECOND_ORDER | THIRD_ORDER},
##                                            {target_raster}, {exclude_raster},
##                                            {NONE | STANDARD_DEVIATION | MINIMUM_MAXIMUM
##                                            | ADAPTIVE}, {gamma}), {block_field}

try:
    import arcpy
    arcpy.env.workspace = "c:/workspace"
    
    # Color Correction Mosaic Dataset with target layer
    arcpy.ColorBalanceMosaicDataset_management("CC.gdb/cc1", "DODGING", "SINGLE_COLOR",
                                              "Aerial_photo.lyr", "#", "NONE", "#", "BlockName")                                      

    # Color Correction Mosaic Dataset with exclude area dataset and prestretch
    arcpy.ColorBalanceMosaicDataset_management("CC.gdb/cc2", "DODGING", "COLOR_GRID",
                                              "#", "excludearea.tif", "STANDARD_DEVIATION",
                                              "3", "BlockName") 
    
    
except:
    print "Color Balance Mosaic Dataset example failed."
    print arcpy.GetMessages()

Environments

This tool does not use any geoprocessing environments

Related Topics

Licensing Information

ArcView: No
ArcEditor: Yes
ArcInfo: Yes

10/27/2014