protocolo package

Submodules

protocolo.analisis_escenas_nubosas module

protocolo.analisis_escenas_nubosas.verificar_normalizacion_completa(escena_name, ruta_nor)

Verifica el estado de normalización de una escena. Retorna un diccionario con detalles.

protocolo.analisis_escenas_nubosas.verificar_productos_generados(escena_name, ruta_pro)

Verifica qué productos han sido generados para una escena.

protocolo.analisis_escenas_nubosas.analizar_escenas_nubosas(umbral_nubes=20)

Genera un análisis completo de las escenas con nubes.

protocolo.analisis_escenas_nubosas.generar_reporte_por_anio(anio, umbral_nubes=20)

Genera un reporte detallado para un año específico.

protocolo.analisis_escenas_nubosas.exportar_lista_para_procesamiento(umbral_nubes=20, tipo='envio')

Exporta listas de escenas para diferentes propósitos.

tipo:

‘envio’ - Escenas listas para enviar (normalizadas + productos) ‘productos’ - Escenas que necesitan generar productos ‘normalizacion’ - Escenas que necesitan normalizar

protocolo.coast module

class protocolo.coast.Coast(pro_escena_path, mtl_dict=None, nombre_mask=None, zona='Bonanza_Bon2_3333')

Bases: object

__init__(pro_escena_path, mtl_dict=None, nombre_mask=None, zona='Bonanza_Bon2_3333')

descargar_nivel_mar()

extraer_marea_en_hora(media_anual=5.4387)

obtener_linea_costa(mask_path)

obtener_duna_embrionaria(ndvi_path)

graficar_nivel_mar_diario(save_path=None, media_anual=5.4387)

run()

protocolo.config module

Configuration module for loading environment variables. This module uses python-dotenv to load variables from a .env file.

protocolo.config.validate_config()

Validate that critical environment variables are loaded.

protocolo.download module

protocolo.envio_escenas_nubosas module

protocolo.envio_escenas_nubosas.verificar_normalizacion(escena_name, ruta_nor)

Verifica que una escena esté normalizada. Retorna True si tiene archivos .tif normalizados, False en caso contrario.

protocolo.envio_escenas_nubosas.copiar_productos_a_servidores(escena_name, ruta_pro_escena)

Copia los productos de una escena a los servidores remotos. Replica la lógica de movidas_de_servidores() de productos.py

protocolo.envio_escenas_nubosas.buscar_y_enviar_escenas_nubosas(umbral_nubes=30, anios=None, modo_prueba=True)

Busca en MongoDB escenas con cloud_RBIOS > umbral_nubes que estén normalizadas y las envía a los servidores.

Parameters:

• umbral_nubes – Porcentaje mínimo de nubes (default: 30)

• anios – Lista de años a procesar (None = todos)

• modo_prueba – Si True, solo muestra lo que haría sin enviar

protocolo.envio_escenas_nubosas.listar_escenas_por_anio(umbral_nubes=30)

Lista las escenas con >umbral_nubes% agrupadas por año. Útil para decidir qué años procesar.

protocolo.hidroperiodo module

protocolo.hidroperiodo.get_escenas_values(path)

Calcula los valores en días para cada escena dentro de un ciclo hidrológico.

Este método genera un diccionario con las escenas como claves y los días asignados como valores. Estos valores se calculan basados en el inicio de un ciclo hidrológico (1 de septiembre).

Parameters:

path (str) – Ruta al directorio que contiene las escenas (archivos .tif).

Returns:

Un diccionario que asigna un valor en días a cada escena.

Return type:

dict

protocolo.hidroperiodo.get_hydroperiod(path, values)

Genera los productos intermedios de inundación, sequía y días válidos para cada escena.

Este método toma los archivos .tif de escenas y genera tres productos intermedios: - flood_rec: Inundación (días de inundación) - dry_rec: Sequía (días secos) - valid_rec: Días válidos (suma de días de inundación y sequía)

Parameters:

• path (str) – Ruta al directorio que contiene las escenas (archivos .tif).

• values (dict) – Diccionario de valores en días para cada escena, generado por get_escenas_values.

protocolo.hidroperiodo.get_products(path)

Genera el hidroperiodo y los días válidos acumulados de todas las escenas.

Este método combina todas las escenas procesadas en get_hydroperiod para calcular dos productos finales: - hydroperiod.tif: Muestra el número total de días de inundación a lo largo de todas las escenas. - valid_days.tif: Muestra el número total de días válidos (inundación + sequía) a lo largo de todas las escenas.

Parameters:

path (str) – Ruta al directorio que contiene los archivos intermedios (_flood_rec.tif, _valid_rec.tif).

protocolo.hidroperiodo.get_normalized_365(path)

Genera el hidroperiodo normalizado a 365 días.

Utiliza los productos hydroperiod.tif y validdays.tif para generar el hidroperiodo normalizado en el que el 100% equivale a 365 días de inundación.

Parameters:

path (str) – Ruta al directorio que contiene los archivos intermedios hydroperiod.tif y valid_days.tif.

protocolo.proceso_automatico_completo module

protocolo.productos module

protocolo.protocolov2 module

class protocolo.protocolov2.Landsat(ruta_escena, inicializar=True)

Bases: object

Handles USGS Landsat Collection 2 Level-2 Surface Reflectance products.

This class provides tools for preprocessing Landsat images, including cloud masking, radiometric calibration, thermal correction, reprojection, and normalization using pseudo-invariant features (PIFs). It also organizes the output into a structured folder hierarchy and inserts metadata into MongoDB.

The class is designed to work with Collection 2 products from Landsat 5, 7, 8, and 9.

See also

__init__

Initializes scene attributes, reads MTL metadata, creates output folders, and prepares MongoDB insertion document.

__init__(ruta_escena, inicializar=True)

Initialize a Landsat object from a given scene path.

This constructor parses the scene’s directory and metadata, identifies the sensor type, sets up internal paths, downloads the quicklook image, and uploads initial metadata to the MongoDB database. If inicializar is False, only basic attributes are set without accessing files or the database.

Parameters:

• ruta_escena (str) – Path to the directory containing the original downloaded Landsat scene.

• inicializar (bool, optional) – Whether to perform full initialization, including metadata parsing, folder creation, and MongoDB insertion (default is True).

escena

Scene folder name extracted from the given path.

Type:

str

last_name

Internal ID for the scene, used as MongoDB _id, based on date, sensor, path and row.

Type:

str

sensor

Sensor name, one of ‘OLI’, ‘ETM+’, or ‘TM’.

Type:

str

path

Path value extracted from the scene ID (3 digits).

Type:

str

row

Row value extracted from the scene ID (2 digits, zero-padded).

Type:

str

base, ori, pro, geo, rad, nor, data, temp

Paths to the root folder and its subdirectories.

Type:

str

pro_escena, geo_escena, rad_escena, nor_escena

Scene-specific folders for storing outputs.

Type:

str

mtl

Dictionary with parsed metadata from the MTL file.

Type:

dict

bandas_normalizadas

List of spectral bands successfully normalized for this scene.

Type:

list of str

cloud_mask_values

Values used to identify cloud or fill pixels, depending on the sensor.

Type:

list of int

qk_name

Path to the downloaded Landsat quicklook JPEG.

Type:

str

pn_cover

Percentage of cloud cover over Doñana, set later in processing.

Type:

float or None

newesc

Document inserted into MongoDB with basic scene metadata and processing info.

Type:

dict

get_hillshade()

Generate a hillshade raster using a fixed DTM and scene solar metadata.

This method uses the solar azimuth and elevation values from the scene’s MTL file to compute a hillshade raster from a pre-defined Digital Terrain Model (DTM) specific to path/row 202/034. The result is saved in the nor folder of the scene.

Raises:

RuntimeError – If the gdaldem hillshade command fails during execution.

get_cloud_pn()

Calculate the cloud coverage percentage over Doñana National Park.

This method uses the QA_PIXEL cloud mask and a shapefile representing the boundaries of Doñana National Park to compute the percentage of valid pixels (i.e., clear land or clear water) within the park. The result is stored in the MongoDB document under the field cloud_PN.

Raises:

• RuntimeError – If the gdalwarp command fails during execution.

• Exception – If an error occurs while updating the MongoDB document.

get_cloud_rbios()

Calculate the cloud coverage percentage over the Doñana Biosphere Reserve.

This method uses the QA_PIXEL cloud mask and a shapefile representing the boundaries of the Doñana Biosphere Reserve to compute the percentage of valid pixels (i.e., clear land or clear water) within the reserve. The result is stored in the MongoDB document under the field Clouds.cloud_RBIOS.

The calculation is performed by: 1. Clipping the QA_PIXEL band to the Biosphere Reserve boundaries 2. Counting pixels classified as clear land (21824/5440) or clear water (21952/5504) 3. Computing the percentage of cloud-free area

Notes

The area constant (RBIOS_AREA) must be adjusted to match the actual area of the RBIOS.shp shapefile in square meters.

Raises:

• RuntimeError – If the gdalwarp command fails during execution.

• Exception – If an error occurs while updating the MongoDB document.

See also

get_cloud_pn

Calculate cloud coverage over Doñana National Park.

remove_masks()

Delete temporary cloud mask files generated during processing.

This method removes all files inside the masks/ subfolder of the Landsat scene directory and then deletes the folder itself. It is typically called after cloud coverage has been calculated and the intermediate mask files are no longer needed.

Raises:

OSError – If any file or the masks/ folder cannot be deleted.

apply_gapfill()

Apply gap-filling to Landsat 7 bands acquired after June 2003.

This method detects if the input scene corresponds to Landsat 7 after the Scan Line Corrector (SLC) failure (June 2003). If so, it uses GDAL’s FillNodata algorithm to interpolate missing pixels (gaps) in each reflectance band.

