Updating to version 0.1.57

README.md

@@ -1,9 +1,36 @@
-Python and JavaScript bindings for calling the Earth Engine API.
+Google Earth Engine API
+=======================
+
+Python and JavaScript client libraries for calling the Earth Engine API.
 
 _**Important Note: Access to Google Earth Engine is currently only available to
 trusted testers. The API is in active development, and users should expect the
 API to change.  When (not if) API changes occur, applications that use the API
 will likely need to be updated.**_
 
-[Installation Instructions](INSTALL.md)
+- [Earth Engine Homepage](https://earthengine.google.org/)
+- [Playground Web IDE](https://ee-api.appspot.com/)
+- [Python Installation](python/README.md)
+
+Here's an example screenshot and the corresponding Playground JavaScript code:
+
+![Trendy Lights Image](https://raw.github.com/google/earthengine-api/master/trendy-lights.png)
+
+    // Compute the trend of nighttime lights from DMSP.
+
+    // Add a band containing image date as years since 1991.
+    function createTimeBand(img) {
+      var year = ee.Date(img.get('system:time_start')).get('year').subtract(1991);
+      return ee.Image(year).byte().addBands(img);
+    }
+
+    // Fit a linear trend to the nighttime lights collection.
+    var collection = ee.ImageCollection('NOAA/DMSP-OLS/NIGHTTIME_LIGHTS')
+        .select('stable_lights')
+        .map(createTimeBand);
 
+    // Display trend in red/blue, brightness in green.
+    Map.addLayer(
+        collection.reduce(ee.Reducer.linearFit()),
+        {min: 0, max: [0.18, 20, -0.18], bands: ['scale', 'offset', 'scale']},
+        'stable lights trend');

javascript/src/computedobject.js

@@ -8,6 +8,7 @@ goog.provide('ee.ComputedObject');
 goog.require('ee.Encodable');
 goog.require('ee.Serializer');
 goog.require('ee.data');
+goog.require('goog.array');
 
 
 
@@ -158,6 +159,29 @@ ee.ComputedObject.prototype.name = function() {
 };
 
 
+/**
+ * Calls a function passing this object as the first argument, and returning
+ * itself. Convenient e.g. when debugging:
+ *
+ * var c = ee.ImageCollection('foo').aside(print)
+ *   .filterDate('2001-01-01', '2002-01-01').aside(print, 'In 2001')
+ *   .filterBounds(geom).aside(print, 'In region')
+ *   .aside(Map.addLayer, {min: 0, max: 142}, 'Filtered')
+ *   .select('a', 'b');
+ *
+ * @param {Function} func The function to call.
+ * @param {...*} var_args Any extra arguments to pass to the function.
+ * @return {ee.ComputedObject} The same object, for chaining.
+ * @export
+ */
+ee.ComputedObject.prototype.aside = function(func, var_args) {
+  var args = goog.array.clone(arguments);
+  args[0] = this;
+  func.apply(goog.global, args);
+  return this;
+};
+
+
 /**
  * Cast a ComputedObject to a new instance of the same class as this.
  * @param {ee.ComputedObject} obj The object to cast.

javascript/src/data.js

@@ -43,6 +43,7 @@ goog.provide('ee.data.VideoTaskConfig');
 
 goog.require('goog.Uri');
 goog.require('goog.array');
+goog.require('goog.functions');
 goog.require('goog.json');
 goog.require('goog.net.XhrIo');
 goog.require('goog.net.XmlHttp');
@@ -74,6 +75,15 @@ ee.data.tileBaseUrl_ = null;
 ee.data.xsrfToken_ = null;
 
 
+/**
+ * @type {function(!goog.Uri.QueryData, string): !goog.Uri.QueryData} A function
+ *     used to transform parameters right before they are sent to the server.
+ *     Takes the URL of the request as the second argument.
+ * @private
+ */
+ee.data.paramAugmenter_ = goog.functions.identity;
+
+
 /**
  * @private {string?} An OAuth2 token to use for authenticating EE API calls.
  */
@@ -125,7 +135,7 @@ ee.data.deadlineMs_ = 0;
  * @private
  * @const
  */
-ee.data.DEFAULT_API_BASE_URL_ = '/api';
+ee.data.DEFAULT_API_BASE_URL_ = 'https://earthengine.googleapis.com/api';
 
 
 /**
@@ -183,9 +193,6 @@ ee.data.reset = function() {
   ee.data.apiBaseUrl_ = null;
   ee.data.tileBaseUrl_ = null;
   ee.data.xsrfToken_ = null;
-  ee.data.authClientId_ = null;
-  ee.data.authScopes_ = [];
-  ee.data.authToken_ = null;
   ee.data.initialized_ = false;
 };
 
@@ -234,24 +241,17 @@ ee.data.authenticate = function(
   ee.data.authClientId_ = clientId;
   ee.data.authScopes_ = scopes;
 
+  if (goog.isNull(clientId)) {
+    ee.data.authToken_ = null;
+    return;
+  }
+
   // Start the authentication flow as soon as we have the auth library.
-  var onImmediateFailed = opt_onImmediateFailed || goog.partial(
-      ee.data.authenticateViaPopup, success, opt_error);
-  if (goog.isObject(goog.global['gapi']) &&
-      goog.isObject(goog.global['gapi']['auth']) &&
-      goog.isFunction(goog.global['gapi']['auth']['authorize'])) {
+  ee.data.ensureAuthLibLoaded_(function() {
+    var onImmediateFailed = opt_onImmediateFailed || goog.partial(
+        ee.data.authenticateViaPopup, success, opt_error);
     ee.data.refreshAuthToken_(success, opt_error, onImmediateFailed);
-  } else {
-    // The library is not loaded; load it now.
-    var callbackName = goog.now().toString(36);
-    while (callbackName in goog.global) callbackName += '_';
-    goog.global[callbackName] = function() {
-      delete goog.global[callbackName];
-      ee.data.refreshAuthToken_(success, opt_error, onImmediateFailed);
-    };
-    goog.net.jsloader.load(
-        ee.data.AUTH_LIBRARY_URL_ + '?onload=' + callbackName);
-  }
+  });
 };
 
 
@@ -265,6 +265,7 @@ ee.data.authenticate = function(
  *     succeeds.
  * @param {function(string)=} opt_error The function to call if authentication
  *     fails, passing the error message.
+ * @export
  */
 ee.data.authenticateViaPopup = function(opt_success, opt_error) {
   goog.global['gapi']['auth']['authorize']({
@@ -275,6 +276,53 @@ ee.data.authenticateViaPopup = function(opt_success, opt_error) {
 };
 
 
+/**
+ * Configures client-side authentication of EE API calls by providing a
+ * current OAuth2 token to use. This is a replacement for expected
+ * ee.data.authenticate() when a token is already available.
+ * @param {string} clientId The OAuth client ID associated with the token.
+ * @param {string} tokenType The OAuth2 token type, e.g. "Bearer".
+ * @param {string} accessToken The token string, typically looking something
+ *     like "ya29.hgGGO...OtA".
+ * @param {number} expiresIn The number of seconds after which this token
+ *     expires.
+ * @param {!Array<string>=} opt_extraScopes Extra OAuth scopes associated with
+ *     the token.
+ * @param {function()=} opt_callback A function to call when the token is set.
+ * @param {boolean=} opt_updateAuthLibrary Whether to also update the token
+ *     set in the Google API Client Library for JavaScript. Defaults to true.
+ * @export
+ */
+ee.data.setAuthToken = function(clientId, tokenType, accessToken,
+                                expiresIn, opt_extraScopes, opt_callback,
+                                opt_updateAuthLibrary) {
+  var scopes = [ee.data.AUTH_SCOPE_];
+  if (opt_extraScopes) {
+    goog.array.extend(scopes, opt_extraScopes);
+    goog.array.removeDuplicates(scopes);
+  }
+  ee.data.authClientId_ = clientId;
+  ee.data.authScopes_ = scopes;
+
+  var tokenObject = {
+    'token_type': tokenType,
+    'access_token': accessToken,
+    'state': scopes.join(' '),
+    'expires_in': expiresIn
+  };
+  ee.data.handleAuthResult_(undefined, undefined, tokenObject);
+
+  if (opt_updateAuthLibrary === false) {
+    if (opt_callback) opt_callback();
+  } else {
+    ee.data.ensureAuthLibLoaded_(function() {
+      goog.global['gapi']['auth']['setToken'](tokenObject);
+      if (opt_callback) opt_callback();
+    });
+  }
+};
+
+
 /**
  * Sets the timeout length for asynchronous API requests.
  *
@@ -287,6 +335,20 @@ ee.data.setDeadline = function(milliseconds) {
 };
 
 
+/**
+ * Sets a function used to transform request parameters.
+ *
+ * @param {?function(!goog.Uri.QueryData, string): !goog.Uri.QueryData}
+ *     augmenter A function used to transform request parameters right
+ *     before they are sent to the server. Takes the URL of the request
+ *     as the second argument.
+ */
+ee.data.setParamAugmenter = function(augmenter) {
+  ee.data.paramAugmenter_ = augmenter || goog.functions.identity;
+};
+goog.exportSymbol('ee.data.setParamAugmenter', ee.data.setParamAugmenter);
+
+
 /**
  * Returns the base URL used for API calls.
  *
@@ -320,6 +382,42 @@ ee.data.getXsrfToken = function() {
 };
 
 
+/**
+ * Returns the current OAuth token; null unless ee.data.setAuthToken() or
+ * ee.data.authorize() previously suceeded.
+ *
+ * @return {?string} The string to pass in the Authorization header of XHRs.
+ * @export
+ */
+ee.data.getAuthToken = function() {
+  return ee.data.authToken_;
+};
+
+
+/**
+ * Returns the current OAuth client ID; null unless ee.data.setAuthToken() or
+ * ee.data.authorize() previously suceeded.
+ *
+ * @return {?string} The OAuth2 client ID for client-side authentication.
+ * @export
+ */
+ee.data.getAuthClientId = function() {
+  return ee.data.authClientId_;
+};
+
+
+/**
+ * Returns the current OAuth scopes; empty unless ee.data.setAuthToken() or
+ * ee.data.authorize() previously suceeded.
+ *
+ * @return {!Array<string>} The OAuth2 scopes for client-side authentication.
+ * @export
+ */
+ee.data.getAuthScopes = function() {
+  return ee.data.authScopes_;
+};
+
+
 /**
  * Load info for an asset, given an asset id.
  *
@@ -936,6 +1034,9 @@ ee.data.send_ = function(path, params, opt_callback, opt_method) {
     headers['Authorization'] = ee.data.authToken_;
   }
 
+  // Apply any custom param augmentation.
+  params = ee.data.paramAugmenter_(params || new goog.Uri.QueryData(), path);
+
   // XSRF protection for a server-side API proxy.
   if (goog.isDefAndNotNull(ee.data.xsrfToken_)) {
     headers['X-XSRF-Token'] = ee.data.xsrfToken_;
@@ -1033,6 +1134,35 @@ ee.data.send_ = function(path, params, opt_callback, opt_method) {
 };
 
 
+/**
+ * Ensures that the Google API Client Library for JavaScript is loaded.
+ * @param {function()} callback The function to call when the library is ready.
+ * @private
+ */
+ee.data.ensureAuthLibLoaded_ = function(callback) {
+  var done = function() {
+    // Speed up auth request by using CORS instead of an iframe.
+    goog.global['gapi']['config']['update']('client/cors', true);
+    callback();
+  };
+  if (goog.isObject(goog.global['gapi']) &&
+      goog.isObject(goog.global['gapi']['auth']) &&
+      goog.isFunction(goog.global['gapi']['auth']['authorize'])) {
+    done();
+  } else {
+    // The library is not loaded; load it now.
+    var callbackName = goog.now().toString(36);
+    while (callbackName in goog.global) callbackName += '_';
+    goog.global[callbackName] = function() {
+      delete goog.global[callbackName];
+      done();
+    };
+    goog.net.jsloader.load(
+        ee.data.AUTH_LIBRARY_URL_ + '?onload=' + callbackName);
+  }
+};
+
+
 /**
  * Retrieves a new OAuth2 token for the currently configured ID and scopes.
  *
@@ -1082,7 +1212,9 @@ ee.data.handleAuthResult_ = function(success, error, result) {
     // Set up a refresh timer. This is necessary because we cannot refresh
     // synchronously, but since we want to allow synchronous API requests,
     // something must ensure that the auth token is always valid.
-    setTimeout(ee.data.refreshAuthToken_, result['expires_in'] * 1000 / 2);
+    if (isFinite(result['expires_in'])) {
+      setTimeout(ee.data.refreshAuthToken_, result['expires_in'] * 1000 / 2);
+    }
     if (success) success();
   } else if (error) {
     error(result['error'] || 'Unknown error.');
@@ -1122,6 +1254,7 @@ ee.data.setupMockSend = function(opt_calls) {
   // If it's an object it has fields specifying more details.
   // If there's nothing set for this url, throw.
   function getResponse(url, method, data) {
+    url = url.replace(ee.data.apiBaseUrl_, '');
     var response;
     if (url in calls) {
       response = calls[url];