Accessing Active Viewport Info, Type, and Transforms

The following global variables and methods provide access to the Viewports of 3ds Max.

In addition, the ViewPanelManager Core Interface introduced in 3ds Max 2013 exposes the View Panel management functionality, as well as methods related to controlling the placement of the splitter bars and the setting of viewports to Extended types.

Viewport-Related System Global Variables
Viewport Layout
Viewport Display and Render Controls
Viewport Transformations
Viewport Snapping
Viewport Regions

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

viewport.numViews

This 3ds Max system global variable 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, Scripting 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.

Up until 3ds Max 2013, MAXScript did not allow any access to 2D view viewports. Since 3ds Max 2013, viewports can be set to some of the extended types, in particular Track View, Schematic View and Scene Explorer. See the method ViewPanelManager.SetExtendedView() for details.

viewport.activeViewport

This 3ds Max system global variable 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.activeViewportID

Let's you get and set the ID of the active viewport.

Available in 3ds Max 2014 and higher.

<integer>viewport.numViewEx [ viewPanelIndex:<view panel index> ]

Returns the number of viewports.

The optional viewPanelIndex keyword argument specifies the indexed viewPanel, and defaults to the current viewPanel if not specified (the same value as returned by ViewPanelManager.GetActiveViewPanelIndex()).

Available in 3ds Max 2014 and higher.

<integer>viewport.activeViewportEx <viewportIndex> [ viewPanelIndex:<view panel index> ]

Activates the specified indexed viewport.

Available in 3ds Max 2014 and higher.

Viewport Layout

<view_layout_name>viewport.getLayout()

Returns the viewport layout. For the list of possible layout names, see below.

<void>viewport.setLayout <view_layout_name>

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	Name	Description
	#layout_1	One viewport
	#layout_2v	Two Viewports, Vertical Split, Equally Sized
	#layout_2h	Two Viewports, Horizontal Split, Equally Sized
	#layout_2ht	Two Viewports, Horizontal Split, Top Viewport Smaller
	#layout_2hb	Two Viewports, Horizontal Split, Bottom Viewport Smaller
	#layout_3vl	Three Viewports, Vertical Split, Horizontal Split On Left
	#layout_3vr	Three Viewports, Vertical Split, Horizontal Split On Right
	#layout_3ht	Three Viewports, Horizontal Split, Vertical Split On Top
	#layout_3hb	Three Viewports, Horizontal Split, Vertical Split On Bottom
	#layout_4vl	Four Viewports, Vertical Split, Two Horizontal Splits On Left
	#layout_4vr	Four Viewports, Vertical Split, Two Horizontal Splits On Right
	#layout_4ht	Four Viewports, Horizontal Split, Two Vertical Splits On Top
	#layout_4hb	Four Viewports, Horizontal Split, Two Vertical Splits On Bottom
	#layout_4	Four Viewports, Equally Sized

Since 3ds Max 2013, the exact location of the splitter bars can be controlled using MAXScript. See the method ViewPanelManager.SetSplitterBarPos() for details.

<view_type_name>viewport.getType [ index:<integer>  viewPanelIndex:<int>]

This method returns the type of the specified viewport, or the currently active viewport if none is specified.

The optional index: keyword argument specifies the indexed viewport, or the currently active viewport (the same value as returned by viewport.activeViewport()).

<boolean>viewport.setType <view_type_name>

This method sets the view type of the active viewport.

Returns True if setting the view type was success, False if not.

Valid <view_type_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

