Py6S - A Python interface to 6S¶

Py6S is a interface to the Second Simulation of the Satellite Signal in the Solar Spectrum (6S) atmospheric Radiative Transfer Model through the Python programming language. It allows you to run many 6S simulations using a simple Python syntax, rather than dealing with the rather cryptic 6S input and output files. As well as generally making it easier to use 6S, Py6S adds a number of new features including:

The ability to run many simulations easily and quickly, with no manual editing of input files
The ability to run for many wavelengths and/or angles and easily plot the results
The ability to import real-world data to parameterise 6S, such as radiosonde measurements, AERONET sun photometer measurements and ground reflectance spectra from spectral libraries

Py6S was originally created as part of my PhD, to allow me to easily run a number of 6S simulations - to perform sensitivity analyses, for example - but has now been extended to cover the entire range of 6S functionality. Anything that can be done using the standard 6S model can be done through Py6S.

If you’ve just arrived here for the first time then you might like to read the Introduction and Intended Audience pages to see whether Py6S is suitable for your needs, and then follow the Installation instructions and then the Quick Start guide. The Py6S posts on my blog may also be of interest to you, as these explain various features of Py6S using case studies and example code. Full documentation of every function in Py6S can be accessed from the Table of Contents below.

If you need further help, or just want to send me some comments about Py6S, then visit the Support page, where you will find details of the Py6S mailing list. If you use Py6S as part of some research you publish then you must cite the first paper listed on the Publications page.

Py6S is fully-working, but also under active development. The Release Notes give information on what has changed in recent releases, and the Roadmap describes plans for future features.

Py6S is copyright Robin Wilson and the contributors listed here, and is released under the GNU Lesser General Public License. The code is available at GitHub

Table of Contents¶

Introduction¶

Py6S is a Python interface to the 6S Radiative Transfer Model. It allows you to run many 6S simulations using a simple Python syntax, rather than dealing with the rather cryptic 6S input and output files. As well as generally making it easier to use 6S, Py6S adds some new features:

The ability to run many simulations easily and quickly, with no manual editing of input files
The ability to run for many wavelengths and/or angles and easily plot the results
The ability to import real-world data to parameterise 6S, from radiosonde measurements and AERONET sun photometer measurements

Py6S has been designed to be easy to use, and to work on the ‘principle of least surprise’. Far more details are available in the rest of this documentation, but a quick code example should give you an idea of what Py6S can do:

# Import the Py6S module
from Py6S import *
# Create a SixS object
s = SixS()
# Set the wavelength to 0.675um
s.wavelength = Wavelength(0.675)
# Set the aerosol profile to Maritime
s.aero_profile = AeroProfile.PredefinedType(AeroProfile.Maritime)
# Run the model
s.run()
# Print some outputs
print s.outputs.pixel_reflectance, s.outputs.pixel_radiance, s.outputs.direct_solar_irradiance
# Run the model across the VNIR wavelengths, and plot the result
wavelengths, results = SixSHelpers.Wavelengths.run_vnir(s, output_name='pixel_radiance')
SixSHelpers.Wavelengths.plot_wavelengths(wavelengths, results, "Pixel radiance ($W/m^2$)")

This will produce the results shown below:

0.283 112.095 667.589

Py6S was described in a journal article in Computers and Geosciences which must be cited if Py6S is used for producing outputs for a scientific report/publication - see the Publications page for more information.

This project was written as part of my PhD at the University of Southampton. The code is open-source, released under the Lesser GNU Public License, and is available at GitHub.

I’m very interested in receiving feedback, bug reports and feature suggestions - please see the Support page to find out how to get in touch with me.

Intended Audience¶

Py6S is an interface to the Second Simulation of the Satellite Signal in the Solar Spectrum (6S) radiative transfer model, and therefore the use of Py6S assumes some familiarity with the 6S model and the concepts behind atmospheric Radiative Transfer Modelling for remote-sensing applications.

The best resources to gain some familiarity with these topics are:

A basic remote sensing textbook for information on the use of Radiative Transfer Models (look in your local academic library)
The original paper on 6S by Vermote et al
The 6S manual, particularly the first section which introduces the conceptual basis of the model (the later parts document each function in the original Fortran code, which may be less useful), here.

Py6S is a Python module, so you will need to have a basic understanding of Python programming to use the model. Don’t worry too much though - you can use the model without being a Python expert! Some good tutorials for basic Python programming include LearnPython and the Google Python class.

Installation¶

Prerequisites¶

Before starting the installation process, ensure that you have a working Python installation with the following modules installed:

numpy
scipy
matplotlib
python-dateutil
pysolar (only required for setting the geometry from a location and time)
pandas (only required for importing AERONET data)

It will also be helpful to have the IPython installed for interactive testing of Py6S.

An easy way to sort all of this out is to use the Enthought Python Distribution which will install Python plus many modules which are often used for scientific computing, along with many tools.

Compiling 6S¶

Py6S is an interface to 6S, not a replacement, so to use Py6S the 6S executable must already exist on your system. 6S is provided as a number of Fortran 77 source-code files from the 6S website, and must be compiled for your specific computer system. Detailed instructions are provided in the sections below.

Windows¶

These instructions were written based on testing with Windows 7, but should work with any version of Windows since Windows XP.

Download the 6S source code from http://6s.ltdri.org/. Choose Download 6S then 6SV1.1 and download the .tar file. This website seems to be down quite often at the moment, so there is a mirror of these files here.
We need to download the make and tar tools to allow us to install 6S. The easiest way to get these is through a project called GNUWin32. Go to http://gnuwin32.sourceforge.net/packages.html and choose the setup link next to tar and make and download the files.
Run the two executable files you just downloaded and work through the setup wizard for each, accepting the default options.
To compile the 6S code we will need a Fortran 77 compiler. These are a little difficult to find, as most compilers are now based on the (more modern) Fortran 95 standard. However, for some reason 6S does not compile using these compilers, so we need to find a Fortran 77 compiler. The best place I’ve found to get one for Windows is http://www.cse.yorku.ca/~roumani/fortran/ftn.htm. Download the FORT99.zip file, and extract it somewhere. Copy the G77 folder to the root of the C drive (so that the folder is C:\G77).
We now need to edit the Windows path so that we can easily call the compiler and other tools. To do this, right-click on the My Computer icon on your desktop, or the Computer item on your Start Menu and select Properties. Choose the Advanced System Settings option on the left-hand side of the resulting window and then click the Environment Variables button in the next dialog. Now scroll down in the bottom list box until you find a variable called PATH. Click Edit and add the following string to the end of its contents:
```
C:\Program Files\GNUWin32\bin;C:\G77\bin
```
Open the command window by opening the start menu and typing cmd.
Use the cd command to move to the folder where the .tar file you downloaded in step 1 is located, for example:
```
cd C:\Users\robin\Downloads
```
Run the following commands, one after each other:
```
tar -xvf 6SV-1.1.tar
    cd 6SV1.1
```
Browse to the 6SV1.1 folder in Windows Explorer (it should in your Downloads folder). Inside the folder you should find a file called Makefile. Open the file by double-clicking on it, and selecting Notepad when asked which program to open the file with. When the file has opened, find the text saying -lm (it will be near the end of the file) and delete it. Save the file.
Switch back to the command window and run the following command:
```
make
```

If no errors have been produced, then test the 6S executable by typing:
```
sixsV1.1 < ..\Examples\Example_In_1.txt
```

If this is working correctly you should see several screen’s worth of output, finishing with something that looks like:

