CreateLightRigFromImage

Creates a special light rig from the given source image. This is the scripting equivalent of selecting Light Rig From Image from the Light menu.

The light rig is a set of infinite lights whose colors, directions, and intensities simulate the lighting in the source image. Because the lights are infinite, scene objects are lit the same way regardless of their location and you don't have to worry about positioning the lights or resizing the rig.

A word of caution: Don't confuse this light rig with the LightRig programming object. If you are looking for light rigs in the scene, any objects that were created with the X3DObject.AddLightRig method have a TypeName or Application.ClassName value of 'LightRig', but any light rigs created with this command are still Null objects. For more information, see the example.

Note: This command uses output arguments. Some scripting languages don't support arguments passed by reference (such as JScript and Python). For more information on how to handle getting output arguments through a return-value array, see Output Arguments, Return Values and Output Value Arrays.

Scripting Syntax

Parameters

Parameter Type Description

Filename String The supported image formats are .pic and .hdr. The image must be a spherical map (longitude/latitude type image). HDR images allow for better and more contrasted lighting. It is not necessary to use a large image, as long as the image has enough contrast between highlights and lowlights. The suggested resolution is 400 x 200. Using low resolution images will also cut down processing time.
Default Value: " empty "

Number_Layers Integer Limits the number of luminance layers being created. Using more layer implies increased processing time and memory usage. (Suggested values: 3 to 5)
Default Value: 3

AreaHigh Float Determines how much luminance will be extracted from the layer. A higher value means more luminance, which implies that more lights can be inserted.
Default Value: 20

LightDistHigh Float Distance between lights (percentage of the image). A lower value means that more lights will be inserted.
Default Value: 40

Examples

Parameter	Type	Description
Filename	String	The supported image formats are .pic and .hdr. The image must be a spherical map (longitude/latitude type image). HDR images allow for better and more contrasted lighting. It is not necessary to use a large image, as long as the image has enough contrast between highlights and lowlights. The suggested resolution is 400 x 200. Using low resolution images will also cut down processing time. Default Value: " empty "
Number_Layers	Integer	Limits the number of luminance layers being created. Using more layer implies increased processing time and memory usage. (Suggested values: 3 to 5) Default Value: 3
AreaHigh	Float	Determines how much luminance will be extracted from the layer. A higher value means more luminance, which implies that more lights can be inserted. Default Value: 20
LightDistHigh	Float	Distance between lights (percentage of the image). A lower value means that more lights will be inserted. Default Value: 40

VBScript Example

'

'	This example demonstrates how to use a PIC file to create a

'	special light rig with several infinite lights. It also shows

'	how to find the light rig in your scene (since the newly-created

'	object is not returned as part of the CreateLightRigFromImage command).

'

'	Note: A number of different strategies are presented here, since there

'	is no "LightRig" filter. You can deploy whichever best suits your needs.

'

'-----------------------------------------

'	CREATING THE LIGHT RIG

'

NewScene , false

' Create a couple of nulls (just to make it interesting)

ActiveSceneRoot.AddNull "Danny"

ActiveSceneRoot.AddNull "Fanny"

' For more sport, add an infinite type light rig using the object model

ActiveSceneRoot.AddLightRig "Infinite", "Almighty"

' Create the light rig from one of the sample image PIC files

CreateLightRigFromImage InstallationPath( siFactoryPath ) _

	& "\Data\XSI_SAMPLES\Pictures\xsilogo.pic", 3, 20, 40

'-----------------------------------------

'	SEARCHING AMONGST THE NULLS

'

' First, get a collection of nulls just for comparison

Set oNullList = ActiveSceneRoot.FindChildren( , siNullPrimType )

showCollectionInfo oNullList

'OUTPUT:

'INFO : "-----------------"

'INFO : "Found 3 rig(s) in this collection:"

'INFO : "	Danny"

'INFO : "	Fanny"

'INFO : "	LightRig"

' Or we can build a collection of light rigs based on which nulls have lights

' for children (because presumably only light rigs will have lights for children)

Set oLRColl = CreateObject( "XSI.Collection" )

oLRColl.SetAsText buildLRCollFromNulls( ActiveSceneRoot.FindChildren( , siNullPrimType ) )

showCollectionInfo oLRColl

'OUTPUT:

'INFO : "-----------------"

'INFO : "Found 1 rig(s) in this collection:"

'INFO : "	LightRig"

' Or we can filter the oNullList collection or use the collection Filter on the whole 

' scene by restricting our list to only nulls that contain 'rig' in their name 

Set oNullList = oNullList.Filter( siNullPrimType,, "*rig*" )

showCollectionInfo oNullList

'OUTPUT:

'INFO : "-----------------"

'INFO : "Found 1 rig(s) in this collection:"

'INFO : "	LightRig"

'-----------------------------------------

'	LOOKING BY NAME

'

Set oRigs = ActiveSceneRoot.Children.Filter( siNullPrimType,, "*rig*" )

showCollectionInfo oRigs 

' Now look for LightRig objects under the scene root 

Set oLRigs = ActiveSceneRoot.FindChildren( "LightRig" )

showCollectionInfo oLRigs

'OUTPUT:

'INFO : "-----------------"

'INFO : "Found 1 rig(s) in this collection:"

'INFO : "	LightRig"

'-----------------------------------------

'	FINDING THE WRONG LIGHT RIG

'

' What about the other light rig in the scene? We can get all the lights in

' the scene, find their parents and add each one with the "LightRig" typename

' to a new collection

Set oLights = ActiveSceneRoot.FindChildren( , , siLightPrimitiveFamily )

Set oLRColl = CreateObject( "XSI.Collection" )

oLRColl.SetAsText buildLRCollFromLights( oLights )

showCollectionInfo oLRColl



'-----------------------------------------

'	HELPER FUNCTIONS

'

function showCollectionInfo( in_coll )

	If TypeName( in_coll ) <> "Nothing" _

	   AND in_coll.Count > 0 Then

		LogMessage "-----------------"

		LogMessage "Found " & in_coll.Count & " rig(s) in this collection:"

		For Each mbr In in_coll

			LogMessage vbTab & mbr.FullName

		Next

	Else

		LogMessage "None found."

	End If

end function

function buildLRCollFromLights( in_light_coll )

	If in_light_coll.Count > 0 Then

		Set oCLRColl = CreateObject( "XSI.Collection" )

		For Each mbr In in_light_coll

			' This makes sure we add only true LightRig objects, not the 

			' ones we created with the CreateLightRigFromImage command, 

			' but with the X3DObject.AddLightRig method

			If TypeName( mbr.Parent ) = "LightRig" Then

				oCLRColl.Add mbr.Parent

			End If

		Next

	Else

		LogMessage "Specified collection is empty."

	End If

	buildLRCollFromLights = oCLRColl

end function

function buildLRCollFromNulls( in_null_coll )

	If in_null_coll.Count > 0 Then

		Set oCLRColl = CreateObject( "XSI.Collection" )

		For Each mbr In in_null_coll

			' This looks for a light amongst the children of the null in

			' the current collection, assuming that only nulls that are 

			' light rigs have lights for children

			If mbr.Children.Filter( , siLightPrimitiveFamily ).Count > 0 Then

				oCLRColl.Add mbr

			End If

		Next

	Else

		LogMessage "Specified collection is empty."

	End If

	buildLRCollFromNulls = oCLRColl

end function