3D-Viewer (WebWidget)
The 3D Viewer is a WebWidget based on WebGL technology, which displays any 3D models in glTF format and allows the user to interact with these models. The WebWidget offers easy navigation with the arrow keys and mouse from the first-person perspective (FPP) and detects collisions by means of simple ray castings. The arrow keys are used to move horizontally forwards, backwards, right and left. If you want to change your vertical position, you have to hold down the CTRL key and use one of the arrow keys "up" or "down" at the same time. With the mouse you can set the direction of rotation of the camera. Simultaneous rotation (with the mouse) and translation (with the arrow keys) is not possible at the moment. | (The model shown in this screenshotis licensed under the CC License and is an artwork by Francesco Coldesina) |
Furthermore, the user can only interact with the model by clicking on 3D areas in the model. When clicking on a so-called interaction area, an IV message with the ID of the area is sent, after which any InstantView instructions can be executed.
These interaction areas are defined by the IV developer and communicated to the WebWidget. In order to help the IV developer to visually define these areas without having to worry about the exact details of position, rotation, scaling, the WebWidget contains a so-called design mode, which can be activated using the menu at the top right-hand edge of the WebWidget. For more information on the design mode, see the Design Mode section.
Use
Dependencies
- 3dViewer.html
- 3dViewer-directive.js
- libs/draco/*
- dependencies/promise-polyfill.js (for IE 11)
- dependencies/three.min.js
- dependencies/threeDRACOLoader.js
- dependencies/threeGLTFLoader.js
- dependencies/threePointerLockControls.js
- dependencies/threeTransformControls.js
- dependencies/ResizeSensor.js
Message interface
When describing the direction, the WebWidget is divided into its two components. The WebWidget implemented in HTML, which implements the presentation logic and user interaction in the browser and the WebWidget implemented in InstantView, which supplies the other side with the data from ClassiX and controls it.
Name | Parameters | Description |
---|---|---|
Push News (IV→HTML) | ||
settings | Settings | This message passes a Settings object as CX_JSON_OBJECT to the WebWidget, thereby configuring the settings of the viewer. This message can be sent as often as you like and is complementary to previous settings messages. |
load_design | Design | This message passes a design object to the Web widget as CX_JSON_OBJECT, thus defining the interaction areas and camera positions. |
load_scene | String | This message passes a path of a glTF file as a string to the WebWidget to be loaded into the viewer. |
set_position | String | Position | This message transfers a camera position to the WebWidget, specified by the name of a camera position saved in the design or by directly specifying the coordinates or rotation angle as CX_JSON_OBJECT of the following format: {x: x-coordinate, y: y-coordinate, z: z-coordinate, rx: rotation angle to x-axis, ry: rotation angle to y-axis, rz: rotation angle to z-axis} The coordinates are in distance units and the rotation angles in radians. Individual coordinates or angles of rotation can also be specified. |
Events (HTML→IV) | ||
INITIALIZE_SOCKET | - | The first message that the WebWidget sends once it has initialised. This indicates that the WebWidget is ready to receive and process push messages. |
SAVE_DESIGN_SOCKET | Design | This message transmits the interaction areas and camera positions defined in the design mode as a JSON string to the executed ClassiX instance, where it can be saved for later use. |
MOUSE_CLICK_SOCKET | String | This message is sent when the user clicks on an interaction area defined in the design. The ID of the area is sent as a string parameter. |
The Settings object
Field | Type | Default value | Description |
---|---|---|---|
allowDesignMode | Boolean | FALSE | Allows you to activate the design mode using the widget menu in the upper right corner. This should not be set to TRUE in productive use, so that the user does not change the default design. Warning: Since the WebWidget is based on JavaScript, manipulating the source code in the browser may cause the user to enter design mode despite this setting. Although this client-side manipulation is not very easy, the IV developer must ensure that the user is authorised to change the design when processing the SAVE_DESIGN_SOCKET message. |
stepSize | CX_NUMERIC | 0.1 | The step length of the navigation movement with the arrow keys. The specification is in the distance unit of the scene. |
camFov | CX_INTEGER | 45 | The angle of view of the camera in degrees. This value is limited between 0° and 90°. |
camNear | CX_NUMERIC | String | Car. | Distance of the front cut plane of the perspective camera. (see frustration) Either an absolute value in the distance unit of the scene or the string 'auto' for auto-adjustment must be entered. An inappropriate value could cause the scene to be partially or completely hidden. |
camFar | CX_NUMERIC | String | Car. | Distance of the rear cut plane of the perspective camera. (see frustration) Either an absolute value in the distance unit of the scene or the string 'auto' for auto-adjustment must be entered. An inappropriate value could cause the scene to be partially or completely hidden. |
exposure | CX_NUMERIC | 1.8 | The lighting value of the scene. |
gammaOutput | Boolean | TRUE | Enables or disables gamma correction of scene images. |
gammaFactor | CX_NUMERIC | 2.2 | If gamma correction is enabled, this setting specifies the size of the gamma exponent (γ) used for correction. |
cubeBorderColor | CX_INTEGER | 0x000000 | The edge colour of the interaction areas in design mode. |
cubeBorderWidth | CX_INTEGER | 4 | The width in pixels of the edges of the interaction areas in Design Mode. |
cubeEdgeLength | CX_NUMERIC | 1 | The edge length of the interaction areas when they are created in design mode (in distance unit of the scene) |
cubeFaceColor | CX_INTEGER | 0x00ff00 | The colour of the interaction areas in design mode. |
selectedCubeBorderColor | CX_INTEGER | 0xff0000 | The colour of the edges of the selected interaction areas in the design mode. |
The design object
Field | Type | Description |
---|---|---|
regions | ARRAY (Region) | The number of interaction areas in this design |
points | ARRAY (Point) | The number of saved camera positions in this design |
The Region object
Field | Type | Description |
---|---|---|
id | String | Number | The unique ID of the interaction area |
position | ARRAY(CX_NUMERIC) | The position of the centre of the cuboid interaction area in distance unit of the scene as a three-element array (x,y,z) |
rotation | ARRAY(CX_NUMERIC) | The rotation angles of the cuboid interaction area around the three spatial axes in radians as a three-element array (rx, ry, rz) |
scale | ARRAY(CX_NUMERIC) | The scaling factors of the cuboid interaction area in all three spatial directions as a three-element array (sx, sy, sz) |
The point object
Field | Type | Description |
---|---|---|
id | String | Number | The unique ID of the camera position |
position | ARRAY(CX_NUMERIC) | The spatial coordinates of the camera position in unit distance of the scene as a three-element array (x,y,z). |
rotation | ARRAY(CX_NUMERIC) | The rotation of the camera around the three spatial axes in radians as a three-element array (rx, ry, rz). |
The distance unit of a scene
All distances in this widget are unitless or in the "distance unit" of the loaded scene. There is no universal correspondence between distance units of a scene and other distance units, be it pixels, meters, points, etc. The same object from different scenes can appear on the screen in the same size but have a thousand times the difference in the scene unit. In a space of small distance units one must therefore select a slightly larger step length in order not to lapse into rigidity when navigating. Conversely, the same applies to rooms with large distance units.
design mode
In Design Mode, the InstantView developer can visually define and edit areas and camera positions that can later be referenced in the InstantView code and with which the user can interact in the 3D viewer. You can start the design mode by clicking on "Start Design Mode" in the menu at the top right. The interaction areas appear as cuboids and a toolbar is displayed. The following table explains all toolbar icons:
Symbol | Declaration |
---|---|
Exit design mode. The changes are not discarded. You can start and stop the design mode at any time to test if you can interact with the defined regions as desired. | |
Save design. Saves the defined design as a design object and sends it to the running ClassiX instance via the message SAVE_DESIGN_SOCKET | |
Adding an interaction area or camera position When you click on this button, a drop-down menu with two entries appears:
| |
Rename interaction area/camera position With this button you can change or display the unique ID of the selected interaction area or camera position. | |
Delete interaction area/camera position Use this button to delete the selected interaction area or camera position. | |
Move area This button displays a coordinate system around the selected interaction area, which can be used to move the interaction area in translation. | |
enlarge/reduce area This button displays a coordinate system around the selected interaction area, which can be used to enlarge or reduce the interaction area. | |
Rotate area This button displays a coordinate system around the selected interaction area, which can be used to rotate the interaction area. | |
Selecting saved positions If the design contains saved camera positions, this button is activated and a list of saved camera positions appears when clicked. When a menu item is clicked, the corresponding camera position is selected and navigated to. | |
Show or hide collision beams This button shows or hides the collision beams and collision points. The lines help to visualise how the WebWidget recognises the boundaries of the objects when navigating. This function is purely informative and serves only as an aid. | |
Show or hide camera visualisation This button shows or hides the visualisation of the camera. This allows you to see the exact target direction of the camera. This function is purely informative and serves only as an aid. | |
Switch permeability This button switches collision detection on or off. When collision detection is switched on, you cannot leave a closed room. Sometimes in design mode it is necessary to navigate through obstacles. This function only serves as an aid in the design mode. | |
Positioning the camera This button opens a dialog where you can enter the desired coordinates and rotation angle of the camera, if number-based navigation in the design mode is desired. | |
Camera position and scene dimensions To determine various distance-relevant parameters, it is necessary to know the scene dimensions or the current camera position or angle of rotation. This information is displayed on the right side of the toolbar. Here the distances are in the distance unit of the loaded scene. |