losAnalysis

R2026b

Add line-of-sight analysis to 3D scenario

Since R2026b

expand all in page

    Description

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

    An LOSAnalysis object represents a line-of-sight (LOS) analysis that uses ray tracing to determine whether visibility exists between actors in a 3D scenario.

    Creation

    Syntax

    losA = losAnalysis(source,destination)
    losA = losAnalysis(source,destination,Name=Value)

    Description

    losA = losAnalysis(source,destination) creates an LOS analysis between a source actor and one or more destination actors. The analysis accounts for the 3D scene and the 3D actor models within the scenario.

    By default, the 3D models of the source actor and a given destination actor do not obstruct the LOS path between the source and that destination. You can change this behavior by setting the SourceSelfObstruction and DestinationSelfObstruction properties.

    losA = losAnalysis(source,destination,Name=Value) sets writeable properties using one or more name-value arguments.

    Input Arguments

    expand all

    Source actor, specified as an Actor object.

    This argument sets the Source property of the LOSAnalysis 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 LOSAnalysis 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: losA = losAnalysis(src,dest,SourceSelfObstruction="on") creates a line-of-sight analysis that includes the 3D model of the source actor as a potential obstruction.

    These properties can be set using name-value arguments.

    Output Arguments

    expand all

    LOS analysis, returned as an LOSAnalysis 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.

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

    Option for the analysis to include the 3D model of the source actor as a potential obstruction, 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" — The 3D model of the source actor can obstruct the LOS path.

    • "off" — The analysis ignores the 3D model of the source actor. Other 3D models can obstruct the LOS path.

    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.

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

    Option for the analysis to include the 3D models of the destination actors as potential obstructions, 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" — The 3D model of a given destination actor can obstruct the LOS path between the source and that destination.

    • "off" — The 3D model of a given destination actor does not obstruct the LOS path between the source and that destination. Other 3D models can obstruct the LOS path.

    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 LOSVisual objects stored in the Visual property.

    LOS visual, represented as an array of LOSVisual objects. By default, when you add a line-of-sight analysis to a scenario with open viewers, the scenario creates a LOSVisual object for each viewer and stores the objects in this property.

    Adjust the properties of a LOSVisual object by using dot notation. For example, change the line width for the visual associated with LOS analysis losA by using losA.Visual.LineWidth = 6. To edit or query the properties of multiple LOS 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
    getvisualGet visual for actor, behavior, or analysis
    removeRemove actor or analysis from 3D scenario

    Limitations

    The accuracy of the LOSAnalysis object can be limited by floating-point precision, 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.

    Version History

    Introduced in R2026b

    See Also

    Objects

    Topics