©Anton Podvalny

Table of Contents

Introduction


In this chapter we'll cover one of the most photorealistic lights present in V-Ray - IES light. IES stands for Illuminating Engineering Society. The plugin implements measured real world lights defined through an .IES profile, which shape can be overridden. The .IES profile generally represents the shape and the direction (generally the distribution) of the emitted light from a real world light source. The format also contains info on real intensity, distance attenuation and color temperature. A lot of .IES files can be found online, provided by the manufacturers.

Light and light units


  • Luminous intensity – candela:
    Wavelength-weighted power emitted by a light source in a particular direction per unit solid angle.

  • Luminous flux – lumen:
    lm = cd·sr (one candela of luminous intensity over a solid angle of one steradian)

  • Illuminance – lux:
    lx = lm/m2

  • Luminance – cd/m2 (nit):
    Luminous intensity per unit area of light traveling in a given direction


Measurement


Far field photometry

Assumes that the light is a point source. It happens with a devices called goniophotometers. The first ones were using a light sensor, which is rotated on 360 degrees around the light source. There are three standards for measurement - Type A, Type B, Type C. All of them result in the same file type. The measurement result is the total luminous flux.

 

 

Near field photometry

Takes into account the shape of the light source. One way to achieve this is when the sensor is closer to the light source. The other ways usually produce too large for practical usage files.

Relative vs absolute photometry

  • Relative photometry - the luminous intensity distribution is scaled by the total luminous flux.
  • Absolute photometry – the total luminous flux is not present.

Further reading


We won't cover the IES format in detail, but you can learn more for the photometric reports format in the following paper:

"IES LM-63-1986: IES Recommended Standard File Format for Electronic Transfer of Photometric Data."
Revised 1991, 1995, 2001, 2002
ANSI/IESNA LM-63-02

Other standards which can be used are CIBSE TM14:1988EULUMDAT.

For more information on the topic you can search for the paper "Thinking Photometrically" by Ian Ashdown, P. Eng., LC, FIES, published on LIGHTFAIR 2001 Pre-Conference Workshop.

Parameters


Along with the common light parameters, the IES lights are affected by the following specific LightIES plugin parameters:

  • ies_file - Path to the file describing the light source
  • filter_color - Use to tint the light. The default is white (1.0, 1.0, 1.0). Light color is defined by color temperature in the IES file.
  • soft_shadows - Set to 0 (default) to cast hard shadows as point light; 1 to use the shape of the light for shadows; 2 to also use the shape for illumination
  • power - Overrides the power specified in the file if > 0. The unit is lumens.
  • ies_light_shape - Overrides the shape in the file if set to ≥ 0. Possible enumerated values: see table below.
  • ies_light_width - Used if ies_light_shape override is on.
  • ies_light_length - Used if ies_light_shape override is on.
  • ies_light_height - Used if ies_light_shape override is on.
  • ies_light_diameter - Used if ies_light_shape override is on.

 

Here's a table with the possible shape values and their parameters' constraints:

ShapeWidthLengthHeightDiameter
0=point0000
1=rectangle≥ 0≥ 000
2=circle000< 0
3=sphere000< 0
4=vertical cylinder00> 0< 0
5=horizontal cylinder (length)0> 00< 0
6=horizontal cylinder (width)> 000< 0
7=ellipse (length)< 0> 000
8=ellipse (width)> 0< 000
9=ellipsoid (length)< 0> 0< 00
10=ellipsoid (width)> 0< 0< 00

Example


The following code uses the example IES file included in the AppSDK installation package in the scenes/assets folder:

 

# Compatibility with Python 2.7.
from __future__ import print_function

# The directory containing the vray shared object should be present in the PYTHONPATH environment variable.
# Try to import the vray module from VRAY_SDK/python, if it is not in PYTHONPATH
import sys, os
VRAY_SDK = os.environ.get('VRAY_SDK')
if VRAY_SDK:
    sys.path.append(os.path.join(VRAY_SDK, 'python'))
import vray

SCENE_PATH = os.path.join(os.environ.get('VRAY_SDK'), 'scenes')
# Change process working directory to SCENE_PATH in order to be able to load relative scene resources.
os.chdir(SCENE_PATH)

