Description The RaySummaryInfo function returns a dictionary object that contains the ray counts and power for entities which currently have rays associated with them as well as various ray status categories.
If needed, the ApplyFilterToRays() command can be used to apply a ray selection criteria filter to the ray buffer prior to calling the RaySummaryInfo command. The resulting summary will return information only for those rays satisfying the ray selection filter criteria.
Summary of dictionary objects •Microsoft documentation on the VB dictionary object can be found here. •A dictionary object in BASIC is an associative array, where each element in the array consists of an "item" and an associated "key" that is used to retrieve it from the dictionary. Visualize the dictionary object in the following way: myDictionary = [ {"Year" : 2015}, {"Month" : "April"}, {"Day" : 10} ] •In this example, the keys of the dictionary are, "Year", "Month" and "Day", while the items in the dictionary are, 2015, "April" and 10. If we wanted to access the item associated with "Month", we would simply write: monthItem = myDictionary("Month") •The convenience of the associative array is that it provides a layer of clarification about what quantities you are retrieving from the array. In our example, it was clear that we were retrieving the "Month" item from the array. •It is also important to note that there is no requirement on the data types of the keys and items. In our example, the items associated with "Year" and "Day" are integers while the item associated with "Month" is a string. Generically, the keys and items are type "Variant".
Dictionary objects have a collection of methods that are used for querying, modifying and retrieving the dictionary contents. These methods are described below, continuing with the example dictionary used previously.
Checking for the existence of a key The exists() method of the dictionary object is used to query the dictionary to see if a key is valid. When a dictionary object is passed a key value that isn't present in the dictionary, the script will halt with a "Type Mismatch" error message. Unless it is known ahead of time that the key being passed to the dictionary is present, the exists() method should be used to query the dictionary for the presence of the key. If myDictionary.exists("Hour") Then hourItem = myDictionary("Hour") Else Print "Sorry, the key you want does not exist!" End If
Retrieving a list of keys from the dictionary A common operation with dictionaries will be to loop over all of the elements in the array. However, unlike a normal array where you would directly loop over the array indexes, with a dictionary you can loop over the keys and then use them to extract the associated items from the dictionary. Getting the list of keys from the dictionary can be accomplished by using the keys() method. Dim curKey As Variant, curItem As Variant, dictKeys() As Variant dictKeys = myDictionary.keys() For each curKey in dictKeys curItem = myDictionary(curKey) Next
Retrieving a list of items from the dictionary Similar to the keys() method, the items() method returns a list of the items from the dictionary. Dim dictItems() As Variant, curItem As Variant dictItems = myDictionary.items() For each curItem in dictItems Print curItem Next
Adding key/item pairs to a dictionary The add() method allows you to add a new key and item pair to an existing dictionary object. myDict.add("I am a key!", "And I am an item!")
Removing all items from a dictionary The removeAll() method allows you to remove all of the key/item pairs from an existing dictionary object. myDict.removeAll()
How the dictionary is used in the RaySummaryInfo() function The RaySummaryInfo() function returns a dictionary object. The items of the dictionary are type T_RAYSUMMARY, whose members are a ray count and a total power. The keys of the dictionary come in two types. The first key type is a set of ray status strings (below) that allow you to access the ray counts and total power for each category (ex. you can retrieve the number and flux for rays which had "bad positions"). total incoherent incoherent polarized coherent normal exceeded allowed total intersections exceeded allowed consecutive intersections bad position bad direction below absolute transmitted power cutoff below absolute reflected power cutoff below relative transmitted power cutoff below relative reflected power cutoff unresolved material exceeded specular ancestry cutoff exceeded scatter ancestry cutoff became evanescent TIR not allowed stopped exceeded allowed step count in inhomogeneous material parabasal ray intersection failure parabasal ray interface interaction failure transmitted ray failed glue intersection reflected ray failed glue intersection invalid ray (zombie) absorbed
The second key type are node numbers (type Long) of entities which had rays associated with them at the end of the raytrace. Passing the dictionary a node number as a key would return to you a corresponding T_RAYSUMMARY item that tells you how many rays ended on that node and how much power ended on that node. Keep in mind that you should use the exists() method on the dictionary first in order to see that a given node number is actually present in the dictionary, otherwise you will get a "Type Mismatch" error message. For example, suppose that we are interested in retrieving the ray summary information for a particular surface in the FRED model:
Dim myDict As Object Dim rs As T_RAYSUMMARY Set myDict = RaySummaryInfo()
Dim sNode As Long sNode = FindFullName("Geometry.CE.Surface") If myDict.exists(sNode) Then rs = myDict(sNode) Else Print "Sorry, the key you want does not exist!" End If
Syntax summaryDict = RaySummaryInfo( )
Parameters summaryDict (dictionary object) Returned dictionary object which can be queried to extract the ray counts and ray fluxes for the items listed in the Description section above.
Example The following script computes the ray summary information and then prints the formatted output to the output window. Sub Main
Dim RaySumDict As Variant Dim key, rs As T_RAYSUMMARY, TabStr As String
'Call RaySummaryInfo, return result into the dictionary variable Set RaySumDict = RaySummaryInfo()
'Begin printing the dictionary results to the output window TabStr = Chr(9) & Chr(9) & Chr(9) Print " " Print "Count" & Chr(9) & "Power" & TabStr & " Entity Name or Ray Status" Print "------" & Chr(9) & "------" & TabStr & " ------------------------------"
'For each key in the dictionary, print out the data For Each key In RaySumDict
'Retrieve the T_RAYSUMMARY info for the current key rs = RaySumDict.item( key ) Print rs.raycount & Chr(9) & rs.raypower & TabStr;
'Print the corresponding key information, differentiating between 'ray status types and node number types 'If Long, then the key is a node number or -1 designation If TypeName$( key ) = "Long" Then If key >= 0 Then Print " [" & key & "] " & GetFullName( key ) Else Print " " & key End If 'If String, then key is a ray status designation ElseIf TypeName$( key ) = "String" Then Print " Ray Status: " & key End If
Next
End Sub
The example script below demonstrates how to retrieve specific information from the ray summary info dictionary. Sub Main
ClearOutputWindow()
'Define the ray summary dictionary and the 'ray summary data structure Dim summaryDict As Variant Dim rs As T_RAYSUMMARY
'Surface of interest 'Perform raytrace EnableTextPrinting(False) DeleteRays() TraceCreate() EnableTextPrinting(True)
'Get ray summary information Set summaryDict = RaySummaryInfo()
'Specifically ask for how many rays had unresolved materials 'by using the dictionary key "unresolved material" rs = summaryDict( "unresolved material" ) Print "Rays with material errors:" Print vbTab & "Count:" & vbTab & rs.raycount Print vbTab & "Power:" & vbTab & rs.raypower
'Specifically ask for how many rays ended on a particular surface of interest 'by using a dictionary key that matches the node number of the object. Dim sNode As Long sNode = FindFullName( "Geometry.Lens 2.Surface 1" ) If summaryDict.exists( sNode ) Then rs = summaryDict( sNode ) Print "Rays on surface of interest:" Print vbTab & "Count:" & vbTab & rs.raycount Print vbTab & "Power:" & vbTab & rs.raypower Else Print "Key [" & sNode & "] does not exist in the dictionary." End If
End Sub
See Also
|