Hillshade

Summary

Creates a raster object of a grayscale 3D representation of a surface by considering the illumination source location and shadows.

Discussion

For more information about how this function works, see the Hillshade raster function.

The referenced raster dataset for the raster object is temporary. To make it permanent, you can call the raster object's save method.

Syntax

Hillshade (dem, {azimuth}, {altitude}, {z_factor}, {slope_type}, {ps_power}, {psz_factor}, {remove_edge_effect}, {hillshade_type})
ParameterExplanationData Type
dem

The input elevation raster.

Raster
azimuth

Azimuth is the sun's relative position along the horizon (in degrees). This position is indicated by the angle of the sun measured clockwise from due north. An azimuth of 0 degrees indicates north, east is 90 degrees, south is 180 degrees, and west is 270 degrees.

This parameter is only valid when the hillshade_type argument is set to TRADITIONAL. The default is 315 degrees, which is from the northwest.

(The default value is 315)

Double
altitude

Altitude is the sun's angle of elevation above the horizon and ranges from 0 to 90 degrees. A value of 0 degrees indicates that the sun is on the horizon, that is, on the same horizontal plane as the frame of reference. A value of 90 degrees indicates that the sun is directly overhead.

This parameter is only valid when the hillshade_type argument is set to TRADITIONAL.

(The default value is 45)

Double
z_factor

The z-factor is a scaling factor used to convert the elevation values for two purposes:

  • To convert the elevation units (such as meters or feet) to the horizontal coordinate units of the dataset, which may be feet, meters, or degrees.
  • To add vertical exaggeration for visual effect.

If the x,y units and z units are in the same units of measure, the z-factor should be set to 1. The z-values of the input surface are multiplied by the z-factor when calculating the final output surface.

(The default value is 1)

Double
slope_type

The inclination of slope can be output as either a value in degrees, or percent rise. Specify one of the following: DEGREE, PERCENTRISE, or SCALED. For more information, see Slope function.

Integer
ps_power

Pixel Size Power accounts for the altitude changes (or scale) as the viewer zooms in and out on the map display. It is the exponent applied to the pixel size term in the equation that controls the rate at which the z-factor changes to avoid significant loss of relief.

This parameter is only valid when the slope_type is SCALED.

(The default value is 0.664)

Double
psz_factor

Pixel Size Factor accounts for changes in scale as the viewer zooms in and out on the map display. It controls the rate at which the z-factor changes.

This parameter is only valid when the slope_type is SCALED.

(The default value is 0.024)

Double
remove_edge_effect

Using this option will avoid any resampling artifacts that may occur along the edges of a raster. The output pixels along the edge of a raster or beside pixels without a value will be populated with NoData; therefore, it is recommended that this option be used only when there are other rasters with overlapping pixels available. When overlapping pixels are available, these areas of NoData will display the overlapping pixel values instead of being blank.

  • False—Bilinear resampling will be applied uniformly to resample the output.
  • True—Bilinear resampling will be used to resample the output, except along the edges of the rasters or beside pixels of NoData. These pixels will be populated with NoData. This will reduce any sharp edge effects that might otherwise occur.

(The default value is False)

Boolean
hillshade_type

Controls the illumination source for the hillshade.

  • 0Calculates hillshade from a single illumination direction. You can set the azimuth and altitude arguments to control the location of the light source.
  • 1Combines light from multiple sources to represent an enhanced visualization of the terrain.

(The default value is 0)

Integer
Return Value
Data TypeExplanation
Raster

The output raster.

Code sample

Hillshade example 1

This example calculates the hillshade for a given elevation.

from arcpy.ia import *
out_hillshade_raster = Hillshade("elevation.tif", 180, 75, 0.3048)
out_hillshade_raster.save("C:/arcpyExamples/outputs/hillshade.tif")
Hillshade example 2

This example calculates the hillshade for a given elevation.

# Import the system modules
import arcpy
from arcpy.ia import *

# Set the analysis environments
arcpy.env.workspace = "C:/arcpyExamples/data"

# Set the local variables
in_dem = "elevation.tif"

# Execute the Hillshade function
out_hillshade_raster = Hillshade(in_dem, 180, 75, 0.3048)

# Save the output
out_hillshade_raster.save("C:/arcpyExamples/outputs/hillshade.tif")