If the current viewport is an extended viewport (that is, a Schematic View, Asset Manager, or Scripting 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.

EXAMPLE

viewport.setType #view_top -- set active viewport to Top view
--> true
viewport.getType() -- should return what you expect...
--> #view_top

Since 3ds Max 2013, the viewport can be set to some of the Extended Viewport Types - Track View, Schematic View or Scene Explorer. See the method ViewPanelManager.SetExtendedView() for details.

<index>viewport.GetID <viewportIndex> [ viewPanelIndex:<view panel index> ]

Returns the ID of the indexed viewport in 3ds Max 2009 and higher. The ID cannot be set.

When a viewport is maximized, its index is always 1, and its ID corresponds to its index when not maximized. For example, if the bottom right viewport with index 4 is maximized, its index will become 1, but its ID will remain 4.

<void>viewport.ResetAllViews()

This method will reset all viewports in 3ds Max to the default layout.

<node>getActiveCamera()

Returns the camera node associated with the active view, undefined if the view is not a camera view.

<node>viewport.getCamera [ index:<integer> viewPanelIndex:<view panel index> ]

Returns the camera node associated with the active view. undefined if the view is not a camera view.

If the optional index: keyword is specified in 3ds Max 2009 and higher, returns the camera of the indexed viewport instead of the active viewport.

The index numbers correspond to the ones used by viewport.activeViewport .

<void>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.

<boolean>viewport.CanSetToViewport()

Returns True for cameras and lights that can be used as a viewport camera (in other words the object is a valid argument for viewport.setCamera() )

Viewport Display and Render Controls

<void>viewport.setGridVisibility {<int> | #all} <boolean> [ viewPanelIndex:<view panel index> ]

This method sets the Grid visibility in a viewport.

<int> is the viewport index, and <boolean> is the new Grid visibility state.

If #all is specified, the grid visibility for all viewports is set to the specified state.

<boolean>viewport.getGridVisibility <int> [ viewPanelIndex:<view panel index> ]

This method returns True when the Grid is visible in the specified viewport, False when it is not.

The <int> argument is the viewport index.

<boolean>viewport.isWire()

This method returns True if the active viewport is in Wire mode

viewport.DispBkgImage

When this property 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.

<boolean>viewport.EnableSolidBackgroundColorMode <boolean>

This method controls the Solid Background Color display vs Gradient Background Color display.

When the boolean argument is True, the background of the current viewport will be set to Solid Color (in other words, the Gradient will be disabled).

When the boolean argument is False, the background of the current viewport will apply the Gradient colors.

Returns True on success, False on failure.

Available in 3ds Max 2013 and higher.

<boolean>viewport.IsSolidBackgroundColorMode()

This method returns True if the current viewport is in Solid Background Color mode, False if it is in Gradient mode.

Available in 3ds Max 2013 and higher.

<render_level>viewport.GetRenderLevel()

Returns the viewport render level.

The return value can be one of the following: #smoothhighlights , #wireFrame , #smooth , #facethighlights , #facet , #flat , #litwireframe , #Box , #hiddenline

<void>viewport.SetRenderLevel <render_level>

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

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

<boolean>viewport.GetShowEdgeFaces()

Returns True if Edged Faces display is enabled in the current viewport, False otherwise.

<void>viewport.SetShowEdgeFaces <boolean>

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

<integer>viewport.GetTransparencyLevel()

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

1 - None

2 - Simple

3 - Best

<void>viewport.SetTransparencyLevel <transp_level>

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

<boolean>viewport.IsEnabled()

Returns True if the current viewport is enabled, False if it is disabled.

<boolean>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...).

<float>viewport.GetFPS()

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.

Available in 3ds Max 9 and higher.

In 3ds Max 2008 and higher, if the Adaptive Degradation is turned on, the value reported will be the target frame rate, not the actual frame rate.

Viewport Transformations

<matrix3>getViewTM() 
<matrix3>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 anon-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
)

<fov_value>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.

<fov_value>viewport.GetFOV()

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

<boolean>viewport.SetFOV <float>

Sets the Field of View for the active viewport to the specified angle in degrees.

Works only with perspective and camera views.

Returns True if successful, False if the current viewport is not a perspective or camera view.

Available in 3ds Max 2008 and higher.

<focal_distance>viewport.getFocalDistance()

Return the focal distance of the active viewport if a perspective view, undefined otherwise.

Available in 3ds Max 2008 and higher.

<boolean>viewport.setFocalDistance <focal_distance>

Sets the focal distance of the active viewport.

Works only with perspective views, does not work with camera views.

Returns True if successful, False if the current viewport is not a perspective or camera view.

Available in 3ds Max 2008 and higher.

<boolean>viewport.pan <float> <float> [applyUIScaling:<true> ]

Performs a pan of the current viewport using the first argument as the X and the second argument as the Y screen delta in pixels.

Works with all viewport types except object-based ones (Camera, Light etc.).

Returns True if successful, False if the viewport is object-based.

The applyUIScaling parameter indicates whether to apply UI scaling on high-DPI displays.

Available in 3ds Max 2008 and higher.

FOR EXAMPLE

viewport.pan 10 0 -- pan horizontally by ten pixel
completeredraw() -- redraw the views to see the changes

<boolean>viewport.zoom <float>

Performs a zoom of the current viewport using the supplied float value as zoom factor- for example, 2.0 zooms out two times, 0.5 zooms in two times.

