Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.

  >  Docs Center  >  Using ENVI  >  Landsat Time Series Tutorial


Landsat Time Series Tutorial

Landsat Time Series Tutorial

This tutorial shows how to construct a time series from nine Landsat images of Las Vegas, Nevada, each May from 1975 to 2014. You will learn how to use the Series Manager to animate the time series and to export the animation to video. The tutorial also includes code examples that show how to perform these tasks in batch mode using the ENVI application programming interface (API).

The estimated time to complete this tutorial is one hour. Use ENVI 5.2 or later.

Files Used in this Tutorial

Tutorial files are available from our website or on the ENVI Resource DVD in the LandsatCaseStudies\TimeSeries directory. Copy the files to a local drive.



LasVegasMay1975.dat (and .hdr)

Landsat-1 MSS image from May 1975, originally 80-meter spatial resolution, resampled by USGS to 57 meters, resampled in ENVI to 30 meters

LasVegasMay1980.dat (and .hdr)

Landsat-3 MSS image from May 1980, originally 60-meter resolution, resampled in ENVI to 30 meters

LasVegasMay1985.dat - LasVegasMay2005.dat (and .hdr)

Landsat-5 TM images, every five years from May 1985 to May 2005, 30 meter resolution

LasVegasMay2014.dat (and .hdr)

Landsat 8 OLI image from May 2014, 30 meter resolution

Landsat images were downloaded from the U.S. Geological Survey (USGS) EarthExplorer web site and pre-processed as follows:

  • Spatial subsetting to the same geographic extent
  • Radiometric correction to top-of-atmosphere (TOA) reflectance
  • Atmospheric correction using QUAC®
  • Creating a common spatial grid and reprojecting all images to it. Images downloaded from the USGS EarthExplorer website already are georeferenced to a UTM Zone 12N (WGS-84) coordinate system; however, instrument drift over the 40-year time period may cause a slight shift in pixel locations. A common spatial grid ensures that the same pixel across multiple images references the same geographic location over time. Reprojecting the two MSS images to the spatial grid (using a cubic convolution resampling) improved their spatial resolution from 60 to 30 meters.

See the ENVI API Code Examples section of this tutorial for an IDL program that was used to perform these steps in batch mode.

An additional step was to manually add acquisition time metadata to each ENVI header file using a text editor, for example:

    acquisition time = 1975-05-13T17:34:00.0

The acquisition time can be derived from the .met or *MTL.txt metadata files distributed with the original Landsat scenes.

The OSAVISeries directory contains a set of Optimized Soil Adjusted Vegetation Index (OSAVI) images for each Landsat image. These have the same spatial extent and acquisition times as the Landsat images.

Case Study: Las Vegas Growth

Las Vegas is one of the fastest growing metropolitan areas in the United States. According to the U.S. Census Bureau, the population of the Las Vegas-Henderson-Paradise, NV Metropolitan Statistical Area (MSA) in 1970 was 273,288 people. The population today is approximately 2 million people.

Remote sensing imagery can be used to monitor the expansion of urban areas over time. High spatial resolution images are preferred for studying different features within an urban area. Of particular interest is the increase in impervious surfaces over time (roads, buildings, parking lots, etc.) High-resolution imagery for an entire metropolitan area may be difficult to obtain and can consume a lot of disk space. Lower-resolution imagery such as the Landsat legacy products are freely available from the USGS and are often suitable for studying urban sprawl over a large spatial extent.

The following change detection image shows the difference in man-made features from 1980 to present. Normalized Difference Built-Up Index images were created from a 1980 Landsat TM image and a 2014 Landsat-8 image. The SPEAR Change Detection tool was used to create this image, which shows built-up features (in red) added since 1980.

Change detection can only provide a "before and after" scenario; a time-series analysis provides an opportunity to study patterns and key changes in urban growth over time. For this tutorial, you will evaluate Landsat images every five years over a 40-year period.

Build a Time Series

