3D Viewer
Updated 4 months ago to v4.0.0 by Flourish team
How to use this template
A template for displaying 3D scenes with physically based rendering. Well-suited for a number of use cases displaying 3D content, including architectural visualisation and product tours.
How to get started
The first thing you'll want to do is to source your 3D model file for the scene. We recommend binary glTF files (.glb), but also support multiple formats:
- glTF
- OBJ
- FBX
If your model has additional files for textures that you would like to include, you can compress all the relevant files in a ZIP archive and upload that.
Your next step would be to pick an environment map from our list of presets, which will determine the lighting for the scene. You can upload your own equirectangular images for custom lighting too, which can be found on sites such as HDRI Haven or HDRI Skies.
FAQ
How can I add animation to my 3D model? If you upload an FBX or glTF file with animations included, these will automatically be loaded into the template. You can pick animations from a dropdown in the bottom right that appears if animations are available.
Is there a maximum upload size for 3D models? This is currently 25MB.
My 3D model is too large to be uploaded. How can I make it smaller? You can use a tool such as Blender to decimate your model and reduce its size. If your textures are taking up a lot of space, you can try resizing them to make them smaller.
When should I normalize the scale? You'll almost always want to normalize the scale, since it means you can rely on the camera being in a sensible position. You might want to disable the feature if you're using separate models across different slides and want to ensure that they line up with each other.
What are the different environment maps for? The environment maps are used for changing the lighting of your scene, and are also used as the default background image. You can also upload your own! Some examples can be found on sites such as HDRI Haven or HDRI Skies.
Credits
Created by the Flourish team, using open source tools including three.js and regl.
Environment map presets are sourced from various authors, and are all CC0:
API information
This section documents API usage specific to this template, so for an introduction we suggest you refer to the generic API documentation instead.
template: @flourish/3d-viewer
version: 4
Template data
This template does not have any data bindings, so you shouldn't include
data or bindings key/value pairs in your
opts object that is passed to the API. You should specify the
template and template version in the opts object like:
{
template: "@flourish/3d-viewer",
version: "4",
...
}
Template settings
Options for opts.state.
Scene
file url
Scene file. Upload a 3D scene file. Accepted formats include .obj, .fbx, .glb and .gltf. If you have separate files for materials or textures you may package these together with the 3D model in a .zip file and upload that.
file_normalize_scale boolean
Normalise scale. Scales your scene so that it fits within a 1×1×1 box. This makes setting up your scene easier, though you might want to disable it if you want to control your scene's scale yourself.
file_normalize_position boolean
Align to center.
file_scale_multiplier number
Scale.
Environment
envmap_type string
Environment map. The environment map determines the lighting for the scene, and is used as the default background imagery. Allowed values:
envmap_preset_url string
Allowed values:
- indoor_pool_2k.hdr (Indoor pool)
- industrial_pipe_and_valve_01_2k.hdr (Industrial pipe/valve)
- kiara_1_dawn_2k.hdr (Kiara dawn)
- kloofendal_48d_partly_cloudy_2k.hdr (Kloofendal)
- signal_hill_dawn_2k.hdr (Signal Hill Dawn)
- rooftop_night_2k.hdr (Rooftop Night)
- champagne_castle_1_2k.hdr (Champagne Castle)
- snowy_park_01_2k.hdr (Snowy park)
- studio_small_01_2k.hdr (Small studio)
- venice_sunset_2k.hdr (Venice sunset)
- wasteland_clouds_2k.hdr (Wasteland)
envmap_preset_ambient boolean
Ambient. Use a blurred version of the environment map. This will load much more
quickly than using the full image.
envmap_gradient_ground color
Ground.
envmap_gradient_horizon color
Horizon.
envmap_gradient_sky color
Sky.
envmap_custom_url url
Image (.hdr, .png, .jpg). Upload a custom environment map. This should be a single rectangular image with an equirectangular projection. Ideally, you want this to be an RGBE (.hdr) image, as this format supports HDR and generally produces better results.
envmap_material_exposure number
Scene exposure. Change the brightness of your uploaded scene. Min: 0.01 Max: 2
envmap_background_exposure number
Background exposure. Change the brightness of the background image behind your scene. Min: 0.01 Max: 2
envmap_rotation number
Rotation. Min: -180 Max: 180
background_type string
Type. Changes the background drawn behind your scene. Note that the environment map chosen above still determines how to light the scene. Allowed values:
background_color color
Color.
Camera and Controls
camera.disable_interaction boolean
Disable user interaction.
camera.hijack_scroll boolean
Require cmd/ctrl to zoom when scrolling.
allow_fullscreen boolean
Allow fullscreen. Shows the fullscreen button when available. Note that the button will still be hidden if fullscreen is blocked or unavailable.
camera.initial.mode string
Mode. Allowed values:
camera.initial.orbit.pitch number
Pitch. Min: -90 Max: 90
camera.initial.orbit.heading number
Heading. Min: -180 Max: 180
camera.initial.orbit.distance number
Distance.
camera.initial.free_look.position_x number
X.
camera.initial.free_look.position_y number
Y.
camera.initial.free_look.position_z number
Z.
camera.initial.free_look.pitch number
Pitch. Min: -90 Max: 90
camera.initial.free_look.heading number
Heading. Min: -180 Max: 180
controls_style.font_size number
Text size. Max: 5
controls_style.font_weight string
Text weight. Allowed values:
controls_style.padding number
Height. Space below and above controls text Max: 5
dropdown_style.background color
Background.
dropdown_style.font_color color
Text color.
dropdown_style.border_styles_advanced boolean
Dropdown border styles.
dropdown_style.border_style string
Border style. Show border on all sides, or only at the bottom Allowed values:
dropdown_style.border_width number
Border width. Max: 20
dropdown_style.border_color color
Color.
dropdown_style.border_transparency number
Transparency. Max: 1
dropdown_style.border_radius number
Radius. Max: 100
Animation
animation_static_label string
"Static" animation label. Uploading a model with animations will display a dropdown in the bottom
corner. This dropdown has an additional selection available for disabling
animations which defaults to "None". Changing this will change the label
in this dropdown.
camera.animation_duration number
Camera transition duration.
Annotations
occlude_annotations boolean
Occlude annotations. Hides annotations if they're behind an object in the scene. Note that this may slow rendering down, so you may want to have it disabled on non-trivial scenes.
annotations.defaults.text_weight string
Weight. Allowed values:
annotations.defaults.text_size number
Text size.
annotations.defaults.label_width number
Max text width. Min: 2 Max: 20
annotations.defaults.line_marker string
Line marker. Allowed values:
annotations.defaults.connector_extend_line string
Extend line. Allowed values:
annotations.defaults.stroke_width number
Stroke width. Max: 4
annotations.defaults.text_line_height number
Line height. Min: 0.5 Max: 3
annotations.defaults.popup_position string
Popup position. Allowed values:
annotations.defaults.text_color color
Text.
annotations.defaults.text_bg color
Text Outline.
annotations.defaults.point_text_color color
Label.
annotations.defaults.popup_bg color
Popup.
annotations.defaults.stroke_color color
Stroke.
annotations.defaults.subject_fill color
Fill.
annotations.defaults.subject_fill_opacity number
Fill opacity. Max: 1
Layout
layout.body_font font
Main font. This font will apply to the whole graphic by default, but you can optionally change the font for the title, subtitle, footer, etc in the Header and Footer settings panels.
layout.font_color color
Text color. This color will apply to the whole graphic by default, but you can optionally change the color for individual text elements, in other settings panels.
layout.background_color_enabled boolean
Color. Allowed values:
layout.background_image_enabled boolean
Image. Allowed values:
layout.background_color color
Background color.
layout.background_image_src url
Image URL.
layout.background_image_size string
Size. Allowed values:
layout.background_image_position string
Position. Allowed values:
layout.max_width_target string
Maximum width. Apply a maximum width to just the main graphic or everything (main graphic plus header, footer, etc) Allowed values:
layout.max_width number
Maximum width. Leave blank to stretch to container width Min: 50
layout.max_width_align string
Align. Allowed values:
layout.layout_order string
Layout order. Allowed values:
layout.space_between_sections string
Space between sections. Allowed values:
layout.space_between_sections_custom number
Custom. Max: 100
layout.margin_top number
Top.
layout.margin_right number
Right.
layout.margin_bottom number
Bottom.
layout.margin_left number
Left.
layout.border.enabled boolean
Show borders around visualisation.
layout.border.top.width number
Top.
layout.border.top.style string
Style. Allowed values:
layout.border.top.color color
Color.
layout.border.right.width number
Right.
layout.border.right.style string
Style. Allowed values:
layout.border.right.color color
Color.
layout.border.bottom.width number
Bottom.
layout.border.bottom.style string
Style. Allowed values:
layout.border.bottom.color color
Color.
layout.border.left.width number
Left.
layout.border.left.style string
Style. Allowed values:
layout.border.left.color color
Color.
Header
layout.header_align string
Alignment. Allowed values:
layout.title string
layout.title_styling boolean
Change title styles.
layout.title_font font
Title Font.
layout.title_size string
Size. Allowed values:
layout.title_size_custom number
Custom. Specify a custom responsive font size. Best results will be with values between 1.2 and 3
layout.title_weight string
Weight. Allowed values:
layout.title_color color
Color.
layout.title_line_height number
Line height. Max: 3
layout.title_space_above string
Space above. Allowed values:
layout.title_space_above_custom number
Custom. Max: 100
layout.subtitle string
layout.subtitle_styling boolean
Change subtitle styles.
layout.subtitle_font font
Subtitle Font.
layout.subtitle_size string
Size. Allowed values:
layout.subtitle_size_custom number
Custom. Specify a custom responsive font size. Best results will be with values between 1.2 and 3
layout.subtitle_weight string
Weight. Allowed values:
layout.subtitle_color color
Color.
layout.subtitle_line_height number
Line height. Max: 3
layout.subtitle_space_above string
Space above. Allowed values:
layout.subtitle_space_above_custom number
Custom. Max: 100
layout.header_text string
layout.header_text_styling boolean
Styling.
layout.header_text_size string
Size. Allowed values:
layout.header_text_size_custom number
Custom. Specify a custom responsive font size. Best results will be with values between 1.2 and 3
layout.header_text_weight string
Weight. Allowed values:
layout.header_text_color color
Color.
layout.header_text_line_height number
Line height. Max: 3
layout.header_text_space_above string
Space above. Allowed values:
layout.header_text_space_above_custom number
Custom. Max: 100
layout.header_border string
Allowed values:
- top (Top)
- bottom (Bottom)
- none (None)
layout.header_border_width number
Width.
layout.header_border_color color
Color.
layout.header_border_style string
Style. Allowed values:
layout.header_border_space number
Space. Space between border and header text
layout.header_logo_enabled boolean
Allowed values:
- true (Enabled)
- false (Disabled)
layout.header_logo_src url
URL.
layout.header_logo_height number
Height.
layout.header_logo_align string
Align. Align logo inside header or outer visualisation container Allowed values:
layout.header_logo_position_inside string
Position. Allowed values:
layout.header_logo_position_outside string
Position. Allowed values:
layout.header_logo_margin_top number
Top.
layout.header_logo_margin_right number
Right.
layout.header_logo_margin_bottom number
Bottom.
layout.header_logo_margin_left number
Left.
Footer
layout.footer_align string
Alignment. Allowed values:
layout.footer_text_size number
Size.
layout.footer_text_color color
Color.
layout.footer_styling boolean
Advanced footer styles.
layout.footer_font font
Font.
layout.footer_text_weight string
Weight. Allowed values:
layout.source_name string
Source name.
layout.source_url string
Source url.
layout.multiple_sources boolean
Multiple sources.
layout.source_name_2 string
Source name.
layout.source_url_2 string
Source url.
layout.source_name_3 string
Source name.
layout.source_url_3 string
Source url.
layout.source_label string
Source label.
layout.footer_note string
Note.
layout.footer_note_secondary string
Note (secondary). The secondary note is placed below the source and primary note
layout.footer_logo_enabled boolean
Image. Allowed values:
layout.footer_logo_src url
Image.
layout.footer_logo_src_light hidden
Image (light version). If provided this version will be used whenever the background colour is dark
layout.footer_logo_link_url string
Link.
layout.footer_logo_height number
Height.
layout.footer_logo_margin number
Margin.
layout.footer_logo_order string
Position. Allowed values:
layout.footer_align_vertical string
V. align. Allowed values:
layout.footer_border string
Allowed values:
- top (Top)
- bottom (Bottom)
- none (None)
layout.footer_border_width number
Width.
layout.footer_border_color color
Color.
layout.footer_border_style string
Style. Allowed values:
layout.footer_border_space number
Space. Space between border and footer text
Accessibility
layout.screenreader_hide_primary boolean
Screenreader mode for main visual container. Whether the main visual container is visible to screenreaders. (Text in the header and footer are always available to screenreaders.) Allowed values:
layout.screenreader_text_primary text
Screenreader description. A text alternative to the visual content that will only be visible to screenreaders, e.g. “The line chart shows China consistently higher than the other countries since 1990”. Do no replicate your title, since that will also be read by screenreaders.
