Function Repository Resource:

StandardSkyLuminanceData

Source Notebook

Get properties of the CIE Standard General Sky

Contributed by: Jason Martinez

ResourceFunction["StandardSkyLuminanceData"][type]

returns CIE Standard General Sky properties of the given sky type.

ResourceFunction["StandardSkyLuminanceData"][type,property]

returns a property of the CIE Standard General Sky type.

ResourceFunction["StandardSkyLuminanceData"][type,property, pos]

returns the value of a property at a specific point pos in the sky.

ResourceFunction["StandardSkyLuminanceData"][type,property, pos, sunpos]

returns the value with the sun location specified at sunpos.

Details and Options

The type can be an Integer between 1 and 15, corresponding to the 15 CIE (Commission Internationale del'Eclairage) Standard General Sky types. It can also be an Association with the keys "GradationGroup" and "IndicatrixGroup", which specify the sky type of interest.

"GradationGroup" characterizes the luminance of the sky as a function of altitude. It ranges in value from 1 to 6. "GradationGroup" can be specified as an Integer or a String consisting of a Roman numeral.

"IndicatrixGroup" dictates how the sky luminance varies relative the position of the Sun. It ranges in value from 1 to 6. "IndicatrixGroup" should be an Integer.

The defined sky types do not cover all possible combinations of "GradationGroup" and "IndicatrixGroup".

ResourceFunction["StandardSkyLuminanceData"]["Properties"] gives a list of all properties available.

Properties include:

"CIEStandardGeneralSkyParameters"

CIE Standard General Sky formula coefficients

"Description"

sky type description

"GradationGroup"

gradation function group

"IndicatrixGroup"

indicatrix function group

"RelativeGradation"

gradation value relative to zenith

"RelativeIndicatrix"

indicatrix value relative to zenith

"RelativeLuminance"

luminance relative to zenith luminance

Alternatively, "PropertyAssociation" can be used to return an Association of the properties.

The pos can be an Association with the keys "Azimuth" and "ZenithAngle". "Azimuth" ranges from 0 to 2 Pi as measured clockwise from the north. "ZenithAngle" ranges from 0 to Pi as measured from the zenith toward the horizon. Alternatively, "Altitude" can be substituted for "ZenithAngle". Another alternative is to specify a list of the form {azimuth, zenithangle}. All angles can be numbers in radians or quantities with angular units.

The azimuth or zenith angle can take values of All, in which case an interpolation of the "RelativeGradation", "RelativeIndicatrix" and "RelativeLuminance" is computed where applicable.

In the absence of a specific sky position, values of All are taken for "Azimuth" and "ZenithAngle".

The sunpos can be an Association with the keys "SolarAzimuth" and "SolarZenithAngle". "SolarAzimuth" ranges from 0 to 2 Pi as measured clockwise from the north. "SolarZenithAngle" ranges from 0 to Pi as measured from the zenith toward the horizon. Alternatively, "SolarAltitude" can be substituted for "SolarZenithAngle". Another alternative is to specify a list of the form {azimuth, zenithangle}. All angles can be numbers in radians or quantities with angular units.

The sunpos can also be specified by providing the Association keys "Date" and "Position". "Date" can be a DateList or DateObject. Position can be an Entity, set of coordinates or GeoPosition. In this case, the position is determine by computing the Sun's position based on the date and location.

In the absence of a specified date and/or position, the sunpos is determined using the current time and $GeoLocation.

"RelativeGradation", "RelativeIndicatrix" and "RelativeLuminance" are unavailable for pos or sunpos below the horizon.

CIE provides the following descriptions for the sky types:

1	Overcast CIE Standard Overcast Sky,steep luminance gradation towards zenith,azimuthal uniformity
2	Overcast,with steep luminance gradation and slight brightening towards the sun
3	Overcast,moderately graded with azimuthal uniformity
4	Overcast,moderately graded and slight brightening towards the sun
5	Sky of uniformity luminance
6	Partly cloudy sky,no gradation towards zenith,slight brightening towards the sun
7	Partly cloudy sky,no gradation towards zenith,brighter circumsolar effect
8	Partly cloudy sky,no gradation towards zenith,distinct solar corona
9	Partly cloudy,with obscured sun
10	Partly cloudy,with brighter circumsolar regio
11	White–blue sky with distinct solar corona
12	CIE Standard Clear Sky,low luminance turbidity
13	CIE Standard Clear Sky,polluted atmosphere
14	Cloudless turbid sky with broad solar corona
15	White–blue turbid sky with broad solar corona

Examples

Basic Examples (3)

Compute the relative luminance of a spot in the sky:

In[1]:=

Out[1]=

Specify a position based on altitude and azimuth:

In[2]:=

Out[2]=

Determine the relative indicatrix as a function of azimuth:

In[3]:=

In[4]:=

Out[4]=

Calculate the relative luminance with a specified sun position:

In[5]:=

ResourceFunction["StandardSkyLuminanceData"][2, "RelativeLuminance", Association["Azimuth" -> Pi/4, "ZenithAngle" -> Quantity[30, "AngularDegrees"]], Association["SolarAzimuth" -> Pi/4, "SolarZenithAngle" -> Quantity[30, "AngularDegrees"]]]

Out[5]=

Scope (8)

Obtain a list of properties:

In[6]:=

Out[6]=

Examine the range of "GradationGroup" and "IndicatrixGroup" values:

In[7]:=

Grid[Prepend[
Table[Prepend[
ResourceFunction["StandardSkyLuminanceData"][
i, #] & /@ {"GradationGroup", "IndicatrixGroup"}, i], {i, 15}], {"Type", "GradationGroup", "IndicatrixGroup"}], Frame -> All]

Out[7]=

Specify sky type via gradation and indicatrix group:

In[8]:=

data = ResourceFunction["StandardSkyLuminanceData"][
Association["GradationGroup" -> "V", "IndicatrixGroup" -> 5], "RelativeLuminance", Association["Azimuth" -> All, "ZenithAngle" -> All], Association["SolarAzimuth" -> Pi, "SolarZenithAngle" -> Pi/4]]

Out[8]=

Visualize the luminance across the sky:

In[9]:=

$SphericalPlot3D[1, {\[Theta], 0, Pi/2}, {\[Phi], 0, 2 Pi}, Mesh -> None, Axes -> False, PlotPoints -> 60, ColorFunctionScaling -> False, ColorFunction -> Function[{x, y, z, \[Theta], \[Phi], r}, ColorData["TemperatureMap"][data[\[Phi], \[Theta]]/5]]]$

Out[9]=

Examine the descriptions of all 15 sky types:

In[10]:=

Out[10]=

Obtain the parameters for a sky type:

In[11]:=

Out[11]=

Compute all properties for a sky type:

In[12]:=

Out[12]=

Plot the relative luminance for an entire sky:

In[13]:=

data = ResourceFunction["StandardSkyLuminanceData"][8, "RelativeLuminance", Association["Azimuth" -> All, "ZenithAngle" -> All], Association["SolarAzimuth" -> 0, "SolarZenithAngle" -> Pi/4]]

Out[13]=

In[14]:=

$DensityPlot[ data[ArcCos[y/Sqrt[x^2 + y^2]], ArcCos[Sqrt[x^2 + y^2]]], {x, -1, 1}, {y, -1, 1}, RegionFunction -> Function[{x, y}, x^2 + y^2 < 1], ColorFunction -> "TemperatureMap", PlotRange -> All]$

Out[14]=

Compute relative luminance using the sun's current position in New York City:

In[15]:=

ResourceFunction["StandardSkyLuminanceData"][2, "RelativeLuminance", Association["Azimuth" -> Pi/4, "Altitude" -> Quantity[30, "AngularDegrees"]], Association["Date" -> Now, "Position" -> Entity["City", {"NewYork", "NewYork", "UnitedStates"}]]]

Out[15]=

Possible Issues (2)

"RelativeGradation" does not vary in azimuth, so no interpolation is generated with "Azimuth" set to All:

In[16]:=

Out[16]=

Computed properties are unavailable for sky and sun positions below the horizon:

In[17]:=

ResourceFunction["StandardSkyLuminanceData"][4, "RelativeLuminance", Association["Azimuth" -> Pi/4, "Altitude" -> Quantity[30, "AngularDegrees"]], Association["Date" -> DateObject[{2012, 1, 2, 1}], "Position" -> GeoPosition[{40, -100}]]]

Out[17]=

In[18]:=

Out[18]=

Version History

1.0.0 – 13 August 2020

Source Metadata

Citation:
- International Organization for Standardization, "Spatial distribution of daylight—CIE standard general sky." ISO 15469:2004(E), February 2004.

Related Resources

License Information

This work is licensed under a Creative Commons Attribution 4.0 International License

Wolfram Function Repository

StandardSkyLuminanceData

Details and Options