vr.canvas class

Superclasses:

Create virtual reality canvas

Description

Create a virtual reality canvas.

Construction

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

virtualCanvas = vrfigure(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.

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

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

world — Virtual world

vrworld object

Virtual world, specified as a vrworld object.

Note

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

parent — Figure for displaying canvas

figure object | uipanel object

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

position — Canvas location and size

vector with four elements

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.

Element	Description
left	Distance 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.
bottom	Distance 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.
width	Distance between the right and left inner edges of the canvas.
height	Distance between the top and bottom inner edges of the canvas.

Example: [230 250 570 510]

Data Types: double

Name-Value Pair 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.

Antialiasing — Smooth textures using antialiasing

'off' (default) | 'on'

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

CameraBound — Camera movement with current viewpoint

'on' (default) | 'off'

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

CameraDirection — Camera direction in the current viewpoint local coordinates

vector of three doubles

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.

CameraPosition — Camera position in the current viewpoint local coordinates

vector of three doubles

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.

CameraUpVector — Camera up vector

vector of three doubles

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.

DeleteFcn — Callback invoked when closing vr.canvas object

string

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

ExaminePivotPoint — Pivot point about which camera rotates in examine navigation mode

vector of three doubles

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

Headlight — Headlight from camera

'on' (default) | 'off'

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 — Lighting effect

'on' (default) | 'off'

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

MaxTextureSize — Maximum pixel size of textures

'auto' (default) | integer in a power of 2

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

NavMode — Navigation mode

'fly' (default) | 'examine' | 'walk' | 'none'

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

NavPanel — Navigation panel appearance

'none' (default) | 'halfbar' | 'bar' | 'opaque' | 'translucent'

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

Navspeed — Navigation speed

'normal' (default) | 'slow' | 'veryslow' | 'fast' | 'veryfast'

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

NavZones — Display navigation zones

'off' (default) | 'on'

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

Position — Canvas location and size

vector with four doubles

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.

Element	Description
left	Distance 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.
bottom	Distance 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.
width	Distance between the right and left inner edges of the canvas.
height	Distance between the top and bottom inner edges of the canvas.

Example: [230 250 570 510]

Sound — Sound effects

'on' (default) | 'off'

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

Stereo3D — Stereoscopic vision mode

'off' (default) | 'anaglyph' | 'active' | vr.utils.stereo3d object

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

Stereo3DCameraOffset — Distance of left and right camera for stereoscopic vision

non-negative floating-point double-precision number

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.

Stereo3DHIT — Horizontal image translation (HIT) of two stereoscopic images

double from 0 to 1

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.

Textures — Texture use

'on' (default) | 'off'

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

Tooltips — Tooltips display

'on' (default) | 'off'

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

Transparency — Transparency effect

'on' (default) | 'off'

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

Triad — Triad location

'bottomleft' (default) | 'bottomright' | 'center | 'topleft' | 'topright' | 'none'

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

Units — Units for Position property

'pixels' (default) | 'normalized'

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

Viewpoint — Active viewpoint of figure

string

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

Wireframe — Wireframe display

'off' (default) | 'on'

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

ZoomFactor — Camera zoom factor

1 (default) | floating-point number

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

virtualCanvas — Virtual reality canvas

vr.canvas object

Virtual reality canvas, represented by a vr.canvas object

Properties

Antialiasing — Smooth textures using antialiasing

'off' (default) | 'on'

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

CameraBound — Camera movement with current viewpoint

'on' (default) | 'off'

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

CameraDirection — Camera direction in the current viewpoint local coordinates

vector of three doubles

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.

CameraDirectionAbs — Camera direction in world coordinates

vector of three doubles

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

CameraPosition — Current camera position in the current viewpoint local coordinates

vector of three doubles

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.

CameraPositionAbs — Camera position in world coordinates

vector of three doubles

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

CameraUpVector — Camera up vector

vector of three doubles

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.

CameraUpVectorAbs — Camera up vector in world coordinates

vector of three doubles

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

DeleteFcn — Callback invoked when closing vr.canvas object

string

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

ExaminePivotPoint — Pivot point about which camera rotates in examine navigation mode

vector of three doubles

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

Headlight — Headlight from camera

'on' (default) | 'off'

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 — Lighting effect

'on' (default) | 'off'

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

MaxTextureSize — Maximum pixel size of textures

'auto' (default) | integer in a power of 2

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

NavMode — Navigation mode

'fly' (default) | 'examine' | 'walk' | 'none'

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

NavPanel — Navigation panel appearance

'none' (default) | 'halfbar' | 'bar' | 'opaque' | 'translucent'

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

Navspeed — Navigation speed

'normal' (default) | 'slow' | 'veryslow' | 'fast' | 'veryfast'

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

NavZones — Display navigation zones

'off' (default) | 'on'

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

Parent — Handle of parent of virtual reality canvas object

double

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

Position — Canvas location and size

vector with four doubles

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.

Element	Description
left	Distance 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.
bottom	Distance 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.
width	Distance between the right and left inner edges of the canvas.
height	Distance between the top and bottom inner edges of the canvas.

Example: [230 250 570 510]

Sound — Sound effects

'on' (default) | 'off'

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

Stereo3D — Stereoscopic vision mode

'off' (default) | 'anaglyph' | 'active' | vr.utils.stereo3d object

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.

Stereo3DCameraOffset — Distance of left and right camera for stereoscopic vision

non-negative floating-point double-precision number

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.

Stereo3DHIT — Horizontal image translation (HIT) of two stereoscopic images

double from 0 to 1

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.

Textures — Texture use

'on' (default) | 'off'

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

Tooltips — Tooltips display

'on' (default) | 'off'

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

Transparency — Transparency effect

'on' (default) | 'off'

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

Triad — Triad location

'bottomleft' (default) | 'bottomright' | 'center | 'topleft' | 'topright' | 'none'

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

Units — Units for Position property

'pixels' (default) | 'normalized'

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

Viewpoint — Active viewpoint of figure

string

Active viewpoint of a figure, returned as a string.

Wireframe — Wireframe display

'off' (default) | 'on'

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

World — World containing canvas

vrworld object

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

ZoomFactor — Camera zoom factor

1 (default) | floating-point number

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

Capture virtual reality canvas image

Examples

Create a Canvas That Displays in a Figure

Create and open a vrworld object.

myWorld = vrworld('vrlights.wrl');
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]);

Create a Virtual World in a Canvas

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

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

Create and open a virtual world.

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

Create a canvas in the virtual world.

c = vr.canvas(w,pp1);

Set Property Values of Canvas

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

Create and open a vrworld object.

vrmountWorld = vrworld('vrmount.wrl');
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 0 -1]
          CameraPosition: [0 0 0]
          CameraUpVector: [0 1 0]
       ExaminePivotPoint: [0 0 0]
               Headlight: 'on'
                Lighting: 'on'
          MaxTextureSize: 'auto'
                NavPanel: 'opaque'
                 NavMode: 'examine'
                NavSpeed: 'normal'
                NavZones: 'on'
                Position: [0 0 1 1]
                   Sound: 'on'
                Stereo3D: 'anaglyph'
    Stereo3DCameraOffset: 0.2500
             Stereo3DHIT: 0.0200
                Textures: 'on'
                Tooltips: 'on'
            Transparency: 'on'
                   Triad: 'none'
                   Units: 'normalized'
               Viewpoint: 'View 1 - Observer'
               Wireframe: 'off'
              ZoomFactor: 1
               DeleteFcn: []
      CameraDirectionAbs: [0 -0.1987 -0.9801]
       CameraPositionAbs: [20.2500 8 50]
       CameraUpVectorAbs: [0 0.9801 -0.1987]
                  Parent: [1x1 Figure]
                   World: [1x1 vrworld]