Main Content

vr.canvas class

Superclasses:

(To be removed) Create virtual reality canvas

vr.canvas will be removed in a future release. For more information, see Version History.

Description

Create a virtual reality canvas.

Construction

virtualCanvas = vr.canvas(world) creates a virtual reality canvas showing the specified virtual world.

virtualCanvas = vr.canvas(world,parent) creates a virtual reality canvas in the specified parent figure or panel. A panel arranges user interface components into groups. By visually grouping related controls, panels can make the user interface easier to understand. A panel can have a title and various borders.

example

virtualCanvas = vr.canvas(world,parent,position) creates a virtual reality canvas in a figure or panel at the specified position.

example

virtualCanvas = vr.canvas(world,PropertyName,Value,...,PropertyName,Value) sets the values of the vr.canvas properties specified by one or more PropertyName,Value pair arguments.

Input Arguments

expand all

Virtual world, specified as a vrworld object.

Note

Open the virtual world before you create a vr.canvas object using that virtual world.

Figure for displaying the canvas, specified as a MATLAB figure or uipanel object

Location and size of virtual canvas, specified as the vector, in the form [left bottom width height]. Specify measurements in pixels.

Note

On Windows® systems, figure windows cannot be less than 104 pixels wide, regardless of the value of the position argument.

ElementDescription
leftDistance from the left edge of the primary display to the inner left edge of the canvas. This value can be negative on systems that have more than one monitor.
bottomDistance from the bottom edge of the primary display to the inner bottom edge of the canvas. This value can be negative on systems that have more than one monitor.
widthDistance between the right and left inner edges of the canvas.
heightDistance between the top and bottom inner edges of the canvas.

Example: [230 250 570 510]

Data Types: double

Name-Value Arguments

Example: set(myFigure,'Antialiasing','on','CameraPosition',[0 100 100])

Specify optional comma-separated pairs of PropertyName,Value arguments. PropertyName is the argument name and Value is the corresponding value. PropertyName must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as PropertyName1,Value1,...,PropertyNameN,ValueN.

Smooth textures using antialiasing, specified as 'on' or 'off'. Antialiasing smooths textures by interpolating values between texture points.

Camera movement with the current viewpoint, specified as 'on' or 'off'.

Camera direction in the current viewpoint local coordinates, specified as a vector of three doubles. The doubles represent the x, y, and z vectors in current viewpoint local coordinates.

Camera position in the current viewpoint local coordinates, specified as a vector of three doubles. The doubles represent the x, y, and z vectors in the current viewpoint local coordinates.

Camera up vector, specified as a vector of three doubles. The doubles represent the x, y, and z vectors in the current viewpoint local coordinates.

Callback invoked when closing the vr.canvas object, specified as a string.

Pivot point about which camera rotates in examine navigation mode, specified as a vector of three doubles in world coordinates.

Headlight from camera, specified as 'on' or 'off'. If you specify 'off', the camera does not emit light and the scene can appear dark.

Lighting effect, specified as 'on' or 'off'. If you specify 'off', the camera does not emit light and the scene can appear dark.

Maximum pixel size of textures, specified as 'auto' or integer in a power of 2. The value of 'auto' sets the maximum texture pixel size. Otherwise, specify an integer in a power of two that is equal to or less than the video card limit (typically 1024 or 2048).

The smaller the size, the faster the texture renders. Increasing the size improves image quality but decreases performance.

Note

Specifying a value that is unsuitable causes a warning. The Simulink® 3D Animation™ software then adjusts the property to the next smaller suitable value.

Data Types: int32

Navigation mode, specified as 'fly', 'examine', 'walk', or 'none'. See Mouse Navigation.

Navigation panel appearance, specified as one of 'none', 'halfbar', 'bar', 'opaque', or 'translucent'.

Navigation speed, specified as 'normal', 'slow', 'veryslow', 'fast', or 'veryfast'.

Navigation zones display, specified as 'on' or 'off'.

Location and size of virtual canvas, specified as the vector in the form [left bottom width height]. Specify measurements in pixels or normalized, based on the Units property setting.

ElementDescription
leftDistance from the left edge of the primary display to the inner left edge of the canvas. You can specify a negative value on systems that have more than one monitor.
bottomDistance from the bottom edge of the primary display to the inner bottom edge of the canvas. You can specify a negative value on systems that have more than one monitor.
widthDistance between the right and left inner edges of the canvas.
heightDistance between the top and bottom inner edges of the canvas.

Example: [230 250 570 510]

Sound effects, specified as 'on' or 'off'.