# The renderer is automatically closed after the `with` block.
with vray.VRayRenderer() as renderer:
    # Register a simple log callback. Always useful for debugging.
    def dumpMsg(renderer, message, level, instant):
        if level == vray.LOGLEVEL_ERROR:
            print("[ERROR]", message)
        elif level == vray.LOGLEVEL_WARNING:
            print("[Warning]", message)
        elif level == vray.LOGLEVEL_INFO:
            print("[info]", message)
        # Uncomment for testing, but you might want to ignore these in real code
        #else: print("[debug]", message)
    renderer.setOnLogMessage(dumpMsg)
    # Load scene from a file.
    renderer.load(os.path.join(SCENE_PATH, 'lighting.vrscene'))
    # Remove original light source from the scene.
    del renderer.plugins["VRayLightDomeShape1"]
    # LightIES is a light source plugin that can be used to create physically accurate area lights 
    # from .IES files produced by metering real life light fixtures.
    # It also allows specifying a simple custom shape like a cylinder or box.
    light = renderer.classes.LightIES()
    # Specify the light position, rotation and scale.
    light.transform = vray.Transform(
        vray.Matrix(
            vray.Vector(0.9745879, 0.2240055, 0),
            vray.Vector(1.110223e-016, -4.440892e-016, -1),
            vray.Vector(-0.2240055, 0.9745879, -4.440892e-016)),
        vray.Vector(227.955764705938, 112.5306789507133, 112.2503672299417))
    # Specify the color of the light in RGB float values and alpha(1.0f)
    light.color = vray.AColor(0.712, 0.9335393, 1)
    # Specify the path to the .IES file to use for the light.
    light.ies_file = os.path.join(SCENE_PATH, 'assets', 'IES_Example_3.IES')
    # Multiplies the light color and intensity. (Can be used as an intensity control).
    light.filter_color = vray.Color(4, 4, 4)
    # Override the shape of the light.
    # Depending on the shape of the light some of the following properties have to be specified:
    #   ies_light_width - Light shape width in metres.
    #   ies_light_height - Light shape height in metres.
    #   ies_light_length - Light shape length in metres.
    #   ies_light_diameter - Light shape diameter in metres.
    # Possible values are:
    #  -1 (default shape from IES file) - default
    #   0 (Point)
    #   1 (Rectangular)
    #   2 (Circular)
    #   3 (Sphere)
    #   4 (Vertical Cylinder)
    #   5 (Horizontal cylinder oriented along lum.lenght)
    #   6 (Horizontal cylinder oriented along lum.width)
    #   7 (Ellipse oriented along lum.lenght)
    #   8 (Ellipse oriented along lum.width)
    light.ies_light_shape = 0
    # Specify shadow offset from the surface. Helps to prevent polygonal shadow artifacts on low-poly surfaces.
    light.shadowBias = 0.02
    # Specify that the bumped normal should be used to check if the light direction is below the surface.
    light.bumped_below_surface_check = True
    # Start rendering.
    renderer.startSync()
    # Wait for rendering to end.
    renderer.waitForRenderEnd()
#define VRAY_RUNTIME_LOAD_PRIMARY

#include "vraysdk.hpp"
#include "vrayplugins.hpp"
#include "utils.h"

using namespace VRay;
using namespace VRay::Plugins;
using namespace std;

const char *BASE_PATH = getenv("VRAY_SDK");
string SCENE_PATH = (BASE_PATH ? string(BASE_PATH) : string(".")) + PATH_DELIMITER + "scenes";

