ModelViewer class

Flutter widget for rendering interactive 3D models.

Inheritance

Constructors

ModelViewer({required String src, Color backgroundColor = Colors.transparent, String? alt, String? poster, Loading? loading, Reveal? reveal, bool? withCredentials, bool? ar, List<String>? arModes, ArScale? arScale, ArPlacement? arPlacement, String? iosSrc, bool? xrEnvironment, bool? cameraControls = true, bool? disablePan, bool? disableTap, TouchAction? touchAction, bool? disableZoom, int? orbitSensitivity, bool? autoRotate, int? autoRotateDelay, String? rotationPerSecond, InteractionPrompt? interactionPrompt, InteractionPromptStyle? interactionPromptStyle, num? interactionPromptThreshold, String? cameraOrbit, String? cameraTarget, String? fieldOfView, String? maxCameraOrbit, String? minCameraOrbit, String? maxFieldOfView, String? minFieldOfView, num? interpolationDecay, String? skyboxImage, String? environmentImage, num? exposure, num? shadowIntensity, num? shadowSoftness, String? animationName, num? animationCrossfadeDuration, bool? autoPlay, String? variantName, String? orientation, String? scale, num? minHotspotOpacity, num? maxHotspotOpacity, String? innerModelViewerHtml, String? relatedCss, String? relatedJs, String? id, bool? debugLogging = true, NodeValidatorBuilder? overwriteNodeValidatorBuilder, Set<JavascriptChannel>? javascriptChannels, ValueChanged<WebViewController>? onWebViewCreated, Key? key})
const

Properties

