Functions
void	freeRawData (struct rawData *data)
	Free encapsulated fields of raw data struct.
void	freeAverageData (struct averagedData *data)
	Free encapsulated fields of averaged data struct.
int	readRasterDataset (GDALDatasetH raster, struct rawData *dataBuffer)
	Read all bands of an GDAL raster dataset into a buffer.
int	averageRawData (const struct rawData data, struct averagedData average)
	Compute arithmetic mean pixel values across raster band dimension for all bands.
int	averageRawDataWithSizeOffset (const struct rawData data, struct averagedData average, const size_t size, const size_t offset)
	Compute arithmetic mean pixel values across raster band dimension for a subset of bands.
int	averagePILRawDataWithSizeOffset (const struct rawData data, struct averagedData average, const size_t size, const size_t offset)
	Compute arithmetic mean pixel values across raster band dimension for a subset of bands.
int	reorderToBandInterleavedByPixel (struct rawData *data)
	Transpose data tensor from band sequential to band interleaved by pixel.
OGRGeometryH	mergeFootprintSplitAtDateline (const OGRGeometryH splitFootprint)
	Shift and merge a Multipolygon split at the dateline.
meanVector *	calculateAreaWeightedMean (intersectionVector intersections, const char rasterWkt, const bool geometriesAreFootprints, const bool useFastGeodesicAreaCalculation)
	Compute area weighted mean for features of AOI dataset.
int	writeWeightedMeans (meanVector values, const char filePath)
	Write area weighted means to file in format usable by FORCE.
double	coordinateFromCell (double origin, double axisOfInterest, double pixelExtent, double complementaryAxis, double rotation)
	Compute corner coordinates of raster cell based on geo transformation.
stringList *	parseLogFile (const char *filePath)
	Parse logfile for processing.
int	writeUpdatedLogFile (stringList list, const char filePath)
	Update logfile with new dataset statuses.
int	backFillOptions (option_t *options, GDALDatasetH dataset)
	Deduce temporal information from a given dataset.
int	process (option_t *options)
	Main procedure to process downloaded ERA-5 datasets.

Detailed Description

Function Documentation

◆ averagePILRawDataWithSizeOffset()

int averagePILRawDataWithSizeOffset	(	const struct rawData *	data,
		struct averagedData *	average,
		const size_t	size,
		const size_t	offset )

Compute arithmetic mean pixel values across raster band dimension for a subset of bands.

This function allows to average a subset of bands pointed to by data by starting from offset up to but not including offset + size.

Note: Assumes data is ordered as column -> row -> band, i.e. band interleaved by pixel.; After the function returns, the caller owns the dataBuffer object and musst free it after use.

Parameters

data	Reference to structure holding data.
average	Indirect reference to structure where averaged values are stored.
size	Size of window to use for arithmetic mean calculation.
offset	Starting band.

Returns: int 0 on success, 1 on error.

◆ averageRawData()

int averageRawData	(	const struct rawData *	data,
		struct averagedData *	average )

Compute arithmetic mean pixel values across raster band dimension for all bands.

Note: Assumes data is ordered as band -> column -> row (see internal offset calculations).; After the function returns, the caller owns the dataBuffer object and musst free it after use.

Parameters

data	Raw data struct.
average	Averaged data struct to store data in.

Returns: int 0 on success, 1 on error.

◆ averageRawDataWithSizeOffset()

int averageRawDataWithSizeOffset	(	const struct rawData *	data,
		struct averagedData *	average,
		const size_t	size,
		const size_t	offset )

Compute arithmetic mean pixel values across raster band dimension for a subset of bands.

This function allows to average a subset of bands pointed to by data by starting from offset up to but not including offset + size.

Note: Assumes data is ordered as band -> column -> row, i.e. band sequential.; After the function returns, the caller owns the dataBuffer object and musst free it after use.

Parameters

data	Reference to structure holding data.
average	Indirect reference to structure where averaged values are stored.
size	Size of window to use for arithmetic mean calculation.
offset	Starting band.

Returns: int 0 on success, 1 on error.

◆ backFillOptions()

int backFillOptions	(	option_t *	options,
		GDALDatasetH	dataset )

