Description

This function returns a True or False indicating whether a given ray is (a) coherent and (b) has invalid internal parameters which render it unsuitable for use in any coherent calculations (ex. scalar field, irradiance, etc.).  The function also indicates the maximum invariant value for the coherent ray, which can be used to determine whether a given ray should be made inactive for the purposes of an analysis even if the ray is otherwise valid.  FRED uses an invariant value of 0.25 to determine whether a given coherent ray should be excluded from an analysis; rays with an invariant value less than this are included and those with an invariant larger are excluded.  An invariant value of 0.25 may not be appropriate for all applications (though in general, it is robust), so the IsInvalidCoherentRay function can be used to selectively deactivate any coherent rays using a smaller invariant value (see example below).

Depending on the number of rays traced, it may be necessary to dimension ray index and ray counter variables as data type Huge_ instead of Long.  Please see Multi-threaded Raytracing for more information.

Syntax

bInvalid = IsInvalidCoherentRay( rayId, maxInvariant )

Parameters

bInvalid (Boolean)

Returned boolean indicating whether the coherent ray has been determined to be invalid (ex. Gaussian exponential decay violation, max invariant > 0.25).  True means that the ray is invalid.  False means that the ray is valid.

rayId As Long (or Huge_)

ID number of the ray being queried.

maxInvariant As Double

After the function is executed, this variable will contain the value of the maximum invariant for the coherent ray that was queried.

Example

The example below demonstrates how to loop over the ray buffer, query each of the rays to see whether it is invalid, and apply some custom logic to deactivate rays based on their maximum invariant value.

Sub Main

    Dim rayId As Long, tRay As T_RAY

    Dim success As Boolean, bInvalid As Boolean

    Dim maxInvariant As Double

    'Set a custom secondary ray invariant value

    'FRED's default is 0.25

    Dim custInv As Double

    custInv = 0.20

    'Loop over the ray buffer and query each ray to see if it is valid.

    success = GetFirstRay( rayId, tRay )

    While success

        bInvalid = IsInvalidCoherentRay( rayId, maxInvariant )

        If Not(bInvalid) Then 'FRED determined ray is valid

            Print "Ray " & rayId & " is valid.  Max invariant = " & maxInvariant

            If maxInvariant > custInv Then 'Ray is valid, but has a larger invariant than we want

                Print ">>> Ray " & rayId & " is valid but has an invariant larger than " & custInv & ".  Deactivating ray."

                SetRayActive( rayId, False )

            End If

        Else 'FRED determined ray is not valid

            Print "Ray " & rayId & " is invalid.  Max invariant = " & maxInvariant

        End If

        success  = GetNextRay( rayId, tRay )

    Wend

    Print ""

    Print "Finished processing rays."

End Sub

See Also

Basic Ray Data Script Commands