In these steps you will build a raster series, which is a collection of images (rasters) used for spatiotemporal analysis. These steps create a series file, which is a metadata file with a .series file extension. The series file does not contain any imagery; it only references the file locations of the source rasters.

If the ENVI header files associated with the source rasters contain an acquisition time metadata field, you have the option to order the series by time.

  1. Start ENVI.
  2. From the menu bar, select File > Preferences.
  3. Click the Data Manager item on the left side of the Preferences dialog.
  4. Click in the white space next to Auto Display Method for Multispectral Files, and select CIR from the drop-down list the appears. This will display all rasters within the series in a color-infrared RGB combination.
  5. Click OK in the Preferences dialog.
  6. From the menu bar, select File > New > Build Raster Series. The Select Rasters for the Raster Series dialog appears.
  7. Click the Add Raster button, then select Add By Filename.
  8. Navigate to the directory where you saved the tutorial data files.
  9. Use the Ctrl or Shift key on your keyboard to select the files LasVegasMay1975.dat through LasVegasMay2014.dat (9 files total). Click Open. The fiilenames appear in the file selection dialog.
  10. Enable the Order By Time option. This will order the rasters by the time listed in the acquisition time metadata field of each ENVI header file.
  11. Click the Browse button next to the Output Filename field, and navigate to the same directory where you saved the tutorial data files.
  12. Name the series file LasVegas. Click the Open button in the Select Output Filename dialog. ENVI automatically appends a .series extension to the filename.
  13. Enable the Display result option.
  14. Click OK when you are finished.

View a Time Series

Once ENVI creates the time series, the Series Manager appears in the display. Since the series is ordered by time, the image with the earliest time is displayed first (LasVegasMay1975.dat). The different components of the Series Manager are described as follows:

Each series is a unique layer in ENVI; it appears in the Layer Manager and is represented by a numbered icon here and in the Series Manager:

Any display operations such as zooming, rotating, or changing the stretch will apply to the entire series, not any specific image within the series.

The Series Manager also lists the current image layer within the series; in this case, LasVegasMay1975.dat. As you scroll through the time series using the navigation tools, the current layer name updates accordingly.

Follow these steps to step through the time series:

  1. Right-click on the series layer in the Layer Manager and select Zoom to Layer Extent.
  2. From the Stretch drop-down menu in the main toolbar, select Linear 1%.
  3. Click the Forward button or click and drag the wheel to step through the series one frame at a time. The associated image is displayed at each frame.
  4. Click and drag the slider needle to move to another point in the series, without updating each image. This allows for a quick selection of a particular frame since you can see the dates or band names in the series. The associated image will load once you release the mouse button.
  5. Click the Play forward button to animate the series. While the series is animating, choose a delay time in seconds (between frames) using the drop-down list next to the play button.
  6. When the series displays LasVegasMay2014.dat, click Pause to stop the animation.
  7. Click the Options drop-down button in the Series Manager, and select Load Current Raster. ENVI opens the associated image (LasVegasMay2014.dat) as a separate layer in the Layer Manager and Data Manager so that you can work with the image apart from the time series:
  8. Loading a currently displayed raster allows you to further explore an image of interest and to use any of ENVI's processing tools with the image, without affecting the series.

  9. Right-click on the LasVegasMay2014.dat layer in the Layer Manager and select Remove.

Multiple Layers

In these steps, you will view another series of Las Vegas images from 1975 to 2014 and link this series with the one you just viewed. These images represent an Optimized Soil Adjusted Vegetation Index (OSAVI) and were created using the ENVI Spectral Index tool. OSAVI is especially sensitive to vegetation cover greater than 50% and is best suited for areas with relatively sparse vegetation, where the soil is visible through the canopy.

