#!/usr/bin/env python

# -*- coding: utf-8 -*-

"""

MODULE: i.worldview.toar

AUTHOR: Nikos Alexandris <nik@nikosalexandris.net>

Converted from a bash shell script | Trikala, November 2014

PURPOSE: Converting WorldView2 DN values to Spectral Radiance or

Reflectance

From the document:

<< Whether the final bit depth is 16 or 8 bits, the goal of the

radiometric correction, other than minimize image artifacts,

is to scale all image pixels to top-of-atmosphere spectral

radiance so that one absolute calibration factor can be applied

to all pixels in a given band.

- - - - - - - - - -

The absolute radiometric calibration factor is dependent on the

specific band, as well as the TDI exposure level, line rate,

pixel aggregration, and bit depth of the product. Based on

these parameters, the appropriate value is provided in the

.IMD file. For this reason, care should be taken not to mix

absolute radiometric calibration factors between products that

might have different collection conditions. >>

Spectral Radiance -------------------------------------------

L(λ|Pixel, Band) = K(Band) * q(Pixel, Band) / Δ(λ|Band)

where:

L(λ): Top-of-Atmosphere Spectral Radiance image pixels

[W/sq.m./sr/μm]

KBand: absolute radiometric calibration factor

[W/sq.m./sr/count] for a given band

q(Pixel,Band): radiometrically corrected image pixels

[countsor or Digital Numbers]

Δ(λ|Band): effective bandwidth [μm] for a given band.

Planetary Reflectance ---------------------------------------

ρ(p) = π x L(λ) x d^2 / ESUN(λ) x cos(θ(S))

where:

- ρ: Unitless Planetary Reflectance

- π: Mathematical constant

- L(λ): Spectral Radiance from equation (1)

- d: Earth-Sun distance in astronomical units

[calculated using AcquisitionTime class]

Sources -----------------------------------------------------

- Radiometric Use of WorldView-2 Imagery, Technical Note (2010),

by Todd Updike & Chris Comp.

- <http://landsat.usgs.gov/how_is_radiance_calculated.php>

COPYRIGHT: (C) 2014 by the GRASS Development Team

This program is free software under the GNU General Public

License (>=v2). Read the file COPYING that comes with GRASS

for details.

"""

#%Module

#% description: Converting WorlView2 (radiometrically corrected) digital numbers to Top-of-Atmosphere Spectral Radiance or Reflectance (Krause, 2005)

#% keywords: imagery, radiometric conversion, radiance, reflectance, WorldView2

#%End

#%flag

#% key: r

#% description: Convert to at-sensor spectral radiance

#%end

#%flag

#% key: k

#% description: Keep current computational region settings

#%end

#%flag

#% key: i

#% description: Print out coversion formulas (Krause, 2005)

#%end

#%option G_OPT_R_INPUTS

#% key: band

#% key_desc: band name

#% type: string

#% label: WorldView2 band

#% description: WorldView2 acquired spectral band(s) (DN values)

#% multiple: yes

#% required: yes

#%end

#%option G_OPT_R_BASENAME_OUTPUT

#% key: outputsuffix

#% key_desc: suffix string

#% type: string

#% label: output file(s) suffix

#% description: Suffix for spectral radiance or reflectance output image(s)

#% required: yes

#% answer: toar

#%end

#%option

#% key: utc

#% key_desc: YYYY_MM_DDThh:mm:ss:ddddddZ; or YYYY-MM-DDThh:mm:ss:ddddddZ;

#% type: string

#% label: UTC

#% description: Coordinated Universal Time string as identified in the acquisition's metadata file (.IMD)

#% guisection: Metadata

#% required: no

#%end

#%option

#% key: doy

#% key_desc: day of year

#% type: integer

#% label: Day of Year

#% description: User defined aquisition's Day of Year (Julian Day) to calculate Earth-Sun distance. Will override UTC string input.

#% options: 1-365

#% guisection: Metadata

#% required: no

#%end

#%option

#% key: sea

#% key_desc: degrees

#% type: double

#% label: Sun Elevation Angle

#% description: Aquisition's mean sun elevation angle

#% options: 0.0 - 90.0

#% guisection: Metadata

#% required: yes

#%end

# required librairies -------------------------------------------------------

import os

import sys

sys.path.insert(1, os.path.join(os.path.dirname(sys.path[0]),

'etc', 'i.worldview.toar'))

import atexit

import grass.script as grass

from grass.pygrass.modules.shortcuts import general as g

from grass.pygrass.raster.abstract import Info

import math

from utc_to_esd import AcquisitionTime, jd_to_esd

# globals -------------------------------------------------------------------

acq_tim = ''

tmp = ''

tmp_rad = ''

tmp_toar = ''

# constants ----------------------------------------------------------------

"""

Factors for Conversion to Top-of-Atmosphere Spectral Radiance

(absolute radiometric calibration factors)

Structure of the dictionary:

- Key: Name of band

- Items in tupple(s):

- 1st: Absolute Calibration Factors

- 2nd: Spectral Band's Effective Bandwidth, Δλ

- 3rd: Band-Averaged Solar Spectral Irradiance [W/sq.m./micro-m]

Retrieving values:

band = <Name of Band>

K[band][0] # for Effective Bandwidth

K[band][1] # for Esun

K[band][2] # for Absolute Conversion Factor

"""

CF_BW_ESUN = {

'NIR2': (0.09960000, 861.2866, 0.009042234)}

spectral_bands = CF_BW_ESUN.keys()

# string for metadata

source1_rad = source1_toar = '''"Radiometric Use of WorldView-2 Imagery,

Technical Note (2010)", by Todd Updike &

Chris Comp'''

source2_rad = source2_toar = ""

# helper functions ----------------------------------------------------------

def cleanup():

grass.run_command('g.remove', flags='f', type="rast",

pattern='tmp.%s*' % os.getpid(), quiet=True)

def run(cmd, **kwargs):

""" """

grass.run_command(cmd, quiet=True, **kwargs)

def main():

flags='i')

if __name__ == "__main__":

options, flags = grass.parser()

atexit.register(cleanup)

sys.exit(main())