## CreateLightRigFromImage

### Description

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

    CreateLightRigFromImage( [Filename], [Number_Layers], [AreaHigh], [LightDistHigh] );

### 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

#### 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

### See Also

CreateImageBasedLightingPass X3DObject.AddLightRig