Once the images were created, acquisition time metadata was manually added back to the respective ENVI header files.

  1. From the menu bar, select Views > Two Vertical Views.
  2. Click inside of the second view to select it. A cyan-colored border surrounds the empty view.
  3. From the menu bar, select File > Open.
  4. Navigate to the directory where you saved the OSAVI*.dat files.
  5. Select the file OSAVI.series, and click Open.
  6. The OSAVI series displays in the second view, and the Series Manager updates to show the OSAVI series. The Layer Manager lists each series in a separate View layer:

  7. Right-click on both series layer names in the Layer Manager and select Zoom to Layer Extent. The display should look similar to the following picture:
  8. From the Options menu of the Series Manager, select Show All Sliders. A new panel appears that allows you to navigate through the two series, independent of each other. The following shows an example:
  9. A more common scenario is to link the two series by time.

  10. Click the Options drop-down button in the Series Manager, and select Link To > [#/#] LasVegas<date>.dat (where # is the current frame number). This creates a temporal link between the two series.
  11. Use the navigation tools in the Series Manager to step through the time series. Since the images are linked by time, the Landsat image and its corresponding OSAVI image for the same date are displayed simultaneously.
  12. When you are finished examining the two series, right click on the View layer that contains the OSAVI series in the Layer Manager and select Remove View. Only the original Landsat series is displayed.

Annotate the Series

If the ENVI header files of each image in the series contain an acquisition time field, you can annotate the time series with the date and time of each frame. Before creating text annotations, you should set some annotation preferences.

  1. From the ENVI menu bar, select File > Preferences.
  2. Click the Text item under Annotations on the left side of the Preferences dialog.
  3. Update the text annotation preferences as follows:
    • Color: select white from the color grid
    • Font: Arial Narrow
    • Font Style: Bold
    • Font Size: 24
    • Fill Background: No
  4. Click OK in the Preferences dialog.
  5. Right-click on the series layer in the Layer Manager and select Zoom to Layer Extent.
  6. Click the Options drop-down in the Series Manager, and select Annotate > Date and Time. The date and time are added to the display.
  7. Click the annotation to select it, and drag it to the top of the image as follows:
  8. Use the navigation tools in the Series Manager to step through the series. The date/time annotation updates with each frame.
  9. Optional step: Right-click on the Series Metadata layer in the Layer Manager and select Save As. Enter an output fiilename and directory for the annotation file (.anz).

Create a Video File

  1. Click the Options drop-down button in the Series Manager, and select Save Video Animation.
  2. Click the Advanced button.
  3. In the Select format list, choose MP4 (MPEG-4 Part 14).
  4. In the Select codec list, choose [Default].
  5. Click the Browse button next to Video filename, and navigate to a directory where you want to save the video file.
  6. Enter an output filename of LasVegasSeriesVideo. Click Open.
  7. There are 9 frames in this series; 2 seconds is a reasonable time to view each frame. In the Save Video dialog, enter a Total time of 18 seconds.
  8. Click OK. ENVI steps through each frame in the series and creates the video file.
  9. If the saved video file does not play for any reason, try selecting a different format (for example, AVI).

  10. To learn more about working with series files and animating through image bands, click Help in the Series Manager menu bar and select Series/Animation Help.
  11. When you are finished, exit ENVI.

ENVI API Code Example

The following API code examples are also available from our website or on the ENVI Resource DVD in the LandsatCaseStudies\TimeSeries directory.


This program was used to pre-process the Landsat imagery in preparation for time-series analysis. It does not include the extra step of adding acquisition time to the ENVI header files at the end of the workflow; this step must be done manually. You can adapt this script for your own needs; be sure to change the disk name and directory in the File_Search line as needed.

PRO PreprocessLandsatSeries
  ; Start the application
  e = ENVI()
  ; Select input files. Select the *MTL.txt files for
  ; Landsat TM, -8, and some MSS images distributed
  ; by the USGS. For Landsat MSS images in .met format,
  ; change this line to search for '*.met' files.
  files = File_Search('C:\Data', '*MTL.txt')
  Foreach file, files DO BEGIN
    Raster = e.OpenRaster(file)
    VisNIRBands = Raster[0]
    ; This is the area of interest:
    UpperLeftLat = 36.4
    UpperLeftLon = -115.4
    LowerRightLat = 35.94
    LowerRightLon = -114.8
    ; Convert these coordinates from degrees to map 
    ; coordinates in meters. Then define a spatial subset 
    ; around the area of interest for the multispectral raster.
    SpatialRef = VisNIRBands.SpatialRef
    SpatialRef.ConvertLonLatToMap, UpperLeftLon, $
      UpperLeftLat, MapX, MapY
    SpatialRef.ConvertLonLatToMap, LowerRightLon, $
      LowerRightLat, MapX2, MapY2
    Subset = ENVISubsetRaster(VisNIRBands, $
      SPATIALREF=SpatialRef, $
      SUB_RECT=[MapX, MapY2, MapX2, MapY])
    ; Calibrate to top-of-atmosphere reflectance
    RCTask = ENVITask('RadiometricCalibration')
    RCTask.Input_Raster = Subset
    RCTask.Calibration_type = 'Top-of-Atmosphere Reflectance'
    RCTask.Output_Raster_URI = e.GetTemporaryFilename()
    ; Perform QUAC atmospheric correction
    QUACTask = ENVITask('QUAC')
    QUACTask.Input_Raster = RCTask.Output_Raster
    QUACTask.Sensor = 'Landsat TM/ETM/OLI'
    QUACTask.Output_Raster_URI = e.GetTemporaryFilename()
    ; Create a spatial grid definition
    ; Coordinate system: UTM Zone 11N, WGS-84
    ; Spatial extent:  35.94N to 36.4N, 114.8W to 115.4W
    ; Pixel size: 30 meters
    CoordSys = ENVICoordSys(COORD_SYS_CODE=32611)
    Grid = ENVIGridDefinition(CoordSys, $
      EXTENT=[MapX, MapY, MapX2, MapY2], $
      PIXEL_SIZE=[30.0D, 30.0D])
    ; Reproject each raster to the common spatial grid
    RegridTask = ENVITask('RegridRaster')
    RegridTask.Input_Raster = QUACTask.Output_Raster
    RegridTask.Grid_Definition = Grid
    RegridTask.Output_Raster_URI = e.GetTemporaryFilename()
    ReprojectedRaster = RegridTask.Output_Raster
    ; Get the year from the file name. For
    ; Landsat TM and -8 filenames, use this format:
    year = Fix(Strmid(File_BaseName(file), 9, 4))
    ; For Landsat MSS images with a .met metadata file:
    ; year = Fix(Strmid(File_BaseName(file), 10, 4))
    ; Export the reprojected raster to disk in the
    ; system's temporary directory 
    outFile = Filepath('LasVegasMay'+StrTrim(year,2)+'.dat',/TMP)
    ReprojectedRaster.Export, outFile, 'ENVI'

Build and Animate a Time Series

Once the images have been pre-processed and saved to ENVI format (from the first code example), use the following program to build a time series and to animate the series. The ENVI API does not currently support annotations, so this video only shows the images in the time series.

PRO BuildAnimateTimeSeries
  ; Start the application
  e = ENVI()
  ; Select input files
  files = File_Search('C:\Data\', 'LasVegasMay*.dat')
  numRasters = N_Elements(files)
  rasters = ObjArr(numRasters)
  FOR i=0, (numRasters-1) DO $
    rasters[i] = e.OpenRaster(files[i])
  ; Build a time series
  Task = ENVITask('BuildTimeSeries')
  Task.Input_Rasters = rasters
  Task.Output_Rasterseries_URI = e.GetTemporaryFilename('series')
  Series = Task.Output_RasterSeries
  ; Create a time series layer
  View = e.GetView()
  Layer = View.CreateLayer(Series)
  View.Zoom, /FULL_EXTENT
  ; Animate the series and export a video file
  VideoFile = e.GetTemporaryFilename('mp4')
  View.ChipToVideo, VideoFile, 'mp4', $

© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us