landsat documentation

This function searches the USGS website for low-resolution Landsat 8 images of specified path and row number and plots the most recent image in georeferenced coordinates.



[I,ImageDate,R,h] = landsat(...)


landsat(WRS2path,WRS2row) plots the most recent available Landsat 8 image for World Reference System 2 (WRS2) path/row combination given by WRS2path, WRS2row.

landsat(...,ImageDate) specifies a search date to start from. By default, ImageDate is the current date, and the landsat function searches each day going back in time until a valid image is found. If you know an exact image date, enter that date instead as a string (e.g., 'January 5, 2014' or in Matlab's datenum format. If you enter an ImageDate as 'January 5, 2014', landsat will look for an image on that date, if no images exist on Jan. 5, it will look on Jan. 4, then Jan. 3, and so on until a valid image is found. Alternatively, if ImageDate is a negative scalar integer N, searching will begin with today, and skip or ignore the most recent N valid images.

I = landsat(...,'nomap') returns the Landsat 8 image I and the 'nomap' command specifies that no map will be created. If you do not have a license for Matlab's Mapping Toolbox, specify 'nomap'. You won't be able to make maps or get georeferencing information, but at least you'll get an image.

[I,ImageDate,R,h] = landsat(...) also returns a georeferencing matrix R, a handle h of plotted image, and the ImageDate in datenum format.

How this function works

This function requires an internet connection. Starting with any specified date, or the current date if no date is specified, landsat searches back through time, attempting to access Landsat 8 images on the USGS website. When an image is found, landsat will attempt to georeference and plot it.

Georeferencing by this function may not always be perfect, and images plotted by this function are of rather low resolution, so if accuracy or precision are important for your work, consider using Level 1 GeoTiff data instead.

Currently, this function only attempts to access Landsat 8 data. Functionality may be extended to other Landsat missions in the future. May not.

Paths and Rows

The only two required inputs for the landsat function are the WRS2row and WRS2path. If you know the lat/lon coordinates of your area of interest, you can get path and row information here. For an acquisition calendar, look here.

Example 1: Sunny California

Let's take a look at sunny San Francisco, which from the path/row tool know is path 44, row 34. To map the most recent Landsat 8 image, of path 44, row 34, syntax is simple:

Image taken 29-Nov-2014

Whoa, that's not sunny at all! That's about as cloudy as cloudy gets. Today, as I'm writing this documention it's December 11, 2014. As the command line message indicates, the most recent available image is that one from November 29, 2014. Let's look farther back in time; we'll look for the image before November 29th. First we'll clear the current map with cla:

Image taken 13-Nov-2014

It was also cloudy on November 13th near San Francisco, can you believe it? Let's keep searching back in time:

Image taken 28-Oct-2014

Ah, that's what I was hoping for. Sunny as can be on October 28, 2014. If you're following along with this example someday in the future, landsat(44,34,-2) will not always refer to October 28th. To ensure an image from October 28, 2014 every time, state it clearly:

landsat(44,34,'October 28, 2014')

Similarly, landsat(44,34,'October 30, 2014') would provide the same result as above because landsat always searches backward through time starting at the specified date. And just for fun we can add Matlab's built-in (rather low resolution) coast line in blue. We can also add a scalebar for reference.

c = load('coast.mat');

Example 2: No Mapping Toolbox

Most of what this function does relies on some tools in the Mapping Toolbox. If you don't have the toolbox, or if you simply do not want to plot images on a map, you can get non-georeferenced images with the 'nomap' option. Here we get an image of the Massachusetts coast and show it non-georeferenced:

close all % clears the figure created above
[I,imdate] = landsat(12,31,'10-Dec-2014','nomap');
axis image
Image taken 29-Nov-2014

Above, I tried to get an image from December 10th, but the satellite didn't fly path 12 that day. As the command window message indicates, the image was taken on

ans =

That image can be found on the USGS site here and the associated metadata file is here.

Example 3: Antarctica

For images around Antarctica, polar stereographic projections provide less distortion than a typical world map projection. If you have a figure window open and the current axes were created with Antarctic Mapping Tools, it's easy to overlay Landsat 8 images. Below we open a 400-km-wide MODIS Mosaic of Antarctica image centered on Pine Island Glacier, overlay the most recent Landsat 8 image from path 233, row 113, and then overlay a red grounding line using ASAID data.

close all
modismoa('pine island glacier',400)

Author Info

This function and supporting documentation were written by Chad A. Greene of the University of Texas at Austin's Institute for Geophysics (UTIG), December 2014.