rayTraceAnalysis

R2026b

Add ray trace analysis to 3D scenario

Since R2026b

expand all in page

    Description

    Add-On Required: This feature requires the 3D Scenarios add-on.

    A RayTraceAnalysis object represents a ray trace analysis that calculates geometric paths that connect actors in a 3D scenario.

    Creation

    Syntax

    rt = rayTraceAnalysis(source,destination)
    rt = rayTraceAnalysis(source,destination,Name=Value)

    Description

    rt = rayTraceAnalysis(source,destination) creates a ray trace analysis between a source actor and one or more destination actors. The analysis uses ray tracing to calculate geometric paths that connect the source actor and destination actors. The analysis accounts for the 3D scene and the 3D actor models within the scenario.

    Ray trace analysis objects calculate the geometric paths using the shooting and bouncing rays method. For more information, see Shooting and Bouncing Rays Method.

    rt = rayTraceAnalysis(source,destination,Name=Value) sets writable properties using one or more name-value arguments.

    example

    Input Arguments

    expand all

    Source actor, specified as an Actor object.

    This argument sets the Source property of the RayTraceAnalysis object.

    Destination actor, specified as an Actor object or a vector of Actor objects. When you specify multiple destination actors, the analysis calculates the visibility from the source to each destination.

    This argument sets the Destination property of the RayTraceAnalysis object.

    Name-Value Arguments

    expand all

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: rt = rayTraceAnalysis(src,dest,MaxNumReflections=3) creates a ray trace analysis that finds paths with up to three reflections.

    These properties can be set using name-value arguments.

    Output Arguments

    expand all

    Ray trace analysis, returned as a RayTraceAnalysis object.

    Properties

    expand all

    This property is read-only while the simulation is running.

    Source actor, specified as an Actor object.

    This property is read-only while the simulation is running.

    Source reference point, specified as a string scalar or a character vector.

    The supported reference points depend on the Asset object in the Asset property of Source. For more information, see the ReferencePoints property of the Asset object.

    For actors with a 3D model, the reference point must be outside the 3D model.

    This property is read-only while the simulation is running.

    Destination actor, specified as an Actor object or a 1-by-n vector of Actor objects.

    This property is read-only while the simulation is running.

    Destination reference point, specified as a string scalar, a vector of strings, a character vector, or a cell array of character vectors. When you specify a string scalar or character vector, the same reference point applies to all destinations. When you specify a vector of strings or a cell array, the number of elements must match the length of Destination.

    The supported reference points depend on the Asset object in the Asset property of Destination. For more information, see the ReferencePoints property of the Asset object.

    For actors with a 3D model, the reference point must be outside the 3D model.

    This property is read-only while the simulation is running.

    Maximum number of path reflections to consider when searching for paths, specified as a nonnegative integer.

    This property is read-only while the simulation is running.

    Number of rays to launch while tracing paths, specified as a positive integer.

    This property is read-only after object creation.

    Option to initially display the analysis in the viewers, specified as "on" or "off", or as numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    • "on" — Initially display the analysis in the viewers.

    • "off" — Do not initially display the analysis in the viewers.

    You can toggle the visibility of the analysis within a specified viewer by changing the Visible property of the RayTraceVisual objects stored in the Visual property.

    Ray trace visual, represented as an array of RayTraceVisual objects. By default, when you add a ray trace analysis to a scenario with open viewers, the scenario creates a RayTraceVisual object for each viewer and stores the objects in this property.

    Adjust the properties of a RayTraceVisual object by using dot notation. For example, change the colormap for the visual associated with ray trace analysis rt by using rt.Visual.Colormap = "turbo". To edit or query the properties of multiple ray trace visuals at once, use the set or get function. To get the visual for a specific viewer, use the getvisual function.

    Adding or removing objects using this property is not supported.

    Object Functions

    hasLOSLine-of-sight visibility status
    findpathsFind ray paths
    getvisualGet visual for actor, behavior, or analysis
    removeRemove actor or analysis from 3D scenario

    Examples

    collapse all

    Car and aircraft actors include 3D models that the scenario uses for visualization and analysis. Ray trace analysis objects require the reference points for such actors to be outside the models, but the default reference points are inside the models. As a result, when creating ray trace analysis objects with these actors, you must specify different reference points using the SourceReferencePoint and DestinationReferencePoint arguments.

    Create a ray trace analysis between two actors:

    • The source actor, c, is a car actor created using the car function. Specify the reference point for the car as the front bumper.

    • The destination actor, a, is an aircraft actor created using the aircraft function. Specify the reference point for the aircraft as the nosecone. 

    rt = rayTraceAnalysis(c,a, ...
  SourceReferencePoint="frontbumper",DestinationReferencePoint="nosecone");

    Limitations

    The accuracy of the RayTraceAnalysis object can be limited by floating-point precision. Though the ray paths returned by the object have exact geometric accuracy with double precision, the SBR method finds the paths using single precision. As a result, the RayTraceAnalysis object might not find all valid paths, particularly when the distance between the destination and a scene surface or actor model is small compared to the distance between the destination and the source.

    Algorithms

    expand all

    Version History

    Introduced in R2026b

    See Also

    Objects

    Topics