-**Purpose**: This module is designed to process Landsat Top of Atmosphere (TOA) imagery using Google Earth Engine (GEE). It focuses on cloud masking, image acquisition based on specific dates, and generating cloud maps for given geometries.
#### Critical Functions
1.**addGridPosition(element)**: Adds grid position metadata to an image.
2.**sliceByRevisit(collection, startingDate, days)**: Filters an image collection by a specific date range.
3.**maskTOAClouds(image, bandName)**: Masks clouds in a TOA image using bitwise operations on quality assessment bands.
4.**acquireFromDate(date, mission, geometry)**: Acquires a mosaicked image for a given date, mission, and geometry, and calculates the cloud ratio.
5.**processCollection(mission, geometry)**: Processes an image collection to find valid dates for image acquisition based on the mission's revisit cycle.
6.**generateCloudMap(dates, mission, geometry)**: Generates a list of cloud ratios for a series of dates.
7.**queryAvailable(mission)**: Queries available dates and cloud ratios for a given mission and geometry.
8.**getAvailable(mission)**: Placeholder function for getting available data.
9.**acquire(mission)**: Acquires an image for a specific date and geometry.
10.**format(properties)**: Formats image properties for display.
#### Key Variables
-**Metadata.GRID_POSITION**: Key for storing grid position metadata.
-**cloudMask, cloudConf, shadowConf, cirrusConf**: Bitwise masks for different cloud and shadow conditions.
-**global, enhanced, northeasternPosition, filtered, northeastern, difference, remainder, step, earliestDate, completeCycles, additions, carriers, valid**: Variables used in `processCollection` to manage image collection processing and filtering.
#### Interdependencies
-**Dependencies on Other Modules**:
-`ee` from `../../services/earth-engine`: Google Earth Engine API.
-`mergeProperties, retrieveExtremes, getDate` from `../utils`: Utility functions for merging properties, retrieving date extremes, and formatting dates.
-`scoreCloudRatio` from `../imagery`: Function to score cloud ratios.
-`Metadata` from `../../common/metadata`: Metadata constants.
#### Core vs. Auxiliary Operations
-**Core Operations**:
-`acquireFromDate`
-`processCollection`
-`generateCloudMap`
-`queryAvailable`
-`acquire`
-**Auxiliary Operations**:
-`addGridPosition`
-`sliceByRevisit`
-`maskTOAClouds`
-`format`
#### Operational Sequence
1.**Image Acquisition**:
- Use `acquireFromDate` to get a mosaicked image for a specific date.
2.**Cloud Masking**:
- Apply `maskTOAClouds` to mask clouds in the image.
3.**Collection Processing**:
- Use `processCollection` to find valid dates for image acquisition.
4.**Cloud Map Generation**:
- Generate cloud maps using `generateCloudMap`.
5.**Querying**:
- Use `queryAvailable` to get available dates and cloud ratios.
#### Performance Aspects
-**Performance Considerations**:
- Efficient filtering and processing of large image collections.
- Use of bitwise operations for cloud masking to enhance performance.
- The module can be extended to support additional missions or different types of imagery.
#### Usage
-**How It Is Used**:
- Import the module and call its functions to process Landsat TOA imagery.
- Use `queryAvailable` to get available dates and cloud ratios for a specific mission and geometry.
- Use `acquire` to acquire images for specific dates.
- Format image properties using `format`.
#### Assumptions
-**Assumptions Made**:
- The input geometry is valid and within the bounds of the mission's coverage.
- The mission object contains necessary metadata such as `name`, `cycle`, and `bands`.
- The GEE environment is properly set up and accessible.
- The utility functions (`mergeProperties`, `retrieveExtremes`, `getDate`) and metadata constants are correctly defined and imported.
This analysis provides a detailed overview of the `landsatToa.js` module, covering its primary objectives, critical functions, key variables, interdependencies, and more.
## Flow Diagram [via mermaid]
```mermaid
graph TD
%% External Entities
User((User))
EarthEngine((Earth Engine))
%% Processes
P1[queryAvailable]
P2[getAvailable]
P3[acquire]
P4[format]
P5[processCollection]
P6[generateCloudMap]
P7[acquireFromDate]
P8[maskTOAClouds]
P9[sliceByRevisit]
P10[addGridPosition]
P11[mergeProperties]
P12[retrieveExtremes]
P13[getDate]
P14[scoreCloudRatio]
%% Data Stores
DS1[Mission Data]
DS2[Geometry Data]
DS3[Image Collection]
DS4[Cloud Data]
%% Data Flows
User -->|Request| P1
P1 -->|Mission, Geometry| P5
P5 -->|Processed Collection| DS3
DS3 -->|Image Collection| P6
P6 -->|Dates, Mission, Geometry| P7
P7 -->|Image| P8
P8 -->|Masked Image| P14
P14 -->|Cloud Ratio| P7
P7 -->|Image with Clouds| DS4
DS4 -->|Cloud Data| P1
P1 -->|Available Data| User
User -->|Request| P2
P2 -->|Mission, Geometry| P5
P5 -->|Processed Collection| DS3
DS3 -->|Image Collection| P6
P6 -->|Dates, Mission, Geometry| P7
P7 -->|Image| P8
P8 -->|Masked Image| P14
P14 -->|Cloud Ratio| P7
P7 -->|Image with Clouds| DS4
DS4 -->|Cloud Data| P2
P2 -->|Available Data| User
User -->|Request| P3
P3 -->|Mission, Date, Geometry| P7
P7 -->|Image| P8
P8 -->|Masked Image| P14
P14 -->|Cloud Ratio| P7
P7 -->|Image with Clouds| P3
P3 -->|Acquired Data| User
User -->|Request| P4
P4 -->|Properties| P11
P11 -->|Formatted Data| P4
P4 -->|Formatted Data| User
%% Internal Data Flows
P5 -->|Mission, Geometry| P12
P12 -->|Extremes| P5
P5 -->|Mission, Geometry| P10
P10 -->|Grid Position| P5
P5 -->|Mission, Geometry| P9
P9 -->|Sliced Collection| P5
P5 -->|Processed Collection| DS3
P6 -->|Dates, Mission, Geometry| P7
P7 -->|Image| P8
P8 -->|Masked Image| P14
P14 -->|Cloud Ratio| P7
P7 -->|Image with Clouds| DS4
DS4 -->|Cloud Data| P6
P7 -->|Image| P11
P11 -->|Merged Properties| P7
P7 -->|Image with Clouds| DS4
P7 -->|Image| P13
P13 -->|Date| P7
```
## Module: landsatToa.js
### Comprehensive Analysis of `landsatToa.js`
#### Module Name
-**Module Name**: `landsatToa.js`
#### Primary Objectives
-**Purpose**: This module is designed to process Landsat Top of Atmosphere (TOA) imagery using Google Earth Engine (GEE). It focuses on cloud masking, image acquisition based on specific dates, and generating cloud maps for given geometries.
#### Critical Functions
1.**addGridPosition(element)**: Adds grid position metadata to an image.
2.**sliceByRevisit(collection, startingDate, days)**: Filters an image collection by a date range.
3.**maskTOAClouds(image, bandName)**: Masks clouds in a TOA image based on specific bitwise operations.
4.**acquireFromDate(date, mission, geometry)**: Acquires a mosaicked image for a given date, mission, and geometry, and calculates the cloud ratio.
5.**processCollection(mission, geometry)**: Processes an image collection to find valid dates for image acquisition.
6.**generateCloudMap(dates, mission, geometry)**: Generates a list of cloud ratios for given dates.
7.**queryAvailable(mission)**: Queries available images and their cloud ratios for a given mission and geometry.
8.**getAvailable(mission)**: Placeholder function for getting available images.
9.**acquire(mission)**: Acquires an image for a given date and geometry.
10.**format(properties)**: Formats image properties for display.
#### Key Variables
-**Metadata.GRID_POSITION**: Key for storing grid position metadata.
-**cloudMask, cloudConf, shadowConf, cirrusConf**: Bitwise masks for cloud, cloud confidence, shadow confidence, and cirrus confidence.
#### Interdependencies
-**External Modules**:
-`ee` from `../../services/earth-engine`: Google Earth Engine API.
- Utility functions from `../utils`: `mergeProperties`, `retrieveExtremes`, `getDate`.
-`scoreCloudRatio` from `../imagery`: Function to score cloud ratio.
-`Metadata` from `../../common/metadata`: Common metadata keys.
#### Core vs. Auxiliary Operations
-**Core Operations**:
-`acquireFromDate`
-`processCollection`
-`generateCloudMap`
-`queryAvailable`
-`acquire`
-**Auxiliary Operations**:
-`addGridPosition`
-`sliceByRevisit`
-`maskTOAClouds`
-`format`
#### Operational Sequence
1.**Image Acquisition**:
- Use `processCollection` to find valid dates.
- Use `acquireFromDate` to acquire images for those dates.
2.**Cloud Masking**:
- Apply `maskTOAClouds` to mask clouds in the images.
3.**Cloud Map Generation**:
- Use `generateCloudMap` to create a list of cloud ratios for the images.
4.**Querying**:
- Use `queryAvailable` to get available images and their cloud ratios.
#### Performance Aspects
-**Efficiency**: The module uses GEE's efficient filtering and mapping functions to handle large datasets.
-**Scalability**: Designed to work with large image collections and extensive geographical areas.
#### Reusability
-**Adaptability**: Functions are modular and can be reused for different missions and geometries. The use of GEE makes it adaptable to various remote sensing tasks.
#### Usage
-**How it is used**:
- Import the module and call its functions to process Landsat TOA imagery.
- Use `queryAvailable` to get available images and cloud ratios.
- Use `acquire` to acquire specific images.
- Use `format` to format image properties for display.
#### Assumptions
-**Assumptions Made**:
- The input geometries are valid and within the bounds of the image collection.
- The mission object contains necessary metadata like `name`, `cycle`, and `bands`.
- The GEE environment is properly set up and authenticated.
This analysis provides a detailed overview of the `landsatToa.js` module, covering its primary objectives, critical functions, key variables, interdependencies, and more.
