SoViewportRegion

InventorModule

genre	Visualization
author	MeVis Medical Solutions AG
package	MeVisLab/Standard
dll	SoUtils
definition	utils.def
see also	SoOrientationInset
keywords	overlay

Purpose

The module SoViewportRegion renders a subgraph into a specified viewport region (VPR).

It can be compared with the picture-in-picture-function of modern TVs.

Interaction is possible in the displayed rendering. The module can also be used with SoView2D renderings. That way, you can build your own ortho views very easily.

Usage

Connect the subgraph to the child input(s) of the SoViewportRegion.

The output field self should be connected to a viewer.

The viewer might display other graphs directly or may have additional SoViewportRegion attached (see example network).

Modify the viewport according to your needs. You can start with one of the presets and then adjust the viewport settings as needed.

You can use SoViewportRegion in a nested manner. This means that a SoViewportRegion that is the child of another SoViewportRegion can use the previously defined viewport region and modify it, rather than altering the original window (ensure Relate to existing viewport region is activated; see the example network). This can be useful if you want to define a margin, which may be complicated to achieve with the viewport definition parameters alone.

Details

The fields of this module allow for certain viewport region definition behaviors dependent on the size of the window or an existing or previous viewport region. However, this field-based definition is limited. More complex behavior can be implemented using a Python callback function. For that, the field Use Python Callback must be enabled. Then, the module’s Python wrapper can be accessed and the function registered:

wrapper = ctx.module("SoViewportRegion").object()

wrapper.setViewportRegionDefinitionCallback(callbackFunc)

The registered function is called with seven parameters:

windowWidth, windowHeight, currentVPROriginX, currentVPROriginY, currentVPRWidth, currentVPRHeight, HiDPIScaleFactor

and is expected to return a list of four values that define the viewport region:

[originX, originY, width, height]

The input and output values are all related to the system’s internal display resolution. Hence, for HiDPI displays this might be upscaled values. This scale factor is given by HiDPIScaleFactor and should be multiplied to any constant pixel values that are used in the function.

If no Python function is used, HiDPI scaling is performed automatically if Auto scale high DPI (pixel domain) is active. Therefore, pixel values specified in the fields must not be adapted.

Windows

Default Panel

Input Fields

child

name: child, type: SoNode

The scene graph to be rendered in the defined viewport region.

Output Fields

self

name: self, type: SoNode

The child graph rendered inside the defined viewport region.

Parameter Fields

Field Index

Alpha (borderAlpha): Float	enableBorder: Bool	Reference (y2ReferenceMode): Enum
Alpha (backgroundAlpha): Float	Forward events to child graph: Bool	Relate to existing viewport region: Bool
Auto scale high DPI (pixel domain): Bool	In viewport only: Bool	Render Delayed Paths: Bool
Cache Viewport Region: Bool	Map to viewport: Bool	Use Python Callback: Bool
Color (borderColor): Color	Mode (xPositionMode): Enum	Width: Integer
Color (backgroundColor): Color	Mode (yPositionMode): Enum	X1: Float
Consume events in viewport: Bool	Modify viewport region: Bool	x1Title: String
Detect if mouse is over the viewport: Bool	Mouse is over: Bool	X2: Float
Do not change 'mouse over' while dragging: Bool	On: Bool	x2Title: String
Domain (x1DomainMode): Enum	Preset: Enum	Y1: Float
Domain (x2DomainMode): Enum	Projection Type: Enum	y1Title: String
Domain (y1DomainMode): Enum	Reference (x1ReferenceMode): Enum	Y2: Float
Domain (y2DomainMode): Enum	Reference (x2ReferenceMode): Enum	y2Title: String
enableBackground: Bool	Reference (y1ReferenceMode): Enum

Visible Fields

On

name: on, type: Bool, default: TRUE

If checked, the module is active.

Modify viewport region

name: modifyVP, type: Bool, default: TRUE

If checked, the current viewport region will be modified.

Otherwise, the module uses the entire viewer or a previously attached viewport region.

Relate to existing viewport region

name: usePreviousVP, type: Bool, default: FALSE

If checked, the modifications will relate to an existing/previous viewport region (which may have been defined by another SoViewportRegion instance in the scene graph already).

Otherwise, the changes relate to the original window and the existing viewport region will be overridden for the child graph.

Auto scale high DPI (pixel domain)

name: autoScaleAbsoluteValuesHiDPI, type: Bool, default: TRUE, deprecated name: autoScaleAbsoluteValuesHDPI

If checked, the automatic rescaling of absolute values (if domain is set to pixels) in high DPI rendering is enabled.

The provided values of X1, X2, Y1, and Y2 are then multiplied with the global rescale factor (set by the OS or by modules such as OffscreenRenderer). Otherwise, the values are used as they are, which will lead to different results depending on the scale factor.

Typically, this should be activated and field values should be independent of high DPI rendering. It has no influence on relative values.

Note: There are some issues with event handling in high DPI rendering if the domain is set to pixels and Render Delayed Paths is enabled!

Cache Viewport Region

name: cacheViewportRegion, type: Bool, default: FALSE

If checked, the determined viewport region is used until the window or an existing/previous viewport region changes.

Use Python Callback

name: useViewportRegionDefinitionCallback, type: Bool, default: FALSE

If checked, the use of a registered callback function is enabled. If no function is registered, the entire window is used. See Details for more information.

Mode (xPositionMode)

name: xPositionMode, type: Enum, default: POSITION_MODE_MIN_AND_MAX

Defines the positioning mode in x-direction.

Values:

Title	Name	Description
Define left and right border of viewport region (VPR)	POSITION_MODE_MIN_AND_MAX	X1 and X2 act as minimum and maximum values horizontally.
Define center and width of viewport region (VPR)	POSITION_MODE_CENTER_AND_SIZE	X1 and X2 act as center and size horizontally.
Define left border and width of viewport region (VPR)	POSITION_MODE_MIN_AND_SIZE	X1 and X2 act as minimum value and size horizontally.
Define right border and width of viewport region (VPR)	POSITION_MODE_MAX_AND_SIZE	X1 and X2 act as maximum value and size horizontally.

X1

name: x1, type: Float, default: 0.5

Sets the minimum/center horizontally.

Reference (x1ReferenceMode)

name: x1ReferenceMode, type: Enum, default: REFERENCE_MODE_MIN

Defines from where the values for X1 are measured.

Basically, the parameter allows for specifying the alignment. Note that you can use different references for the left and right border for example. This allows for the definition of a border, for example (see example network).

Values:

Title	Name	Description
Left window border	REFERENCE_MODE_MIN	Value (X1, X2, Y1, Y2) relates to the left (x) / lower (y) border of the window (or previously defined viewport).
Window center	REFERENCE_MODE_CENTER	Value relates window center (or to the center of a previously defined viewport).
Right window border	REFERENCE_MODE_MAX	Value relates to the right (x) / upper (y) border of the window (or previously defined viewport).

Domain (x1DomainMode)

name: x1DomainMode, type: Enum, default: DOMAIN_MODE_RELATIVE_TO_WIDTH

Defines how the value of X1 is interpreted.

Values:

Title	Name	Description
Pixels	DOMAIN_MODE_ABSOLUTE	Value is interpreted as an absolute value in pixels.
Fraction of height	DOMAIN_MODE_RELATIVE_TO_HEIGHT	value is interpreted relative to the viewer’s height.
Fraction of width	DOMAIN_MODE_RELATIVE_TO_WIDTH	Value is interpreted relative to the viewer’s width.
Fraction of smallest dimension	DOMAIN_MODE_RELATIVE_TO_MIN	Value is interpreted relative to the viewer’s minimum value.
Fraction of largest dimension	DOMAIN_MODE_RELATIVE_TO_MAX	Value is interpreted relative to the viewer’s maximum value.

X2

name: x2, type: Float, default: 1

Sets the maximum/width horizontally.

Reference (x2ReferenceMode)

name: x2ReferenceMode, type: Enum, default: REFERENCE_MODE_MIN

Defines from where the values for X2 are measured.

Values:

Title	Name
Left window border	REFERENCE_MODE_MIN
Window center	REFERENCE_MODE_CENTER
Right window border	REFERENCE_MODE_MAX

Domain (x2DomainMode)

name: x2DomainMode, type: Enum, default: DOMAIN_MODE_RELATIVE_TO_WIDTH

Defines how the value of X2 is interpreted.

Values:

Title	Name
Pixels	DOMAIN_MODE_ABSOLUTE
Fraction of height	DOMAIN_MODE_RELATIVE_TO_HEIGHT
Fraction of width	DOMAIN_MODE_RELATIVE_TO_WIDTH
Fraction of smallest dimension	DOMAIN_MODE_RELATIVE_TO_MIN
Fraction of largest dimension	DOMAIN_MODE_RELATIVE_TO_MAX

Mode (yPositionMode)

name: yPositionMode, type: Enum, default: POSITION_MODE_MIN_AND_MAX

Defines the positioning mode in y-direction.

Values:

Title	Name
Define lower and upper border of viewport region (VPR)	POSITION_MODE_MIN_AND_MAX
Define center and height of viewport region (VPR)	POSITION_MODE_CENTER_AND_SIZE
Define lower border and height of viewport region (VPR)	POSITION_MODE_MIN_AND_SIZE
Define upper border and height of viewport region (VPR)	POSITION_MODE_MAX_AND_SIZE

Y1

name: y1, type: Float, default: 0.5

Sets the minimum/center vertically.

Reference (y1ReferenceMode)

name: y1ReferenceMode, type: Enum, default: REFERENCE_MODE_MAX

Defines from where the values for Y1 are measured.

Values:

Title	Name
Lower window border	REFERENCE_MODE_MIN
Window center	REFERENCE_MODE_CENTER
Upper window border	REFERENCE_MODE_MAX

Domain (y1DomainMode)

name: y1DomainMode, type: Enum, default: DOMAIN_MODE_RELATIVE_TO_HEIGHT

Defines how the value of Y1 is interpreted.

Values:

Title	Name
Pixels	DOMAIN_MODE_ABSOLUTE
Fraction of height	DOMAIN_MODE_RELATIVE_TO_HEIGHT
Fraction of width	DOMAIN_MODE_RELATIVE_TO_WIDTH
Fraction of smallest dimension	DOMAIN_MODE_RELATIVE_TO_MIN
Fraction of largest dimension	DOMAIN_MODE_RELATIVE_TO_MAX

Y2

name: y2, type: Float, default: 1

Sets the maximum/height vertically.

Reference (y2ReferenceMode)

name: y2ReferenceMode, type: Enum, default: REFERENCE_MODE_MAX

Defines from where the values for Y2 are measured.

Values:

Title	Name
Lower window border	REFERENCE_MODE_MIN
Window center	REFERENCE_MODE_CENTER
Upper window border	REFERENCE_MODE_MAX

Domain (y2DomainMode)

name: y2DomainMode, type: Enum, default: DOMAIN_MODE_RELATIVE_TO_HEIGHT

Defines how the value of Y2 is interpreted.

Values:

Title	Name
Pixels	DOMAIN_MODE_ABSOLUTE
Fraction of height	DOMAIN_MODE_RELATIVE_TO_HEIGHT
Fraction of width	DOMAIN_MODE_RELATIVE_TO_WIDTH
Fraction of smallest dimension	DOMAIN_MODE_RELATIVE_TO_MIN
Fraction of largest dimension	DOMAIN_MODE_RELATIVE_TO_MAX

Projection Type

name: projectionType, type: Enum, default: UNMODIFIED

Defines the type of camera used for rendering the scene.

Values:

Title	Name	Description
Orthographic	ORTHOGRAPHIC	Creates its own orthographic camera.
Perspective	PERSPECTIVE	Creates its own perspective camera.
Auto	AUTO	Uses the camera from the state.
Unmodified	UNMODIFIED	Uses the camera from the child graph.

Render Delayed Paths

name: renderDelayedPaths, type: Bool, default: FALSE

If checked, the rendering is performed using the delayed path rendering of Open Inventor.

This should be disabled if direct rendering is desired or even required, e.g., if using the SoPostEffectRenderer, SoFramebufferSampler, or SoDepthPeelRenderer. Other modules however, such as SoAnnotation or So3DMarkerEditor, require delayed path rendering.

Detect if mouse is over the viewport

name: detectMouseOver, type: Bool, default: FALSE

If checked, the module detects whether the mouse is over the viewport.

Mouse is over

name: mouseOverViewport, type: Bool, persistent: no

Shows whether the mouse is over the viewport.

Forward events to child graph

name: forwardEvents, type: Bool, default: TRUE

If checked, events will be evaluated by the child graph.

In viewport only

name: forwardEventsInViewportOnly, type: Bool, default: TRUE

If checked, only events that occur in the viewport are forwarded to the child graph (should be checked in most cases).

Do not change ‘mouse over’ while dragging

name: keepViewportWhileDragging, type: Bool, default: TRUE

If checked, the Mouse is over field will not change its value while there is a drag operation in the viewer (some mouse button is down and the mouse is moved).

This also means that - if In viewport only is set - the mouse events will still be sent to the viewport scene even when the mouse leaves the viewport region while dragging, and vice versa will not be sent if the dragging started outside the viewport region.

Map to viewport

name: mapEventToViewport, type: Bool, default: TRUE

If checked, the event coordinates will be mapped to the viewport region (should be checked in most cases).

Otherwise, event handling inside the child graph will not work as expected.

Consume events in viewport

name: consumeEventsInViewport, type: Bool, default: TRUE

If checked, all events that occur in the viewport region will be consumed.

Even if there is no module in the subgraph that reacts to the event, the event will be consumed by the SoViewportRegion module itself. This avoids the handling of the event by a module that is not in the SoViewportRegion.

Note: under certain circumstances, this might interfere with MDL EventFilters controls!

Width

name: borderWidth, type: Integer, default: 1, minimum: 1, maximum: 50

Sets the width of the border.

Color (borderColor)

name: borderColor, type: Color, default: 1 1 1

Sets the color used for rendering the border.

Alpha (borderAlpha)

name: borderAlpha, type: Float, default: 1, minimum: 0, maximum: 1

Sets the alpha value used for rendering the border.

Color (backgroundColor)

name: backgroundColor, type: Color, default: 1 1 1

Sets the color used for rendering the background.

Alpha (backgroundAlpha)

name: backgroundAlpha, type: Float, default: 1, minimum: 0, maximum: 1

Sets the alpha value used for rendering the background.

Preset

name: preset, type: Enum, default: centeredThird

Defines a preset for positioning the viewport inside a viewer.

Values:

Title	Name
Centered and third of dimensions	centeredThird
Centered and third of minimum dimension	centeredMinThird
Centered and fixed size	centeredFixed
Upper left corner and third of minimum dimension	upperLeftMinThird
Upper right corner and third of minimum dimension	upperRightMinThird
Lower left corner and third of minimum dimension	lowerLeftMinThird
Lower right corner and third of minimum dimension	lowerRightMinThird
20 Pixel margin	margin

Hidden Fields

enableBorder

name: enableBorder, type: Bool, default: FALSE

If checked, the rendering of a border is enabled.

enableBackground

name: enableBackground, type: Bool, default: FALSE

If checked, the rendering of a background is enabled.

x1Title (hidden)

name: x1Title, type: String, persistent: no

x2Title (hidden)

name: x2Title, type: String, persistent: no

y1Title (hidden)

name: y1Title, type: String, persistent: no

y2Title (hidden)

name: y2Title, type: String, persistent: no