honeybee_radiance.lightsource.sky.climatebased module

Generate a point-in-time climate-based sky.

class honeybee_radiance.lightsource.sky.climatebased.ClimateBased(altitude, azimuth, direct_normal_irradiance, diffuse_horizontal_irradiance, ground_reflectance=0.2, is_colored=False)[source]

Bases: _PointInTime

Point-in-time Climate-based sky.

The output of Climatebased sky is similar to using command Radiance’s gendaylit command. For more information see gendaylit documentation.

Parameters:

  • altitude – Solar altitude. The altitude is measured in degrees above the horizon.

  • azimuth – Solar azimuth. The azimuth is measured in degrees east of North. East is 90, South is 180 and West is 270. Note that this input is different from the Radiance convention. In Radiance the azimuth degrees are measured in west of South.

  • direct_normal_irradiance – Direct normal irradiance (W/m2).

  • diffuse_horizontal_irradiance – Diffuse horizontal irradiance (W/m2).

  • ground_reflectance – Average ground reflectance (Default: 0.2).

  • is_colored – Boolean to note whether the sky will be rendered in full color (True) or it will simple be a grey sky with the same average value as the colored sky (False). (Default: False).

Properties:

  • altitude

  • azimuth

  • direct_normal_irradiance

  • diffuse_horizontal_irradiance

  • ground_hemisphere

  • sky_hemisphere

  • ground_reflectance

  • is_colored

  • is_point_in_time

  • is_climate_based

ToString()

Overwrite .NET ToString.

classmethod from_dict(data)[source]

Create a ClimateBased sky from a dictionary.

Parameters:

data – A python dictionary in the following format

{
    'type': 'ClimateBased',
    'altitude': 0.0,
    'azimuth': 0.0,
    'direct_normal_irradiance': 800,
    'diffuse_horizontal_irradiance': 120,
    'ground_reflectance': 0.2,  # optional float for ground reflectance
    'is_colored': True  # boolean for whether the sky is colored
}
classmethod from_epw(epw, month, day, hour, north_angle=0, ground_reflectance=0.2, is_colored=False)[source]

Create a standard climate-based sky from a EPW.

Parameters:

  • epw – A Ladybug EPW objects.

  • month – An integer between 1-12 for month.

  • day – An integer between 1 to 28-31 depending on the input month.

  • hour – A float number larger or equal to 0 and smaller than 24.

  • north_angle – North angle in degrees. A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East (Default: 0).

  • ground_reflectance – Average ground reflectance (Default: 0.2).

  • is_colored – Boolean to note whether the sky will be rendered in full color (True) or it will simple be a grey sky with the same average value as the colored sky (False). (Default: False).

classmethod from_epw_monthly_average(epw, month, hour, north_angle=0, ground_reflectance=0.2, is_colored=False)[source]

Create a monthly averaged climate-based sky from an EPW and a hour of the day.

Parameters:

  • epw – A Ladybug EPW objects.

  • month – An integer between 1-12 for month.

  • hour – A float number larger or equal to 0 and smaller than 24.

  • north_angle – North angle in degrees. A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East (Default: 0).

  • ground_reflectance – Average ground reflectance (Default: 0.2).

  • is_colored – Boolean to note whether the sky will be rendered in full color (True) or it will simple be a grey sky with the same average value as the colored sky (False). (Default: False).

classmethod from_lat_long(latitude, longitude, time_zone, month, day, hour, direct_normal_irradiance, diffuse_horizontal_irradiance, north_angle=0, ground_reflectance=0.2, is_colored=False)[source]

Create a climate based sky from latitude, longitude and a date/time.

Parameters:

  • latitude – Location latitude between -90 and 90.

  • longitude – Location longitude between -180 (west) and 180 (east).

  • time_zone – Time zone between -12 hours (west) and +14 hours (east). If None, the time will be interpreted as solar time at the given longitude.

  • month – An integer between 1-12 for month.

  • day – An integer between 1 to 28-31 depending on the input month.

  • hour – A float number larger or equal to 0 and smaller than 24.

  • direct_normal_irradiance – Direct normal irradiance (W/m2).

  • diffuse_horizontal_irradiance – Diffuse horizontal irradiance (W/m2).

  • north_angle – North angle in degrees. A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East (Default: 0).

  • ground_reflectance – Average ground reflectance (Default: 0.2).

  • is_colored – Boolean to note whether the sky will be rendered in full color (True) or it will simple be a grey sky with the same average value as the colored sky (False). (Default: False).

classmethod from_location(location, month, day, hour, direct_normal_irradiance, diffuse_horizontal_irradiance, north_angle=0, ground_reflectance=0.2, is_colored=False)[source]

Create a standard climate-based sky for a location.

Parameters:

  • location – A Ladybug location.

  • month – An integer between 1-12 for month.

  • day – An integer between 1 to 28-31 depending on the input month.

  • hour – A float number larger or equal to 0 and smaller than 24.

  • direct_normal_irradiance – Direct normal irradiance (W/m2).

  • diffuse_horizontal_irradiance – Diffuse horizontal irradiance (W/m2).

  • north_angle – North angle in degrees. A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East (Default: 0).

  • ground_reflectance – Average ground reflectance (Default: 0.2).

  • is_colored – Boolean to note whether the sky will be rendered in full color (True) or it will simple be a grey sky with the same average value as the colored sky (False). (Default: False).

classmethod from_string(sky_string)[source]

Create a ClimateBased sky from a string.

Parameters:

sky_string – A text string representing a ClimateBased sky. This can either be a minimal string representation of the sky (eg. “climate-based -alt 71.6 -az 185.2 -dni 800 -dhi 120”). Or it can be a detailed specification of time and location (eg. “climate-based 21 Jun 12:00 -lat 41.78 -lon -87.75 -dni 800 -dhi 120”). Any sky string can optionally have a “-g” property of a fractional number, which sets the reflectance of the ground. If unspecified, the ground will have a reflectance of 0.2. The detailed string can optionally have a “-tz” property with an integer between -12 and +14 to denote the time zone. If unspecified, the time will be interpreted as solar time at the given longitude. The detailed string can also have a “-n” property between 0 and 360 to set the counterclockwise difference between the North and the positive Y-axis in degrees. All other properties specified in the string are required.

Usage:

# minimal string representation of the sky
sky_string = "climate-based -alt 71.6 -az 185.2 -dni 800 -dhi 120"
sky = ClimateBased.from_string(sky_string)

# detailed location-specific representation of the sky
sky_string = "climate-based 21 Jun 12:00 -lat 41.78 -lon -87.75 -tz -6 "                 " -dni 800 -dhi 120 -n 0 -g 0.2"
sky = ClimateBased.from_string(sky_string)
classmethod from_wea(wea, month, day, hour, north_angle=0, ground_reflectance=0.2, is_colored=False)[source]

Create a standard climate-based sky from a Wea.

Parameters:

  • wea – A Ladybug wea object.

  • month – An integer between 1-12 for month.

  • day – An integer between 1 to 28-31 depending on the input month.

  • hour – A float number larger or equal to 0 and smaller than 24.

  • north_angle – North angle in degrees. A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East (Default: 0).

  • ground_reflectance – Average ground reflectance (Default: 0.2).

  • is_colored – Boolean to note whether the sky will be rendered in full color (True) or it will simple be a grey sky with the same average value as the colored sky (False). (Default: False).

classmethod from_wea_monthly_average(wea, month, hour, north_angle=0, ground_reflectance=0.2, is_colored=False)[source]

Create a monthly averaged climate-based sky from a Wea and a hour of the day.

Parameters:

  • wea – A Ladybug wea object.

  • month – An integer between 1-12 for month.

  • hour – A float number larger or equal to 0 and smaller than 24.

  • north_angle – North angle in degrees. A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East (Default: 0).

  • ground_reflectance – Average ground reflectance (Default: 0.2).

  • is_colored – Boolean to note whether the sky will be rendered in full color (True) or it will simple be a grey sky with the same average value as the colored sky (False). (Default: False).

to_dict()[source]

Translate sky to a dictionary.

to_file(folder, name=None, mkdir=False)[source]

Write sky hemisphere to a sky_hemisphere.rad Radiance file.

Parameters:

  • folder – Target folder.

  • name – File name.

  • mkdir – A boolean to note if the directory should be created if doesn’t exist (default: False).

Returns:

Full path to the newly created file.

to_radiance(output_type=0)[source]

Return Radiance description of the sky.

Parameters:

output_type – An integer between 0 to 2 for output type. * 0 = output in W/m2/sr visible (default) * 1 = output in W/m2/sr solar * 2 = output in lm/m2/sr luminance

property altitude

Get or set a number between -90 and 90 for the solar altitude.

The altitude is measured in degrees above the horizon.

property azimuth

Get or set a number between 0 and 360 for the solar azimuth.

The azimuth is measured in degrees east of North. East is 90, South is 180 and West is 270. Note that this input is different from Radiance convention. In Radiance the azimuth degrees are measured in west of South.

property diffuse_horizontal_irradiance

Get or set diffuse horizontal irradiance (W/m2).

property direct_normal_irradiance

Get or set direct normal irradiance (W/m2).

property ground_hemisphere

Sky ground glow source.

property ground_reflectance

Get or set a value between 0 and 1 for the ground reflectance.

If not specified, a default of 0.2 will be used.

property is_climate_based

Return True if the sky is created based on values from weather data.

property is_colored

Get or set a boolean for whether the sky is rendered in full color.

property is_point_in_time

Return True if the sky is generated for a single point in time.

property sky_hemisphere

Sky hemisphere glow source.