alt → String?
Configures the model with custom text that will be used to describe the model to viewers who use a screen reader or otherwise depend on additional semantic context to understand what they are viewing.
final
animationCrossfadeDuration → num?
When the current animation is changed,
final
animationName → String?
Selects an animation to play by name. This animation will play when the .play() method is invoked, or when the
final
ar → bool?
Enable the ability to launch AR experiences on supported devices.
final
arModes → List<String>?
A prioritized list of the types of AR experiences to enable. Allowed values are "webxr", to launch the AR experience in the browser, "scene-viewer", to launch the Scene Viewer app, "quick-look", to launch the iOS Quick Look app. You can specify any number of modes separated by whitespace. Note that the presence of an ios-src will enable quick-look by itself; specifying quick-look here allows us to generate a USDZ on the fly rather than downloading a separate ios-src file.
final
arPlacement → ArPlacement?
Selects whether to place the object on the floor (horizontal surface) or a wall (vertical surface) in AR. The back (negative Z) of the object's bounding box will be placed against the wall and the shadow will be put on this surface as well. Note that the different AR modes handle the placement UX differently.
final
arScale → ArScale?
Controls the scaling behavior in AR mode. Set to "fixed" to disable scaling of the model, which sets it to always be at 100% scale. Defaults to "auto" which allows the model to be resized by pinch.
final
autoPlay → bool?
If this is true and a model has animations, an animation will automatically begin to play when this attribute is set (or when the property is set to true). If no animation-name is specified, plays the first animation.
final
autoRotate → bool?
Enables the auto-rotation of the model.
final
autoRotateDelay → int?
Sets the delay before auto-rotation begins. The format of the value is a number in milliseconds.
final
backgroundColor → Color
The backgroundColor of the ModelViewer's WebView. Defaults to Colors.transparent.
final
cameraControls → bool?
Enables controls via mouse/touch. This attribute should nearly always be specified, unless all model motion is being controlled by JavaScript functions.
final
cameraOrbit → String?
Set the starting and/or subsequent orbital position of the camera. You can control the azimuthal, theta, and polar, phi, angles (phi is measured down from the top), and the radius from the center of the model. Accepts values of the form "$theta $phi $radius", like "10deg 75deg 1.5m". Also supports units in radians ("rad") for angles and centimeters ("cm") or millimeters ("mm") for camera distance. Camera distance can also be set as a percentage ('%'), where 100% gives the model tight framing within any window based on all possible theta and phi values. Any time this value changes from its initially configured value, the camera will interpolate from its current position to the new value. Any value set to 'auto' will revert to the default. For camera-orbit, camera-target and field-of-view, parts of the property value can be configured with CSS-like functions. The CSS calc() function is supported for these values, as well as a specialized form of the env() function. You can use env(window-scroll-y) anywhere in the expression to get a number from 0-1 that corresponds to the current top-level scroll position of the current frame. For example, a value like "calc(30deg - env(window-scroll-y) * 60deg) 75deg 1.5m" cause the camera to orbit horizontally around the model as the user scrolls down the page.
final
cameraTarget → String?
Set the starting and/or subsequent point the camera orbits around. Accepts values of the form "$X $Y $Z", like "0m 1.5m -0.5m". Also supports units in centimeters ("cm") or millimeters ("mm"). A special value "auto" can be used, which sets the target to the center of the model's bounding box in that dimension. Any time this value changes from its initially configured value, the camera will interpolate from its current position to the new value.
final
debugLogging → bool?
If false, HTMLBuilder will not print debug logs.
final
disablePan → bool?
Disables panning interactions, which are enabled by default using two-finger touch, or dragging with right-click or modifier keys.
final
disableTap → bool?
Disables tap-to-recenter behavior (both center-the-tapped-point and reset-view-when-tapping-outside). This attribute has no effect in combination with 'disable-pan', as the tap-to-recenter behavior is part of the panning interactions. It is recommended to create custom re-centering behavior when using 'disable-tap' as after panning and rotating, it is effectively impossible for the user to exactly return to their starting view.
final
disableZoom → bool?
Disables user zoom when camera-controls is enabled (has no effect otherwise). Has the secondary effect of not swallowing mouse wheel events and pinch gestures, so these will then scroll and zoom the page, respectively.
final
environmentImage → String?
Controls the environmental reflection of the model. Normally if skybox-image is set, that image will also be used for the environment-image. Use environment-image to only set the reflection without affecting the background. If neither is specified, default lighting will be applied. If 'neutral' is specified without a skybox, then a more evenly-lit environment is applied instead.
final
exposure → num?
Controls the exposure of both the model and skybox, for use primarily with HDR environments.
final
fieldOfView → String?
Used to configure the vertical field of view of the camera. Accepts values in both degrees and radians (e.g., "30deg" or "0.5rad"). Accepts any value between the configured min and max field of view. Any time this value changes from its initially configured value, the camera will interpolate from its current value to the new value. Defaults to "auto", which sets either the vertical or horizontal field of view to 45 degrees depending on the dimensions of the model and the aspect ratio of the canvas. Seamless poster transitions for arbitrary element aspect ratios are only possible using "auto".
final
hashCode → int
The hash code for this object.
no setterinherited
id → String?
The id of the ModelViewer in HTML.
final
innerModelViewerHtml → String?
HTML code inside <model-viewer> Tag.
final
interactionPrompt → InteractionPrompt?
Allows you to change the conditions under which the visual and audible interaction prompt will display. If set to "auto", the interaction prompt will be displayed as soon as the interaction-prompt-threshold (see below) time has elapsed (after the model is revealed). If set to "when-focused", the interaction prompt will only be activated if the element has first received focus. The interaction prompt will only display if camera-controls are enabled.
final
interactionPromptStyle → InteractionPromptStyle?
Configures the presentation style of the interaction-prompt when it is raised. When set to "wiggle", the prompt will animate horizontally and the model will rotate as though the prompt is interacting with it. When set to "basic", the prompt is not animated, and instead simply appears until it is dismissed by user interaction.
final
interactionPromptThreshold → num?
When camera-controls are enabled,
final
interpolationDecay → num?
Controls the rate of interpolation when the camera or model moves, due to either user interaction or attribute changes. The decay is asymptotic and the value is in milliseconds, where the majority of the movement will occur within this value's time. Doubling this value will cut the speed in half.
final
iosSrc → String?
The url to a USDZ model which will be used on supported iOS 12+ devices via AR Quick Look on Safari. The presence of this attribute will automatically enable the quick-look ar-mode, however it is no longer necessary. If instead the quick-look ar-mode is specified and ios-src is not specified, then we will generate a USDZ on the fly when the AR button is pressed. This means modifications via the scene-graph API will now be reflected in Quick Look. Hoowever, USDZ generation is not perfect, for instance animations are not yet supported, so in some cases supplying ios-src may give better results.
final
javascriptChannels → Set<JavascriptChannel>?
Passthrough to javascriptChannels in the underlying WebView.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
loading → Loading?
An enumerable attribute describing under what conditions the model should be preloaded. The supported values are "auto", "lazy" and "eager". Auto is equivalent to lazy, which loads the model when it is near the viewport for reveal="auto", and when interacted with for reveal="interaction". Eager loads the model immediately.
final
maxCameraOrbit → String?
Set the maximum orbital values of the camera. Takes values in the same form as camera-orbit, but does not support env(). Note "Infinity" is not an accepted keyword, but the default can still be obtained by passing "auto". The radius value for "auto" is the same as the camera-orbit radius "auto" value.
final
maxFieldOfView → String?
Set the maximum field of view of the camera, corresponding to maximum zoom-out. Takes values in the same form as field-of-view, but does not support env(). The default "auto" is the same as the default field-of-view.
final
maxHotspotOpacity → num?
Sets the opacity of visible hotspots.
final
minCameraOrbit → String?
Set the minimum orbital values of the camera. Note "Infinity" is not an accepted keyword, but the default can still be obtained by passing "auto". The radius value for "auto" is a conservative value to ensure the camera never enters the model, so be careful when setting this to another value.
final
minFieldOfView → String?
Set the minimum field of view of the camera, corresponding to maximum zoom-in. Takes values in the same form as field-of-view, but does not support env(). Set this to a small value to get close zoom-in without the camera entering the model.
final
minHotspotOpacity → num?
This read-only attribute enables DOM content to be styled based on the status of the WebXR AR presentation. For instance, a prompt for the user to move their phone until the object is successfully placed in their space can be shown by scoping a CSS rule to model-viewerar-status="session-started". Setting this attribute has no effect.
final
onWebViewCreated → ValueChanged<WebViewController>?
Passthrough to onWebViewCreated in the underlying WebView.
final
orbitSensitivity → int?
Adjusts the speed of theta and phi orbit interactions. Can also be set negative to reverse, which is helpful when using zero radius to look around the inside of a cave-like model.
final
orientation → String?
Rotates the model to the orientation specified by roll, pitch, yaw Euler angles, where yaw is first applied about the Y-axis, then pitch about the new local X-axis (positive is front-down), then roll about the new local Z-axis. If specified before the model loads, automatic camera framing will take this change into account; otherwise the updateFraming() method must be called manually.
final
overwriteNodeValidatorBuilder → NodeValidatorBuilder?
Customize allowed tags & attrubutes for Web platform.
final
poster → String?
Displays an image instead of the model, useful for showing the user something before a model is loaded and ready to render. If you use a poster with transparency, you may also want to set --poster-color to transparent so that the background shows through.
final
relatedCss → String?
Custom CSS
final
relatedJs → String?
Custom JS
final
reveal → Reveal?
This attribute controls when the model should be revealed. It currently supports three values: "auto", "interaction", and "manual". If reveal is set to "interaction",
final
rotationPerSecond → String?
Sets the speed of auto-rotate, when enabled. Accepts values with units in degrees or radians (e.g., "30deg" or "0.5rad"), as well as percent (e.g. "-100%") of the default value of pi/32 radians.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scale → String?
Scales the model as specified in the X, Y, and Z directions. Scale is applied before orientation. If specified before the model loads, automatic camera framing will take this change into account; otherwise the updateFraming() method must be called manually.
final
shadowIntensity → num?
Controls the opacity of the shadow. Set to 0 to turn off the shadow entirely.
final
shadowSoftness → num?
Controls the blurriness of the shadow. Set to 0 for hard shadows. Softness should not be changed every frame as it incurs a performance cost. Softer shadows render faster.
final
skyboxImage → String?
Sets the background image of the scene. Takes a URL to an equirectangular projection image that's used for the skybox, as well as applied as an environment map on the model. Supports png, jpg and hdr (recommended) images.
final
src → String
The URL or path to the 3D model. This parameter is required. Only glTF/GLB models are supported.
final
touchAction → TouchAction?
Akin to the CSS touch-action property (which does not work due to some iOS bugs), the default 'pan-y' allows touch users to vertically scroll the
final
variantName → String?
Selects a model variant by name.
final
withCredentials → bool?
This attribute makes the browser include credentials (cookies, authorization headers or TLS client certificates) in the request to fetch the 3D model. It's useful if the 3D model file is stored on another server that require authentication. By default the file will be fetch without credentials. Note that this has no effect if you are loading files locally or from the same domain.
final
xrEnvironment → bool?
Enables AR lighting estimation in WebXR mode; this has a performance cost and replaces the lighting selected with environment-image during an AR session. Known issues: sometimes too dark, sudden updates, shiny materials look matte.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<ModelViewer>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited