Workspace To Raster Dataset (Data Management)

Summary

Merges all of the raster datasets in a folder into one raster dataset.

Usage

  • The target raster dataset must already exist for the tool to run.

  • If a target raster dataset does not already exist, use the Create Raster Dataset tool to create a new raster dataset.

  • Since mosaicking will take place, you will need to specify the mosaic method and color map mode to use.

  • If the target raster dataset is an empty raster dataset, the cell size and spatial reference of the first input raster dataset will be applied to the mosaic.

  • Whenever possible use the Last Mosaic Operator to mosaic raster datasets to an existing raster dataset in a file geodatabase or an enterprise geodatabase; it is by far the most effective way to mosaic.

  • For mosaicking of discrete data, the First, Minimum, or Maximum option in Mosaic Operator will provide the most meaningful results. The Blend and Mean options are best suited for continuous data.

  • The color matching method drop-down arrow allows you to choose an algorithm to color match the datasets in your mosaic.

  • For file-based rasters, Ignore Background Value must be set to the same value as NoData for the background value to be ignored. Geodatabase rasters will work without this extra step.

  • For floating-point input raster datasets of different resolutions or when cells are not aligned, it is recommended that you resample all the data using bilinear interpolation or cubic convolution before running Mosaic. Otherwise, Mosaic will automatically resample the raster datasets using nearest neighbor resampling, which is not appropriate for continuous data types.

Parameters

LabelExplanationData Type
Input Workspace

The folder containing the raster datasets to merge.

Workspace
Target Raster Dataset

An existing raster dataset in which to merge all of the raster datasets from the input workspace.

Raster Dataset
Include Sub-directories
(Optional)

Specify whether to include subdirectories.

  • Unchecked—Does not include subdirectories. This is the default.
  • Checked—Includes all the raster datasets in the subdirectories when loading.
Boolean
Mosaic Operator
(Optional)

Specifies the method that will be used to mosaic overlapping areas.

  • First — The output cell value of the overlapping areas will be the value from the first raster dataset mosaicked into that location.
  • Last — The output cell value of the overlapping areas will be the value from the last raster dataset mosaicked into that location. This is the default.
  • Blend — The output cell value of the overlapping areas will be a horizontally weighted calculation of the values of the cells in the overlapping area.
  • Mean — The output cell value of the overlapping areas will be the average value of the overlapping cells.
  • Minimum — The output cell value of the overlapping areas will be the minimum value of the overlapping cells.
  • Maximum — The output cell value of the overlapping areas will be the maximum value of the overlapping cells.
  • Sum —The output cell value of the overlapping areas will be the total sum of the overlapping cells.
String
Mosaic Colormap Mode
(Optional)

Specifies the method that will be used to choose which color map from the input rasters will be applied to the mosaic output.

  • First — The color map from the first raster dataset in the list will be applied to the output raster mosaic. This is the default.
  • Last — The color map from the last raster dataset in the list will be applied to the output raster mosaic.
  • Match — All the color maps will be considered when mosaicking. If all possible values are already used (for the bit depth), the tool will match the value with the closest available color.
  • Reject — Only the raster datasets that do not have a color map associated with them will be mosaicked.
String
Ignore Background Value
(Optional)

Use this option to remove the unwanted values created around the raster data. The value specified will be distinguished from other valuable data in the raster dataset. For example, a value of zero along the raster dataset's borders will be distinguished from zero values in the raster dataset.

The pixel value specified will be set to NoData in the output raster dataset.

For file-based rasters the Ignore Background Value must be set to the same value as NoData in order for the background value to be ignored. Enterprise and file geodatabase rasters will work without this extra step.

Double
NoData Value
(Optional)

All the pixels with the specified value will be set to NoData in the output raster dataset.

Double
Convert 1 bit data to 8 bit
(Optional)

Choose whether the input 1-bit raster dataset will be converted to an 8-bit raster dataset. In this conversion, the value 1 in the input raster dataset will be changed to 255 in the output raster dataset. This is useful when importing a 1-bit raster dataset to a geodatabase. One-bit raster datasets have 8-bit pyramid layers when stored in a file system, but in a geodatabase, 1-bit raster datasets can only have 1-bit pyramid layers, which makes the display unpleasant. By converting the data to 8 bit in a geodatabase, the pyramid layers are built as 8 bit instead of 1 bit, resulting in a proper raster dataset in the display.

  • Unchecked—No conversion will be done. This is the default.
  • Checked—The input raster will be converted.
Boolean
Mosaicking Tolerance
(Optional)

When mosaicking occurs, the target and the source pixels do not always line up exactly. When there is a misalignment of pixels, you need to decide whether to resample or shift the data. The mosaicking tolerance controls whether resampling of the pixels will occur or the pixels will be shifted.