int main() {
	// Change process working directory to SCENE_PATH in order to be able to load relative scene resources.
	changeCurrentDir(SCENE_PATH.c_str());
	// Load V-Ray SDK library.
	VRayInit init(NULL, true);
	// Create an instance of VRayRenderer with default options.
	// The renderer is automatically closed at the end of the current scope.
	VRayRenderer renderer;
	// It's recommended to always have a console log
	renderer.setOnLogMessage(logMessage);
	// Load scene from a file.
	renderer.load("lighting.vrscene");
	// Remove original light source from the scene.
	renderer.deletePlugin("VRayLightDomeShape1");
	// LightIES is a light source plugin that can be used to create physically accurate area lights 
	// from .IES files produced by metering real life light fixtures.
	// It also allows specifying a simple custom shape like a cylinder or box.
	LightIES light = renderer.newPlugin<LightIES>();
	// Specify the light position, rotation and scale.
	light.set_transform(Transform(
		Matrix(
			Vector(0.9745879, 0.2240055, 0.0),
			Vector(1.110223e-016, -4.440892e-016, -1.0),
			Vector(-0.2240055, 0.9745879, -4.440892e-016)),
		Vector(227.955764705938, 112.5306789507133, 112.2503672299417)));
	// Specify the color of the light in RGB float values and alpha(1.0f)
	light.set_color(AColor(0.712, 0.9335393, 1.0));
	// Specify the path to the .IES file to use for the light.
	light.set_ies_file("assets/IES_Example_3.IES");
	// Multiplies the light color and intensity. (Can be used as an intensity control).
	light.set_filter_color(Color(4.0, 4.0, 4.0));
	// Override the shape of the light.
	// Depending on the shape of the light some of the following properties have to be specified :
	//   ies_light_width - Light shape width in metres.
	//   ies_light_height - Light shape height in metres.
	//   ies_light_length - Light shape length in metres.
	//   ies_light_diameter - Light shape diameter in metres.
	// Possible values are :
	//  -1 (default shape from .IES file) - default
	//   0 (Point)
	//   1 (Rectangular)
	//   2 (Circular)
	//   3 (Sphere)
	//   4 (Vertical Cylinder)
	//   5 (Horizontal cylinder oriented along lum.lenght)
	//   6 (Horizontal cylinder oriented along lum.width)
	//   7 (Ellipse oriented along lum.lenght)
	//   8 (Ellipse oriented along lum.width)
	light.set_ies_light_shape(0);
	// Specify shadow offset from the surface. Helps to prevent polygonal shadow artifacts on low-poly surfaces.
	light.set_shadowBias(0.02f);
	// Specify that the bumped normal should be used to check if the light direction is below the surface.
	light.set_bumped_below_surface_check(true);
	// Start rendering.
	renderer.startSync();
	// Wait for rendering to end.
	renderer.waitForRenderEnd();
	return 0;
}
using System;
using System.IO;
using VRay;
using VRay.Plugins;

namespace _05_ies
{
    class Program
    {
        static void Main(string[] args)
        {
            string SCENE_PATH = Path.Combine(Environment.GetEnvironmentVariable("VRAY_SDK"), "scenes");
            // Change process working directory to SCENE_PATH in order to be able to load relative scene resources.
            Directory.SetCurrentDirectory(SCENE_PATH);

            // Create an instance of VRayRenderer with default options. The renderer is automatically closed after the `using` block.
			using (VRayRenderer renderer = new VRayRenderer())
            {
                // Add a listener for any type of log message.
                renderer.LogMessage += new EventHandler<MessageEventArgs>((source, e) =>
                {
                    // You can remove the if for testing, but you might want to ignore Debug in real code
                    if (e.LogLevel != LogLevelType.Debug)
                    {
                        Console.WriteLine(String.Format("[{0}] {1}", e.LogLevel.ToString(), e.Message));
                    }
                });
                // Load scene from a file.
                renderer.Load("lighting.vrscene");
                // Remove original light source from the scene.
                renderer.DeletePlugin("VRayLightDomeShape1");
                // LightIES is a light source plugin that can be used to create physically accurate area lights 
                // from .IES files produced by metering real life light fixtures.
                // It also allows specifying a simple custom shape like a cylinder or box.
                LightIES light = renderer.NewPlugin<LightIES>();
                // Specify the light position, rotation and scale.
                light.Transform = new Transform(
                    new Matrix(
                        new Vector(0.9745879, 0.2240055, 0),
                        new Vector(1.110223e-016, -4.440892e-016, -1),
                        new Vector(-0.2240055, 0.9745879, -4.440892e-016)),
                    new Vector(227.955764705938, 112.5306789507133, 112.2503672299417));
                // Specify the color of the light in RGB float values and alpha = 1.
                light.Color = new AColor(0.712, 0.9335393, 1);
                // Specify the path to the .IES file to use for the light.
                light.IesFile = Path.Combine("assets", "IES_Example_3.IES");
                // Multiplies the light color and intensity. (Can be used as an intensity control).
                light.FilterColor = new Color(4, 4, 4);
                // Override the shape of the light.
                // Depending on the shape of the light some of the following properties have to be specified:
                //   ies_light_width - Light shape width in metres.
                //   ies_light_height - Light shape height in metres.
                //   ies_light_length - Light shape length in metres.
                //   ies_light_diameter - Light shape diameter in metres.
                // Possible values are:
                //  -1 (default shape from IES file) - default
                //   0 (Point)
                //   1 (Rectangular)
                //   2 (Circular)
                //   3 (Sphere)
                //   4 (Vertical Cylinder)
                //   5 (Horizontal cylinder oriented along lum.lenght)
                //   6 (Horizontal cylinder oriented along lum.width)
                //   7 (Ellipse oriented along lum.lenght)
                //   8 (Ellipse oriented along lum.width)
                light.IesLightShape = 0;
                // Specify shadow offset from the surface. Helps to prevent polygonal shadow artifacts on low-poly surfaces.
                light.ShadowBias = 0.02F;
                // Specify that the bumped normal should be used to check if the light direction is below the surface.
                light.BumpedBelowSurfaceCheck = true;
                // Specify the number of parameter samples for motion blur.
                light.Nsamples = 1;
                // Start rendering.
                renderer.StartSync();
                // Wait for rendering to end.
                renderer.WaitForRenderEnd();
            }
        }
    }
}
var path = require('path');
var vray = require(path.join(process.env.VRAY_SDK, 'node', 'vray'));

var SCENE_PATH = path.join(process.env.VRAY_SDK, 'scenes');
// Change process working directory to SCENE_PATH in order to be able to load relative scene resources.
process.chdir(SCENE_PATH);

// Create an instance of VRayRenderer with default options.
var renderer = vray.VRayRenderer();
// It's recommended to always have a console log callback
renderer.on("logMessage", function(message, level, instant) {
	if (level == vray.LOGLEVEL_ERROR)
		console.log("[ERROR] ", message);
	else if (level == vray.LOGLEVEL_WARNING)
		console.log("[Warning] ", message);
	else if (level == vray.LOGLEVEL_INFO)
		console.log("[info] ", message);
	// Uncomment for testing, but you might want to ignore these in real code
	//else console.log("[debug] ", message);
});
// Load scene from a file asynchronously.
renderer.load("lighting.vrscene", function(err) {
    if (err) throw err;
    // Remove original light source from the scene.
    delete renderer.plugins["VRayLightDomeShape1"];
    // LightIES is a light source plugin that can be used to create physically accurate area lights
    // from .IES files produced by metering real life light fixtures.
    // It also allows specifying a simple custom shape like a cylinder or box.
    var light = renderer.classes.LightIES();
    // Specify the light position, rotation and scale.
    light.transform = vray.Transform(
        vray.Matrix(
            vray.Vector(0.9745879, 0.2240055, 0),
            vray.Vector(1.110223e-016, -4.440892e-016, -1),
            vray.Vector(-0.2240055, 0.9745879, -4.440892e-016)),
        vray.Vector(227.955764705938, 112.5306789507133, 112.2503672299417));
    // Specify the color of the light in RGB float values and alpha(1.0f)
    light.color = vray.AColor(0.712, 0.9335393, 1);
    // Specify the path to the .IES file to use for the light.
    light.ies_file = path.join(SCENE_PATH, 'assets', 'IES_Example_3.IES');
    // Multiplies the light color and intensity. (Can be used as an intensity control).
    light.filter_color = vray.Color(4, 4, 4);
    // Override the shape of the light.
    // Depending on the shape of the light some of the following properties have to be specified:
    //   ies_light_width - Light shape width in metres.
    //   ies_light_height - Light shape height in metres.
    //   ies_light_length - Light shape length in metres.
    //   ies_light_diameter - Light shape diameter in metres.
    // Possible values are:
    //  -1 (default shape from IES file) - default
    //   0 (Point)
    //   1 (Rectangular)
    //   2 (Circular)
    //   3 (Sphere)
    //   4 (Vertical Cylinder)
    //   5 (Horizontal cylinder oriented along lum.lenght)
    //   6 (Horizontal cylinder oriented along lum.width)
    //   7 (Ellipse oriented along lum.lenght)
    //   8 (Ellipse oriented along lum.width)
    light.ies_light_shape = 0;
    // Specify shadow offset from the surface. Helps to prevent polygonal shadow artifacts on low-poly surfaces.
    light.shadowBias = 0.02;
    // Specify that the bumped normal should be used to check if the light direction is below the surface.
    light.bumped_below_surface_check = true;
    // Start rendering.
    renderer.start(function(err) {
        if (err) throw err;
        // Wait for rendering to end.
        renderer.waitForRenderEnd(function() {
            renderer.close();
        });
    });
});

Result


 

The scene used for this render is called "Lighting_IES.vrscene" and can be found in the scene bundle (comments to the different parameters available inside).

To test this locally, you'll need to change the absolute path to the IES profile (located in the included scene: "vrscenes/light_ies.vrscene").
  • No labels