3D-Viewer (WebWidget)
Der 3D-Viewer ist ein auf der Technologie WebGL basierendes WebWidget, der beliebige 3D-Modelle im glTF-Format anzeigt und dem Benutzer erlaubt, mit diesen Modellen zu interagieren. Das WebWidget bietet eine einfache Navigation mit den Pfeiltasten und der Maus aus der Egoperspektive (first-person perspective, FPP) an und erkennt Kollisionen mittels einfachen Raycastings. Dabei dienen die Pfeiltasten der horizontalen Bewegung nach vorne, hinten, rechts und links. Wenn man seine vertikale Position ändern möchte, muss man die STRG-Taste gedrückt halten und gleichzeitig eine der Pfeiltasten "oben" oder "unten" verwenden. Mit der Maus kann man die Drehrichtung der Kamera festlegen. Eine gleichzeitige Dreh- (mit der Maus) und translatorische Bewegung (mit den Pfeiltasten) ist im Moment nicht möglich. |
(Das demonstrativ angezeigte Modell in diesem Screenshot unterliegt der CC Lizenz und ist ein Kunstwerk von Francesco Coldesina) |
Desweiteren besteht die Interaktion des Benutzers mit dem Modell nur durch das Anklicken von 3D-Bereichen im Modell. Beim Anklicken eines sogeannten Interaktionsbereichs wird eine IV-Nachricht mit der ID des Bereichs geschickt, woraufhin beliebige InstantView-Anweisungen ausgeführt werden können.
Diese Interaktionsbereiche werden vom IV-Entwickler festgelegt und dem WebWidget mitgeteilt. Um dem IV-Entwickler dabei zu helfen, diese Bereiche visuell zu bestimmen, ohne sich um die genauen Angaben der Position, Rotation, Skalierung zu kümmern, enthält das WebWidget einen sogenannten Design-Modus, der mittels des Menüs am oberen rechten Rand des WebWidget aktiviert werden kann. Weitere Erklärungen zum Design-Modus finden Sie unter dem Abschnitt Design-Modus.
Verwendung
Abhängigkeiten
- 3dViewer.html
- 3dViewer-directive.js
- libs/draco/*
- dependencies/promise-polyfill.js (für IE 11)
- dependencies/three.min.js
- dependencies/threeDRACOLoader.js
- dependencies/threeGLTFLoader.js
- dependencies/threePointerLockControls.js
- dependencies/threeTransformControls.js
- dependencies/ResizeSensor.js
Nachrichtenschnittstelle
Bei der Richtungsbeschreibung wird das WebWidget in seine zwei Komponenten unterteilt. Das in HTML implementierte WebWidget, welches die Darstellungslogik und Nutzerinteraktion im Browser implementiert und das in InstantView implementierte WebWidget, welches die andere Seite mit den Daten aus ClassiX versorgt und es steuert.
Name | Parameter | Beschreibung |
---|---|---|
Push-Nachrichten (IV→HTML) | ||
settings | Settings | Diese Nachricht übergibt ein Settings-Objekt als CX_JSON_OBJECT ans WebWidget und konfiguriert damit die Einstellungen des Viewers. Diese Nachricht kann beliebig oft geschickt werden und ist komplimentär zu früheren Settings-Nachrichten. |
load_design | Design | Diese Nachricht übergibt ein Design-Objekt als CX_JSON_OBJECT ans WebWidget und legt somit die Interaktionsbereiche und die Kamerapositionen fest. |
load_scene | String | Diese Nachricht übergibt einen Pfad einer glTF-Datei als String ans WebWidget, damit sie in den Viewer geladen wird. |
set_position | String | Position |
Diese Nachricht übergibt eine Kameraposition ans WebWidget, festgelegt durch den Namen einer im Design gespeicherten Kameraposition oder durch die direkte Angabe der Koordinaten bzw. der Drehwinkel als CX_JSON_OBJECT des folgenden Formats: {x: x-Koordinate, y: y-Koordinate, z: z-Koordinate, rx: Drehwinkel zur x-Achse, ry: Drehwinkel zur y-Achse, rz: Drehwinkel zur z-Achse} Dabei sind die Koordinaten in Abstandseinheiten und die Drehwinkel in Radian. Dabei können auch einzelne Koordinaten bzw. Drehwinkel angegeben werden. |
Ereignisse (HTML→IV) | ||
INITIALIZE_SOCKET | - | Die erste Nachricht, die das WebWidget schickt, sobald es sich initialisiert hat. Dies signalisiert die Bereitschaft des WebWidgets, Push-Nachrichten zu empfangen und zu verarbeiten. |
SAVE_DESIGN_SOCKET | Design | Diese Nachricht übermittelt die im Design-Modus festgelegten Interaktionsbereiche und Kamerapositionen als JSON-String an die ausgeführte ClassiX-Instanz, wo sie dann für spätere Verwendung gespeichert werden kann. |
MOUSE_CLICK_SOCKET | String |
Diese Nachricht wird geschickt, wenn der Benutzer auf einen im Design definierten Interaktionsbereich klickt. Die ID des Bereich wird als String-Parameter mitgeschickt. |
Das Settings-Objekt
Feld | Typ | Standardwert | Beschreibung |
---|---|---|---|
allowDesignMode | Boolean | FALSE |
Erlaubt die Aktivierung des Design-Modus mittels des Widget-Menüs am oberen rechten Rand. Dies sollte im produktiven Einsatz nicht auf TRUE gesetzt werden, damit der Benutzer das vorgegebene Design nicht ändert. Warnung: Da das WebWidget auf JavaScript basiert, kann der Benutzer durch Manipulation des Quellcodes im Browser den Designmodus trotz dieser Einstellung starten. Wenngleich diese clientseitige Manipulation nicht ganz einfach ist, muss der IV-Entwickler beim Verarbeiten der Nachricht SAVE_DESIGN_SOCKET darauf achten, ob der Benutzer befugt ist, das Design zu ändern. |
stepSize | CX_NUMERIC | 0.1 | Die Schrittlänge der Navigationsbewegung mit den Pfeiltasten. Die Angabe ist im Abstandseinheit der Szene. |
camFov | CX_INTEGER | 45 | Der Bildwinkel der Kamera in Grad. Dieser Wert wird zwischen 0° und 90° beschränkt. |
camNear | CX_NUMERIC | String | 'auto' |
Abstand der vorderen Schnittebene der perspektivischen Kamera. (s. Frustum) Es ist entweder ein absoluter Wert in der Abstandseinheit der Szene anzugeben oder der String 'auto' für die Autojustierung. Ein unpassender Wert könnte dazu führen, die Szene zum Teil oder vollständig ausgeblendet wird. |
camFar | CX_NUMERIC | String | 'auto' |
Abstand der hinteren Schnittebene der perspektivischen Kamera. (s. Frustum) Es ist entweder ein absoluter Wert in der Abstandseinheit der Szene anzugeben oder der String 'auto' für die Autojustierung. Ein unpassender Wert könnte dazu führen, die Szene zum Teil oder vollständig ausgeblendet wird. |
exposure | CX_NUMERIC | 1.8 | Der Lichtwert der Szene. |
gammaOutput | Boolean | TRUE | Aktiviert bzw. Deaktiviert die Gammakorrektur der Szenebilder. |
gammaFactor | CX_NUMERIC | 2.2 | Falls die Gammakorrektur aktiviert ist, gibt diese Einstellung die Größe des Exponenten Gamma (γ), der zur Korrektur verwendet wird. |
cubeBorderColor | CX_INTEGER | 0x000000 | Die Kantenfarbe der Interaktionsbereiche im Designmodus. |
cubeBorderWidth | CX_INTEGER | 4 | Die Breite der Kanten der Interaktionsbereiche im Designmodus in Pixel. |
cubeEdgeLength | CX_NUMERIC | 1 | Die Kantenlänge der Interaktionsbereiche bei deren Erstellung im Designmodus (in Abstandseinheit der Szene) |
cubeFaceColor | CX_INTEGER | 0x00ff00 | Die Farbe der Interaktionsbereiche im Designmodus. |
selectedCubeBorderColor | CX_INTEGER | 0xff0000 | Die Farbe der Kanten der selektierten Interaktionsbereiche im Designmodus. |
Das Design-Objekt
Feld | Typ | Beschreibung |
---|---|---|
regions | ARRAY(Region) | Die Menge der Interaktionsbereiche in diesem Design |
points | ARRAY(Point) | Die Menge der gespeicherten Kamerapositionen in diesem Design |
Das Region-Objekt
Feld | Typ | Beschreibung |
---|---|---|
id | String | Number | Die eindeutige ID des Interaktionsbereichs |
position | ARRAY(CX_NUMERIC) | Die Position des Mittelpunktes des quaderförmigen Interaktionsbereichs in Abstandseinheit der Szene als dreielementiges Array (x,y,z) |
rotation | ARRAY(CX_NUMERIC) | Die Drehwinkel des quaderförmigen Interaktionsbereichs um die drei räumlichen Achsen in Radian als dreielementiges Array (rx, ry, rz) |
scale | ARRAY(CX_NUMERIC) | Die Skalierungsfaktoren des quaderförmigen Interaktionsbereichs in allen drei Raumrichtungen als dreielementiges Array (sx, sy, sz) |
Das Point-Objekt
Feld | Typ | Beschreibung |
---|---|---|
id | String | Number | Die eindeutige ID der Kameraposition |
position | ARRAY(CX_NUMERIC) | Die Raumkoordinaten der Kameraposition in Abstandseinheit der Szene als dreielementiges Array (x,y,z) |
rotation | ARRAY(CX_NUMERIC) | Die Drehung der Kamera um die drei räumlichen Achsen in Radian als dreielementiges Array (rx, ry, rz) |
Die Abstandseinheit einer Szene
Alle Abstandsangaben in diesem Widget sind einheitslos bzw. in der "Abstandseinheit" der geladenen Szene. Es gibt keine allgemeingültige Entsprechung zwischen Abstandseinheiten einer Szene und andere Abstandeinheiten, sei es Pixel, Meter, Punkt, etc. Das ein und dasselbe Objekt aus unterschiedlichen Szenen kann gleichgroß auf dem Bildschirm erscheinen aber eine tausendfache Differenz in der Szeneeinheit haben. In einem Raum von kleinen Abstandseinheiten muss man somit eine etwas größere Schrittlänge auswählen, um nicht in eine Starre beim Navigieren zu verfallen. Umgekehrt gilt es für Räume mit großen Abstandseinheiten.
Design-Modus
Im Design-Modus kann der InstantView-Entwickler Bereiche und Kamerapositionen visuell definieren und bearbeiten, auf die er später im InstantView-Code Bezug nehmen kann und mit denen der Benutzer im 3D-Viewer interagieren kann. Man kann den Design-Modus starten, indem man auf "Designmodus starten" im Menü am oberen rechten Rand klickt. Dabei erscheinen die Interaktionsbereiche als Quader und es wird eine Toolbar eingeblendet. Die folgende Tabelle erklärt alle Symbole der Toolbar:
Symbol | Erklärung |
---|---|
Designmodus beenden. Dabei werden die Änderungen nicht verworfen. Man kann jederzeit den Design Modus wieder starten und beenden, um zu testen, ob man mit den definierten Regionen wie gewünscht interagieren kann. |
|
Design speichern. Speichert das definierte Design als ein Design-Object und schickt es an die laufende ClassiX-Instanz mittels der Nachricht SAVE_DESIGN_SOCKET |
|
Interaktionsbereich bzw. Kameraposition hinzufügen Beim Klicken auf diesen Button erscheint ein Dropdown-Menü mit zwei Einträgen:
|
|
Interaktionsbereich/Kameraposition umbenennen Mit diesem Button kann man die eindeutige ID des ausgewählten Interaktionsbereichs bzw. der ausgewählten Kameraposition ändern oder anzeigen. |
|
Interaktionsbereich/Kameraposition löschen Mit diesem Button kann den ausgewählten Interaktionsbereich bzw. die ausgewählte Kameraposition löschen. |
|
Bereich bewegen Dieser Button blendet ein Koordinatensystem um den ausgewählten Interaktionsbereich ein, mittels dessen man den Interaktionsbereich translatorisch bewegen kann. |
|
Bereich vergrößern/verkleinern Dieser Button blendet ein Koordinatensystem um den ausgewählten Interaktionsbereich ein, mittels dessen man den Interaktionsbereich vergrößern oder verkleinern kann. |
|
Bereich rotieren Dieser Button blendet ein Koordinatensystem um den ausgewählten Interaktionsbereich ein, mittels dessen man den Interaktionsbereich rotieren kann. |
|
Gespeicherte Positionen auswählen Falls das Design gespeicherte Kamerapositionen enthält, wird dieser Button aktiviert und es erscheint bei dessen Anklicken eine Liste der gespeicherten Kamerapositionen. Beim Anklicken eines Menüeintrags wird die entsprechende Kameraposition ausgewählt und zu dieser navigiert. |
|
Kollisionsstrahlen ein- bzw. ausblenden Dieser Button blendet die Kollisionsstrahlen und Kollisionspunkte ein bzw. aus. Die Linien helfen dabei zu visualisieren, wie das WebWidget die Grenzen der Objekte beim Navigieren erkennet. Diese Funktion ist rein informativ und dient nur als Hilfsmittel. |
|
Kamerasvisualisierung ein- bzw. ausblenden Dieser Button blendet die Visualisierung der Kamera ein bzw. aus. Damit kann man die genaue Zielrichtung der Kamera erkennen. Diese Funktion ist rein informativ und dient nur als Hilfsmittel. |
|
Durchlässigkeit umschalten Dieser Button schaltet die Kollisionserkennung ein bzw. aus. Bei eingeschalteter Kollisionserkennung kann man einen geschlossenen Raum nicht verlassen. Manchmal ist es im Designmodus erfoderlich, durch Hindernisse hindurch zu navigieren. Diese Funktion dient nur als Hilfsmittel im Design-Modus. |
|
Kamera positionieren Dieser Button öffnet einen Dialog, worin man die gewünschten Koordinaten und Drehwinkel der Kamera eingeben kann, falls eine zahlenbasierte Navigierung im Designmodus gewünscht ist. |
|
Kameraposition und Szeneabmessungen Zur Bestimmung diverser abstandsrelevanter Parameter ist es notwendig, die Szeneabmessungen oder die aktuelle Kameraposition bzw. Drehwinkel zu kennen. Diese Informationen werden am rechten Rand der Toolbar angezeigt. Dabei sind die Abstände in der Abstandseinheit der geladenen Szene. |