Summary
Saves a copy of a raster dataset or converts a mosaic dataset into a single raster dataset.
Usage
You can save your output to BIL, BIP, BMP, BSQ, CRF, DAT, Esri Grid, GIF, IMG, JPEG, JPEG 2000, MRF, PNG, TIFF, or any geodatabase raster dataset.
When storing a raster dataset in a geodatabase, no file extension should be added to the name of the raster dataset. When storing the raster dataset in a file format, you need to specify the file extension:
- .bil for Esri BIL
- .bip for Esri BIP
- .bmp for BMP
- .bsq for Esri BSQ
- .dat for ENVI DAT
- .gif for GIF
- .img for ERDAS IMAGINE
- .jpg for JPEG
- .jp2 for JPEG 2000
- .png for PNG
- .tif for TIFF
- .mrf for MRF
- .crf for CRF
- No extension for Esri Grid
This tool can be used to scale the pixel type from one bit depth to another. When you scale the pixel depth, your raster will display the same, but the values will be scaled to the new bit depth that was specified.
The output of this tool is always a raster dataset. This tool will accept a mosaic dataset as the input, but the output will be a raster dataset—the contents of the mosaic dataset will be mosaicked to create a raster dataset.
If you checked Use world file to define the coordinates of the raster in Options, a world file will be written out. If a world file exists, it will be overwritten. There may also be a half-pixel shift in the output spatial reference.
For file-based rasters, Ignore Background Value must be set to the same value as NoData for the background value to be ignored. File geodatabase rasters and enterprise geodatabase rasters will work without this extra step.
When storing your raster dataset to a JPEG file, a JPEG 2000 file, or a geodatabase, you can specify a Compression Type and Compression Quality in the Environments.
The GIF format only supports single-band raster datasets.
The Pixel Type parameter determines the bit depth of the output raster dataset. Rescaling of the raster values occurs when a different pixel type is chosen. If the pixel type is demoted (lowered), the raster values outside the valid range for that pixel depth will be truncated and lost. To learn about the bit depth capacity for supported export formats, see List of supported sensors.
The Build Multidimensional Transpose parameter is for data access optimization. By default, a CRF file stores each multidimensional slice in a separate folder and each slice is chunked into tiles. When you perform a transpose, the data will be chunked along dimensions rather than by slice and tile, making analysis such as temporal profiling faster and easier.
When you specify an extent outside the boundaries of the raster dataset, the area not containing data is filled with NoData values.
Syntax
arcpy.management.CopyRaster(in_raster, out_rasterdataset, {config_keyword}, {background_value}, {nodata_value}, {onebit_to_eightbit}, {colormap_to_RGB}, {pixel_type}, {scale_pixel_value}, {RGB_to_Colormap}, {format}, {transform}, {process_as_multidimensional}, {build_multidimensional_transpose})| Parameter | Explanation | Data Type |
in_raster | The raster dataset or mosaic dataset to be copied. | Raster Dataset; Mosaic Dataset; Mosaic Layer; Raster Layer; File; Image Service |
out_rasterdataset | The name and format for the raster dataset being created.
When storing a raster dataset in a geodatabase, do not add a file extension to the name of the raster dataset. When storing a raster dataset to a JPEG file, JPEG 2000 file, TIFF file, or geodatabase, you can specify a compression type and compression quality. | Raster Dataset |
config_keyword (Optional) | Specifies the storage parameters (configuration) for a geodatabase. Configuration keywords are set up by your database administrator. | String |
background_value (Optional) | 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, Ignore Background Value must be set to the same value as NoData for the background value to be ignored. Enterprise and 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. | String |
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.
| Boolean |
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.
| Boolean |
pixel_type (Optional) | Specifies the bit depth, or radiometric resolution, to use for the raster or mosaic dataset. If not defined, the value will be taken from the first raster dataset.
| String |
scale_pixel_value (Optional) | Specifies whether pixel values will be scaled. When the output is a pixel type other than the input (such as 16 bit to 8 bit), you can scale the values to fit into the new range; otherwise, the values that do not fit into the new pixel range will be discarded. If scaling up, such as 8 bit to 16 bit, the minimum and maximum of the 8-bit values will be scaled to the minimum and maximum in the 16-bit range. If scaling down, such as 16 bit to 8 bit, the minimum and maximum of the 16-bit values will be scaled to the minimum and maximum in the 8-bit range.
| Boolean |
RGB_to_Colormap (Optional) | Specifies whether an 8-bit, 3-band (RGB) raster dataset will be converted to a single-band raster dataset with a color map. This operation suppresses noise that is often found in scanned images and is ideal for screen captures, scanned maps, or scanned documents. This is not recommended for satellite or aerial imagery or thematic raster data.
| Boolean |
format (Optional) | Specifies the output raster format.
| String |
transform (Optional) | Specifies whether a transformation associated with the input raster will be applied to the output. The input raster can have a transformation associated with it that is not saved in the input, such as a world file or a geometric function.
| Boolean |
process_as_multidimensional (Optional) | Specifies whether to process the input mosaic dataset as a multidimensional raster dataset.
| Boolean |
build_multidimensional_transpose (Optional) | Specifies whether to build the transpose for the input multidimensional raster dataset, which will chunk the data along each dimension to optimize performance when accessing pixel values across all slices.
| Boolean |
Code sample
This is a Python sample for the CopyRaster tool.
##====================================
##Copy Raster
##Usage: CopyRaster_management(
## in_raster, out_rasterdataset, {config_keyword}, {background_value},
## {nodata_value}, {NONE | OneBitTo8Bit}, {NONE | ColormapToRGB},
## {1_BIT | 2_BIT | 4_BIT | 8_BIT_UNSIGNED | 8_BIT_SIGNED | 16_BIT_UNSIGNED |
## 16_BIT_SIGNED | 32_BIT_UNSIGNED | 32_BIT_SIGNED | 32_BIT_FLOAT | 64_BIT},
## {NONE | ScalePixelValue}, {NONE | RGBToColormap}, {TIFF | IMAGINE Image |
## BMP | GIF | PNG | JPEG | JPEG2000 | Esri Grid | Esri BIL | Esri BSQ |
## Esri BIP | ENVI | CRF | MRF}, {NONE | Transform}, {CURRENT_SLICE | ALL_SLICES}, {NO_TRANSPOSE | TRANSPOSE})
try:
import arcpy
arcpy.env.workspace = r"C:\PrjWorkspace"
##Copy Multidimensional Raster Dataset to a new multidimensional dataset in Cloud raster format and with transpose for faster data access
arcpy.CopyRaster_management('SeaSurfaceTemp.nc',"https://s3.amazonaws.com/S3Storage/seasurfacetemp","","","","","","","","", format = "CRF",'NONE',process_as_multidimensional = 'ALL_SLICES', build_multidimensional_transpose='TRANSPOSE')
##Copy 1 BIT
arcpy.CopyRaster_management("1bit.tif","SDE94.sde\\bit8","DEFAULTS","","","OneBitTo8Bit","","")
##Copy File RasterDataset to GDB Dataset with Background and Nodata setting
arcpy.CopyRaster_management("background.tif","CpRaster.gdb\\background","DEFAULTS","0","9","","","8_BIT_UNSIGNED")
except:
print "Copy Raster example failed."
print arcpy.GetMessages()This is a Python script sample for the CopyRaster tool.
##====================================
##Usage: CopyRaster_management(
## in_raster, out_rasterdataset, {config_keyword}, {background_value},
## {nodata_value}, {NONE | OneBitTo8Bit}, {NONE | ColormapToRGB},
## {1_BIT | 2_BIT | 4_BIT | 8_BIT_UNSIGNED | 8_BIT_SIGNED | 16_BIT_UNSIGNED |
## 16_BIT_SIGNED | 32_BIT_UNSIGNED | 32_BIT_SIGNED | 32_BIT_FLOAT | 64_BIT},
## {NONE | ScalePixelValue}, {NONE | RGBToColormap}, {TIFF | IMAGINE Image |
## BMP | GIF | PNG | JPEG | JPEG2000 | Esri Grid | Esri BIL | Esri BSQ |
## Esri BIP | ENVI | CRF | MRF}, {NONE | Transform}, {CURRENT_SLICE | ALL_SLICES}, {NO_TRANSPOSE | TRANSPOSE})
import arcpy
arcpy.env.workspace = r"C:\PrjWorkspace"
##Copy to new multidimensional dataset in cloud raster format and with transpose for faster data access
arcpy.CopyRaster_management(
"SeaSurfaceTemp.nc", "SST_Transpose.crf","","",-3.402823e+38,"NONE","NONE","","NONE","NONE", "CRF", "NONE", "ALL_SLICES", "TRANSPOSE")Environments
Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes