Back to Top

Copy Raster (Data Management)

In this topic

  1. Summary
  2. Usage
  3. Parameters
  4. Environments
  5. Licensing information

Summary

Saves a copy of a raster dataset or converts a mosaic dataset into a single raster dataset.

Usage

  • You can save the output to BIL, BIP, BMP, BSQ, COG, CRF, ENVI DAT, ERDAS IMAGINE, GIF, JPEG, JPEG 2000, MRF, NetCDF, PNG, TIFF, or Esri Grid format or to any geodatabase raster dataset.

  • When storing a raster dataset in a geodatabase, do not add a file extension to the name of the raster dataset. When storing the raster dataset in a file format, specify the file extension as follows:

    • .bil for Esri BIL
    • .bip for Esri BIP
    • .bmp for BMP
    • .bsq for Esri BSQ
    • .crf for CRF
    • .dat for ENVI DAT
    • .img for ERDAS IMAGINE
    • .gif for GIF
    • .jpg for JPEG
    • .jp2 for JPEG 2000
    • .mrf for MRF
    • .nc for NetCDF
    • .png for PNG
    • .tif for TIFF and Cloud Optimized GeoTIFF
    • .zarr for Zarr
    • 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, the 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 check Use world file to define the coordinates of the raster in the Raster and Imagery 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, the Ignore Background Value parameter must be set to the same value as the NoData Value parameter for the background value to be ignored. File geodatabase rasters and enterprise geodatabase rasters will work without this extra step.

  • When storing a raster dataset to a JPEG format file, a JPEG 2000 format file, or a geodatabase, you can specify a Compression Type value and a Compression Quality value in the geoprocessing 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 creation of a Cloud Optimized GeoTIFF (COG) format file from any raster by the tool is a two step process as it involves the proper ordering of the GeoTIFF internal structure with COG specifications. The first step is to generate a temporary GeoTIFF format file from the input raster with pyramids, statistics, and other metadata. This temporary GeoTIFF format file is then copied to generate a COG format file.

    The disk requirements for COG format generation will be at least twice the space of the source image, which also depends on the compression of the input raster and the output COG format file.

  • The type of NetCDF format supported for output follows the NetCDF Climate and Forecast (CF) metadata conventions.

  • NetCDF format only supports single-band data. For multidimensional and multiband data, such as satellite data, the first band will be used.

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

  • When you specify an extent outside the boundaries of the raster dataset, the area that does not contain data is filled with NoData values.

Parameters

DialogPython

LabelExplanationData Type
Input Raster

The raster dataset or mosaic dataset to be copied.

Raster Dataset; Mosaic Dataset; Mosaic Layer; Raster Layer; File; Image Service
Output Raster Dataset

The name and format for the raster dataset being created.

  • .bil—Esri BIL
  • .bip—Esri BIP
  • .bmp—BMP
  • .bsq—Esri BSQ
  • .crf—CRF
  • .dat—ENVI DAT
  • .img—ERDAS IMAGINE
  • .gif—GIF
  • .jpg—JPEG
  • .jp2—JPEG 2000
  • .mrf—MRF
  • .nc—NetCDF
  • .png—PNG
  • .tif—TIFF and Cloud Optimized GeoTIFF
  • .zarr—Zarr
  • No extension for Esri Grid

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 JPEG, JPEG 2000, or TIFF format, or to a geodatabase, you can specify a compression type and compression quality.

Raster Dataset
Configuration Keyword
(Optional)

The storage parameters (configuration) for a geodatabase. Configuration keywords are set up by your database administrator.

String
Ignore 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 Value 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
Convert 1 bit data to 8 bit
(Optional)

Specifies 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 results in a lower-quality display. 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 occur. This is the default.
  • Checked—The input raster will be converted.
Boolean
Colormap to RGB
(Optional)

Specifies whether the input raster dataset will be converted to a three-band output raster dataset if the input raster dataset includes a color map. 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
Pixel Type
(Optional)

Specifies the bit depth, or radiometric resolution, that will be used for the raster or mosaic dataset. If not defined, the value from the first raster dataset will be used.

  • 1 bit—The pixel type will be a 1-bit unsigned integer. The values can be 0 or 1.
  • 2 bit—The pixel type will be a 2-bit unsigned integer. The values supported can range from 0 to 3.
  • 4 bit—The pixel type will be a 4-bit unsigned integer. The values supported can range from 0 to 15.
  • 8 bit unsigned—The pixel type will be an unsigned 8-bit data type. The values supported can range from 0 to 255.
  • 8 bit signed—The pixel type will be a signed 8-bit data type. The values supported can range from -128 to 127.
  • 16 bit unsigned—The pixel type will be a 16-bit unsigned data type. The values can range from 0 to 65,535.
  • 16 bit signed—The pixel type will be a 16-bit signed data type. The values can range from -32,768 to 32,767.
  • 32 bit unsigned—The pixel type will be a 32-bit unsigned data type. The values can range from 0 to 4,294,967,295.
  • 32 bit signed—The pixel type will be a 32-bit signed data type. The values can range from -2,147,483,648 to 2,147,483,647.
  • 32 bit float—The pixel type will be a 32-bit data type supporting decimals.
  • 64 bit—The pixel type will be a 64-bit data type supporting decimals.
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.

  • Unchecked—The pixel values will remain the same and will not be scaled. Any values that do not fit within the value range will be discarded. This is the default.
  • Checked—The pixel values will be scaled to the new pixel type. When you scale the pixel depth, the raster will display the same, but the values will be scaled to the new bit depth that was specified.
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.

  • Unchecked—The RGB raster dataset will not be converted.
  • Checked—The RGB raster dataset will be converted to a color map.
Boolean
Format
(Optional)

Specifies the output raster format.

  • TIFF format—The output format will be TIFF.
  • Cloud Optimized GeoTIFF—The output format will be Cloud Optimized GeoTIFF.
  • ERDAS IMAGINE format—The output format will be ERDAS IMAGINE.
  • BMP format—The output format will be BMP.
  • GIF format—The output format will be GIF.
  • PNG format—The output format will be PNG.
  • JPEG format—The output format will be JPEG.
  • JPEG 2000 format—The output format will be JPEG 2000.
  • Esri Grid format—The output format will be Esri Grid.
  • Esri BIL format—The output format will be Esri BIL.
  • Esri BSQ format—The output format will be Esri BSQ.
  • Esri BIP format—The output format will be Esri BIP.
  • ENVI DAT format—The output format will be ENVI DAT.
  • Cloud raster format—The output format will be CRF.
  • Meta raster format—The output format will be MRF.
  • NetCDF format—The output format will be NetCDF.
  • Zarr format—The output format will be Zarr.
String
Apply Transformation
(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.

  • Unchecked—No associated transformation will be applied to the output.
  • Checked—Any associated transformation will be applied to the output.

  • Do not apply transformation—No associated transformation will be applied to the output.
  • Apply transformation—Any associated transformation will be applied to the output.
Boolean
Process as Multidimensional
(Optional)

Specifies whether the input mosaic dataset will be processed as a multidimensional raster dataset.

  • Unchecked—The input will not be processed as a multidimensional raster dataset. If the input is multidimensional, only the slice that is currently displayed will be processed. This is the default.
  • Checked—The input will be processed as a multidimensional raster dataset and all slices will be processed to produce a new multidimensional raster dataset. Set the Format parameter to Cloud raster format to use this option.
Boolean
Build Multidimensional Transpose
(Optional)

Specifies whether the transpose for the input multidimensional raster dataset will be built to optimize data access. The transpose will chunk the multidimensional data along each dimension to optimize performance when accessing pixel values across all slices.

  • Unchecked—No transpose will be built. This is the default.
  • Checked—The input multidimensional raster dataset will be transposed. The Process as multidimensional parameter must be checked to use this option.
Boolean

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})
NameExplanationData 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.

  • .bil—Esri BIL
  • .bip—Esri BIP
  • .bmp—BMP
  • .bsq—Esri BSQ
  • .crf—CRF
  • .dat—ENVI DAT
  • .img—ERDAS IMAGINE
  • .gif—GIF
  • .jpg—JPEG
  • .jp2—JPEG 2000
  • .mrf—MRF
  • .nc—NetCDF
  • .png—PNG
  • .tif—TIFF and Cloud Optimized GeoTIFF
  • .zarr—Zarr
  • No extension for Esri Grid

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 JPEG, JPEG 2000, or TIFF format, or to a geodatabase, you can specify a compression type and compression quality.

Raster Dataset
config_keyword
(Optional)

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 Value 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)

Specifies 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 results in a lower-quality display. 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.

  • NONE—No conversion will occur. This is the default.
  • OneBitTo8Bit—The input raster will be converted.
Boolean
colormap_to_RGB
(Optional)

Specifies whether the input raster dataset will be converted to a three-band output raster dataset if the input raster dataset includes a color map. This is useful when mosaicking rasters with different color maps.

  • NONE—No conversion will occur. This is the default.
  • ColormapToRGB—The input dataset will be converted.
Boolean
pixel_type
(Optional)

Specifies the bit depth, or radiometric resolution, that will be used for the raster or mosaic dataset. If not defined, the value from the first raster dataset will be used.

  • 1_BIT—The pixel type will be a 1-bit unsigned integer. The values can be 0 or 1.
  • 2_BIT—The pixel type will be a 2-bit unsigned integer. The values supported can range from 0 to 3.
  • 4_BIT—The pixel type will be a 4-bit unsigned integer. The values supported can range from 0 to 15.
  • 8_BIT_UNSIGNED—The pixel type will be an unsigned 8-bit data type. The values supported can range from 0 to 255.
  • 8_BIT_SIGNED—The pixel type will be a signed 8-bit data type. The values supported can range from -128 to 127.
  • 16_BIT_UNSIGNED—The pixel type will be a 16-bit unsigned data type. The values can range from 0 to 65,535.
  • 16_BIT_SIGNED—The pixel type will be a 16-bit signed data type. The values can range from -32,768 to 32,767.
  • 32_BIT_UNSIGNED—The pixel type will be a 32-bit unsigned data type. The values can range from 0 to 4,294,967,295.
  • 32_BIT_SIGNED—The pixel type will be a 32-bit signed data type. The values can range from -2,147,483,648 to 2,147,483,647.
  • 32_BIT_FLOAT—The pixel type will be a 32-bit data type supporting decimals.
  • 64_BIT—The pixel type will be a 64-bit data type supporting decimals.
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.

  • NONE—The pixel values will remain the same and will not be scaled. Any values that do not fit within the value range will be discarded. This is the default.
  • ScalePixelValue—The pixel values will be scaled to the new pixel type. When you scale the pixel depth, the raster will display the same, but the values will be scaled to the new bit depth that was specified.
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.

  • NONE—The RGB raster dataset will not be converted.
  • RGBToColormap—The RGB raster dataset will be converted to a color map.
Boolean
format
(Optional)

Specifies the output raster format.

  • TIFF—The output format will be TIFF.
  • COG—The output format will be Cloud Optimized GeoTIFF.
  • IMAGINE Image—The output format will be ERDAS IMAGINE.
  • BMP—The output format will be BMP.
  • GIF—The output format will be GIF.
  • PNG—The output format will be PNG.
  • JPEG—The output format will be JPEG.
  • JP2—The output format will be JPEG 2000.
  • GRID—The output format will be Esri Grid.
  • BIL—The output format will be Esri BIL.
  • BSQ—The output format will be Esri BSQ.
  • BIP—The output format will be Esri BIP.
  • ENVI—The output format will be ENVI DAT.
  • CRF—The output format will be CRF.
  • MRF—The output format will be MRF.
  • NetCDF—The output format will be NetCDF.
  • ZARR—The output format will be Zarr.
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.

  • NONE—No associated transformation will be applied to the output.
  • Transform—Any associated transformation will be applied to the output.
Boolean
process_as_multidimensional
(Optional)

Specifies whether the input mosaic dataset will be processed as a multidimensional raster dataset.

  • CURRENT_SLICE—The input will not be processed as a multidimensional raster dataset. If the input is multidimensional, only the slice that is currently displayed will be processed. This is the default.
  • ALL_SLICES—The input will be processed as a multidimensional raster dataset and all slices will be processed to produce a new multidimensional raster dataset. Set the format parameter to CRF to use this option.
Boolean
build_multidimensional_transpose
(Optional)

Specifies whether the transpose for the input multidimensional raster dataset will be built, which will chunk the data along each dimension to optimize performance when accessing pixel values across all slices.

  • NO_TRANSPOSE—No transpose will be built. This is the default.
  • TRANSPOSE—The input multidimensional raster dataset will be transposed. The process_as_multidimensional parameter must be set to ALL_SLICES to use this option.
Boolean

Code sample

CopyRaster example 1 (Python window)

This is a Python sample for the CopyRaster function.

##====================================
##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()
CopyRaster example 2 (stand-alone script)

This is a Python script sample for the CopyRaster function.

##====================================
##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

Cell Alignment, Cell Size, Compression, Current Workspace, Extent, Geographic Transformations, NoData, Output CONFIG Keyword, Output Coordinate System, Parallel Processing Factor, Pyramid, Raster Statistics, Resampling Method, Scratch Workspace, Snap Raster, Tile Size

Licensing information

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

Related topics

  • An overview of the Raster toolset
  • Find a geoprocessing tool

Feedback on this topic?

In this topic
  1. Summary
  2. Usage
  3. Parameters
  4. Environments
  5. Licensing information