Header file for KNMI's sun scanning functionality. More...

#include <time.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <math.h>
#include "rave_debug.h"
#include "rave_io.h"
#include "polarscan.h"
#include "polarvolume.h"
#include "rave_object.h"
#include "rave_types.h"
#include "rave_attribute.h"
#include "rave_alloc.h"
#include "rave_list.h"

Classes
struct	scanmeta

struct	rvals

Macros
#define	HEIGMIN1 (8.0) /Minimum height for first analyses in km./

#define	HEIGMIN2 (4.0) /Minimum height for second analyses in km./

#define	RAYMIN (20.0) /Minimum length of rays for analyses in km./

#define	FRACDATA (0.70) /Fraction of rangebins passing the analyses./

#define	DBDIFX (2.0) /Maximum dev. of power from 1st fit in dB./

#define	ANGLEDIF (5.0) /Maximum dev. from calculated sun in deg./

#define	GASATTN (0.016) /Two-way gaseous attenuation in dB/km./

#define	CWIDTH (1.2) /Factor between bandwidth and 1/pulselength./

#define	WAVELENGTH (0.053) /Default wavelength in meters/

#define	ANTVEL (18.0) /Default antenna velocity in deg/s/

#define	ANTGAIN (45.0) /Default antenna gain in dB/

#define	ASTART (0.0) /Default azimuthal offset from 0 in degrees/

#define	PULSEWIDTH (2.0) /Default pulse width in microseconds/

#define	RXLOSS (0.0) /Default receiver chain loss in dB/

#define	RADCNST (64.0) /Super-arbitrary default radar constant/

#define	ONEPOL (3.01) /Losses due to one-pol RX only in dB./

#define	AVGATTN (1.39) /Averaging and overlap losses in dB for 1deg./

#define	DEG2RAD (0.017453293) /Degrees to radians./

#define	RAD2DEG (57.29578) /Radians to degrees./

#define	LSTR (128) /Length of all strings used./

#define	NELEVX (64) /Maximum number of elevations./

#define	RADIUS43 (8495.0) /Earth radius used for height calculations./

#define	EARTHRAD (6371.0) /Radius of spherical earth in km./

#define	KFACT (1.25) /K-factor in Equivalent Earth Model./

#define	N0 (313.0) /Atmospherc refractivity at the surface./

Typedefs
typedef enum ZdrType	ZdrType
	Different value types for whether ZDR is its own quantity or must be calculated.

typedef struct scanmeta	SCANMETA

typedef struct rvals	RVALS

Enumerations
enum	ZdrType { ZdrType_None = 0 , ZdrType_READ = 1 , ZdrType_CALCULATE = 2 }
	Different value types for whether ZDR is its own quantity or must be calculated. More...

Functions
int	getDoubleAttribute (RaveCoreObject obj, const char aname, double *tmpd)
	Returns a double attribute value from any polar object type.

int	getDoubleArrayAttribute (PolarScan_t scan, const char aname, double *array, PolarScanParam_t param)
	Returns a double attribute array from a polar scan object.

void	fill_toplevelmeta (RaveCoreObject object, SCANMETA meta)
	Reads metadata into the SCANMETA structure from top-level object, whether it be volume or scan, where required metadata are located in top-level 'how'.

void	fill_meta (PolarScan_t scan, PolarScanParam_t dbzh, SCANMETA *meta)
	Reads metadata into the SCANMETA structure from volume, scan, param.

double	ElevHeig2Rang (double elev, float heig)
	This function calculates the height and range from the Radar corresponding to a point with a known elevation and on-ground distance from the Radar.

void	datetime (long date1, long time1, long ss, long date2, long time2)
	This function returns the date/time of (date1,time1) and 'ss' later.

double	refraction (double *elev)
	This function calculates the refraction correction of the solar position.

void	solar_elev_azim (double lon, double lat, long yyyymmdd, long hhmmss, double elev, double azim, double *relev)
	This function calculates the solar elevation and azimuth using the geographical position, date, and time.

void	readoutTiming (SCANMETA meta, int ia, long date, long time, double timer)
	Determines the exact observation times based on acquired readout times for each ray.