Stereoscopic vision mode, specified as 'off', 'anaglyph', 'active' or a vr.utils.stereo3d object.

Specifying a vr.utils.stereo3d object sets the Stereo3D, Stereo3DCameraOffset, and Stereo3DHIT properties. Specifying a vr.utils.stereo3d object also sets color filters for the left and right cameras.

Data Types: int32

Distance of left and right camera from parallax for stereoscopic vision, specified as a non-negative floating-point double-precision number.

Specifying a vr.utils.stereo3d object for the Stereo3D property also sets the Stereo3DCameraOffset and Stereo3DHIT properties and sets color filters for the left and right cameras.

Horizontal image translation (HIT) of two stereoscopic images, specified as a double from 0 through 1, inclusive. The larger the value, the further back the background appears.

Specifying a vr.utils.stereo3d object for the Stereo3D property also sets the Stereo3DCameraOffset and Stereo3DHIT properties and sets color filters for the left and right cameras.

Texture use, specified as 'on' or 'off'.

Tooltips display, specified as 'on' or 'off'.

Transparency effect, specified as 'on' or 'off'.

Triad location, specified 'bottomleft', 'bottomright', 'center, 'topleft', 'topright', or 'none'.

Units for Position property, specified as 'pixels' or 'normalized'.

Active viewpoint of a figure, specified as a string. If the active viewpoint has no description, use an empty string.

Wireframe display, specified as 'on' or 'off'.

Camera zoom factor, specified as a floating-point number. A zoom factor of 2 makes the scene look twice as large. A zoom factor of 0.1 makes it look 10 times smaller, and so forth.

Output Arguments

expand all

Virtual reality canvas, represented by a vr.canvas object

Properties

expand all

Smooth textures using antialiasing, returned as 'on' or 'off'. Antialiasing smooths textures by interpolating values between texture points.

Camera movement with the current viewpoint, returned as 'on' or 'off'.

Camera direction in the current viewpoint local coordinates, specified as a vector of three doubles. The doubles represent the x, y, and z vectors in current viewpoint local coordinates.

Camera direction in world coordinates, returned as a vector of three doubles (read-only property).

Camera position in the current viewpoint local coordinates, returned as a vector of three doubles. The doubles represent the x, y, and z vectors in the current viewpoint local coordinates.

Camera direction in world coordinates, represented by a vector of three doubles (read-only property).

Camera up vector, returned as a vector of three doubles. The doubles represent the x, y, and z vectors in the current viewpoint local coordinates.

Camera up vector in world coordinates, represented by a vector of three doubles (read-only property).

Callback invoked when closing the vr.canvas object, returned as a string.

Pivot point about which camera rotates in examine navigation mode, returned as a vector of three doubles in world coordinates.

Headlight from camera, returned as 'on' or 'off'. If set to 'off', the camera does not emit light and the scene can appear dark.

Lighting effect, returned as 'on' or 'off'. If set to 'off', the camera does not emit light and the scene can appear dark.

Maximum pixel size of a texture used. The smaller the size, the faster the texture can render. A value of 'auto' means the texture is set to the maximum pixel size.

Data Types: int32

Navigation mode, returned as 'fly', 'examine', 'walk', or 'none'. See Mouse Navigation.

Navigation panel appearance, returned as 'none', 'halfbar', 'bar', 'opaque', or 'translucent'.

Navigation speed, returned as 'normal', 'slow', 'veryslow', 'fast', or 'veryfast'.

Navigation zones display, returned as 'on' or 'off'.

Handle of parent of virtual reality canvas object, represented by a double (read-only property).

Location and size of virtual canvas, returned as the vector in the form [left bottom width height]. Specify measurements in pixels or normalized, based on the Units property setting.

Note

On Windows systems, figure windows cannot be less than 104 pixels wide, regardless of the value of the Position property.

ElementDescription
leftDistance from the left edge of the primary display to the inner left edge of the canvas. You can specify a negative value on systems that have more than one monitor.
bottomDistance from the bottom edge of the primary display to the inner bottom edge of the canvas. You can specify a negative value on systems that have more than one monitor.
widthDistance between the right and left inner edges of the canvas.
heightDistance between the top and bottom inner edges of the canvas.

Example: [230 250 570 510]

Sound effects, returned as 'on' or 'off'.

Stereoscopic vision mode, returned as 'off', 'anaglyph', 'active' or a vr.utils.stereo3d object.

Specifying a vr.utils.stereo3d object sets the Stereo3D, Stereo3DCameraOffset, and Stereo3DHIT properties. Specifying a vr.utils.stereo3d object also sets color filters for the left and right cameras.

Distance of left and right camera from parallax for stereoscopic vision, specified as a non-negative floating-point double-precision number.

Specifying a vr.utils.stereo3d object for the Stereo3D property also sets the Stereo3DCameraOffset and Stereo3DHIT properties and sets color filters for the left and right cameras.

Horizontal image translation (HIT) of two stereoscopic images, returned as a double from 0 through 1, inclusive. The larger the value, the further back the background appears. By default, the background image is at zero and the foreground image appears to pop out from the monitor toward the person viewing the virtual world.

Specifying a vr.utils.stereo3d object for the Stereo3D property also sets the Stereo3DCameraOffset and Stereo3DHIT properties and sets color filters for the left and right cameras.

Texture use, returned as 'on' or 'off'.

Tooltips display, returned as 'on' or 'off'.

Transparency effect, returned as 'on' or 'off'.

Triad location, returned as 'bottomleft', 'bottomright', 'center, 'topleft', 'topright', or 'none'.

Units for Position property, returned as 'pixels' or 'normalized'.

Active viewpoint of a figure, returned as a string.

Wireframe display, returned as 'on' or 'off'.

World containing canvas, represented by a vrworld object (read-only property).

Camera zoom factor, returned as a floating-point number. A zoom factor of 2 makes the scene look twice as large. A zoom factor of 0.1 makes it look 10 times smaller, and so forth.

Methods

capture(To be removed) Capture virtual reality canvas image

Examples

collapse all

Create and open a vrworld object.

myWorld = vrworld('vrlights');
open(myWorld);

Create a figure to use as the parent of the canvas. Create a canvas. Use a figure as the parent and specify the position.

fig = figure;
myCanvas = vr.canvas(myWorld,'Parent',fig,'Units',...
'normalized','Position',[0 0 1 1]);

Figure contains an object of type hgjavacomponent.

Create a figure. Create a canvas in the figure and specify a title.

pf = figure;  
pp1 = uipanel('Parent',pf,'Title','Panel with Title');

Figure contains an object of type uipanel.

Create and open a virtual world.

w = vrworld('vrlights');
open(w);

Create a canvas in the virtual world.

c = vr.canvas(w,pp1);

Figure contains an object of type uipanel.

Set the camera direction, navigation mode, and stereoscopic vision properties of a canvas.

Create and open a vrworld object.

vrmountWorld = vrworld('vrmount.x3d');
open(vrmountWorld);

Create a vr.utils.stereo3d object to use to specify stereoscopic vision properties.

myStereo3D = vr.utils.stereo3d.ANAGLYPH_RED_CYAN;

Create a canvas. Define non-default values for some properties.

myCanvas = vr.canvas(vrmountWorld,'Antialiasing','on',...
           'NavPanel','opaque','NavZones','on','Stereo3D',...
           myStereo3D,'Stereo3DCameraOffset',0.25,...
           'Stereo3DHIT',0.02)
myCanvas = 

  canvas with properties:

            Antialiasing: 'on'
             CameraBound: 'on'
         CameraDirection: [-0.0245 0 -0.9997]
          CameraPosition: [0 0 0]
          CameraUpVector: [0 1 0]
       ExaminePivotPoint: [0 0 0]
               Headlight: 'on'
            Highlighting: 'on'
                Lighting: 'on'
          MaxTextureSize: 'auto'
                NavPanel: 'opaque'
                 NavMode: 'examine'
                NavSpeed: 'normal'
                NavZones: 'on'
                Position: [0 0 1 1]
               Rendering: 'on'
                   Sound: 'on'
                Stereo3D: 'anaglyph'
    Stereo3DCameraOffset: 0.2500
             Stereo3DHIT: 0.0200
                Textures: 'on'
                Tooltips: 'off'
            Transparency: 'on'
                   Triad: 'none'
                   Units: 'normalized'
               Viewpoint: 'View 1 - Observer'
               Wireframe: 'off'
              ZoomFactor: 1
               DeleteFcn: []
      CameraDirectionAbs: [0 -0.1987 -0.9801]
       CameraPositionAbs: [20 8 50]
       CameraUpVectorAbs: [0 0.9801 -0.1987]
                  Parent: [1×1 Figure]
                   World: [1×1 vrworld]

Version History

Introduced before R2006a

collapse all

R2023b: To be removed

The vr.canvas will be removed in a future release. Instead, use sim3d classes and Simulation 3D blocks in Unreal Engine Scenario Applications to interface MATLAB® and Simulink with the Unreal Engine® 3D simulation environment. To get started, see Get Started Creating Virtual World with Actors.