Deduce temporal information from a given dataset.

This function deduces temoporal information (contained years, months, days and hours) of a given dataest by reading the metadata from all bands and counting observed values.

Note: The options struct is manipulated by this function; assumes files contain only a single year and a single month, thus only storing arbitrary days and hours combinations.

Parameters

CLI Arguments Parsing and Program Setup	Reference to parsed options, without temoporal information fields set.
dataset	Opened GDAL dataset, from which temoporal information should be read.

Returns: 0 on success, 1 on error.

◆ calculateAreaWeightedMean()

meanVector * calculateAreaWeightedMean	(	intersectionVector *	intersections,
		const char *	rasterWkt,
		const bool	geometriesAreFootprints,
		const bool	useFastGeodesicAreaCalculation )

nodiscard

Compute area weighted mean for features of AOI dataset.

This functions iterates over all features in intersections, computes their centroid coordinates and, depending on the version of GDAL used, the geographic or planar area. All intersecting geometries extracted from an STRTree are converted from GEOS geometries to OGR geometries via the WKB import/export interface. The actual intersection is performed without regards to underlying CRS, though the newly created polygon is assigned the spatial reference derived from rasterWkt. The error introduced by assuming planar geometries should be small. Area calculation is performed, depending on the version of GDAL used, differently depending of the CRS type (geographic vs. planar). A weight equal to the fractional cover of the intersecting geometry to the AOI feature is computed and used to calculate an area weighted arithmetic mean.

Warning: Only use with wkbPolygon, wkbPolygon25D, wkbMultiPolygon, wkbMultiPolygon25D.

Note: With GDAL >= 3.9.0, area calculation of geographic coordinates is correct. Otherwise, planar geometries are assumed.; Intersection of geometries is performed assuming planar geometries in all cases.; After the function returns, the caller owns the returned object and musst free it.; Outputs intersection geometries in debug builds in a GeoPackage in the current working directory.

Parameters

intersections	Vector containing AOI features and all vectorized raster cells that intersect a given feature.
rasterWkt	CRS in WKT representation of raster dataset.
geometriesAreFootprints	Boolean indicating if geometries represent footprints and should be merged if cut at dateline.
useFastGeodesicAreaCalculation	Use fast implementations for geodesic area calculation. Should only be used when sure that input geometries are already in a CRS that directly allows geodesic caclulations. See fastGeodesicArea() for further details on the imposed limitations.

Returns: mean_t* Reference to vector containing centroids of AOI geometries and associated water column value, NULL on error.

◆ coordinateFromCell()

double coordinateFromCell	(	double	origin,
		double	axisOfInterest,
		double	pixelExtent,
		double	complementaryAxis,
		double	rotation )

Compute corner coordinates of raster cell based on geo transformation.

Computes the x/y coordinate given pixel/line index and a geo transformation. The axis of interest refers to the axis whose coordinate should be computed and influences which coordinate is used as the origin. I.e. to compute the x coordinate of the upper-left pixel, the origin must refer to x coordinate, the axis of interest to the columnn index 0, the pixel extent to the width of the pixel, the complementary axis to the row index and the rotation to the row rotation.

Note: GDAL uses the upper-left corner of a pixel as its origin, mapping the upper-left pixel to cell (0, 0). To get the center coordinate, one would need to use (0.5, 0.5)

Parameters

origin	Origin coordinate of upper-left pixel in direction of requested coordinate dimension.
axisOfInterest	Index in direction of requested coordinate dimension.
pixelExtent	Pixel extent in CRS units in direction of requested coordinate dimension.
complementaryAxis	Index in direction of complementary coordinate dimension.
rotation	Rotation of complementary axis.

Returns: double Georeferenced coordinate value in direction of requested coordinate dimension.

◆ freeAverageData()

void freeAverageData ( struct averagedData * data )

Free encapsulated fields of averaged data struct.

Parameters

data	Object to free.

◆ freeRawData()

void freeRawData ( struct rawData * data )

Free encapsulated fields of raw data struct.

Parameters

data	Object to free.

◆ mergeFootprintSplitAtDateline()

