radolan

README

radolan

Go package radolan parses the DWD RADOLAN / RADVOR radar composite format.

This format is used by the DWD for weather radar data.

The obtained results can be processed and visualized with additional functions. The example program radolan2png is included to quickly convert composite files to png images.

This library was developed for Regenampel.de, but offers even more features for awesome ideas and projects.

Besides local scans, the following grids are currently supported:

• National Grid (900km x 900km)
• National Picture Grid (920km x 920km)
• Extended National Grid (900km x 1100km)
• DE1200 National Grid (1100km x 1200km)
• Middle-European Grid (1400km x 1500km)

Tested input products:

Product	Grid	Description
EX	middle-european	reflectivity
FX	national	nowcast reflectivity
FZ	national	nowcast reflectivity
PE	local	echo top
PF	local	reflectivity
PG	national picture	reflectivity
PR	local	doppler radial velocity
PX	local	reflectivity
PZ	local	3D reflectivity CAPPI
RW	national	hourly accumulated
RX	national	reflectivity
SF	national	daily accumulated
WX	extended national	reflectivity
WN	DE1200 Sphere	nowcast reflectivity
WN	DE1200 WGS84	nowcast reflectivity

Those can be considered working with sufficient accuracy. Other formats might be working (not tested).

Documentation

Documentation is included in the corresponding source files and also available at https://godoc.org/gitlab.cs.fau.de/since/radolan

Installation

mkdir -p ~/go/src ~/go/pkg ~/go/bin
GOPATH="~/go" go get gitlab.cs.fau.de/since/radolan/radolan2png

Sample image

This image shows radar reflectivity (dBZ) captured 31.07.2016 18:50 CEST

Datenbasis: Deutscher Wetterdienst, Radardaten bildlich wiedergegeben

Documentation

Overview