*******************************************************************************
*                        atmospheric correction result                        *
*                        -----------------------------                        *
*       input apparent reflectance            :    0.100                      *
*       measured radiance [w/m2/sr/mic]       :   38.529                      *
*       atmospherically corrected reflectance                                 *
*       Lambertian case :      0.22187                                        *
*       BRDF       case :      0.22187                                        *
*       coefficients xa xb xc                 :  0.00685  0.03870  0.06820    *
*       y=xa*(measured radiance)-xb;  acr=y/(1.+xc*y)                         *
*******************************************************************************

OS X¶

These instructions were written based on testing with Mac OS X 10.7 (Lion), but should work with previous (and later) versions.

Download the 6S source code from http://6s.ltdri.org/. Choose Download 6S then 6SV1.1 and download the .tar file. This website seems to be down quite often at the moment, so there is a mirror of these files here.
You will need to have gcc installed to compile 6S. If you already have the XCode developement environment for OS X installed then you’ve already got GCC, if not, go to https://github.com/kennethreitz/osx-gcc-installer/ and choose Option 1: Downloading Pre-Built Binaries and download the appropriate file for your version of OS X. Double-click the file to run it, and follow through the installer.
Download the f77 compiler from http://hpc.sourceforge.net/. You should choose one of the binary download links under the g77 3.4 heading. If you’re not sure which binary you require then choose the Intel version, as that is what most modern Macs use.
Open the Terminal (Applications->Utilities->Terminal) and type the following commands (this assumes the files you downloaded above are located in your Downloads folder, and you will need to enter your password when prompted):
```
cd ~/Downloads
sudo tar -xvf g77-intel-bin.tar.gz -C /
```

Now run the following commands, one after each other:

tar -xvf 6SV-1.1.tar
    cd 6SV1.1
    make

If no errors have been produced, then test the 6S executable by typing:
```
sixsV1.1 < ../Examples/Example_In_1.txt
```

If this is working correctly you should see a number of screen’s worth of output, finishing with something that looks like:

*******************************************************************************
*                        atmospheric correction result                        *
*                        -----------------------------                        *
*       input apparent reflectance            :    0.100                      *
*       measured radiance [w/m2/sr/mic]       :   38.529                      *
*       atmospherically corrected reflectance                                 *
*       Lambertian case :      0.22187                                        *
*       BRDF       case :      0.22187                                        *
*       coefficients xa xb xc                 :  0.00685  0.03870  0.06820    *
*       y=xa*(measured radiance)-xb;  acr=y/(1.+xc*y)                         *
*******************************************************************************

Linux¶

Part of the problem with installation instructions for Linux is that there are so many distributions of Linux available, and they all do things slightly differently. Therefore, the instructions below will be a bit more general than those above, but you should be able to work out what to do.

Download the 6S source code from http://6s.ltdri.org/. Choose Download 6S then 6SV1.1 and download the .tar file. This website seems to be down quite often at the moment, so there is a mirror of these files here.
You need to install gfortran - the GNU Fortran compiler. This may already be installed in your system - you can check by typing gfortran -v in a terminal, if you don’t get an error, then it is installed. If not, install it using the standard installation method for your distribution. You can often do this via a GUI tool, such as Synaptic Package Manager, or via the command-line, for example:
```
# For Debian/Ubuntu-based distributions
sudo apt-get install gfortran
# For Gentoo
sudo emerge gfortran
# For Arch
sudo pacman -S gfortran
```

Extract the source code from the .tar file you downloaded:

cd ~/Downloads (or wherever you put the file)
tar -xvf 6SV-1.1.tar
cd 6SV1.1

The Makefile that comes with 6S expects to use the g77 compiler, so we need to instruct it to use gfortran instead. Open the file called Makefile in an editor of your choice, for example:
```
nano Makefile
```
Change the line which contains:
```
FC      = g77 $(FFLAGS)
```

to:

FC      = gfortran -std=legacy -ffixed-line-length-none $(FFLAGS)

Exit the editor and return to the command line.
Run make
If no errors have been produced, then test the 6S executable by typing:
```
sixsV1.1 < ../Examples/Example_In_1.txt
```

If this is working correctly you should see a number of screen’s worth of output, finishing with something that looks like:

*******************************************************************************
*                        atmospheric correction result                        *
*                        -----------------------------                        *
*       input apparent reflectance            :    0.100                      *
*       measured radiance [w/m2/sr/mic]       :   38.529                      *
*       atmospherically corrected reflectance                                 *
*       Lambertian case :      0.22187                                        *
*       BRDF       case :      0.22187                                        *
*       coefficients xa xb xc                 :  0.00685  0.03870  0.06820    *
*       y=xa*(measured radiance)-xb;  acr=y/(1.+xc*y)                         *
*******************************************************************************

Installing 6S¶

Once you have compiled 6S, you must place the executable (which is, by default, called sixsV1.1) somewhere where Py6S can find it. The best thing to do is place it somewhere within your system path, as defined by the PATH environment variable. There are two ways to do this:

Modify your system path to include the location of 6S: To do this, leave 6S where it is (or place it anywhere else that you want) and then edit the PATH environment variable to include that folder. The method to do this varies by platform, but a quick Google search should show you how to accomplish this.
Move 6S to a location which is already in the path: This is fairly simple as it just involves copying a file. Sensible places to copy to include /usr/bin (on Linux or OS X) and C:\Windows\System32 on Windows.

If it is impossible (for some reason) to place the 6S executable on the PATH it is possible to specify the location manually when running Py6S (see below).

Installing Py6S¶

Installation from PyPI¶

