Accessing Active Viewport Info, Type, and Transforms

The following 3ds Max system global variables are associated with the viewports:

viewport.activeViewport

Lets you get and set the index of the active viewport. If you change the currently active viewport to a 2D view, this variable will contain the value 0.

 

viewport.numViews

Contains the number of 3D viewports in the current viewport layout. This variable is read-only. This variable does not reflect any 2D (Track View, Schematic View, Listener, and so on) views in the viewport layout. So, for example, if viewport.getLayout() returns #layout_4 and this variable contains the value 2, you know that two of the viewports contain 2D views. MAXScript currently does not allow you to access 2D view viewports.

The following methods access viewport information and transforms:

viewport.getLayout()

viewport.setLayout <view_layout_name>

Gets or sets the viewport layout, where <view_layout_name> specifies the viewport layout configuration. When setting the layout, the view shown in each viewport is based on the configuration set in Customize > Viewport Configuration > Layout. The list of valid <view_layout_name> values below uses the following syntax:

# is the total number of viewports.

V = vertical split

H = horizontal split

L/R = left/right placement

T/B = top/bottom placement

The valid <view_layout_name> values are:

#layout_1 -- 1 viewport

#layout_2v -- 2 viewports, vertical split, both same size

#layout_2h -- 2 viewports, horizontal split, both same size

#layout_2ht -- 2 viewports, horizontal split, top smaller

#layout_2hb -- 2 viewports, horizontal split, top larger

#layout_3vl -- 3 viewports, 2 on left, 1 on right

#layout_3vr -- 3 viewports, 1 on left, 2 on right

#layout_3ht -- 3 viewports, 2 on top, 1 on bottom

#layout_3hb -- 3 viewports, 1 on top, 2 on bottom

#layout_4 -- 4 viewports, all same size

#layout_4vl -- 4 viewports, 3 on left, 1 on right

#layout_4vr -- 4 viewports, 1 on left, 3 on right

#layout_4ht -- 4 viewports, 3 on top, 1 on bottom

#layout_4hb -- 4 viewports, 1 on top, 3 on bottom

viewport.getType()

viewport.setType <name>

Get and set the view type for the current viewport. Valid <name> values are:

#view_top -- Top

#view_bottom -- Bottom

#view_right -- Right

#view_left -- Left

#view_front -- Front

#view_back -- Back

#view_persp_user -- Perspective

#view_iso_user -- User

#view_camera -- Camera

#view_spot -- Light

#view_shape -- Shape

#view_grid -- Grid

Notes:

If the current viewport is an extended viewport (that is, a Schematic View, Asset Manager, or MAXScript Listener viewport), getType() will return undefined. If a Camera is specified with setType(), and there is not exactly one camera selected, a dialog will be displayed for the user to select the camera to use. If there is no Camera, a message box "No Cameras in scene" will be issued.

viewport.getType can also return a value of #view_none. If none of the viewports have focus, a value of false is returned.

viewport.setType returns a boolean - true if setting the view type was successful, false if not.

Example:

viewport.setType #view_top -- set active viewport to Top view

true

viewport.getType() -- should return what you expect...

#view_top

 

viewport.ResetAllViews()

This function will reset all viewports in Max to the default layout.

 

getActiveCamera()

viewport.getCamera()

Return the camera node associated with the active view if any, undefined if none.

 

viewport.setCamera <camera_or_light_node>

Sets the active viewport to a Camera view, using the specified camera.

You can also set the active view to a Light view using a free, target or direct light.

 

viewport.CanSetToViewport()

Returns true for cameras and lights that can be used as a viewport camera (valid argument to viewport.setCamera)

 

viewport.setRegionRect <viewport index> <box2>

Set the region rectangle for the specified viewport.

 

viewport.getRegionRect <viewport index>

Get the region rectangle for the specified viewport.

 

viewport.setBlowupRect <viewport index> <box2>

