Advanced: Modify a Lamp Model
In this tutorial you will learn about the files required for a lamp model and how to modify an example model.
Skill Level
Advanced
Downloads
1. Video Tutorial
2. LDF File Format (Lamp Definition File)
An example LDF file is shown below. The section containing layer specific information must be repeated for each geometry layer in the lamp model, but not for the lamp axis layer that ends with “A.”
LDF File Contents:
Name: Custom model with SPD
Library Name: CustomSPD1
Manufacturer: Generic
Code: CustomSPD1
Lamp Watts: 1.0
Typical Ballast Watts: 0.0
Radiant Watts: 1.0
LER: 324.372
PFER: 4.57219
PARER: 4.46869
Theory
Lumen Ratio: 1.0
Layer: LAMP-CustomSPD11
Material: PERFECT9
Luminance Filename: 100
SPD File: CustomSPD1.SPD
Shading Ability: SHADOW
Medium: DOWMS1002
Name - Lamp description
Library Name - Lamp model filename prefix. Our convention is to define names that end with the lamp CCT when it’s a broad band emitter or the peak wavelength when it’s a narrow band emitter.
Manufacturer - Manufacturer name
Code - Lamp order code
Lamp Watts - Electrical watts of the light source only
Typical Ballast Watts - Electrical watts of the ballast or driver for the light source
Radiant Watts - Radiant watts of the light source
LER - Luminous efficacy ratio (lumens / radiant watts). All 3 of these “efficacy ratio” values can be obtained in Photopia’s color report after running a power distribution raytrace for the lamp model.
PFER - Photon flux efficacy ratio (micro-mol/photons/second photon flux / radiant watts)
PARER - Photosynthetic Active Radiation (PAR) photon flux efficacy ratio (micro-mol/photons/second PAR photon flux / radiant watts). PAR photon flux is the photon flux from 400-700nm.
Theory - This parameter is optional. When present, rays will emit from the luminous surfaces of the lamp based on their relative luminance/radiance values. If this parameter is not present, then an IES file is required to define the lamp model intensity distribution.
Lumen Ratio - This parameter is optional, and the value scales the radiant watt output of the lamp model. This value allows a lamp model that includes primary optical elements such as a lens, reflector, mounting hardware, etc., to achieve the desired initial output after optical losses from those elements. So this parameter accounts for the optical efficiency of the lamp package. For example, if an LED loses 10% of the light from the chip after it interacts with an included primary lens & lamp base due to Fresnel reflections, TIR effects, etc., then the lamp Lumen Ratio value would be set to 1.0/0.9 = 1.1111. When the lamp is simulated on its own, it then produces 100% of the radiant watts assigned to it.
Layer - The CAD geometry layer name. This item and the following parameters associated with the layer are to be repeated for each geometry layer in the model.
Material - The material filename prefix assigned to the lamp layer. This must be a reflective or transmissive material type. Parts of a lamp model package that include refractive materials, such as a primary lens element, are included as “non-lamp” layers in the model.
Luminance Filename - This parameter has 3 options:
- A constant scalar value - This value defines a relative Lambertian luminance/radiance for the surfaces on this layer. If a lamp only has 1 geometry layer, then this can be set to any non-zero positive value. If a lamp has 2 emission layers with one having twice the luminance/radiance as the other, then the values on the 2 layers could be set to any 2 values where one is twice the magnitude of the other. The 2 values could be 2 & 1 or 100 & 50, to the same effect. Non-emission geometry layers should be assigned a value of 0.
- A LUM filename - This file defines the relative luminance values at a range of emission angles, thus allowing for non-Lambertian surfaces. Format shown below.
- A RAD filename - This file defines the relative radiance values and an SPD file reference at a range of emission angles. Format shown below.
SPD File - This parameter is optional and used when a constant spectrum is assigned to the layer rather than defining the SPD files in a RAD file. Format shown below.
Shading Ability - The options are SHADOW and TRANSMIT. These define whether the geometry on this lamp layer will shadow or transmit rays emitted from other lamp layers. This parameter is optionally respected according to the “Ray Shadowing” raytrace option, which is enabled by default.
Medium - This parameter is optional and specifies the initial refractive material filename prefix that light emits into if the luminous surfaces are encapsulated within a refractive medium.
3. LUM File Format (Lamp Luminance File)
The lamp LUM file is an ASCII file with the following format. The first value in the file is an angular increment in degrees. This value should evenly divide into 90 since rays only emit from one side of a surface. The remaining items are the relative luminance values at each emission angle away from the surface normal. In this case, the values are defined at emission angles of 0, 10, 20 … 90°.
LUM File Contents:
10
1097
1094
1076
1046
1004
947
865
746
528
0
4. RAD File Format (Lamp Radiance File)
The RAD file is used to define a varying surface radiance and SPD as a function of the ray emission angle away from the surface normal. This is useful if a lamp's spectrum changes over the emission angle, such as with most white LEDs. An example RAD file is shown below. The first value indicates the angular increment of the radiance values away from the surface normal in degrees. This value should evenly divide into 90 since rays only emit from one side of a surface. The following lines indicates the relative radiance value and the SPD filename for each emission angle. The parameters on each line are separated by one or more spaces. In this case, the values are defined at emission angles of 0, 5, 10 … 90°.
RAD File Contents:
5
0.25087089 XM-L2-CW-COLORCORE1-Phosphor.spd
0.25170371 XM-L2-CW-COLORCORE1-Phosphor.spd
0.25166374 XM-L2-CW-COLORCORE1-Phosphor.spd
0.24981118 XM-L2-CW-COLORCORE1-Phosphor.spd
0.24806928 XM-L2-CW-COLORCORE1-Phosphor.spd
0.24514935 XM-L2-CW-COLORCORE1-Phosphor.spd
0.24055276 XM-L2-CW-COLORCORE1-Phosphor.spd
0.23492028 XM-L2-CW-COLORCORE1-Phosphor.spd
0.22691229 XM-L2-CW-COLORCORE1-Phosphor.spd
0.21761859 XM-L2-CW-COLORCORE1-Phosphor.spd
0.20502744 XM-L2-CW-COLORCORE1-Phosphor.spd
0.18886223 XM-L2-CW-COLORCORE1-Phosphor.spd
0.17054023 XM-L2-CW-COLORCORE1-Phosphor.spd
0.14934448 XM-L2-CW-COLORCORE1-Phosphor.spd
0.12141541 XM-L2-CW-COLORCORE1-Phosphor.spd
0.09156504 XM-L2-CW-COLORCORE1-Phosphor.spd
0.05907444 XM-L2-CW-COLORCORE1-Phosphor.spd
0.02928571 XM-L2-CW-COLORCORE1-Phosphor.spd
0.00913998 XM-L2-CW-COLORCORE1-Phosphor.spd
5. SPD File Format (Lamp SPD File)
The first few lines of an example SPD file are shown below. The first line includes the start wavelength, end wavelength and wavelength increment, all separated by 1 or more spaces. All wavelengths are defined in nm. The wavelength increment must be an integer. The smallest increment allowed is therefore 1nm. The wavelength range can be anywhere from the UV to the far IR. The subsequent lines indicate the relative output at each wavelength. These can be relative radiant watts or irradiance values, as only the shape of the distribution is important. This example provides output from 380 to 780nm in 1nm increments.
SPD File Contents:
380 780 1
4.632E-04
4.600E-04
4.538E-04
4.486E-04
4.458E-04
.
.
.
6. IES File Format (Lamp IES File)
The IES photometric file format is shown below. Items in ( ) are brief data descriptions. Items surrounded by [ ] brackets are keywords that must be present, followed by a space and the data. Multiple data on the same line shall be separated by at least one space.
Photopia requires the IES file to include a Type C intensity distribution and only the relative shape of the distribution is used. All other data needs to be included so the file format is valid, but the values of the rest of the data will not affect the lamp model performance.
IES File Contents:
IESNA:LM-63-1995
[TEST] ...
[MANUFAC] ...
Keyword 3
.
.
.
Keyword n
TILT=NONE
(number of lamps) (lumens per lamp or -1) (candela multiplier) (number of vertical angles) (number of horizontal angles) (photometric type - 1,2 or 3) (dim units - 1 or 2) (width) (length) (height)
(ballast factor) (ballast lamp factor) (input watts)
vertical angle list
horizontal angle list
candela values for all vertical angles at first horizontal angle
candela values for all vertical angles at second horizontal angle
.
.
.
candela values for all vertical angles at last horizontal angle