The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-MODIS-2.0
River stage zero No dependents
2 ++
/ WebService::MODIS

NAME

WebService::MODIS - Perl extension for downloading MODIS satellite data

SYNOPSIS use WebService::MODIS;

  ### to initalize or reload the cached server side directory structure
  initCache;
  ### write the cache to configuration files.
  ### A different directory can be passed as parameter.
  writeCache;
  ### load the cache from a previous writeCache.
  ### A different directory can be passed as parameter.
  readCache;

  ### Only available with use WebService::MODIS qw(:all);
  # my %ret = getModisProducts;
  # print "$_ : $ret{$_}\n" foreach (keys %ret);
  # %ret = getModisGlobal;
  # print "$_ : $ret{$_}\n" foreach (keys %ret);

  ### print available versions of a certain product
  print "Versions of MCD12Q1:";
  print " $_" foreach (getVersions("MCD12Q1"));
  print "\n";

  ### new object of land cover type in Rondonia, Brazil for 2001 and 2010
  my $lct = WebService::MODIS->new(product => "MCD12Q1", 
              dates => ['2001-01-01', '2010-01-01'], ifExactDates => 1,
              h => [11,12], v=> [9,10]);
  $lct->createUrl;
  ### print the list of URLs for usage with e.g. wget
  print "$_\n" foreach $lct->url;
  ### download the data to the current working directory (>700MB!)
  # $lct->download;
  ### test partial download
  # system("mv MCD12Q1.A2001001.h11v09.051.2014287162321.hdf MCD12Q1.A2001001.h11v09.051.2014287162321.hdf.bak");
  # system("head -c 72268718 MCD12Q1.A2001001.h11v09.051.2014287162321.hdf.bak >MCD12Q1.A2001001.h11v09.051.2014287162321.hdf"); 
  # $lct->download;

  ### intialize an empty object and populate it with NDVI/EVI data 
  ### for one tile of Europe for 3 years
  my $phen = WebService::MODIS->new();
  $phen->product("MYD13A2");
  $phen->version('005');
  $phen->h([18]);
  $phen->v([4]);
  $phen->dates(["2002.01.01", "2004.12.31"]);
  $phen->createUrl;
  print "$_\n" foreach $phen->url;
  # $phen->download("$ENV{HOME}/tmp/test_modisdownload");

DESCRIPTION

This module can dowload a MODIS satellite product in standard hdf format. It loads metadata of all available products and their respective versions and can save this metadata for future use to configuration files. You can either print a list of desired files or download them directly with this module. The module supports continuous download.

You need the following information

product ID: which product do you want
[version]: not necessarily, but better so you know what you get. If not set, the highest version number is choosen.
dates: for which time frame do you want the data
h, v: values of desired MODIS sinusoidal grid (if not a global product is choosen)

FUNCTIONS

initCache

initCache;

This function retrieves the directory structure of the server

writeCache

writeCache(directory);

Writes the saved metadata to perl parsable configuration files. If no argument is supplied the files will be saved to a standard directory otherwise to the given directory.

readCache

readCache(directory);

Loads the server metadata from local configuration files. If no argument is supplied the files are read from a standard directory otherwise from the given one.

getCacheState

$ret = getCacheState;

returns either '', 'mem or 'file', if nothing is cached, cache data was initialized from the server to memory or read from (or already written to ) local configuration files, respectively.

getVersions

@ver = getVersions($product);

Lists the available versions of a certain MODIS product, which must be supplied as argument.

isGlobal

$ret = isGlobal($product)

returns either 1(global) or 0 (sinusoidal) for a certain MODIS product

new

$x = WebService::MODIS->new(); $x = WebService::MODIS->new(product => "$product", ...);

Either an empty object can be created and the properties are filled later on. Available options are:

product: MODIS product ID as string
version: desired version of MODIS product as string of three digits
dates: anonymous string array of form YYYY-MM-DD or YYYY.MM.DD
ifexactDates: either 1, then the URL for the exact dates in the dates option is checked or 0 (default) then all possible data between the minimum und maximum dates is checked.
h: the horizontal ID of the MODIS sinusoidal grid
v: the vertical ID of the MODIS sinusoidal grid
ifExactHV: either 1, then the exact combination of option h and v are checked or 0 (default), then all combinations between min and max h and v are checked. Setting it to 1 makes it possible to download several tiles far away from each other (p.e. Alaska and Australia).
targetDir: where to save the data. Can be modified via method "download"
forceReload: if set to 1 already files existing will be reloaded from the server and overwritten.

METHODS for WebService::MODIS objects

product

$prod = $x->prod($newprod); $prod = $x->product;

With parameter it checks whether the supplied string is a valid MODIS product and resets the version to '' and the url list to [];

Without parameter it return the currently set MODIS product.

version

With parameter it checks if the version is available and sets it. And resets the url list to []. It makes no sense to set it before the product is set.

Without parameter it return the currently set version of the MODIS product.

dates

$x->dates(["2002-01-01", "2002-12-31"]); @dates = $x->dates;

Either an anonymous array of date strings (YYYY-MM-DD or YYYY.MM.DD) for the desired period (resets the url list to []) or no parameter, then the already set dates are return as array reference.

h

$x->h([1,5]); @h = $x->h;

Either anonymous array of desired horizontal grid ID of the sinusoidal grid (resets the url list to []) or nothing, then the already set values are returned.

v

$x->v([1,5]); @v = $x->v;

Either anonymous array of desired vertical grid ID of the sinusoidal grid (resets the url list to []) or nothing, then the already set values are returned.

ifExactDates

$x->ifExactDates(1); $ret = $x->ifExactDates;

Whether the data between min and max of dates should be retrieved (0, default) or the data for the exact dates is to be used (all other values). Without parameter just return the value.

ifExactHV

$x->ifExactHV(1); $ret = $x->ifExactHV;

Whether the data between and max of h and v IDs should be retrieved (0, default) or the data for the exact h and v pairs is to be used (all other values). Without parameter just return the value.

createUrl

$x->createUrl;

Product, dates, h and v values need to be set before this method works. version, ifExactDates, ifExactHV parameters are optional and set to reasonable defaults.

url

@url = $x->url;

return the list of URLs created by createUrl.

download

$x->download; $x->download($targetDirectory); $x->download($targetDirectory, $force);

Downloads the hdf files to the current working directory or a supplied one. If the given directory does not exist it will be created if possible. If any second parameter is given already existing files will be overwritten, otherwise (default) a already existing files will be checked against the file size on the server and missing data will be appended if necessary. createUrl is called from within here if 'url' is unset.

TODO

Wrinting a test.pl file
Test the module on other operating systems.
make_path dies if the path can not be created, catch it or use something else for error handling

SEE ALSO

Description of terrestrial MODIS products can be found on https://lpdaac.usgs.gov/. The work was inspired by ModisDownload.R (http://r-gis.net/?q=ModisDownload), which sadly did so far not support continued download if the connection was interrupted, which happened quiet often for me.

AUTHOR

Joerg Steinkamp, joergsteinkamp@yahoo.de

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Joerg Steinkamp

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.20.1 or, at your option, any later version of Perl 5 you may have available.