If the difference in pixel alignment (of the incoming dataset and the target dataset) is greater than the tolerance, resampling will occur. If the difference in pixel alignment (of the incoming dataset and the target dataset) is less than the tolerance, resampling will not occur and a shift will be performed.

The unit of tolerance is a pixel with a valid value range of 0 to 0.5. A tolerance of 0.5 will guarantee a shift occurs. A tolerance of zero guarantees resampling will occur if there is a misalignment in pixels.

For example, the source and target pixels have a misalignment of 0.25. If the mosaicking tolerance is set to 0.2, resampling will occur since the pixel misalignment is greater than the tolerance. If the mosaicking tolerance is set to 0.3, the pixels will be shifted.

Double
Color Matching Method
(Optional)

The color matching method to apply to the rasters.

  • None —This option will not use the color matching operation when mosaicking your raster datasets.
  • Match statistics —This method will use descriptive statistics from the overlapping areas; the transformation will then be applied to the entire target dataset.
  • Match histogram —This method will match the histogram from the reference overlap area to the source overlap area; the transformation will then be applied to the entire target dataset.
  • Linear correlation —This method will match overlapping pixels and then interpolated the rest of the source dataset; pixels without a one-to-one relationship will use a weighted average.
String
Colormap to RGB
(Optional)

If the input raster dataset has a color map, the output raster dataset can be converted to a three-band output raster dataset. This is useful when mosaicking rasters with different color maps.

  • Unchecked—No conversion will occur. This is the default.
  • Checked—The input dataset will be converted.
Boolean

Derived Output

LabelExplanationData Type
Updated Target Raster Dataset

The updated raster dataset.

Raster Dataset

arcpy.management.WorkspaceToRasterDataset(in_workspace, in_raster_dataset, {include_subdirectories}, {mosaic_type}, {colormap}, {background_value}, {nodata_value}, {onebit_to_eightbit}, {mosaicking_tolerance}, {MatchingMethod}, {colormap_to_RGB})
NameExplanationData Type
in_workspace

The folder containing the raster datasets to merge.

Workspace
in_raster_dataset

An existing raster dataset in which to merge all of the raster datasets from the input workspace.

Raster Dataset
include_subdirectories
(Optional)

Specify whether to include subdirectories.

  • NONEDoes not include subdirectories. This is the default.
  • INCLUDE_SUBDIRECTORIESIncludes all the raster datasets in the subdirectories when loading.
Boolean
mosaic_type
(Optional)

Specifies the method that will be used to mosaic overlapping areas.

  • FIRSTThe output cell value of the overlapping areas will be the value from the first raster dataset mosaicked into that location.
  • LASTThe output cell value of the overlapping areas will be the value from the last raster dataset mosaicked into that location. This is the default.
  • BLENDThe output cell value of the overlapping areas will be a horizontally weighted calculation of the values of the cells in the overlapping area.
  • MEANThe output cell value of the overlapping areas will be the average value of the overlapping cells.
  • MINIMUMThe output cell value of the overlapping areas will be the minimum value of the overlapping cells.
  • MAXIMUMThe output cell value of the overlapping areas will be the maximum value of the overlapping cells.
  • SUMThe output cell value of the overlapping areas will be the total sum of the overlapping cells.
String
colormap
(Optional)

Specifies the method that will be used to choose which color map from the input rasters will be applied to the mosaic output.

  • FIRSTThe color map from the first raster dataset in the list will be applied to the output raster mosaic. This is the default.
  • LASTThe color map from the last raster dataset in the list will be applied to the output raster mosaic.
  • MATCHAll the color maps will be considered when mosaicking. If all possible values are already used (for the bit depth), the tool will match the value with the closest available color.
  • REJECTOnly the raster datasets that do not have a color map associated with them will be mosaicked.
String
background_value
(Optional)

Use this option to remove the unwanted values created around the raster data. The value specified will be distinguished from other valuable data in the raster dataset. For example, a value of zero along the raster dataset's borders will be distinguished from zero values in the raster dataset.

The pixel value specified will be set to NoData in the output raster dataset.

For file-based rasters the Ignore Background Value must be set to the same value as NoData in order for the background value to be ignored. Enterprise and file geodatabase rasters will work without this extra step.

Double
nodata_value
(Optional)

All the pixels with the specified value will be set to NoData in the output raster dataset.

Double
onebit_to_eightbit
(Optional)

