guides/linked/generated/image_math.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#@title Copyright 2021 The Earth Engine Community Authors { display-mode: \"form\" }\n",
    "#\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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Mathematical Operations\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Image math can be performed using operators like `add()` and `subtract()`, but for complex computations with more than a couple of terms, the `expression()` function provides a good alternative. See the following sections for more information on [operators](https://developers.google.com#operators) and [expressions](https://developers.google.com#expressions)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Earth Engine setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ee\n",
    "ee.Authenticate()\n",
    "ee.Initialize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Import `geemap`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import geemap.core as geemap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Operators\n",
    "\n",
    "Math operators perform basic arithmetic operations on image bands. They take two inputs: either two images or one image and a constant term, which is interpreted as a single-band constant image with no masked pixels. Operations are performed per pixel for each band.\n",
    "\n",
    "As a simple example, consider the task of calculating the Normalized Difference Vegetation Index (NDVI) using Landsat imagery, where `add()`, `subtract()`, and `divide()` operators are used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load a 5-year Landsat 7 composite 1999-2003.\n",
    "landsat_1999 = ee.Image('LANDSAT/LE7_TOA_5YEAR/1999_2003')\n",
    "\n",
    "# Compute NDVI.\n",
    "ndvi_1999 = (\n",
    "    landsat_1999.select('B4')\n",
    "    .subtract(landsat_1999.select('B3'))\n",
    "    .divide(landsat_1999.select('B4').add(landsat_1999.select('B3')))\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note:** the normalized difference operation is available as a shortcut method: [`normalizedDifference()`](https://developers.google.com/earth-engine/apidocs/ee-image-normalizeddifference). \n",
    "\n",
    "Only the intersection of unmasked pixels between the two inputs are considered and returned as unmasked, all else are masked. In general, if either input has only one band, then it is used against all the bands in the other input. If the inputs have the same number of bands, but not the same names, they're used pairwise in the natural order. The output bands are named for the longer of the two inputs, or if they're equal in length, in the first input's order. The type of the output pixels is the union of the input types.\n",
    "\n",
    "The following example of multi-band image subtraction demonstrates how bands are matched automatically, resulting in a “change vector” for each pixel for each co-occurring band."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load a 5-year Landsat 7 composite 2008-2012.\n",
    "landsat_2008 = ee.Image('LANDSAT/LE7_TOA_5YEAR/2008_2012')\n",
    "\n",
    "# Compute multi-band difference between the 2008-2012 composite and the\n",
    "# previously loaded 1999-2003 composite.\n",
    "diff = landsat_2008.subtract(landsat_1999)\n",
    "\n",
    "# Compute the squared difference in each band.\n",
    "squared_difference = diff.pow(2)\n",
    "\n",
    "# Define a map centered on Australia.\n",
    "map_diff = geemap.Map(center=[-24.003, 133.565], zoom=5)\n",
    "\n",
    "# Add the image layers to the map and display it.\n",
    "map_diff.add_layer(\n",
    "    diff, {'bands': ['B4', 'B3', 'B2'], 'min': -32, 'max': 32}, 'diff.'\n",
    ")\n",
    "map_diff.add_layer(\n",
    "    squared_difference,\n",
    "    {'bands': ['B4', 'B3', 'B2'], 'max': 1000},\n",
    "    'squared diff.',\n",
    ")\n",
    "display(map_diff)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the second part of this example, the squared difference is computed using `image.pow(2)`. For the complete list of mathematical operators handling basic arithmetic, trigonometry, exponentiation, rounding, casting, bitwise operations and more, see the [API documentation](https://developers.google.com/earth-engine/apidocs)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Expressions\n",
    "\n",
    "To implement more complex mathematical expressions, consider using `image.expression()`, which parses a text representation of a math operation. The following example uses `expression()` to compute the Enhanced Vegetation Index (EVI):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load a Landsat 8 image.\n",
    "image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318')\n",
    "\n",
    "# Compute the EVI using an expression.\n",
    "evi = image.expression(\n",
    "    '2.5 * ((NIR - RED) / (NIR + 6 * RED - 7.5 * BLUE + 1))',\n",
    "    {\n",
    "        'NIR': image.select('B5'),\n",
    "        'RED': image.select('B4'),\n",
    "        'BLUE': image.select('B2'),\n",
    "    },\n",
    ")\n",
    "\n",
    "# Define a map centered on San Francisco Bay.\n",
    "map_evi = geemap.Map(center=[37.4675, -122.1363], zoom=9)\n",
    "\n",
    "# Add the image layer to the map and display it.\n",
    "map_evi.add_layer(\n",
    "    evi, {'min': -1, 'max': 1, 'palette': ['a6611a', 'f5f5f5', '4dac26']}, 'evi'\n",
    ")\n",
    "display(map_evi)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Observe that the first argument to `expression()` is the textual representation of the math operation, the second argument is a dictionary where the keys are variable names used in the expression and the values are the image bands to which the variables should be mapped. Bands in the image may be referred to as `b(\"band name\")` or `b(index)`, for example `b(0)`, instead of providing the dictionary. Bands can be defined from images other than the input when using the band map dictionary. Note that `expression()` uses \"floor division\", which discards the remainder and returns an integer when two integers are divided. For example `10 / 20 = 0`. To change this behavior, multiply one of the operands by `1.0`: `10 * 1.0 / 20 = 0.5`. Only the intersection of unmasked pixels are considered and returned as unmasked when bands from more than one source image are evaluated. Supported expression operators are listed in the following table.\n",
    "\n",
    "Operators for `expression()`:\n",
    "\n",
    "Type | Symbol | Name  \n",
    "---|---|---  \n",
    "**Arithmetic** |  \\+ - * / % ** | Add, Subtract, Multiply, Divide, Modulus, Exponent  \n",
    "**Relational** |  == != < > <= >= | Equal, Not Equal, Less Than, Greater than, etc.  \n",
    "**Logical** |  && || ! ^ | And, Or, Not, Xor  \n",
    "**Ternary** | ? : |  If then else"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "name": "Mathematical Operations"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}