int	processData (PolarScan_t scan, SCANMETA meta, RaveList_t *list)
	Finds sun hits in reflectivity data.

int	processScan (PolarScan_t scan, SCANMETA meta, RaveList_t *list)
	Helper function that calls processReflectivity for each of a number of given parameters/quantities.

void	outputMeta (SCANMETA *meta)
	Debug function that writes metadata to file.

int	scansunFromObject (RaveCoreObject object, Rave_ObjectType ot, RaveList_t list, char **source)
	Masterminds the scanning of polar data and determination of sun hits, from object in memory.

int	scansun (const char filename, RaveList_t list, char **source)
	Masterminds the scanning of polar data and determination of sun hits.

Detailed Description

Header file for KNMI's sun scanning functionality.

Author: Original algorithm and code: Iwan Holleman, KNMI, and Integration: Daniel Michelson, SMHI

Date: 2015-05-11

Typedef Documentation

◆ ZdrType

typedef enum ZdrType ZdrType

Different value types for whether ZDR is its own quantity or must be calculated.

Enumeration Type Documentation

◆ ZdrType

enum ZdrType

Different value types for whether ZDR is its own quantity or must be calculated.

Enumerator
ZdrType_None	Non-existant.
ZdrType_READ	ZDR is in its own quantity and can be read as such.
ZdrType_CALCULATE	Vertical reflectivity is read and ZDR needs to be calculated.

Function Documentation

◆ datetime()

void datetime	(	long	date1,
		long	time1,
		long	ss,
		long *	date2,
		long *	time2 )

This function returns the date/time of (date1,time1) and 'ss' later.

The date should be given in yyyymmhh format and the time in hhmmss format. The time lapse between the input and output date/time is given in seconds.

Parameters

[in]	date1	- long int of the input date
[in]	time1	- long int of the input time
[in]	date2	- long int of the output date
[in]	time2	- long int of the output time

Returns: nothing

◆ ElevHeig2Rang()

double ElevHeig2Rang	(	double	elev,
		float	heig )

This function calculates the height and range from the Radar corresponding to a point with a known elevation and on-ground distance from the Radar.

The formulae used are exact. For details see lab book.

Parameters

[in]	elev	- Elevation angle as a double
[in]	heig	- Height (above the radar) in meters

Returns: Range from the radar in meters, as a double

◆ fill_meta()

void fill_meta	(	PolarScan_t *	scan,
		PolarScanParam_t *	dbzh,
		SCANMETA *	meta )

Reads metadata into the SCANMETA structure from volume, scan, param.

Parameters

[in]	scan	- PolarScan_t object containing the sweep
[in]	dbzh	- PolarScanParam_t object containing the sweep's parameter
[in]	meta	- SCANMETA struct that will be filled with metadata

◆ fill_toplevelmeta()

void fill_toplevelmeta	(	RaveCoreObject *	object,
		SCANMETA *	meta )

Reads metadata into the SCANMETA structure from top-level object, whether it be volume or scan, where required metadata are located in top-level 'how'.

Parameters

[in]	object	- RaveCoreObject containing either volume or scan
[in]	meta	- SCANMETA struct that will be filled with metadata

◆ getDoubleArrayAttribute()

int getDoubleArrayAttribute	(	PolarScan_t *	scan,
		const char *	aname,
		double **	array,
		PolarScanParam_t *	param )

Returns a double attribute array from a polar scan object.

Parameters

[in]	obj	- a polar scan
[in]	aname	- a string of the attribute to retrieve
[in]	array	- the double array to retrieve
[in]	param	- if attribute not found in scan, try this parameter. May be NULL and in that case, only scan will be checked.

Returns: 1 on success or 0 if the attribute doesn't exist

◆ getDoubleAttribute()

int getDoubleAttribute	(	RaveCoreObject *	obj,
		const char *	aname,
		double *	tmpd )

Returns a double attribute value from any polar object type.

Parameters

[in]	obj	- a polar volume, scan, or scan parameter
[in]	aname	- a string of the attribute to retrieve
[in]	tmpd	- the double value to retrieve

Returns: 1 on success or 0 if the attribute doesn't exist

◆ outputMeta()

void outputMeta ( SCANMETA * meta )

Debug function that writes metadata to file.

Parameters