Choose whether the input 1-bit raster dataset will be converted to an 8-bit raster dataset. In this conversion, the value 1 in the input raster dataset will be changed to 255 in the output raster dataset. This is useful when importing a 1-bit raster dataset to a geodatabase. One-bit raster datasets have 8-bit pyramid layers when stored in a file system, but in a geodatabase, 1-bit raster datasets can only have 1-bit pyramid layers, which makes the display unpleasant. By converting the data to 8 bit in a geodatabase, the pyramid layers are built as 8 bit instead of 1 bit, resulting in a proper raster dataset in the display.

  • NONENo conversion will be done. This is the default.
  • OneBitTo8BitThe input raster will be converted.
Boolean
mosaicking_tolerance
(Optional)

When mosaicking occurs, the target and the source pixels do not always line up exactly. When there is a misalignment of pixels, you need to decide whether to resample or shift the data. The mosaicking tolerance controls whether resampling of the pixels will occur or the pixels will be shifted.

If the difference in pixel alignment (of the incoming dataset and the target dataset) is greater than the tolerance, resampling will occur. If the difference in pixel alignment (of the incoming dataset and the target dataset) is less than the tolerance, resampling will not occur and a shift will be performed.

The unit of tolerance is a pixel with a valid value range of 0 to 0.5. A tolerance of 0.5 will guarantee a shift occurs. A tolerance of zero guarantees resampling will occur if there is a misalignment in pixels.

For example, the source and target pixels have a misalignment of 0.25. If the mosaicking tolerance is set to 0.2, resampling will occur since the pixel misalignment is greater than the tolerance. If the mosaicking tolerance is set to 0.3, the pixels will be shifted.

Double
MatchingMethod
(Optional)

The color matching method to apply to the rasters.

  • NONEThis option will not use the color matching operation when mosaicking your raster datasets.
  • STATISTIC_MATCHINGThis method will use descriptive statistics from the overlapping areas; the transformation will then be applied to the entire target dataset.
  • HISTOGRAM_MATCHINGThis method will match the histogram from the reference overlap area to the source overlap area; the transformation will then be applied to the entire target dataset.
  • LINEARCORRELATION_MATCHINGThis method will match overlapping pixels and then interpolated the rest of the source dataset; pixels without a one-to-one relationship will use a weighted average.
String
colormap_to_RGB
(Optional)

If the input raster dataset has a color map, the output raster dataset can be converted to a three-band output raster dataset. This is useful when mosaicking rasters with different color maps.

  • NONENo conversion will occur. This is the default.
  • ColormapToRGBThe input dataset will be converted.
Boolean

Derived Output

NameExplanationData Type
out_raster_dataset

The updated raster dataset.

Raster Dataset

Code sample

WorkspaceToRasterDataset example 1 (Python window)

This is a Python sample for the WorkspaceToRasterDataset tool.

import arcpy
arcpy.WorkspaceToRasterDataset_management("c:/data/WS2RD", "c:/fgdb.gdb/outdats",
                                          "INCLUDE_SUBDIRECTORIES", "LAST",
                                          "FIRST", "0", "9", "", "",
                                          "HISTOGRAM_MATCHING", "")
WorkspaceToRasterDataset example 2 (stand-alone script)

This is a Python script sample for the WorkspaceToRasterDataset tool.

##==================================
##Workspace To Raster Dataset
##Usage: WorkspaceToRasterDataset_management in_workspace in_raster_dataset {NONE | INCLUDE_SUBDIRECTORIES} 
##                                           {LAST | FIRST | BLEND | MEAN | MINIMUM | MAXIMUM} {FIRST | REJECT
##                                           | LAST | MATCH} {background_value} {nodata_value} {NONE | OneBitTo8Bit} 
##                                           {mosaicking_tolerance}  {NONE | STATISTIC_MATCHING | HISTOGRAM_MATCHING
##                                           | LINEARCORRELATION_MATCHING} {NONE | ColormapToRGB}

import arcpy
arcpy.env.workspace = r"\\MyMachine\PrjWorkspace\RasGP"
##Mosaic images to File Geodatabase Raster Dataset with Background and Nodata setting and Color Correction
arcpy.WorkspaceToRasterDataset_management("WS2RD", "fgdb.gdb\\dataset", "INCLUDE_SUBDIRECTORIES", "LAST", \
                                          "FIRST", "0", "9", "", "", "HISTOGRAM_MATCHING", "")

##Mosaic Colormap image to RGB image
arcpy.WorkspaceToRasterDataset_management("WS2RD_clr","fgdb.gdb\\dataset2", "INCLUDE_SUBDIRECTORIES", "LAST",\
                                          "FIRST", "", "", "", "0.3", "", "ColormapToRGB")

Environments

This tool does not use any geoprocessing environments.

Licensing information

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

Related topics