Set the blowup rectangle for the specified viewport. The blowup rectangle must have the same aspect as the current render output size aspect. The top, bottom, and left component values are taken from the Box2 value argument, but the right component value is re-calculated to force the proper aspect.

 

viewport.getBlowupRect <viewport index>

Get the blowup rectangle for the specified viewport.

 

viewport.setGridVisibility {<int> | #all} <bool>

Set whether the grid is visible in a viewport, where <int> is the viewport index, and <bool> is the grid visibility state. If #all is specified, the grid visibility for all viewports is set to the specified state.

 

viewport.getGridVisibility <int>

Get whether the grid is visible in a viewport, where <int> is the viewport index.

 

viewport.isWire()

Returns true if the active viewport is in Wire mode

 

viewport.DispBkgImage

When this variable is set to true, the background image will be displayed in the active viewport. When set to false, the background image will not be displayed.

 

viewport.GetRenderLevel()

Returns the viewport render level.

Can be one of the following: #smoothhighlights, #wireFrame, #smooth, #facethighlights, #facet, #flat, #litwireframe, #Box

 

viewport.SetRenderLevel <render_level>

Sets the current viewport's render level to the specified mode.

Valid values are #smoothhighlights, #wireFrame, #smooth, #facethighlights, #facet, #flat, #litwireframe, #Box

 

viewport.GetShowEdgeFaces()

Returns true if Edged Faces are enabled in the current viewport, false otherwise.

 

viewport.SetShowEdgeFaces <boolean>

Turns the Edged Faces display on or off depending on the boolean argument.

 

viewport.GetTransparencyLevel()

Returns the current viewport's transparency level. Possible values are:

1 - None

2 - Simple

3 - Best

 

viewport.SetTransparencyLevel <transp_level>

When Sets the current viewport's transparency level. See above for possible values.

 

viewport.IsEnabled()

Returns true if the current viewport is enabled, false if it is disabled.

 

viewport.IsPerspView()

Returns true if the current viewport is a perspective viewport (Pespective or non-othographic Camera), false if it is an orthographic view (Top, Bottom, Front, Back, Left, Right, User, orthographic Camera...).

 

viewport.GetFPS()

new.gif NEW in 3ds Max 9: Returns the last frame rate value in frames per second calculated by the Show Statistics overlay for the current viewport. If the viewport's Show Statistics option is not turned on, the value will not represent the current frame rate of the viewport.

 

getViewTM()

viewport.getTM()

viewport.setTM <matrix3>

Get or set the active view screen-to-world transform matrix for non-orthographic (perspective and isometric user views) viewports. This is the affine camera or viewport matrix. setTM only operates on Perspective viewports, and returns a value of true if the view transform matrix was successfully set, false otherwise.

The following function returns as a Ray value the "eye" location and direction for the active viewport. The viewport needs to be a non-orthographic viewport.

Example:

fn getViewDirectionRay =

(

-- The affine TM transforms from world coords to view coords

-- so we need the inverse of this matrix

local coordSysTM = Inverse(getViewTM())

-- The Z axis of this matrix is the view direction.

local viewDir = -coordSysTM.row3

-- get the view position from this matrix

local viewPt = coordSysTM.row4

return ray viewPt viewDir

)

getViewFOV()

Returns the Field of View for the active viewport. If the viewport is an orthographic viewport, a value of 57.2958 degrees (1 radian) is returned.

viewport.GetFOV()

Returns the Field of View for the active viewport. Same as getViewFOV()

 

getViewSize()

Returns the active view size as point2 in pixels.

 

getScreenScaleFactor <point3>

Returns the active view scale factor, giving the width in world-space units at the point's distance from the view space origin.

viewport.GetScreenScaleFactor()

Returns the active view scale factor, giving the width in world-space units at the point's distance from the view space origin. Same as getScreenScaleFactor()

 

mapScreenToWorldRay <pixel_coord_point2>

Returns a Ray value in world space through the given viewport pixel coordinates in the current active view, and perpendicular to the viewport plane.

 

mapScreenToView <pixel_coord_point2> <depth_float> \
[ <viewport_size_point2> ]

Returns a 3D point in the view coordinate space. Given a point in the active viewport screen (in viewport pixel coordinates), and a depth in view coordinates, this method maps the point into view coordinates. If <viewport_size_point2> is supplied, the specified viewport size is used instead of the actual viewport size.

 

mapScreenToCP <pixel_coord_point2> [ <viewport_size_point2> ]

Maps viewport pixel coordinates in the current active view to the construction plane in world coordinates. If <viewport_size_point2> is supplied, the specified viewport size is used instead of the actual viewport size.

 

getCPTM()

Construction-plane-to-world transform matrix.

 

gw.nonScalingObjectSize()

The value returned from this method may be used as a scale factor that will counteract the viewport zoom. For example, lights, cameras, and tape helper objects use this factor so the size of the node in the scene remains constant when the viewport is zoomed in and out.

This value is affected by the 'Non-Scaling Object Size' spinner in the Viewport Preferences dialog, so the user has some control over this as well.

 

gw.getPointOnCP <pixel_coord_point2>

Returns a point in world space on the current construction plane based on the specified screen coordinate.

 

gw.getCPDisp <base_point3> <dir_point3> \
<start_pixel_coord_point2> <end_pixel_coord_point2>

This method returns a length in world space given a start screen point (<start_pixel_coord_point2>), an end screen point (<end_pixel_coord_point2>), a base point (<base_point3>) and a direction vector (<dir_point3>). For example, when creating a cylinder, the user clicks the mouse down to define the center point of the cylinder (base), then drags out a radius. They then drag out a height for the cylinder. This method is used to return intermediate and final heights for the cylinder based on the initial base point, the direction vector (the Z axis), the start mouse point, and the current point the user is interactively adjusting.

 

gw.getVPWorldWidth <point3>

Returns the viewport screen width factor in world space at a point in world space.

 

gw.mapCPToWorld <point3>

Returns the corresponding world space point given a point on the construction plane. For example, if you use gw.getPointOnCP() to convert a screen coordinate to a point on the construction plane, you could then call this method to convert that point on the construction plane to a world space point.

 

gw.IsPerspView()

Returns true if the active viewport is a perspective view; otherwise returns false.

 

gw.getFocalDist()

Returns the focal distance of an active perspective view.

 

gw.snapPoint <pixel_coord_point2> [ snapType:<snapType_name> ] [ snapPlane:<matrix3> ]

Given a 2D screen coordinate, this method returns a 3D point on either the current construction plane or the optional snapPlane based on the current snap settings and the optional snapType parameter.

The valid <snapType_name> values are:

#in3d

Snap to all points.

#inPlane

Snap only to points on the construction plane.

#unSelObjs

Ignore selected nodes when considering snap points.

#selObjs

Ignore unselected nodes when considering snap points.

#unSelSubobj

Ignore selected sub-object geometry when considering snap points.

#selSubobj

Ignore unselected sub-object geometry when considering snap points.

#force3d

Override user settings to force snap in 3D.

The optional snapPlane argument available in 3ds Max 8 and higher is a matrix3 value which is the transform that maps the XY plane to the snapping plane. If the matrix3 value supplied is equal to the identity matrix (Matrix3 1), the snapping plane is identical to the XY construction plane.

For example:

tm = Matrix3(1) --represents the XY plane

m = Point2 0 0 --screen pixel coordinates

p = gw.snapPoint m snapPlane:tm --returns the snapping point

 

gw.snapLength <length_float>

This method snaps the length to the nearest snap increment and returns the snapped distance.

 

units.formatValue <float>

Returns a <string> value representing the <float> in the current unit scale. This method can cause a string overflow, especially when the units are set to miles or kilometers. If an overflow occurs a run-time error is thrown.

 

units.decodeValue <string>

Parses <string> using the current unit settings and returns a <float>. A run-time error is thrown if an error occurs in the parsing of the string.