The method only processes the following bands: blue, green, red, nir, swir1, and swir2.

Raises:

RuntimeError – If a band cannot be opened or processed during the gap-filling operation.

projwin()

Apply projection, resolution, and geographic extent to all valid bands.

This method uses gdalwarp to reproject the reflectance and thermal bands to a common spatial reference system, apply a standard 30-meter resolution, and clip them to a predefined extent defined by a WRS-2 shapefile. It accounts for differences in band naming between OLI (Landsat 8/9) and TM/ETM+ (Landsat 4/5/7) sensors.

The output files are saved in the geo directory of the scene.

Raises:

RuntimeError – If any band fails to process during the reprojection or clipping steps.

coef_sr_st()

Apply surface reflectance and land surface temperature coefficients to image bands.

This method scales the radiometrically corrected bands using standard coefficients to produce physically meaningful values:

• Reflectance bands (blue, green, red, NIR, SWIR1, SWIR2) are rescaled to the [0, 1] range.

• The thermal band (LST) is converted from digital numbers to degrees Celsius.

• The fmask (cloud mask) band is copied directly without modification.

The processed bands are saved in the rad (radiometric correction) and pro (final products) directories.

Raises:

RuntimeError – If any band cannot be processed or written to disk.

normalize()

Perform full band normalization using invariant areas and cloud masking.

This method normalizes all spectral bands by comparing them with a reference image over predefined pseudo-invariant features (PIFs). It applies cloud masking and iteratively adjusts regression parameters to meet quality thresholds.

For each band: - Calls nor1() to compute regression parameters. - If parameters satisfy quality criteria (R² > 0.85 and at least 10 valid pixels per invariant area), normalization is applied using nor2l8(). - Normalization parameters and diagnostics are saved and stored in MongoDB.

Outputs

• Normalized bands saved in nor_escena with _grn2_ suffix.

• Diagnostic plots and normalization logs.

• A coeficientes.txt file with per-band regression statistics.

• Normalization metadata inserted into MongoDB.

raises RuntimeError:

If normalization fails for one or more bands.

nor1(banda, mascara, coef=1)

Perform linear normalization on a single band using pseudo-invariant areas (PIFs).

This method compares a target image band with its homologous band from a fixed reference scene (e.g., August 2022) using only pixels that are cloud-free and fall within predefined regions of interest defined in the PIFs mask.

It performs a first linear regression, computes residuals, and removes outliers based on a standard deviation threshold multiplied by coef. A second regression is then fitted to the filtered data.

If the second regression meets quality criteria (R > 0.85 and at least 10 valid pixels per class), the slope and intercept are stored, and the normalized image is subsequently generated via nor2l8().

Parameters:

• banda (str) – Path to the input image band to be normalized.

• mascara (str) – Path to the PIFs mask image (e.g., Equilibrada.tif, NoEquilibrada.tif).

• coef (int, optional) – Multiplier for the standard deviation of residuals used to filter outliers in the second regression. Default is 1.

• Results

• -------

• self.parametrosnor. (- Regression coefficients and pixel counts are saved to)

• met. (- Normalized image is generated via nor2l8() if criteria are)

• regressions. (- Diagnostic plots are produced comparing both)

nor2l8(banda, slope, intercept)

Apply a linear normalization equation to a Landsat band and save the output raster.

This method applies a linear transformation to a reflectance-corrected Landsat band using a given slope and intercept from a regression model. It ensures that pixel values remain within the valid range and that NoData values are preserved.

The normalized raster is saved with _grn2_ in the filename and stored in the corresponding nor_escena folder.

Parameters:

• banda (str) – Path to the input raster file to be normalized.

• slope (float) – Regression slope to apply in the normalization equation.

• intercept (float) – Regression intercept to apply in the normalization equation.

Notes

• Output values below 0 are clipped to 0.

• Output values equal to or above 1 are clipped to 1.

• NoData values (-9999) in the input are preserved in the output.

run()

Execute the complete Landsat scene processing workflow.

This method orchestrates the full processing pipeline for a USGS Landsat Collection 2 Level-2 scene. It assumes all required input files (bands, metadata, masks, etc.) are present and correctly structured in the scene directory.

The steps performed are:

1. Generate a hillshade image using DTM and solar angles.

2. Compute cloud coverage within Doñana National Park.

3. Compute cloud coverage within Doñana Biosphere Reserve.

4. Delete temporary cloud mask files.

5. Apply gap-filling (only for Landsat 7 scenes post-SLC failure).

6. Reproject and clip spectral bands to a standard extent.

7. Apply surface reflectance and temperature coefficients.

8. Normalize all bands using pseudo-invariant features (PIFs) and a reference image.

Outputs are stored in the appropriate subdirectories: pro (products), geo (georeferenced), rad (radiometrically corrected), and nor (normalized).

The method also updates MongoDB with relevant metadata and processing results.

Prints

Completion message and total execution time.

raises RuntimeError:

If any critical step in the pipeline fails.

protocolo.utils module