Package radolan parses the DWD RADOLAN / RADVOR radar composite format. This data is available at the Open Data Portal (https://www.dwd.de/DE/leistungen/opendata/opendata.html). The obtained results can be processed and visualized with additional functions.

Tested input products and grids:

| Product | Grid              | Description             |
| ------- | ----------------- | ----------------------- |
| EX      | middle-european   | reflectivity            |
| FX      | national          | nowcast reflectivity    |
| FZ      | national          | nowcast reflectivity    |
| PE      | local             | echo top                |
| PF      | local             | reflectivity            |
| PG      | national picture  | reflectivity            |
| PR      | local             | doppler radial velocity |
| PX      | local             | reflectivity            |
| PZ      | local             | 3D reflectivity CAPPI   |
| RW      | national          | hourly accumulated      |
| RX      | national          | reflectivity            |
| SF      | national          | daily accumulated       |
| WX      | extended national | reflectivity            |

Those can be considered working with sufficient accuracy.

In cases, where the publicly available format specification is unprecise or contradictory, reverse engineering was used to obtain reasonable approaches.

Used references:

[1] https://www.dwd.de/DE/leistungen/radolan/radolan_info/radolan_radvor_op_komposit_format_pdf.pdf
[2] https://www.dwd.de/DE/leistungen/gds/weiterfuehrende_informationen.zip
[3] https://www.dwd.de/DE/leistungen/radarprodukte/formatbeschreibung_fxdaten.pdf
[4] https://www.dwd.de/DE/leistungen/opendata/help/radar/radar_pg_coordinates_pdf.pdf
[5] https://www.dwd.de/DE/leistungen/radarniederschlag/rn_info/download_niederschlagsbestimmung.pdf
[6] https://www.dwd.de/DE/leistungen/radarprodukte/formatbeschreibung_wndaten.pdf
[7] hex editor and much reverse engineering

Index

• Constants
• Variables
• func IsNaN(f float32) (is bool)
• func PrecipitationRate(relation ZR, dBZ float32) (rate float64)
• func Reflectivity(relation ZR, rate float64) (dBZ float32)
• type Composite
  • func NewComposite(rd io.Reader) (comp *Composite, err error)
  • func NewComposites(rd io.Reader) ([]*Composite, error)
  • func NewDummy(product string, format, dx, dy int) (comp *Composite)
  • func (c *Composite) At(x, y int) float32
  • func (c *Composite) AtZ(x, y, z int) float32
  • func (c *Composite) Project(north, east float64) (x, y float64)
• type Unit
  • func (u Unit) String() string
• type ZR
  • func NewZR(A, B float64) ZR

Constants

const (
	Unit_unknown = iota
	Unit_mm      // mm/interval
	Unit_dBZ     // dBZ
	Unit_km      // km
	Unit_mps     // m/s
)

const (
	DE1200Grid grid // resolution: 1100km * 1200km

)

Variables

var (
	Aniol80          = NewZR(256, 1.42) // operational use in germany, described in [5]
	Doelling98       = NewZR(316, 1.50) // operational use in switzerland
	JossWaldvogel70  = NewZR(300, 1.50)
	MarshallPalmer55 = NewZR(200, 1.60) // operational use in austria
)

Common Z-R relationships

var ErrUnknownUnit = newError("NewComposite", "data unit not defined in catalog. data values can be incorrect")

ErrUnknownUnit indicates that the unit of the radar data is not defined in the catalog. The data values can be incorrect due to unit dependent conversions during parsing. Be careful when further processing the composite.

var NaN = float32(math.NaN())

Functions

func IsNaN

func IsNaN(f float32) (is bool)

func PrecipitationRate

func PrecipitationRate(relation ZR, dBZ float32) (rate float64)

PrecipitationRate returns the estimated precipitation rate in mm/h for the given reflectivity factor and Z-R relationship.

func Reflectivity

func Reflectivity(relation ZR, rate float64) (dBZ float32)

Reflectivity returns the estimated reflectivity factor for the given precipitation rate (mm/h) and Z-R relationship.

Types

type Composite

type Composite struct {
	Product string // composite product label

	CaptureTime  time.Time     // time of source data capture used for forcasting
	ForecastTime time.Time     // data represents conditions predicted for this time
	Interval     time.Duration // time duration until next forecast

	DataUnit Unit

	PlainData [][]float32 // data for parsed plain data element [y][x]
	Px        int         // plain data width
	Py        int         // plain data height

	DataZ [][][]float32 // data for each voxel [z][y][x] (composites use only one z-layer)
	Data  [][]float32   // data for each pixel [y][x] at layer 0 (alias for DataZ[0][x][y])

	Dx int // data width
	Dy int // data height
	Dz int // data layer

	Rx float64 // horizontal resolution in km/px
	Ry float64 // vertical resolution in km/px

	HasProjection bool // coordinate projection available

	Format int // Version Format
	// contains filtered or unexported fields
}

Radolan radar data is provided as single local sweeps or so called composite formats. Each composite is a combined image consisting of mulitiple radar sweeps spread over the composite area. The 2D composite c has a an internal resolution of c.Dx (horizontal) * c.Dy (vertical) records covering a real surface of c.Dx * c.Rx * c.Dy * c.Dy square kilometers. The pixel value at the position (x, y) is represented by c.Data[ y ][ x ] and is stored as raw float value (NaN if the no-data flag is set). Some 3D radar products feature multiple layers in which the voxel at position (x, y, z) is accessible by c.DataZ[ z ][ y ][ x ].

The data value is used differently depending on the product type: (also consult the DataUnit field of the Composite)

Product label            | values represent         | unit
-------------------------+--------------------------+------------------------
 PG, PC, PX*, ...        | cloud reflectivity       | dBZ
 RX, WX, EX, FZ, FX, ... | cloud reflectivity	    | dBZ
 RW, SF,  ...            | aggregated precipitation | mm/interval
 PR*, ...                | doppler radial velocity  | m/s

The cloud reflectivity (in dBZ) can be converted to rainfall rate (in mm/h) via PrecipitationRate().

The cloud reflectivity factor Z is stored in its logarithmic representation dBZ:

dBZ = 10 * log(Z)

Real world geographical coordinates (latitude, longitude) can be projected into the coordinate system of the composite by using the projection method:

// if c.HasProjection
x, y := c.Project(52.51861, 13.40833)	// Berlin (lat, lon)

dbz := c.At(int(x), int(y))					// Raw value is Cloud reflectivity (dBZ)
rat := radolan.PrecipitationRate(radolan.Doelling98, dbz)	// Rainfall rate (mm/h) using Doelling98 as Z-R relationship

fmt.Println("Rainfall in Berlin [mm/h]:", rat)

func NewComposite

func NewComposite(rd io.Reader) (comp *Composite, err error)

NewComposite reads binary data from rd and parses the composite. An error is returned on failure. When ErrUnknownUnit is returned, the data values can be incorrect due to unit dependent conversions during parsing. In this case be careful when further processing the composite.

func NewComposites

func NewComposites(rd io.Reader) ([]*Composite, error)

NewComposites reads .tar.bz2 data from rd and returns the parsed composites sorted by ForecastTime in ascending order.

func NewDummy

func NewDummy(product string, format, dx, dy int) (comp *Composite)

NewDummy creates a blank dummy composite with the given product label, format version, and dimensions. It can be used for generic coordinate projection.

func (*Composite) At

func (c *Composite) At(x, y int) float32

At is shorthand for c.Data[y][x] and returns the radar video processor value at the given point. NaN is returned, if no data is available or the requested point is located outside the scanned area.

func (*Composite) AtZ

func (c *Composite) AtZ(x, y, z int) float32

AtZ is shorthand for c.DataZ[z][y][x] and returns the radar video processor value at the given point. NaN is returned, if no data is available or the requested point is located outside the scanned volume.

func (*Composite) Project

func (c *Composite) Project(north, east float64) (x, y float64)

Project transforms geographical coordinates (latitude north, longitude east) to the according data indices in the coordinate system of the composite. NaN is returned when no projection is available. Procedures adapted from [1] and [6].

type Unit

type Unit int

func (Unit) String

func (u Unit) String() string

type ZR

type ZR struct {
	// contains filtered or unexported fields
}

Z-R relationship

func NewZR

func NewZR(A, B float64) ZR

New Z-R returns a Z-R relationship mathematically expressed as Z = a * R^b