[in] meta - internal metadata structure

◆ processData()

int processData	(	PolarScan_t *	scan,
		SCANMETA *	meta,
		RaveList_t *	list )

Finds sun hits in reflectivity data.

Parameters

[in]	scan	- polar scan object
[in]	meta	- internal metadata structure
[in]	list	- RAVE list object containing hits

Returns: 1 upon success, otherwise 0

◆ processScan()

int processScan	(	PolarScan_t *	scan,
		SCANMETA *	meta,
		RaveList_t *	list )

Helper function that calls processReflectivity for each of a number of given parameters/quantities.

Called internally by scansun.

Parameters

[in]	scan	- polar scan object
[in]	meta	- internal metadata structure
[in]	list	- RAVE list object containing hits

Returns: 1 upon success, otherwise 0

◆ readoutTiming()

void readoutTiming	(	SCANMETA *	meta,
		int	ia,
		long *	date,
		long *	time,
		double *	timer )

Determines the exact observation times based on acquired readout times for each ray.

Parameters

[in]	meta	- internal metadata structure
[in]	the	index of the ray (azimuth), as an int
[in]	date	in the form YYYYMMDD as a long
[in]	time	in the form HHMMSS as a long
[in]	sub-second	time (r="remainder") as a double

◆ refraction()

double refraction ( double * elev )

This function calculates the refraction correction of the solar position.

The function uses the true elevation, i.e., the calculated elevation of the sun in degrees. Formulas derived from the Equivalent Earth Model are used to calculated the refraction in degrees. (Holleman & Huuskonen, 2013, Rad. Sci.)

Returns: a double containing the value of the refracted (perceived) elevation angle in degrees.

◆ scansun()

int scansun	(	const char *	filename,
		RaveList_t *	list,
		char **	source )

Masterminds the scanning of polar data and determination of sun hits.

Parameters

[in]	filename	- string containing the name (and path if somewhere else) of the file to process
[out]	list	- RaveList_t object for holding one or more sets of return values
[out]	source	- string containing the value of /what/source

Returns: 1 upon success, otherwise 0

◆ scansunFromObject()

int scansunFromObject	(	RaveCoreObject *	object,
		Rave_ObjectType	ot,
		RaveList_t *	list,
		char **	source )

Masterminds the scanning of polar data and determination of sun hits, from object in memory.

Parameters

[in]	object	- Polar scan or volume object in memory
[in]	ot	- Object type identifier enum, preferably Rave_ObjectType_SCAN or Rave_ObjectType_PVOL
[out]	list	- RaveList_t object for holding one or more sets of return values
[out]	source	- string containing the value of /what/source

Returns: 1 upon success, otherwise 0

◆ solar_elev_azim()

void solar_elev_azim	(	double	lon,
		double	lat,
		long	yyyymmdd,
		long	hhmmss,
		double *	elev,
		double *	azim,
		double *	relev )

This function calculates the solar elevation and azimuth using the geographical position, date, and time.

The equations and constants are taken from the WMO guide on Meteorological Instruments and Methods of Observations (CIMO, WMO no. 8), annex 7.D. The equations have been slightly modified and extended to include the calculation of both the sine and cosine of the azimuth. Modified slightly further to include the refracted (perceived) elevation angle.

Parameters

[in]	lon	- double containing the longitude position
[in]	lat	- double containing the latitude position
[in]	yyyymmdd	- year-month-day as a long
[in]	hhmmss	- hour-minute-second as a long
[out]	elev	- elevation angle above the horizon in degrees, as a pointer to a double
[out]	azim	- azimuth angle clockwise from true north, as a pointer to a double
[out]	relev	- refracted elevation angle, based on elev, as a pointer to a double

Returns: nothing

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ZdrType

Enumeration Type Documentation

◆ ZdrType

Function Documentation

◆ datetime()

◆ ElevHeig2Rang()

◆ fill_meta()

◆ fill_toplevelmeta()

◆ getDoubleArrayAttribute()

◆ getDoubleAttribute()

◆ outputMeta()

◆ processData()

◆ processScan()

◆ readoutTiming()

◆ refraction()

◆ scansun()

◆ scansunFromObject()

◆ solar_elev_azim()