Works with all viewport types except object-based ones (Camera, Light etc.).

Returns True if successful, False if the view is object-based.

Available in 3ds Max 2008 and higher.

FOR EXAMPLE

--while the perspective viewport is active, evaluate
viewport.setFOV 50.0 --set viewport Field Of View to 50 deg.
true
completeredraw() --redraw the views
OK
viewport.zoom 2.0 --zoom out two times
true
completeredraw() --redraw the views
OK
viewport.getFOV() --get the new Field Of View
86.0061

What does this result mean?

The FOV angle is dependent on the width of the image plane, but the target distance remains the same.

When the angle is 50 degrees, tangent of half the angle is

tan (50.0/2) -> 0.466308

When you zoom in two times, the width increases twice.

Thus, atan(0.466308*2) -> 43.0031 (new half-angle) and

43.0031 * 2 =86.0062 which is the full viewport FOV angle:

<boolean>viewport.zoomPerspective <float>

Zooms the active viewport. Exactly equivalent to the Interactive Zoom tool in the 3ds Max UI.

This method only works with Perspective views. Does not work for camera views. In the 3ds Max UI, when a user zooms in an orthographic or Isometric User view, internally, a switch is performed on the viewport type, and instead a call to ViewExp::Zoom ( viewport.zoom() )is made.

Returns True if successful, False if the viewport is not a perspective view.

Available in 3ds Max 2008 and higher.

<boolean>viewport.rotate <quat> [center:<Point3>]

Performs a rotate of the current viewport using the supplied quaternion value for the rotation and the Point3 value as the center to perform the rotation about.

Works with all viewport types except object-based ones (Camera, Light etc.).

Returns True if successful, False if the view is object-based.

Available in 3ds Max 2008 and higher.

FOR EXAMPLE

theAxis = (viewport.getTM()).row3
for i = 1 to 180 do
(
viewport.rotate (quat 2 theAxis)
completeredraw()
)

viewport.setCanvasNavigationMode <boolean>

Set the Canvas Navigation Mode of the active viewport on or off.

When a viewport is in 2D Canvas Navigation Mode, the user can only perform 2D pan and zoom in the viewport, all other viewport navigation commands will be rejected.

Available in 3ds Max 2014 and higher.

<boolean>viewport.isCanvasNavigationMode()

Returns True if the viewport is in Canvas Navigation Mode, False if it is not.

When a viewport is in 2D Canvas Navigation Mode, the user can only perform 2D pan and zoom in the viewport, all other viewport navigation commands will be rejected.

Available in 3ds Max 2014 and higher.

<bitmap>viewport.getViewportDib index:<int> viewPanelIndex:<int> captureAlpha:<boolean> gammaCorrect:<boolean>

This method returns the active viewport's graphics window image as a Bitmap value.

The size of the bitmap is the same size as the viewport.

This method is different from gw.getViewportDib() documented here in that it includes the results of using maxops.displayActiveCameraViewWithMultiPassEffect() . Thus, it can be used to generate viewport images containing Depth Of Field or Motion Blur previews.

Available in 3ds Max 2008 and higher . Previously available in Avguard Extensions.

The following options were added in 3ds Max 2015:

If neither index: nor viewPanelIndex: are specified, returns the currently active viewport.

if only index: is specified, returns the bitmap of the indexed viewport in the current viewPanel.

If viewPanelIndex: is specified but index: is not specified, returns the bitmap of the active viewport in the indexed viewPanel.

If both viewPanelIndex: and index: are specified, returns the bitmap of the indexed viewport in the indexed viewPanel.

If the captureAlpha: optional keyword argument is specified and set to True, the viewport Alpha will also be captured. If set to False or not specified, the returned image will contain no Alpha and only the RGB channels (old behavior).

If the gammaCorrect: optional keyword argument is not specified or set to True, gamma correction will be performed on the returned Bitmap value. If set to False, no gamma correction will be performed.

See also windows.snapshot() documented here.

<IntegerPtr>viewport.getHWnd [ index:<int>viewPanelIndex:<int> ]

Returns the HWND Windows handle of the specified viewport or viewPanel.

If neither index: nor viewPanelIndex: are specified, returns the currently active viewport.

if only index: is specified, returns the HWND of the indexed viewport in the current viewPanel.

If viewPanelIndex: is specified but index: is not specified, returns the HWND of the active viewport in the indexed viewPanel.

If both viewPanelIndex: and index: are specified, returns the HWND of the indexed viewport in the indexed viewPanel.

