# AI Usage Disclaimer

I have used AI (Claude) to implement this and teach me the concepts. I gave the general direction and objective. 
- The STAC and Copernicus API usage I mostly did it.
- From the band loader onwards I used AI to assist me and teach me concepts.
- The /website section (backend and frontend) was done by AI.
- README was generated by AI

# 1. Objective of this project

The objective of this project was to learn some fundamental concepts of Geospatial Science and Earth Observation.
These involved python libraries and Satellite imagery (including some concepts behind this, such as Bands, STAC, learning to use Copernicus API).
To provide a way to estimate the reservoir storage as SINA Api stopped providing data after April 23, 2025.

# 2. Scope and Changes

The target project was to have a way to estimate the current Cutzamala System storage (this is the system of reservoirs that provide Mexico City with clean water).
Due to time constraints I could not implement for the rest of the reservoirs, but I implemented the estimation for the most important reservoir: Valle de Bravo.
The biggest change in scope was only doing the estimation for Valle de Bravo, not for the rest or the whole Cutzamala System.

# 3. Project Roadmap

1. Learn how to use the Copernicus API
2. Fetch and cache responses from Copernicus API using Sentinel-2
3. Use STAC to load the bands (and configure the endpoints)
	1. Use a rectangle shape to read only this area. We don't make stac.load go through all the pixels this way.
4. Convert Band values to reflectance
5. Use Band colors to differentiate land from water
	1. Use NIR (near infrared) band and green to make the distinction between water and land (as water absorbs NIR much more)
	2. Using NDWI, we calculated the contrast between water and land
6. Do a clear mask for Pixels that have a clear view
7. Process month by month

8. Check how much of the lake is visible (clearly), and drop the days that had more than 5% of obstruction (cloudy sections).
9. Use CONAGUA Api to get the storage for a date
	1. Cache results
10. Use Otsu algorithm to get the threshold value (NDWI cutoff). We use it to form a water mask (every pixel greater than the threshold)
11. Get the largest connected water region and count water pixels. Then convert from pixels to km2
12. Calculate the curve from area (lake surface) to get the lake volume
13. When CONAGUA's data is available, we compare our estimation against them and get mean absolute error.

# 4. Verifying Step by Step

You can see, in most of the files, that we use a main function. That's because every time a python file was made, I tested we had the behavior we desired during that step. I made sure the concepts were sticking to me or at least I had some understanding of some of the complex logic going on behind them (for instance Otsu threshold).

The main verification steps were:
1. Getting the Copernicus Responses
2. Storing in file cache (under the respective /data folders)
3. Loading an image from an item within a Collection
4. Configuring the Environment variables correctly (to use S3) and load bands successfully
5. Converting to reflectance
6. Composing an image with the pixel data and band data
7. Getting data from SINA Conagua Endpoint (as long as it was before the mentioned date)
8. Creating a water mask and getting a km2 area from that water mask
9. Using the surface to calculate volume
10. Presenting results in a visual way

# 5. Conclusion and learnings

1. On Satellite Imagery:
	1. Copernicus allows for far more customization than I initially thought. Which means there's a lot of configuration to learn. Confusing at first, but once you get the basics down it's very powerful.
	2. Good to see there's a standard for how data is structured (STAC) as data from response can be very big json files.
	3. Bands allow for a lot of usages. At first I did not even consider the use case of reflectance or using NIR.
	4. Rastering images using ODC STAC takes longer than I anticipated. Being granular with your data and specifying bounding boxes is essential, there's a lot of data to process in these high res images.
2. On calculating surface area or volume:
	1. Imagery is more robust than I thought. I thought of doing a ML model at first, and with image labelled against SINA Api, but Satellite Imagery offers much more. It's amazing to me that using reflectance and other algorithms you can calculate and estimate sizes.
	2. No need for ML Models for everything. In the end, you can use mathematical models to make the calculations you need.
	3. Need to add filters to prepare and clean data (for instance counting clear pixels vs pixels with clouds on top), need to add gates to use only clean data (for instance, if we removed dirty pixels we could have a lake short of couple of km2)
3. AI as a personalized learning tool:
	1. It's great having a tool that you can personalize and learn (and reinforce learning) based on the best way to learn for you. In my case, I understand something far better by doing than by reading. 

**Conclusion:**

This was extremely useful for me as an introduction to understand how a Geospatial pipeline works. How there are standards and systems behind things I did not know before (such as Coordinate system like the ones that use EPSG registry). It puts into perspective all the collective effort we have in this infrastructure and the potential they have to build new technologies on top of.
