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