Available in 3ds Max 2015 and higher.

FOR EXAMPLE

--Print the HWND Handles of all valid viewports:
for i = 1 to viewport.numViews do 
    format "HWND of Viewport % is %\n" i (viewport.getHWnd index:i)

--Snapshot the valid viewports:
for i = 1 to viewport.numViews do
    display (windows.snapshot (viewport.getHWnd index:i)) caption:("Viewport "+i as string)

<void>viewport.ZoomToBounds <All_Bool> <A_Point3> <B_Point3>

Zooms all or the current viewport to a bounding region.

When the first argument is passed as True, all viewports are zoomed. When False, only the selected viewport is zoomed.

The second and third arguments define the bounding region to zoom to.

<point2>getViewSize [ removeUIScaling:<true> ]

Returns the active view size as point2 in pixels.

The optional removeUIScaling parameter indicates whether to remove scaling on high-DPI displays.

<float>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.

<float>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()

<ray>mapScreenToWorldRay <pixel_coord_point2> applyUIScaling:<true>

Returns a Ray value in world space through the given viewport pixel coordinates in the current active view, and perpendicular to the viewport plane. When applyUIScaling is true (the default), any scaling required by HDPI displays is applied to the returned ray.

<point3>mapScreenToView <pixel_coord_point2> <depth_float> \
  [ <viewport_size_point2> ]  applyUIScaling:<true>

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. When applyUIScaling is true (the default), any scaling required by HDPI displays is applied to the returned point3.

<point3>mapScreenToCP <pixel_coord_point2> [ <viewport_size_point2> ] \
  applyUIScaling:<true>

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. When applyUIScaling is true (the default), any scaling required by HDPI displays is applied to the returned point3.

<matrix3>getCPTM()

Returns the construction-plane-to-world transformation matrix.

<float>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.

<point3>gw.getPointOnCP <pixel_coord_point2> [ applyUIScaling:<true> ]

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

The applyUIScaling parameter indicates whether to apply UI scaling on high-DPI displays.

<float>gw.getCPDisp <base_point3> <dir_point3> <start_pixel_coord_point2> \ 
  <end_pixel_coord_point2> [ applyUIScaling:<true> ]

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.

The applyUIScaling parameter indicates whether to apply UI scaling on high-DPI displays.

<float>gw.getVPWorldWidth <point3>

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

<point3>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.

<float>gw.getFocalDist()

Returns the focal distance of an active perspective view.

<boolean>gw.IsPerspView()

Returns True if the active viewport is a perspective view; otherwise returns False.

Viewport Snapping

<point3>gw.snapPoint<pixel_coord_point2> [ snapType:<snapType_name> ] \
  [ snapPlane:<matrix3> ]  [ applyUIScaling:<true> ]

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.

The applyUIScaling parameter indicates whether to apply UI scaling on high-DPI displays.

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

<float>gw.snapLength <length_float>

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

Viewport Regions

viewport.setRegionRect <viewport index> <box2> \
  [ viewPanelIndex:<view panel index>  applyUIScaling:<true> ]

Sets the region rectangle for the specified viewport.

The applyUIScaling parameter indicates whether to apply UI scaling on high-DPI displays.

The index: keyword argument specifies the indexed viewport.

viewport.getRegionRect <viewport index> [ viewPanelIndex:<view panel index> removeUIScaling:<true> ]

Get the region rectangle for the specified viewport.

The optional removeUIScaling parameter indicates whether to remove scaling on high-DPI displays.

The index: keyword argument specifies the indexed viewport.

viewport.setBlowupRect <viewport index> <box2> \
  [ viewPanelIndex:<view panel index> applyUIScaling:<true> ]

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.

The applyUIScaling parameter indicates whether to apply UI scaling on high-DPI displays.

The index: keyword argument specifies the indexed viewport.

viewport.getBlowupRect <viewport index>  [ viewPanelIndex:<view panel index> removeUIScaling:<true> ]

Get the blowup rectangle for the specified viewport.

The optional removeUIScaling parameter indicates whether to remove scaling on high-DPI displays.

You can use the Interface: EditRenderRegion to control the manual region editing gizmo in 3ds Max 2009 and higher.

The index: keyword argument specifies the indexed viewport.

Accessing Active Viewport Info, Type, and Transforms

Viewport-Related System Global Variables

Viewport Layout

Viewport Display and Render Controls

Viewport Transformations

Viewport Snapping

Viewport Regions

Related pages