The easiest way to install Py6S is from the Python Package Index (PyPI; http://pypi.python.org/pypi). Simply open a command prompt and type:

> pip install Py6S

If you get an error saying that pip cannot be found or is not installed, simply run:

> easy_install pip

and then perform the installation as above.

Installation from a .egg file¶

Py6S is also distributed as a Python Egg file, with a name like Py6S-0.51-py2.7.egg. You will need to choose the correct egg file for your version of python. To find out your Python version run:

> python -V
Python 2.7.2 -- EPD 7.1-2 (64-bit)

Then simply run the following code, which will install PySolar (required for some Py6S functions), and then Py6S itself:

> pip install PySolar
> easy_install <eggfile>

Where <eggfile> is the correct egg file for your Python version.

Testing Py6S¶

To check that both 6S and Py6S have been installed correctly, and that Py6S can find the 6S executable, run ipython from the command line, and then run the following commands:

from Py6S import *
SixS.test()

The output should look like this:

6S wrapper script by Robin Wilson
Using 6S located at C:\_Work\Py6S\6S\sixs.exe
Running 6S using a set of test parameters
The results are:
Expected result: 619.158000
Actual result: 619.158000
#### Results agree, Py6S is working correctly

This shows where the 6S executable that Py6S is using has been found (C:\_Work\Py6S\6S\sixs.exe in this case). If the executable cannot be found then it is possible to specify the locationmanually:

from Py6S import *
SixS.test("C:\Test\sixsV1.1")

If you choose this method then remember to include the same path whenever you instantiate the SixS class, as follows:

from Py6S import *
s = SixS("C:\Test\sixsV1.1")

Quick Start¶

Now that you’ve installed Py6S, this section will give you a brief guide on how to use it.

A note on IPython¶

IPython is an interactive Python shell that has many more features than the standard Python shell. The most useful of these is tab-completion, which will provide significant help in learning how to use Py6S. If you type part of an identifier - for example, s.a and press TAB you will see all of the possible completions. This works for all parts of Py6S, including the output values. For example:

In [3]: s.a<TAB>
s.aero_profile   s.altitudes      s.aot550         s.atmos_corr s.atmos_profile

In [4]: s.outputs.tra<TAB>
s.outputs.transmittance_aerosol_scattering   s.outputs.transmittance_oxygen
s.outputs.transmittance_ch4                  s.outputs.transmittance_ozone
s.outputs.transmittance_co                   s.outputs.transmittance_rayleigh_scattering
s.outputs.transmittance_co2                  s.outputs.transmittance_total_scattering
s.outputs.transmittance_global_gas           s.outputs.transmittance_water
s.outputs.transmittance_no2

It is also very easy to get help on individual parts of Py6S from within IPython. Simply type any name, and append a ? to it - for example AeroProfile.MultimodalLogNormal?. The documentation which is shown will describe the parameters required and give an example of usage.

A first run¶

The SixS class is at the heart of Py6S. It has methods and attributes that allow you to set 6S parameters, run 6S and then view the outputs.

Py6S sets every 6S parameter to a sensible default, so the simplest possible code just uses the default values. As a nice introduction, we’re going to plot one of the 6S outputs across the whole Visible-NIR wavelength range:

# Import all of the Py6S code
from Py6S import *
# Create a SixS object called s (used as the standard name by convention)
s = SixS()
# Run the 6S simulation defined by this SixS object across the
# whole VNIR range
wavelengths, results = SixSHelpers.Wavelengths.run_vnir(s, output_name="pixel_radiance")
# Plot these results, with the y axis label set to "Pixel Radiance"
SixSHelpers.Wavelengths.plot_wavelengths(wavelengths, results, "Pixel Radiance")

This will produce a graph like the following:

You will see a number of buttons in the window that is showing the graph. These allow you to zoom in to specific areas of the plot, move the plot around, adjust the margins, and save the plot to a file.

This shows the utility of Py6S very nicely - imagine how long it would have taken to produce this plot by editing and running 6S input files manually! However, the plot probably isn’t particularly helpful as the defaults I’ve chosen probably aren’t the parameters that you want to use for your simulation, and you may not be interested in the calculated pixel radiance. The sections below will explain how to alter this simple program to produce more useful results.

Setting parameters¶

We’ll start with an example, and then explain the details:

from Py6S import *
s = SixS()
s.atmos_profile = AtmosProfile.PredefinedType(AtmosProfile.Tropical)
s.wavelength = Wavelength(0.357)
s.run()
print s.outputs.pixel_radiance

You can see here that we have changed the atmospheric profile to a pre-defined profile called ‘Tropical’, and changed the wavelength that we are using for the simulation to 0.357 micrometres. You can also see that here we’re accessing the outputs directly, rather than running it over a specific wavelength range and plotting it. Try finding out what other outputs you can access, by typing s.outputs. and pressing TAB.

We’ll look in detail at extracting outputs later, but first, lets have a look at the parameters that we can change, summarised in the table below:

SixS Parameter	Description	Possible values
`atmos_profile`	Atmospheric profile (pressure, water vapour, ozone etc)	Any outputs from `AtmosProfile`
`aero_profile`	Aerosol profile (types, distributions etc)	Any outputs from `AeroProfile`
`ground_reflectance`	Ground reflectance (Homogeneity, BRDF etc.)	Any outputs from `GroundReflectance`
`geometry`	Viewing/Illumination geometry (manual or satellite-specific)	A `Geometry*` class, for example `Geometry.User`
`aot550`	Aerosol Optical Thickness at 550nm	Floating point number
`visibility`	Visibility in km	Floating point number
`altitude`	Altitudes of the sensor and target	An instance of the `Altitudes` class
`atmos_corr`	Atmospheric correction settings (yes/no, reflectances)	Any outputs from `AtmosCorr`

As you can see, the parameter and class names are designed to be fairly self-explanatory. Using the details from above, a more advanced parameterisation is shown below:

from Py6S import *
s = SixS()
s.atmos_profile = AtmosProfile.UserWaterAndOzone(3.6, 0.9) # Set the atmosphere profile to be based on 3.6cm of water and 0.9cm-atm of ozone
s.wavelength = Wavelength(PredefinedWavelengths.LANDSAT_TM_B3) # Set the wavelength to be that of the Landsat TM Band 3 - includes response function
s.ground_reflectance = GroundReflectance.HomogeneousWalthall(1.08, 0.48, 4.96, 0.5) # Set the surface to have a BRDF approximated by the Walthall model
s.geometry = Geometry.Landsat_TM()
s.geometry.month = 7
s.geometry.day = 14
s.geometry.gmt_decimal_hour = 7.75
s.geometry.latitude = 51.148
s.geometry.longitude = 0.307
s.run()
print s.outputs.pixel_radiance

This is far more detailed, but should be self-explanatory given the comments and the table above. Far more details about the individual parameterisations are available in their documentation pages.

The real power of Py6S comes when you combine the paramterisation abilities of Py6S with the standard Python programming constructs. This is basically what we did above for the run_vnir example, although there we used a SixSHelpers method to make it easier for us. We can also do this manually, for example, you can easily loop over a number of parameter values and produce the outputs for each of them:

from Py6S import *
s = SixS()

for param in [AtmosProfile.Tropical, AtmosProfile.MidlatitudeSummer, AtmosProfile.MidlatitudeWinter]:
  s.atmos_profile = AtmosProfile.PredefinedType(param)
  s.run()
  print s.outputs.pixel_radiance

You can see that in this instance the change in pixel radiance over different atmospheric profiles is fairly low (< 0.8). Again, this saves a lot of time and complex input file editing.

That’s it for the quick guide to setting parameters - for more details see the rest of the documentation.

Accessing outputs¶

The outputs from the 6S model are available under the s.outputs attribute. The outputs are actually stored as dictionaries, and the main set of outputs can be printed (and saved) from the s.outputs.values attribute. For example:

from Py6S import *
s = SixS()
s.run()
print s.outputs.values

However, it’s normally more useful to access individual outputs. This can be done using the standard Python dictionary access methods - for example, print s.outputs.values['pixel_radiance'], but it is generally easy to do this by appending the output name to s.outputs.. For example:

from Py6S import *
s = SixS()
s.run()
print s.outputs.pixel_radiance
print s.outputs.environmental_irradiance
print s.outputs.total_gaseous_transmittance

The outputs stored under s.outputs.values are the main outputs of 6S provided on the first two ‘screenfulls’ of raw 6S output. The names of the outputs in Py6S have been kept as similar to the labels in the raw 6S output as possible, although sometimes names have been changed to improve clarity. Remember that a list of all possible outputs can be gained by typing s.outputs. and pressing TAB in IPython.

The tables showing the integrated values of various transmittances (rayleigh, water, ozone etc) are stored under the s.outputs.trans dictionary as instances of the Transmittance class. This allows the easy storage of the three different transmittances: downward, upward and total. Again, rather than dealing with the dictionary directly, courtesy methods are provided, for example:

from Py6S import *
s = SixS()
s.run()
print s.outputs.transmittance_rayleigh_scattering
print s.outputs.transmittance_rayleigh_scattering.downward
print s.outputs.transmittance_rayleigh_scattering.upward
print s.outputs.transmittance_rayleigh_scattering.total
print s.outputs.transmittance_water

Outputs from the other large grid shown in the raw 6S output, which includes outputs like spherical albedo, total optical depth and polarized reflectance, are also available:

from Py6S import *
s = SixS()
s.run()
print s.outputs.spherical_albedo
print s.outputs.optical_depth_total
print s.outputs.polarized_reflectance

SixSHelpers¶

A number of ‘helper’ methods have been written to make it easier to perform common operations using Py6S. These can be split into two categories:

Running for a set of parameters¶

It is often necessary to run a simulation across a number of wavelengths - as it is very rare that we are only interested in a single wavelength. We saw an example of this above, when we used the run_vnir method to run a simulation across the Visible-NIR wavelengths. We can do similar things for other wavelengths really easily. For example:

from Py6S import *
s = SixS()
# Run for the whole range of wavelengths that 6S supports
wv, res = SixSHelpers.Wavelengths.run_whole_range(s, output_name='pixel_radiance')
# Do the same, but at a coarser resolution, so that it's quicker
wv, res = SixSHelpers.Wavelengths.run_whole_range(s, spacing=0.030, output_name='pixel_radiance')
# Run for the Landsat TM bands
wv, res = SixSHelpers.Wavelengths.run_landsat_tm(s, output_name='pixel_radiance')

Py6S supports running across all of the bands for all of the sensors that 6S supports - see the documentation for SixSHelpers.Wavelengths for more details.

You can plot the results really easily too, just by passing the resulting wavelengths and results to the SixSHelpers.Wavelengths.plot_wavelengths() function:

wv, res = SixSHelpers.Wavelengths.run_landsat_tm(s, output_name='pixel_radiance')
# Plot the results, setting the y-axis label appropriately
SixSHelpers.Wavelengths.plot_wavelengths(wv, res, 'Pixel radiance ($W/m^2$)')

You’ll note that all of the run_xxx methods require a SixS instance as the first argument, and then an optional output_name argument. This specifies the output that you want to return from the function, and should whatever you would put after s.outputs. to print the output. For example, the output name could be any of the following:

pixel_reflectance
background_reflectance
transmittance_co2.downward

If you don’t set the output_name argument then the function will return lots of Outputs instances rather than actual values. This can be handy if you want to work with lots of the outputs from a simulation, as it saves you having to run the whole simulation many times. For example:

s = SixS()
# Run for the whole range (takes a long time!)
wv, res = SixSHelpers.Wavelengths.run_landsat_tm(s)
# Look at what is in the results list - it should be an outputs instance
print res[0]
# We can't do anything with the outputs instances directly, but lets
# extract some outputs - we can do all of this without having to run
# the whole simulation again, as the res variable is storing all of the
# outputs
refl = SixSHelpers.Wavelengths.extract_output(res, "pixel_reflectance")
rad = SixSHelpers.Wavelengths.extract_output(res, "pixel_radiance")
SixSHelpers.Wavelengths.plot_wavelengths(wv, refl, "Pixel reflectance")
SixSHelpers.Wavelengths.plot_wavelengths(wv, rad, "Pixel radiance")

Another common use is to simulate a number of different view or solar angles, to examine the changes in the reflectance of a target due to its Bi-Directional Reflectance Distribution Factor. Doing this manually can be very tricky, as many simulations must be run, and then the results must be put into the right format to be plotted. Py6S makes this nice and easy by reducing it to one function call:

from Py6S import *
s = SixS()
# Set the ground reflectance to have some sort of BRDF, or the plot will
# be really boring! In this case, we're using the Roujean model
s.ground_reflectance = GroundReflectance.HomogeneousRoujean(0.037, 0.0, 0.133)
# Run the model and plot the results, varying the view angle (the other
#  option is to vary the solar angle) and plotting the pixel reflectance.
SixSHelpers.Angles.run_and_plot_360(s, 'view', 'pixel_reflectance')

This will produce a plot like the following:

Using real-world measurements to parameterise Py6S¶

Another common task is to parameterise 6S with some values collected from real-world measurements, so that the results of 6S simulations can be directly related to measurements in the field.

Py6S provides two ways to parameterise 6S from real-world measurements:

By importing radiosonde data to set the atmospheric profile, using the import_uow_radiosonde_data() function
By importing AERONET data to set the aerosol profile, using the import_aeronet_data() function

Detailed descriptions of these functions are given on their respective pages.

The SixS class¶

The SixS class is the heart of Py6S. It has attributes and methods that allow you to set parameters, run 6S and access the outputs. These are described in detail below, but the basic usage pattern is:

from Py6S import *
s = SixS() # Instantiate the class
s.aero_profile = AeroProfile.PredefinedType(AeroProfile.Maritime) # Set various parameters
s.run() # Run the model
print s.outputs.pixel_irradiance # Access the outputs

class Py6S.SixS(path=None)¶

Wrapper for the 6S Radiative Transfer Model.

This is the main class which can be used to instantiate an object which has the key methods for running 6S.

The most import method in this class is the run() method which writes the 6S input file, runs the model and processes the output.

The parameters of the model are set as the attributes of this class, and the outputs are available as attributes under the output attribute.

For a simple test to ensure that Py6S has found the correct executable for 6S simply run the test() method of this class:

SixS.Test()

Attributes:

atmos_profile – The atmospheric profile to use. Should be set to the output of an AtmosProfile method. For example:
```
s.atmos_profile = AtmosProfile.PredefinedType(AtmosProfile.MidlatitudeSummer)
```
aero_profile – The aerosol profile to use. Should be set to the output of an AeroProfile method. For example:
```
s.aero_profile = AeroProfile.PredefinedType(AeroProfile.Urban)
```
ground_reflectance – The ground reflectance to use. Should be set to the output of a GroundReflectance method. For example:
```
s.ground_reflectance = GroundReflectance.HomogeneousLambertian(0.3)
```
geometry – The geometrical settings, including solar and viewing angles. Should be set to an instance of a Geometry class, which can then have various attributes set. For example:
```
s.geometry = GeometryUser()
s.geometry.solar_z = 35
s.geometry.solar_a = 190
```
altitudes – The settings for the sensor and target altitudes. This should be set to an instance of the Altitudes() class, which can then have various attributes set. For example:
```
s.altitudes = Altitudes()
s.altitudes.set_target_custom_altitude(2.3)
s.altitudes.set_sensor_sea_level()
```
wavelength – The wavelength settings. Should be set to the output of the Wavelength() method. For example:
```
s.wavelength = Wavelength(0.550)
```
atmos_corr – The settings for whether to perform atmospheric correction or not, and the parameters for this correction. Should be set to the output of a AtmosCorr method. For example:
```
s.atmos_corr = AtmosCorr.AtmosCorrLambertianFromReflectance(0.23)
```

produce_debug_report()¶: Prints out information about the configuration of Py6S generally, and the current SixS object specifically, which will be useful when debugging problems.

run()¶

Runs the 6S model and stores the outputs in the output variable.

May raise an ExecutionError if the 6S executable cannot be found.

classmethod test()¶: Runs a simple test to ensure that 6S and Py6S are installed correctly.

write_input_file(filename=None)¶

Generates a 6S input file from the parameters stored in the object and writes it to the given filename.

The input file is guaranteed to be a valid 6S input file which can be run manually if required

Attributes¶

sixs_path¶: The sixs path

Accessing outputs¶

The Outputs class stores the outputs produced by a 6S run and allows easy access to them.

class Py6S.Outputs(stdout, stderr)¶

Stores the output from a 6S run.

Attributes:

fulltext – The full output of the 6S executable. This can be written to a file with the write_output_file method.

values – The main outputs from the 6S run, stored in a dictionary. Accessible either via standard dictionary notation (s.outputs.values['pixel_radiance']) or as attributes (s.outputs.pixel_radiance)

Methods:

__init__() – Constructor which takes the stdout and stderr from the model and processes it into the numerical outputs.

extract_results() – Function called by the constructor to parse the output into individual variables

to_int() – Convert a string to an int, so that it works even if passed a float.

write_output_file() – Write the full textual output of the 6S model to a file.

extract_aot(data)¶: Extracts the AOT from the visibility and AOT line in the output.

extract_results()¶: Extract the results from the text output of the model and place them in the values dictionary.

extract_vis(data)¶: Extracts the visibility from the visibility and AOT line in the output

to_int(str)¶

Converts a string to an integer.

Does this by converting to float and then converting that to int, meaning that converting “5.00” to an integer will actually work.

Arguments:

str – The string containing the number to convert to an integer

write_output_file(filename)¶

Writes the full textual output of the 6S model run to the specified filename.

Arguments:

filename – The filename to write the output to

Parameter Setting¶

Parameters for 6S can be set using the classes and methods described below.

Atmospheric Profiles¶

class Py6S.AtmosProfile¶

Stores a enumeration for the pre-specified atmospheric model types

classmethod PredefinedType(type)¶

Set 6S to use a predefined atmosphere type.

Arguments:

type – the predefined atmosphere type, one of the constants defined in this class

Example usage:

s.atmosprofile = AtmosProfile.PredefinedType(AtmosProfile.MidlatitudeSummer)

classmethod RadiosondeProfile(data)¶

Set 6S to use an atmosphere defined by a profile from a radiosonde measurements.

Arguments:

data – A dictionary containing five iterables (eg. lists) with the radiosonde measurements in them. The dictionary must have the following keys:
- altitude – in km
- pressure – in mb
- temperature – in k
- water – in g/m^3
- ozone – in g/m^3

There must be 34 items in each iterable, or a ParameterExeception will be thrown.

classmethod UserWaterAndOzone(water, ozone)¶

Set 6S to use an atmosphere defined by an amount of water vapour and ozone.

Arguments:

water – The total amount of water in a vertical path through the atmosphere (in g/cm^2)
ozone – The total amount of ozone in a vertical path through the atmosphere (in cm-atm)

Example usage:

s.atmosprofile = AtmosProfile.UserWaterAndOzone(3.6, 0.9)

Aerosol Profiles¶

class Py6S.AeroProfile¶

Class representing options for Aerosol Profiles

class AerosolDistribution(rmin, rmax, numtype)¶

Stores data regarding a specific Aerosol Distribution.

Used by the following methods:

MultimodalLogNormalDistribution()
ModifiedGammaDistribution()
JungePowerLawDistribution()

add_component(rmean, sigma, percentage_density, refr_real, refr_imag)¶

Adds a component to the aerosol distribution.

Wavelength dependent values must be input at the following wavelengths (given in micrometers): 0.350, 0.400, 0.412, 0.443, 0.470, 0.488, 0.515, 0.550, 0.590, 0.633, 0.670, 0.694, 0.760, 0.860, 1.240, 1.536, 1.650, 1.950, 2.250, 3.750

Arguments:

rmean – The mean radius of the aerosols
sigma – Sigma, as defined by the distribution (Log Normal etc)
percentage_density – The percentage density of the aerosol
refr_real – A 20-element iterable giving the real part of the refractive indices at the specified wavelengths (see above)
refr_imag – A 20-element iterable giving the imaginary part of the refractive indices at the specified wavelengths (see above)

classmethod JungePowerLawDistribution(rmin, rmax)¶

Set 6S to use a Junge Power Law distribution.

Arguments:

rmin – The minimum aerosol radius
rmax – The maximum aerosol radius

This returns an AerosolDistribution object. Components can then be added to this distribution using the add_component() method of the returned class.

Example usage:

s.aeroprofile = AeroProfile.JungePowerLawDistribution(0.1, 0.3)
s.aeroprofile.add_component(...)

classmethod ModifiedGammaDistribution(rmin, rmax)¶

Set 6S to use a Modified Gamma distribution.

Arguments:

rmin – The minimum aerosol radius
rmax – The maximum aerosol radius

This returns an AerosolDistribution object. Components can then be added to this distribution using the add_component() method of the returned class.

Example usage:

s.aeroprofile = AeroProfile.ModifiedGammaDistribution(0.3, 0.1)
s.aeroprofile.add_component(...)

classmethod MultimodalLogNormalDistribution(rmin, rmax)¶

Set 6S to use a Multimodal Log-Normal distribution.

Arguments:

rmin – The minimum aerosol radius
rmax – The maximum aerosol radius

This returns an AerosolDistribution object. Components can then be added to this distribution using the add_component() method of the returned class.

Example usage:

s.aeroprofile = AeroProfile.MultimodalLogNormalDistribution(0.3, 0.1)
s.aeroprofile.add_component(...)

classmethod PredefinedType(type)¶

Set 6S to use a predefined aerosol type, one of the constants defined in this class.

Arguments:

type – the predefined aerosol type, one of the constants defined in this class

Example usage:

s.aeroprofile = AeroProfile.PredefinedType(AeroProfile.Urban)

classmethod SunPhotometerDistribution(r, dvdlogr, refr_real, refr_imag)¶

Set 6S to use an aerosol parameterisation from Sun Photometer measurements.

The real and imaginary parts of the refractive indices must be input at the following wavelengths (given in micrometers): 0.350, 0.400, 0.412, 0.443, 0.470, 0.488, 0.515, 0.550, 0.590, 0.633, 0.670, 0.694, 0.760, 0.860, 1.240, 1.536, 1.650, 1.950, 2.250, 3.750

Arguments:

r – A list of radius measurements from a sun photometer (microns)
dvdlogr – A list of dV/d(logr) measurements from a sun photometer, for the radiuses as above (cm^3/cm^2/micron)
refr_real – A list containing the real part of the refractive indices for each of the 20 wavelengths (above). If a single float value is given then the value is treated as constant for all wavelengths.
refr_imag – A list containing the imaginary part of the refractive indices for each of the 20 wavelengths (above). If a single float value is given then the value is treated as constant for all wavelengths.

classmethod User(**kwargs)¶

Set 6S to use a user-defined aerosol profile based on proportions of standard aerosol components.

The profile is set as a mixture of pre-defined components, each given as an optional keyword. Not all keywords need to be given, but the values for the keywords given must sum to 1, or a ParameterError will be raised.

Optional keywords:

dust – The proportion of dust-like aerosols
water – The proportion of water-like aerosols
oceanic – The proportion of oceanic aerosols
soot – The proportion of soot-like aerosols

Example usage:

s.aeroprofile = AeroProfile.User(dust=0.3, oceanic=0.7)
s.aeroprofile = AeroProfile.User(soot = 0.1, water = 0.3, oceanic = 0.05, dust = 0.55)

class UserProfile(atype)¶

Set 6S to use a user-defined aerosol profile, with differing AOTs over the height of the profile.

Arguments:

atype – Aerosol type to be used for all layers. Must be one of the pre-defined types defined in this class.

Methods:

add_layer() – Adds a layer to the user-defined aerosol profile, with the specified height and aerosol optical thickness.

Example usage:

s.aeroprofile = AeroProfile.UserProfile(AeroProfile.Maritime)
s.aeroprofile.add_layer(5, 0.34) # Add a 5km-thick layer with an AOT of 0.34
s.aeroprofile.add_layer(10, 0.7) # Add a 10km-thick layer with an AOT of 0.7
s.aeroprofile.add_layer(100, 0.01) # Add a 100km-thick layer with an AOT of 0.01

add_layer(height, optical_thickness)¶

Adds a layer to the user-defined profile.

Arguments:

height – Height of the layer (in km)
optical_thickness – Optical thickness of the layer

Example usage:

s.aeroprofile.add_layer(5, 0.34) # Add a 5km-thick layer with an AOT of 0.34

Ground Reflectances¶

class Py6S.GroundReflectance¶

Produces strings for the input file for a number of different ground reflectance scenarios.

Options are:

Homogeneous
- Lambertian
- BRDF
  - Walthall et al. model
  - Rahman et al. model
  - etc
Heterogeneous
- Lambertian

These are combined to give function names like:

HomogeneousLambertian() or HomogeneousWalthall()

The standard functions (HomogeneousLambertian() and HeterogeneousLambertian()) will decide what to do based on the types of inputs they are given:

model.ground_reflectance = GroundReflectance.HomogeneousLambertian(0.7) # A spectrally-constant reflectance of 0.7
model.ground_reflectance = GroundReflectance.HomogeneousLambertian(GroundReflectance.GreenVegetation) # A built-in green vegetation spectrum
model.ground_reflectance = GroundReflectance.HomogeneousLambertian([0.6, 0.8, 0.34, 0.453]) # A user-defined spectrum given in micrometers with steps of 2.5nm
# A 2D ndarray, such as that returned by any of the Spectra.import_* functions
model.ground_reflectance = GroundReflectance.HomogeneousLambertian(Spectra.import_from_usgs("http://speclab.cr.usgs.gov/spectral.lib06/ds231/ASCII/V/russianolive.dw92-4.30728.asc"))

classmethod HeterogeneousLambertian(radius, ro_target, ro_env)¶

Provides parameterisation for heterogeneous Lambertian (ie. uniform BRDF) surfaces.

These surfaces are modelled in 6S as a circular target surrounded by an environment of a different reflectance.

Arguments:

radius – The radius of the target (in km)
ro_target – The reflectance of the target
ro_env – The reflectance of the environment

Both of the reflectances can be set to any of the following:

A single float value (for example, 0.634), in which case it is interpreted as a spectrally-constant reflectance value.
A constant defined by this class (one of GroundReflectance.GreenVegetation, GroundReflectance.ClearWater, GroundReflectance.Sand or GroundReflectance.LakeWater) in which case a built-in spectrum of the specified material is used.
An array of values (for example, [0.67, 0.85, 0.34, 0.65]) in which case the values are taken to be reflectances across the whole wavelength range at a spacing of 2.5nm. In this case, if the start wavelength is s and the end wavelength is e, the values must be given for the wavelengths: s, s+2.5, s+5.0, s+7.5, ..., e-2.5, e
A multidimensional ndarray giving wavelength (column 0) and reflectance (column 1) values

classmethod HomogeneousHapke(albedo, assymetry, amplitude, width)¶

Parameterisation for a surface BRDF based on the Hapke model.

The parameters are:

albedo
assymetry parameter for the phase function
amplitude of hot spot
width of the hot spot

classmethod HomogeneousIaquintaPinty(leaf_dist, hot_spot, lai, hot_spot_param, leaf_reflec, leaf_trans, soil_albedo)¶

Parameterisation for a surface BRDF based on the Iaquinta and Pinty model.

The parameters are:

Leaf distribution (one of the GroundReflectance.LeafDistXXX constants)
Hot spot setting (GroundReflectance.HotSpot or GroundReflectance.NoHotSpot)
Leaf Area Index (1-15)
Hot spot parameter 2*r*lambda (0-2)
Leaf reflectance (0-0.99)
Leaf transmittance (0-0.99)
Soil albedo (0-0.99)

Leaf reflectance + Leaf transmittance must be less than 0.99. If this is not the case, a ParameterException is raised.

classmethod HomogeneousKuuskMultispectralCR(lai, lad_eps, lad_thm, relative_leaf_size, chlorophyll_content, leaf_water_equiv_thickness, effective_num_layers, ratio_refractive_indices, weight_first_price_function)¶

Parameterisation for a surface BRDF based on Kuusk’s multispectral CR model.

The Parameters are:

Leaf Area Index (0.1-10)
LAD eps (0.0-0.9)
LAD thm (0.0-90.0)
Relative leaf size (0.01-1.0)
Chlorophyll content (ug/cm^2, 0-30)
Leaf water equivalent thickness (0.01-0.03)
Effective number of elementary layers inside a leaf (1-225)
Ratio of refractive indices of the leaf surface wax and internal material (0-1.0)
Weight of the 1st Price function for the soil reflectance (0.1-0.8)

classmethod HomogeneousLambertian(ro)¶

Provides parameterisation for homogeneous Lambertian (ie. uniform BRDF) surfaces.

The single argument can be either:

A single float value (for example, 0.634), in which case it is interpreted as a spectrally-constant reflectance value.
A constant defined by this class (one of GroundReflectance.GreenVegetation, GroundReflectance.ClearWater, GroundReflectance.Sand or GroundReflectance.LakeWater) in which case a built-in spectrum of the specified material is used.
An array of values (for example, [0.67, 0.85, 0.34, 0.65]) in which case the values are taken to be reflectances across the whole wavelength range at a spacing of 2.5nm. In this case, if the start wavelength is s and the end wavelength is e, the values must be given for the wavelengths: s, s+2.5, s+5.0, s+7.5, ..., e-2.5, e
A multidimensional ndarray giving wavelength (column 0) and reflectance (column 1) values

classmethod HomogeneousMODISBRDF(par1, par2, par3)¶

Parameterisation for a surface BRDF based on the MODIS Operational BRDF model.

The parameters are:

Weight for lambertian kernel
Weight for Ross Thick kernel
Weight for Li Spare kernel

classmethod HomogeneousMinnaert(k, alb)¶

Parameterisation for a surface BRDF based on the Minnaert BRDF model.

The parameters are: - K surface parameter - Surface albedo

classmethod HomogeneousOcean(wind_speed, wind_azimuth, salinity, pigment_concentration)¶

Parameterisation for a surface BRDF based on the Ocean BRDF model.

The parameters are:

wind speed (in m/s)
azimuth of the wind (in degrees)
salinity (in ppt) (set to 34.3ppt if < 0)
pigment concentration (in mg/m3)

classmethod HomogeneousRahman(intensity, asymmetry_factor, structural_parameter)¶

Parameterisation for a surface BRDF based on the Rahman BRDF model.

The parameters are:

Intensity of the reflectance of the surface (N/D value >= 0)
Asymmetry factor, N/D value between -1.0 and 1.0
Structural parameter of the medium

classmethod HomogeneousRoujean(albedo, k1, k2)¶

Parameterisation for a surface BRDF based on the Roujean et al. model.

The parameters are:

albedo
geometric parameter for hot spot effect
geometric parameter for hot spot effect

HomogeneousUserDefined(albedo, ro_sun_at_thetas, ro_sun_at_thetav)¶

Parameterisation for a user-defined surface BRDF.

The parameters are:

observed_reflectance – Observed reflectance in the geometry specified in the Geometry parameterisation
albedo – Surface spherical albedo
ro_sun_at_thetas – A reflectance table (described below) for the scenario when the sun is at theta_s (the solar zenith angle specified in the Geometry parameterisation)
ro_sun_at_thetav – A reflectance table (described below) for the scenario when the sun is at theta_v (the view zenith angle specified in the Geometry parameterisation)

The reflectance tables mentioned above must be NumPy arrays (that is, instances of ndarray) with a shape of (10, 14) where the table headers are as below, and each cell contains the reflectance of the surface in the specified geometry:

      zenith
      0   10    20    30    40    50    60    70    80    85
a 0
z 30
i 60
m 90
u 120
t 150
h .
  .
  .

classmethod HomogeneousVerstaeteEtAl(kappa_param, phase_funct, scattering_type, leaf_area_density, sun_flecks_radius, ssa, legendre_first, legendre_second, k1, k2, asym_factor, chil)¶

Parameterisation for a surface BRDF based on the Verstraete, Pinty and Dickinson model.

The parameters are:

The type of Kappa parameterisation (one of the GroundReflectance.KappaXXX constants)
The phase function to use (one of the GroundReflectance.PhaseXXX constants)
The scattering type to use (either GroundReflectance.SingleScatteringOnly or GroundReflectance.DickinsonMultipleScattering)
Leaf area density (m^2/m^-3)
Radius of the sun flecks on the scatterer (m)
Single Scattering Albedo (0-1)
First coefficient of Legendre polynomial (Only used if phase function is not GroundReflectance.PhaseIsotropic, set to None otherwise)
Second coefficient of Legendre polynomial (Only used if phase function is not GroundReflectance.PhaseIsotropic, set to None otherwise)
Kappa value k1 (Only used if Kappa parameterisation was GroundReflectance.KappaGivenValues, set to None otherwise)
Kappa value k2 (Only used if Kappa parameterisation was GroundReflectance.KappaGivenValues, set to None otherwise)
Asymmetry factor for Heyney-Greenstein parameterisation (Only used if Phase function is set to GroundReflectance.PhaseHeyneyGreenstein, set to None otherwise)
Goudriaan’s chil parameter (Only used if Kappa parameterisation was NOT GroundReflectance.KappaGivenValues, set to None otherwise)

classmethod HomogeneousWalthall(param1, param2, param3, albedo)¶

Parameterisation for a surface BRDF based on the Walthall et al. model.

The parameters are:

term in square ts*tv
term in square ts*ts+tv*tv
term in ts*tv*cos(phi) (limacon de pascal)
albedo

Geometries¶

class Py6S.Geometry¶

class AVHRR_AM¶

Stores parameters for a AVHRR morning pass geometry for 6S.

Attributes:

month – The month the image was acquired in (0-12)

day – The day the image was acquired in (1-31)

column – The AVHRR column of the image

ascendant_node_longitude – The longitude of the ascendant node of the image

ascendant_node_hour – The hour of the ascendant node of the image

class AVHRR_PM¶

Stores parameters for a AVHRR afternoon pass geometry for 6S.

Attributes:

month – The month the image was acquired in (0-12)

day – The day the image was acquired in (1-31)

column – The AVHRR column of the image

ascendant_node_longitude – The longitude of the ascendant node of the image

ascendant_node_hour – The hour of the ascendant node of the image

class GoesEast¶

Stores parameters for a GOES East geometry for 6S.

Attributes:

month – The month the image was acquired in (0-12)

day – The day the image was acquired in (1-31)

gmt_decimal_hour – The time in GMT, as a decimal, in hours (eg. 7.5 for 7:30am)

column – The GOES East column of the image

line – The GOES East line of the image

class GoesWest¶

Stores parameters for a GOES West geometry for 6S.

Attributes:

month – The month the image was acquired in (0-12)

day – The day the image was acquired in (1-31)

gmt_decimal_hour – The time in GMT, as a decimal, in hours (eg. 7.5 for 7:30am)

column – The GOES West column of the image

line – The GOES West line of the image

class Landsat_TM¶

Stores parameters for a Landsat TM geometry for 6S.

Attributes:

month – The month the image was acquired in (0-12)

day – The day the image was acquired in (1-31)

gmt_decimal_hour – The time in GMT, as a decimal, in hours (eg. 7.5 for 7:30am)

latitude – The latitude of the centre of the image

longitude – The longitude of the centre of the image

class Meteosat¶

Stores parameters for a Meteosat geometry for 6S.

Attributes:

month – The month the image was acquired in (0-12)

day – The day the image was acquired in (1-31)

gmt_decimal_hour – The time in GMT, as a decimal, in hours (eg. 7.5 for 7:30am)

column – The Meteosat column of the image

line – The Meteosat line of the image

class SPOT_HRV¶

Stores parameters for a SPOT HRV geometry for 6S.

Attributes:

month – The month the image was acquired in (0-12)

day – The day the image was acquired in (1-31)

gmt_decimal_hour – The time in GMT, as a decimal, in hours (eg. 7.5 for 7:30am)

latitude – The latitude of the centre of the image

longitude – The longitude of the centre of the image

class User¶

Stores parameters for a user-defined geometry for 6S.

Attributes:

solar_z – Solar zenith angle

solar_a – Solar azimuth angle

view_z – View zenith angle

view_a – View azimuth angle

day – The day the image was acquired in (1-31)

month – The month the image was acquired in (0-12)

from_time_and_location(lat, long, datetimestring, view_z, view_a)¶

Sets the user-defined geometry to a given view zenith and azimuth, and a solar zenith and azimuth calculated from the lat, long and date given.

Uses the PySolar module for the calculations.

Arguments:

lat – The latitude of the location (0-90 degrees)
long – The longitude of the location
datetimestring – Any string that can be parsed to produce a date/time object. All that is really needed is a time - eg. “14:53”
view_z – The view zenith angle
view_a – The view azimuth angle

Altitudes¶

class Py6S.Altitudes¶

Allows the specification of target and sensor altitudes.

set_sensor_custom_altitude(altitude, aot=-1, water=-1, ozone=-1)¶

Set the altitude of the sensor, along with other variables required for the parameterisation of the sensor.

Takes optional arguments of aot, water and ozone to specify atmospheric contents underneath the sensor. If these aren’t specified then the water and ozone contents will be interpolated from the US-1962 standard atmosphere, and the AOT will be interpolated from a 2km exponential aerosol profile.

Arguments:

altitude – The altitude of the sensor, in km.
aot – (Optional, keyword argument) The AOT at 550nm at the sensor
water – (Optional, keyword argument) The water vapour content (in g/cm^2) at the sensor
ozone – (Optional, keyword argument) The ozone content (in cm-atm) at the sensor

Example usage:

s.altitudes.set_sensor_custom_altitude(8, 0.35, 1.6, 0.4) # Altitude of 8km, AOT of 0.35, Water content of 1.6g/cm^2 and Ozone of 0.4cm-atm

set_sensor_satellite_level()¶: Set the sensor altitude to be satellite level.

set_sensor_sea_level()¶: Set the sensor altitude to be sea level.

set_target_custom_altitude(altitude)¶

Set the altitude of the target.

Arguments:

altitude – The altitude of the target, in km

set_target_pressure(pressure)¶

Set the pressure of the target (a proxy for the height of the target).

Arguments:

pressure – The pressure at the target, in mb

set_target_sea_level()¶: Set the altitude of the target to be at sea level (0km)

Wavelengths¶

class Py6S.Wavelength¶

Select one or more wavelengths for the 6S simulation.

There are a number of ways to do this:

Pass a single value of a wavelength in micrometres. The simulation will be performed for just this wavelength:
```
Wavelength(0.43)
```
Pass a start and end wavelength in micrometres. The simulation will be performed across this wavelength range with a constant filter function (spectral response function) of 1.0:
```
Wavelength(0.43, 0.50)
```
Pass a start and end wavelength, and a filter given at 2.5nm intervals. The simulation will be performed across this wavelength range using the given filter function:
```
Wavelength(0.400, 0.410, [0.7, 0.9, 1.0, 0.3])
```
Pass a constant (as defined in this class) for a pre-defined wavelength range:
```
Wavelength(PredefinedWavelengths.LANDSAT_TM_B1)
```

METEOSAT_VISIBLE

GOES_EAST_VISIBLE

GOES_WEST_VISIBLE

AVHRR_NOAA6_B1

AVHRR_NOAA6_B2

AVHRR_NOAA7_B1

AVHRR_NOAA7_B2

AVHRR_NOAA8_B1

AVHRR_NOAA8_B2

AVHRR_NOAA9_B1

AVHRR_NOAA9_B2

AVHRR_NOAA10_B1

AVHRR_NOAA10_B2

AVHRR_NOAA11_B1

AVHRR_NOAA11_B2

SPOT_HRV1_B1

SPOT_HRV1_B2

SPOT_HRV1_B3

SPOT_HRV1_PAN

SPOT_HRV2_B1

SPOT_HRV2_B2

SPOT_HRV2_B3

SPOT_HRV2_PAN

LANDSAT_TM_B1

LANDSAT_TM_B2

LANDSAT_TM_B3

LANDSAT_TM_B4

LANDSAT_TM_B5

LANDSAT_TM_B7

LANDSAT_MSS_B1

LANDSAT_MSS_B2

LANDSAT_MSS_B3

LANDSAT_MSS_B4

ER2_MAS_B1

ER2_MAS_B2

ER2_MAS_B3

ER2_MAS_B4

ER2_MAS_B5

ER2_MAS_B6

ER2_MAS_B7

MODIS_B1

MODIS_B2

MODIS_B3

MODIS_B4

MODIS_B5

MODIS_B6

MODIS_B7

MODIS_B8

AVHRR_NOAA12_B1

AVHRR_NOAA12_B2

AVHRR_NOAA14_B1

AVHRR_NOAA14_B2

POLDER_B1

POLDER_B2

POLDER_B3

POLDER_B4

POLDER_B5

POLDER_B6

POLDER_B7

POLDER_B8

SEAWIFS_B1

SEAWIFS_B2

SEAWIFS_B3

SEAWIFS_B4

SEAWIFS_B5

SEAWIFS_B6

SEAWIFS_B7

SEAWIFS_B8

AATSR_B1

AATSR_B2

AATSR_B3

AATSR_B4

MERIS_B1

MERIS_B2

MERIS_B3

MERIS_B4

MERIS_B5

MERIS_B6

MERIS_B7

MERIS_B8

MERIS_B9

MERIS_B10

MERIS_B11

MERIS_B12

MERIS_B13

MERIS_B14

MERIS_B15

GLI_B1

GLI_B2

GLI_B3

GLI_B4

GLI_B5

GLI_B6

GLI_B7

GLI_B8

GLI_B9

GLI_B10

GLI_B11

GLI_B12

GLI_B13

GLI_B14

GLI_B15

GLI_B16

GLI_B17

GLI_B18

GLI_B19

GLI_B20

GLI_B21

GLI_B22

GLI_B23

GLI_B24

GLI_B25

GLI_B26

GLI_B27

GLI_B28

GLI_B29

GLI_B30

ALI_B1P

ALI_B1

ALI_B2

ALI_B3

ALI_B4

ALI_B4P

ALI_B5P

ALI_B5

ALI_B7

ASTER_B1

ASTER_B2

ASTER_B3N

ASTER_B3B

ASTER_B4

ASTER_B5

ASTER_B6

ASTER_B7

ASTER_B8

ASTER_B9

ETM_B1

ETM_B2

ETM_B3

ETM_B4

ETM_B5

ETM_B7

HYPBLUE_B1

HYPBLUE_B2

SPOT_VGT_B1

SPOT_VGT_B2

SPOT_VGT_B3

SPOT_VGT_B4

VIIRS_BM1

VIIRS_BM2

VIIRS_BM3

VIIRS_BM4

VIIRS_BM5

VIIRS_BM6

VIIRS_BM7

VIIRS_BM8

VIIRS_BM9

VIIRS_BM10

VIIRS_BM11

VIIRS_BM12

VIIRS_BI1

VIIRS_BI2

VIIRS_BI3

VIIRS_BI4

Atmospheric Corrections¶

class Py6S.AtmosCorr¶

Class representing options for selecting atmospheric correction settings for 6S.

classmethod AtmosCorrBRDFFromRadiance(radiance)¶

Set 6S to perform atmospheric correction using a fully BRDF-represented surface, using a given radiance value.

Arguments: * radiance – Radiance of the surface

classmethod AtmosCorrBRDFFromReflectance(reflectance)¶

Set 6S to perform atmospheric correction using a fully BRDF-represented surface, using a given reflectance value.

Arguments: * reflectance – Reflectance of the surface.

classmethod AtmosCorrLambertianFromRadiance(radiance)¶

Set 6S to perform atmospheric correction assuming a Lambertian surface, using a given radiance value.

Arguments: * radiance – Radiance of the surface.

classmethod AtmosCorrLambertianFromReflectance(reflectance)¶

Set 6S to perform atmospheric correction assuming a Lambertian surface, using a given reflectance value.

Arguments: * reflectance – Reflectance of the surface.

classmethod NoAtmosCorr()¶: Set 6S not to perform any atmospheric correction

Helper methods¶

The SixSHelpers module contains a number of helper functions that improve the ease-of-use of Py6S. These include functions to set 6S parameters from various external data sources, as well as functions to make it easy to produce wavelength and BRDF plots from 6S runs.

Running for many wavelengths¶

The Wavelengths class contains functions to run 6S over a number of wavelength ranges.

For example, the following code runs 6S simulations across the Visible-Near Infrared wavelength range and plots the results, producing the output shown below:

from Py6S import *
s = SixS()
s.aero_profile = AeroProfile.PredefinedType(AeroProfile.Maritime)
wavelengths, values = SixSHelpers.Wavelengths.run_vnir(s, output_name='pixel_radiance')
SixSHelpers.Wavelengths.plot_wavelengths(wavelengths, values, 'Pixel Radiance (W/m^2)')

A similar function exist to run across the whole 6S wavelength range (run_whole_range()), and arbritary lists of wavelengths can be run using the run_wavelengths() function. For example, you can manually specify a number of wavelengths to run for:

wv, res = SixSHelpers.Wavelengths.run_wavelengths(s, [0.46, 0.67, 0.98], output_name='apparent_radiance')

If you want to run user-specific ranges of wavelengths then you can use the handy numpy functions arange and linspace to generate the lists of wavelengths for you. For example:

# Run the model between 0.5 and 0.7um with a step of 0.001um (1nm)
wv, res = SixSHelpers.Wavelengths.run_wavelengths(s, np.arange(0.5, 0.7, 0.001), output_name='apparent_radiance')

# Run the model at 50 equally-spaced wavelengths in the range 0.9-1.5um
wv, res = SixSHelpers.Wavelengths.run_wavelengths(s, np.linspace(0.9, 1.5, 50), output_name='apparent_radiance')

Functions also exist to run for all bands of the various sensors supported in 6S (for example, run_landsat_tm(), run_modis() and run_aatsr()). It should be noted that for these functions, bands which are outside of the 6S wavelength range (0.2-4.0um), such as the Landsat thermal band, will not be simulated. The example below shows the creation of a plot for the Landsat ETM bands:

from Py6S import *
s = SixS()
s.aero_profile = AeroProfile.PredefinedType(AeroProfile.Maritime)
wavelengths, values = SixSHelpers.Wavelengths.run_landsat_etm(s, output_name='pixel_reflectance')
SixSHelpers.Wavelengths.plot_wavelengths(wavelengths, values, 'Pixel Reflectance')

The supported sensors are:

Landsat MSS, TM and ETM

SPOT HRV1, HRV2 and Vegetation

MERIS

MODIS

POLDER

SeaWiFS

AATSR

ASTER

VIIRS

ER2 MODIS Airborne Simulator (MAS)

ALI

GLI

class Py6S.SixSHelpers.Wavelengths¶

Helper functions for running the 6S model for a range of wavelengths, and plotting the result

classmethod extract_output(results, output_name)¶

Extracts data for one particular SixS output from a list of SixS.Outputs instances.

Basically just a wrapper around a list comprehension.

Arguments:

results – A list of SixS.Outputs instances
output_name – The name of the output to extract. This should be a string containing whatever is put after the s.outputs when printing the output, for example ‘pixel_reflectance’.

classmethod plot_wavelengths(wavelengths, values, y_axis_label)¶

Plot the given wavelengths and values, such as those produced by the other functions in this class.

Arguments:

wavelengths – A list of wavelengths (in um)
values – A corresponding list of values at the wavelengths above
y_axis_label – A string containing tha axis label to use for the Y axis

Example usage:

SixSHelpers.PredefinedWavelengths.plot_wavelengths(wavelengths, values, 'Pixel Radiance ($W/m^2$)')

classmethod run_aatsr(s, **kwargs)¶

Runs the given SixS parameterisation for all of the AATSR bands within the 6S band range, optionally extracting a specific output.

Arguments:

s – A SixS instance with the parameters set as required
output_name – (Optional) The output to extract from s.outputs, as a string that could be placed after s.outputs., for example pixel_reflectance

Return value: