honeybee_radiance.luminaire module

Module for simulating electric lighting.

class honeybee_radiance.luminaire.CustomLamp(name, depreciation_factor=1.0, candela_multiplier=1.0, rgb=None, white_xy=None, color_temperature=None)[source]

Bases: object

Custom lamp definition for a luminaire.

A CustomLamp overrides or modifies the luminous output of an IES-defined luminaire without changing its photometric distribution.

Parameters:

  • name – Text identifier for the lamp.

  • depreciation_factor – Lumen depreciation factor (0-1).

  • rgb – Optional RGB tuple (r, g, b), values 0-1.

  • white_xy – Optional CIE xy tuple (x, y).

  • color_temperature – Optional color temperature in Kelvin.

ToString()[source]

Overwrite ToString .NET method.

classmethod from_color_temperature(name, color_temperature, depreciation_factor=1.0)[source]

Create a CustomLamp from a correlated color temperature (CCT).

Parameters:

  • name – Name of the lamp.

  • color_temperature – CCT in Kelvin (1000-25000).

  • depreciation_factor – Optional lumen depreciation factor.

Returns:

CustomLamp instance with white_xy computed from CCT.

classmethod from_default_white(name, depreciation_factor=1.0)[source]

Create a default white CustomLamp with 3200 K CCT.

Parameters:

  • name – Name of the lamp.

  • depreciation_factor – Optional lumen depreciation factor.

Returns:

CustomLamp instance with metadata.

classmethod from_dict(data)[source]

Create a CustomLamp from a dictionary.

classmethod from_lamp_name(lamp_name)[source]

Create a CustomLamp from a lamp name from a list of predefined lamps.

Parameters:

  • lamp_name – Name matching a legacy Honeybee lamp type.

  • depreciation_factor – Optional lumen depreciation factor.

Returns:

CustomLamp

classmethod from_rgb_colors(name, rgb_color, depreciation_factor=1.0)[source]

Create a CustomLamp from RGB colors.

Parameters:

  • name – Name of the lamp.

  • rgb_color – Tuple/list with values (R, G, B, A) in 0-255.

  • depreciation_factor – Optional lumen depreciation factor.

Returns:

CustomLamp instance with metadata.

classmethod from_xy_coordinates(name, x, y, depreciation_factor=1.0, color_space=0)[source]

Create a CustomLamp from CIE xy coordinates.

Parameters:

  • name – Name of the lamp.

  • x – CIE xy coordinates (0-1).

  • y – CIE xy coordinates (0-1).

  • depreciation_factor – Optional lumen depreciation factor.

  • color_space – Optional color space (0=1931, 1=1960, 2=1976).

Returns:

CustomLamp instance with metadata.

to_dict()[source]

Convert CustomLamp to dictionary.

property candela_multiplier

Return candela multiplier.

property color_temperature

Correlated color temperature in Kelvin, if defined.

property depreciation_factor

Return depreciation factor.

property is_rgb

Return boolean to note whether or not lamp is RGB.

property is_white

Return boolean to note whether or not lamp is White.

property metadata

Return lamp metadata.

property name

Return lamp name.

property rgb

Return RGB values.

property white_xy

Rwturn x, y chromaticities.

class honeybee_radiance.luminaire.Luminaire(ies_path, identifier=None, luminaire_zone=None, custom_lamp=None, light_loss_factor=1, candela_multiplier=1)[source]

Bases: object

A luminaire defined by an IES photometric file.

The Luminaire object stores the photometric data of a light fixture and provides methods to:

  • Parse IES LM-63 photometric data

  • Generate Radiance geometry via ies2rad

  • Generate pure-Python photometric web geometry

  • Place and orient luminaires in space via a LuminaireZone

Parameters:

  • ies_path – Path to an IES LM-63 photometric file. The file will be read and stored internally as text to ensure the Luminaire can be serialized and recreated even if the original file is no longer available.

  • identifier – Optional text string for a unique Luminaire ID. This identifier is used to name Radiance output files and geometry. If None, the identifier will be derived from the IES file name.

  • luminaire_zone – Optional LuminaireZone object defining the spatial placement, orientation, and repetition of the luminaire in the scene. This is required to generate positioned Radiance geometry (xform output).

  • light_loss_factor – A scalar multiplier applied to account for lamp lumen depreciation, dirt depreciation, or other system losses. Must be greater than 0. Default: 1.

  • candela_multiplier – Additional scalar multiplier applied to candela values after parsing the IES file. Must be greater than 0. Default: 1.

Properties:

  • ies_path

  • ies_content

  • identifier

  • luminaire_zone

  • custom_lamp

  • light_loss_factor

  • candela_multiplier

  • vertical_angles

  • horizontal_angles

  • candela_values

  • unit_type

  • width

  • length

  • height

  • max_candela

  • unit_scale

ToString()[source]

Overwrite ToString .NET method.

classmethod from_dict(data)[source]

Create a Luminaire from a dictionary.

Parameters:

data – A python dictionary of a Luminaire.

generate_photometric_web(normalize=True)[source]

Generate a photometric web geometry.

Parameters:

normalize – If set to True the geometry is normalized to unit dimensions.

Returns:

  • points: list of Point3D objects.

  • horizontal_angles (rad)

  • vertical_angles (rad)

  • scale

Return type:

dict with keys

generate_scene(libdir=None, prefdir=None)[source]

Create a combined scene description of LuminaireZone and Luminaire.

This method will create a scene description where there scene from ies2rad is added in the correct location via xform.

Parameters:

  • libdir – Set the library directory.

  • prefdir – Set the library subdirectory.

Returns:

Combined Radiance scene description of LuminaireZone and Luminaire.

ies2rad(libdir=None, prefdir=None, outname=None)[source]

Executes ies2rad.

Parameters:

  • libdir – Set the library directory.

  • prefdir – Set the library subdirectory.

  • outname – Output file name root.

Returns:

Radiance scene description (rad file).

parse_photometric_data()[source]

Parse IES LM-63 photometric data from stored IES content.

Populates:

  • vertical_angles

  • horizontal_angles

  • candela_values

  • unit_type

  • width, length, height

  • max_candela

to_dict()[source]

Return Luminaire as a dictionary.

write_ies(folder, filename=None)[source]

Write the stored IES content back to disk.

property candela_multiplier

Get or set the candela multiplier (default = 1).

property candela_values

Raw candela values from IES

property custom_lamp

Get or set the custom lamp of the luminaire.

property height

Get the luminaire height.

property height_m

Get the luminaire height in meters.

property horizontal_angles

Get the list of horizontal angles defined in the IES file.

property identifier

Get or set the identifier of the luminaire.

property ies_content

Get or set the IES content of the luminaire.

property ies_path

Get or set the IES file of the luminaire.

property length

Get the luminaire length.

property length_m

Get the luminaire length in meters.

property light_loss_factor

Get or set the light loss factor (default = 1).

property luminaire_zone

Get or set the LuminaireZone of the luminaire.

property max_candela

Get the maximum candela value in the photometric distribution.

property normalized_candela_values

Candela values normalized by max candela

property unit_scale

Scale factor to convert IES units to meters

property unit_type

1=feet, 2=meters

Type:

IES unit type

property vertical_angles

Get the list of vertical angles defined in the IES file.

property width

Get the luminaire width.

property width_m

Get the luminaire width in meters.

class honeybee_radiance.luminaire.LuminaireInstance(point, spin=0, tilt=0, rotation=0)[source]

Bases: object

A single positioned and oriented instance of a luminaire.

A LuminaireInstance represents one physical placement of a luminaire in space. It defines the luminaire’s location and orientation using IES LM-63 C0-G0 conventions.

Orientation is defined using three angular values (in degrees):

A single Luminaire may have many LuminaireInstance objects, typically grouped together within a LuminaireZone.

Parameters:

  • point – Location of the luminaire instance. Can be a Ladybug Geometry Point3D or a list/tuple of three numeric values [x, y, z].

  • spin – Rotation about the local vertical axis (degrees). Default: 0.

  • tilt – Tilt angle away from the negative Z axis (degrees). Default: 0.

  • rotation – Rotation in the horizontal plane about the C0 axis (degrees). Default: 0.

Properties:

  • point

  • spin

  • tilt

  • rotation

ToString()[source]

Overwrite ToString .NET method.

classmethod from_aiming_point(point, aiming_point, spin=0, tilt=0, rotation=0)[source]

Create a LuminaireInstance aimed at a target point.

Parameters:

  • point – Luminaire location. Can be Point3D or list/tuple of three values.

  • aiming_point – Target point the luminaire should aim at. Can be Point3D or list/tuple of three values.

  • spin – User-defined spin offset (degrees).

  • tilt – User-defined tilt offset (degrees).

  • rotation – User-defined rotation offset (degrees).

classmethod from_dict(data)[source]

Create a LuminaireInstance from a dictionary.

Parameters:

data – A python dictionary of a LuminaireInstance.

to_dict()[source]

Return LuminaireInstance as a dictionary.

property point

Get the Point3D object of the LuminaireInstance.

property rotation

Get the rotation value of the LuminaireInstance.

property spin

Get the spin value of the LuminaireInstance.

property tilt

Get the tilt value of the LuminaireInstance.

class honeybee_radiance.luminaire.LuminaireZone(instances)[source]

Bases: object

A collection of luminaire instances defining a lighting layout.

A LuminaireZone groups one or more LuminaireInstance objects together to describe how a Luminaire is distributed, positioned, and oriented within a scene.

The LuminaireZone is attached to a Luminaire object and is required for generating positioned Radiance geometry (xform output).

Typical use cases include:

  • Repeated luminaires in a grid

  • Multiple luminaires sharing the same photometric definition

  • Luminaires with varying orientation and aiming directions

Parameters:

instances – A list of LuminaireInstance objects.

Properties:

  • instances

  • points

  • spins

  • tilts

  • rotations

ToString()[source]

Overwrite ToString .NET method.

classmethod from_dict(data)[source]

Create a LuminaireZone from a dictionary.

Parameters:

data – A python dictionary of a LuminaireZone.

to_dict()[source]

Return LuminaireZone as a dictionary.

property instances

Get a list of LuminaireInstance objects.

property points

Return a list of points.

property rotations

Return a list of rotation values.

property spins

Return a list of spin values.

property tilts

Return a list of tilt values.

honeybee_radiance.luminaire.calc_cct(a, b, year)[source]

Calculate Correlated Color Temperature (CCT) and Duv from CIE coordinates.

Parameters:

  • a – CIE coordinates (x,y or u,v or u’,v’) depending on year.

  • b – CIE coordinates (x,y or u,v or u’,v’) depending on year.

  • year – Year of the coordinates (1931, 1960, 1976)

Returns:

(CCT in K, Duv)

Return type:

Tuple

honeybee_radiance.luminaire.calc_xy_1931_from_cct(cct, wavelengths, cmfs)[source]

Calculate CIE 1931 x,y chromaticity from correlated color temperature.

This function computes the chromaticity coordinates of a blackbody radiator at the given color temperature using Planck’s law and the CIE 1931 color matching functions.

The implementation matches the legacy Honeybee Custom Lamp behavior, including normalization at 560 nm.

Parameters:

  • cct – Correlated color temperature in Kelvin. Valid range is approximately 1000-25000 K.

  • wavelengths – Mapping of wavelength (nm) > wavelength in meters. Expected keys: integers from 360 to 830.

  • cmfs – Mapping of wavelength (nm) > (x, y, <) CIE 1931 values.

Returns:

(x, y) CIE 1931 chromaticity coordinates, rounded to 8 decimals.

Return type:

tuple

Raises:

ValueError – If CCT is outside a reasonable range or data is missing.

honeybee_radiance.luminaire.color_coordinates(a, b, year)[source]

Convert CIE color coordinates between 1931, 1960, and 1976 systems.

This function takes a pair of chromaticity coordinates defined in one CIE color space and returns the equivalent coordinates in all three standard CIE systems.

Parameters:

  • a – First chromaticity coordinate (x or u or u’).

  • b – Second chromaticity coordinate (y or v or v’).

  • year – CIE diagram year. Must be one of - 1931 (x, y) - 1960 (u, v) - 1976 (u’, v’)

Returns:

Dictionary with keys {1931, 1960, 1976}, each mapped to a (a, b) tuple rounded to 8 decimal places.

Example:
{

1931: (x, y), 1960: (u, v), 1976: (u_prime, v_prime)

}

Return type:

dict

honeybee_radiance.luminaire.planckian_table(u_src, v_src, min_temp=1000, max_temp=100000, growth=1.01)[source]

Build a table of Planckian temperatures along with (u, v) coordinates and distances.

Parameters:

  • u_src – Reference u,v coordinates (CIE 1960) to compare against.

  • v_src – Reference u,v coordinates (CIE 1960) to compare against.

  • min_temp – Starting temperature (K). Default 1000 K.

  • max_temp – Maximum temperature (K). Default 100,000 K.

  • growth – Multiplicative growth factor per step. Default 1.01 (~1% step).

Returns:

(temperature, u, v, distance_to_ref, counter)

Return type:

List of tuples