Description This script command prints a compressed form of the stray light report for all paths ending on the specified entity node to either the FRED output window or a tab delimited text file. An advanced raytrace must have been issued with the Determine Raypaths option enabled. The stray light report always includes a list of the contributing sources, a summary of the raytrace control settings, and a high level summary of the raytrace paths. Specular and scatter paths will be reported depending on the subroutine arguments.
This version of the stray light report is a compressed form of the output provided by the command StrayLightReport. In the StrayLightReportByEntity command, path output is grouped by scatter/specular splitting events. Any paths ending on the specified entity and containing the same scatter/specular splitting events are grouped together and the intermediary non scatter/specular splitting events are ignored. While the StrayLightReport command provides detailed information about all unique raypaths in the system, the StrayLightReportByEntity variant provides a higher level summary which can be used to identify contributions from all paths containing a certain series of scatter/specular split events.
Consider a baffled Cassegrain telescope system which has the following four unique raytrace paths:
Paths #1, #2 and #3 all have the same splitting events at the Primary and Secondary mirrors. These three paths would all be listed together as a single entry in the StrayLightReportByEntity command, allowing the user to quickly identify the contributions at the detector plane due to second level scatter between the primary and secondary mirrors. Path #4 would be in a separate listing because its set of split events is different from paths #1, #2 and #3. In contrast, the StrayLightReport script command would list all four paths independently because they are unique raytrace paths (when considering the sequence of all events).
Syntax StrayLightReportByEntity( entNode, normMethod, normRef, specAncestry, scatAncestry, threshold, saveFile )
Parameters entNode As Long Node number of the entity on which stray light paths end.
normMethod As Long Stray light paths are listed by percentage of power in descending order. The percentage is calculated using one of the following options: 0 = use total power on the surface specified by the entNode argument 1 = use total specular power on the surface specified by the entNode argument 2 = use total scatter power on the surface specified by the entNode argument 3 = use accumulated power of the specular level specified by the normRef argument 4 = use accumulated power of the scatter level specified by the normRef argument
Specified values outside of this range are reset to 0. Note that if the reference normalization power is zero, percentages are not computed and the stray light paths are listed by total power in descending order.
normRef As Long The scatter/specular ancestry level used for calculation of the power normalization (normMethod = 3 or 4). Specified values less than zero are reset to 0.
specAncestry As Long Report paths ending on entNode having specular ancestry level specAncestry. Other valid values are: -2 = suppress the specular path list (i.e. display scatter paths only) -1 = show all specular ancestry levels
scatAncestry As Long Report paths ending on entNode having scatter ancestry level scatAncestry. Other valid values are: -2 = suppress the scatter path list (i.e. display specular paths only) -1 = show all scatter ancestry levels
threshold As Double Power percentage cutoff threshold for reported paths. Paths with power percentages below this threshold will not be reported. Possible values are: < 0 = only a high level summary is printed and no paths are listed 0 = all specified paths are listed > 0 = paths with power percentages above the threshold are listed. Note that if the reference normalization power is zero and threshold > 0, no paths will be listed.
saveFile As String Output file the report should be written to. If saveFile = "", the report will be written to the FRED output window.
Examples The following example code sets up an advanced raytrace to use the rayPaths option, performs the advanced raytrace, and then writes the stray light report to the output window. The reference power is the total power on the entity specified by entNode (therefore normRef does not apply), specular paths with ancestry level 2 will be displayed, scatter paths will be suppressed, only paths whose power% is greater than 0.2 will be displayed, and the file name is an empty string to direct the report to the output window.
Sub Main
Dim entNode As Long, cnt As Long Dim normMethod As Long, normRef As Long, specAncestry As Long, scatAncestry As Long Dim threshold As Double Dim saveFile As String Dim adv As T_ADVANCEDRAYTRACE
ClearOutputWindow
'get the entity node number for reference power entNode = FindFullName( "Geometry.dbgausscodev.Surface 12.Surf 12" )
'setup the advanced raytrace WITH rayPaths ON InitAdvancedRaytrace adv adv.rayPaths = True adv.draw = False adv.suppressSummary = True
'perform the advanced raytrace cnt = AdvancedRaytrace (adv)
'setup options for the stray light report output normMethod = 0 'use total power on the entNode entity normRef = 0 'not using normMethod 3 or 4, so this does not apply specAncestry = 2 'report paths having specular ancestry level 2 scatAncestry = -2 'suppress all scatter paths threshold = 0.02 'report paths whose percentage power is above this value saveFile = "" 'print to the FRED output window, not to file StrayLightReportByEntity entNode, normMethod, normRef, specAncestry, scatAncestry, threshold, saveFile
End Sub
See Also Raytrace Path Scripting Commands
|