OGRGeometryH mergeFootprintSplitAtDateline ( const OGRGeometryH splitFootprint )

nodiscard

Shift and merge a Multipolygon split at the dateline.

If input geometries represent satellite scene footprints and are split at the the dateline, the centroid computation using OGR_G_Centroid returns a wrong result because the returned point is not guarantueed to lie within the geometry. To mitigate this issue, a similar approach is implemented to sf::st_shift_longitude (https://r-spatial.github.io/sf/reference/st_shift_longitude.html) from the sf package for R by shifting all vertices whose longitudinal value is < 0° by +360° and computing the unsion of the new sub-geometries to obtain a "normal" polygon.

Parameters

splitFootprint Const reference to geometry object.

Returns: Reference to newly created, merged geometry (extending beyond +180°), NULL on error.

◆ parseLogFile()

stringList * parseLogFile ( const char * filePath )

Parse logfile for processing.

This function reads lines of the log file sequentially, extracting the the file path of respective ERA-5 dataset and processing status. It's assuming the format mentioned below. The order of lines in the log file are preserved in the returned linked list to keep diffs between program runs minimal.

Note: The log file's format is "<file path>\tSTATUS".

Parameters

filePath File path to logfile.

Returns: Reference to linked list storing one line per node, possibly NULL on error.

◆ process()

int process ( option_t * options )

Main procedure to process downloaded ERA-5 datasets.

This function implements processing ERA-5 datasets to a water vapor database usable by FORCE. Each unprocessed dataset is scanned to deduce temporal information stored in it, averaged on a daily basis, vectorized and stored in a STRTree. The supplied vector dataset containing the area of interest is converted to GEOS geometries once and possibly reprojected to EPSG:4326. Intersections between vectorized ERA-5 data and AOI are used to compute area-weighted mean of water vapor, whereby a single geometry entry in the AOI is used to compute weight values.

Note: The SRS of input files is hardcoded to EPSG:4326 as ECMWF is aligned to it horizontally. Should this change in the future, this procedure would need to be updated.

Parameters

CLI Arguments Parsing and Program Setup Reference to parsed options struct.

Returns: 0 on success, 1 on error.

◆ readRasterDataset()

int readRasterDataset	(	GDALDatasetH	raster,
		struct rawData *	dataBuffer )

Read all bands of an GDAL raster dataset into a buffer.

Note: This function returns an error if inputs are not of type double/GDT_FLOAT64.; After the function returns, the dataBuffer object contains a heap-allocated buffer and the caller musst free it after use.

Parameters

raster	Opened raster dataset.
dataBuffer	Reference to raw data buffer.

Returns: 0 on success, 1 on error.

◆ reorderToBandInterleavedByPixel()

int reorderToBandInterleavedByPixel ( struct rawData * data )

Transpose data tensor from band sequential to band interleaved by pixel.

Parameters

data	Reference to structure holding data.

Returns: int 0 on success, 1 on error.

◆ writeUpdatedLogFile()

int writeUpdatedLogFile	(	stringList *	list,
		const char *	filePath )

Update logfile with new dataset statuses.

Note: The log file's format is "<file path>\tSTATUS".

Parameters

list	Linked list storing one line per node with file path of ERA-5 dataset and processing status.
filePath	File path to logfile.

Returns: int 0 on success, 1 on error.

◆ writeWeightedMeans()

int writeWeightedMeans	(	meanVector *	values,
		const char *	filePath )

Write area weighted means to file in format usable by FORCE.

Parameters

values	vector containing centroids of AOI geometries and associated water column value.
filePath	Path to output file.

Returns: in 0 on success, 1 on error.

Functions

Detailed Description

Function Documentation

◆ averagePILRawDataWithSizeOffset()

◆ averageRawData()

◆ averageRawDataWithSizeOffset()

◆ backFillOptions()

◆ calculateAreaWeightedMean()

◆ coordinateFromCell()

◆ freeAverageData()

◆ freeRawData()

◆ mergeFootprintSplitAtDateline()

◆ parseLogFile()

◆ process()

◆ readRasterDataset()

◆ reorderToBandInterleavedByPixel()

◆ writeUpdatedLogFile()

◆ writeWeightedMeans()