{"nbformat":4,"nbformat_minor":0,"metadata":{"colab":{"name":"Earth_Engine_REST_API_compute_image.ipynb","private_outputs":true,"provenance":[{"file_id":"1cLECy_jcK8DxQVd1eR2CHJFf5RSgrwBo","timestamp":1605024879401},{"file_id":"https://github.com/google/earthengine-api/blob/master/python/examples/ipynb/Earth_Engine_REST_API_computation.ipynb","timestamp":1605024830392},{"file_id":"1roGESkJ-6YGl3Xod7WJ1q1DhofbDo_Jh","timestamp":1591133797094}],"collapsed_sections":[],"toc_visible":true,"authorship_tag":"ABX9TyOKV7RHd650OqlisGHp9kTs"},"kernelspec":{"name":"python3","display_name":"Python 3"}},"cells":[{"cell_type":"code","metadata":{"id":"fSIfBsgi8dNK"},"source":["#@title Copyright 2020 Google LLC. { display-mode: \"form\" }\n","# Licensed under the Apache License, Version 2.0 (the \"License\");\n","# you may not use this file except in compliance with the License.\n","# You may obtain a copy of the License at\n","#\n","# https://www.apache.org/licenses/LICENSE-2.0\n","#\n","# Unless required by applicable law or agreed to in writing, software\n","# distributed under the License is distributed on an \"AS IS\" BASIS,\n","# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n","# See the License for the specific language governing permissions and\n","# limitations under the License."],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"aV1xZ1CPi3Nw"},"source":["<table class=\"ee-notebook-buttons\" align=\"left\"><td>\n","<a target=\"_blank\"  href=\"http://colab.research.google.com/github/google/earthengine-api/blob/master/python/examples/ipynb/Earth_Engine_REST_API_compute_image.ipynb\">\n","    <img src=\"https://www.tensorflow.org/images/colab_logo_32px.png\" /> Run in Google Colab</a>\n","</td><td>\n","<a target=\"_blank\"  href=\"https://github.com/google/earthengine-api/blob/master/python/examples/ipynb/Earth_Engine_REST_API_compute_image.ipynb\"><img width=32px src=\"https://www.tensorflow.org/images/GitHub-Mark-32px.png\" /> View source on GitHub</a></td></table>"]},{"cell_type":"markdown","metadata":{"id":"CrEM35gqHouU"},"source":["# Image computations with the Earth Engine REST API\n","\n","***Note:*** *The REST API contains new and advanced features that may not be suitable for all users.  If you are new to Earth Engine, please get started with the [JavaScript guide](https://developers.google.com/earth-engine/guides/getstarted).*\n","\n","The [Earth Engine REST API quickstart](https://developers.google.com/earth-engine/reference/Quickstart) shows how to access blocks of pixels from an Earth Engine asset.  Suppose you want to apply a computation to the pixels before obtaining the result.  This guide shows how to prototype a computation with one of the client libraries, serialize the computation graph and use the REST API to obtain the computed result.  Making compute requests through the REST API corresponds to a `POST` request to one of the compute endpoints, for example [`computePixels`](https://developers.google.com/earth-engine/reference/rest/v1beta/projects.image/computePixels), [`computeFeatures`](https://developers.google.com/earth-engine/reference/rest/v1beta/projects.table/computeFeatures), or the generic [`value.compute`](https://developers.google.com/earth-engine/reference/rest/v1beta/projects.value/compute).  Specifically, this example demonstrates getting a median composite of Sentinel-2 imagery in a small region."]},{"cell_type":"markdown","metadata":{"id":"H2VOD2agf4Cm"},"source":["## Before you begin\n","\n","Follow [these instructions](https://developers.google.com/earth-engine/earthengine_cloud_project_setup#apply-to-use-earth-engine) to:\n","\n","1. Apply for Earth Engine\n","2. Create a Google Cloud project\n","3. Enable the Earth Engine API on the project\n","4. Create a service account\n","5. Give the service account project level permission to perform Earth Engine computations\n","\n","**Note**: To complete this tutorial, you will need a service account that is registered for Earth Engine access.  See [these instructions](https://developers.google.com/earth-engine/guides/service_account#register-the-service-account-to-use-earth-engine) to register a service account before proceeding."]},{"cell_type":"markdown","metadata":{"id":"OfMAA6YhPuFl"},"source":["## Authenticate to Google Cloud\n","\n","The first thing to do is login so that you can make authenticated requests to Google Cloud.  You will set the project at the same time.  Follow the instructions in the output to complete the sign in."]},{"cell_type":"code","metadata":{"id":"FRm2HczTIlKe"},"source":["# INSERT YOUR PROJECT HERE\n","PROJECT = 'your-project'\n","\n","!gcloud auth login --project {PROJECT}"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"hnufOtSfP0jX"},"source":["## Obtain a private key file for your service account\n","\n","You should already have a service account registered to use Earth Engine.  If you don't, follow [these instructions](https://developers.google.com/earth-engine/guides/service_account#create-a-service-account) to get one.  Copy the email address of your service account into the following cell.  (The service account must already be registered to use Earth Engine).  In the following cell, the `gsutil` command line is used to generate a key file for the service account.  The key file will be created on the notebook VM."]},{"cell_type":"code","metadata":{"id":"tLxOnKL2Nk5p"},"source":["# INSERT YOUR SERVICE ACCOUNT HERE\n","SERVICE_ACCOUNT='your-service-account@your-project.iam.gserviceaccount.com'\n","KEY = 'key.json'\n","\n","!gcloud iam service-accounts keys create {KEY} --iam-account {SERVICE_ACCOUNT}"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"6QksNfvaY5em"},"source":["## Start an `AuthorizedSession` and test your credentials\n","\n","Test the private key by using it to get credentials.  Use the credentials to create an authorized session to make HTTP requests.  Make a `GET` request through the session to check that the credentials work."]},{"cell_type":"code","metadata":{"id":"h2MHcyeqLufx"},"source":["from google.auth.transport.requests import AuthorizedSession\n","from google.oauth2 import service_account\n","\n","credentials = service_account.Credentials.from_service_account_file(KEY)\n","scoped_credentials = credentials.with_scopes(\n","    ['https://www.googleapis.com/auth/cloud-platform'])\n","\n","session = AuthorizedSession(scoped_credentials)\n","\n","url = 'https://earthengine.googleapis.com/v1beta/projects/earthengine-public/assets/LANDSAT'\n","\n","response = session.get(url)\n","\n","from pprint import pprint\n","import json\n","pprint(json.loads(response.content))"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"U7ZzzoW_HgZ5"},"source":["## Serialize a computation\n","\n","Before you can send a request to compute something, the computation needs to be put into the Earth Engine expression graph format.  The following demonstrates how to obtain the expression graph.\n","\n","### Authenticate to Earth Engine\n","\n","Get Earth Engine scoped credentials from the service account.  Use them to initialize Earth Engine."]},{"cell_type":"code","metadata":{"id":"LdTW8sPQIsFx"},"source":["import ee\n","\n","# Get some new credentials since the other ones are cloud scope.\n","ee_creds = ee.ServiceAccountCredentials(SERVICE_ACCOUNT, KEY)\n","ee.Initialize(ee_creds)"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"Zb243CYTP48x"},"source":["### Define a computation\n","\n","Prototype a simple computation with the client API.  Note that the result of the computation is an `Image`."]},{"cell_type":"code","metadata":{"id":"S9fsJ4RtPr12"},"source":["coords = [\n","  -121.58626826832939, \n","  38.059141484827485,\n","]\n","region = ee.Geometry.Point(coords)\n","\n","collection = ee.ImageCollection('COPERNICUS/S2')\n","collection = collection.filterBounds(region)\n","collection = collection.filterDate('2020-04-01', '2020-09-01')\n","image = collection.median()"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"HLk-i3htLEBf"},"source":["### Serialize the expression graph\n","\n","This will create an object that represents the Earth Engine expression graph (specifically, an [`Expression`](https://developers.google.com/earth-engine/reference/rest/v1beta/Expression)).  In general, you should build these with one of the client APIs."]},{"cell_type":"code","metadata":{"id":"Mvbi4LuhV9BR"},"source":["serialized = ee.serializer.encode(image)"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"LufqOdLWKJ9l"},"source":["Create the desired projection (WGS84) at the desired scale (10 meters for Sentinel-2).  This is just to discover the desired scale in degrees, the units of the projection.  These scales will be used to specify the affine transform in the request."]},{"cell_type":"code","metadata":{"id":"ZJaOvVgUKKJK"},"source":["# Make a projection to discover the scale in degrees.\n","proj = ee.Projection('EPSG:4326').atScale(10).getInfo()\n","\n","# Get scales out of the transform.\n","scale_y = -proj['transform'][0]\n","scale_x = proj['transform'][4]"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"Y_Lu1qq5GUTF"},"source":["## Send the request\n","\n","Make a `POST` request to the [`computePixels`](https://developers.google.com/earth-engine/reference/rest/v1beta/projects.image/computePixels) endpoint.  Note that the request contains the [`Expression`](https://developers.google.com/earth-engine/reference/rest/v1beta/Expression), which is the serialized computation.  It also contains a [`PixelGrid`](https://developers.google.com/earth-engine/reference/rest/v1beta/PixelGrid).  The `PixelGrid` contains `dimensions` for the desired output and an `AffineTransform` in the units of the requested coordinate system.  Here the coordinate system is geographic, so the transform is specified with scale in degrees and geographic coordinates of the upper left corner of the requested image patch."]},{"cell_type":"code","metadata":{"id":"_pbqvd48dT33"},"source":["import json\n","\n","url = 'https://earthengine.googleapis.com/v1beta/projects/{}/image:computePixels'\n","url = url.format(PROJECT)\n","\n","response = session.post(\n","  url=url,\n","  data=json.dumps({\n","    'expression': serialized,\n","    'fileFormat': 'PNG',\n","    'bandIds': ['B4','B3','B2'],\n","    'grid': {\n","      'dimensions': {\n","        'width': 640,\n","        'height': 640\n","      },\n","      'affineTransform': {\n","        'scaleX': scale_x,\n","        'shearX': 0,\n","        'translateX': coords[0],\n","        'shearY': 0,\n","        'scaleY': scale_y,\n","        'translateY': coords[1]\n","      },\n","      'crsCode': 'EPSG:4326',\n","    },\n","    'visualizationOptions': {'ranges': [{'min': 0, 'max': 3000}]},\n","  })\n",")\n","\n","image_content = response.content"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"NZRt0HQU65Hy"},"source":["If you are running this in a notebook, you can display the results using the `IPython` image display widget."]},{"cell_type":"code","metadata":{"id":"4edL2ZLe7E2a"},"source":["# Import the Image function from the IPython.display module. \n","from IPython.display import Image\n","Image(image_content)"],"execution_count":null,"outputs":[]}]}