Museum VR PlannerUser ManualVersion 1.0December 2017

Table of Contents

1. Installation Requirements 1 Process 1

2. Account Creation and Management Create a new account 1 Log in 1 Validate account 2 Change/reset password 2 Edit details 2 Admins and user roles 3 3. Syncing With the Cloud Syncing data 3 Syncing files 3

4. Server Administration Accessing server 4 Server scripts 4 Server database 4

5. User Interface and Navigation General 4 Top Toolbar 4 Left Panel 5 Right Panel 5 Footer 6 Object Forms 7 Main Menu and Admin Forms 7

6. Editing Exhibits and Versions Navigation 8 Import exhibit 8 Add version 8 Version priority levels 8 Access/edit details 9 Refresh model 9 Scale 9 Starting points 9 Warp colliders 10

7. Editing Layouts Create new layout 10 Open layout 10 Access/edit layout details 10 Add floorplan to layout 11 Add exterior model to layout 12 Add exhibit to layout 12 8. Annotations Create/access annotation threads and markers 12 Viewing annotations 13 Adding or editing annotations 13

9. VR Supported headsets and configuration 14 Entering VR 14 VR navigation 14 Annotations panel 15 Add annotation thread 16 Select annotation thread 16 Add or edit annotations 16 Exiting VR 16 10. Other Considerations File formats 17 Performance considerations 17 Undoing/redoing actions in editor 17 Saving edits 18 Deleting and restoring objects 18 Activity Logs 18

1

1. InstallationRequirements The Museum VR Planner is an application for importing and arranging 3D models of museum exhibitry and 2D floorplans into editable layouts, and enable collaborative review of designs in VR on a 1:1 scale. As such, it requires a higher-end, Windows 7 or 10 PC, with a minimum requirements of an i5 CPU, NVIDIA 970 graphics card (or higher), 8 GB DDR4 RAM, and preference for an SSD. For VR, it requires an Oculus Rift headset and Touch controllers. Additionally, an internet connection is required for user authentication before entering the application, as well as for syncing data to and from the server.

ProcessThe Museum VR Planner is a portable application, so it need only be unzipped into whatever location (typically ‘Program Files’) you prefer. Shortcuts can be added to the desktop, start menu or taskbar by right clicking the .exe’s icon and selecting the appropriate option (Pin to Taskbar, Pin to Start, or Send To > Desktop). After running the application, a local database storing all exhibitry, annotations and layout information will be created under “C:\User\[your user name]\AppData\LocalLow\CapstoneProject\Muse-umVRPlanner,” as well as folders for holding 3D models and 2D floorplans (in this same location).

2. Account Creation and ManagementCreate New AccountThe initial admin account for your instance of the Museum VR Planner will be created by the developer, and login information provided. Admins may make additional user accounts.

Log InTo log in to the application, you will need an internet connection. Enter the user name and password pro-vided by your admin and hit “Log In.” If this is your first attempt, you will begin the account and IP valida-tion process.

Log In Form

2

Validate AccountWhen you first attempt to log in, your account and the IP address you are working from will need to be validated; you will receive an e-mail with a validation link, which will activate your account and grant you access. If you do not receive an e-mail, be sure to check your junk folder, and if not there, contact a server admin or the developer.

Change/Rest PasswordOnce you are logged in for the first time, open the menu (top left of screen), select “Edit Profile”, and update your password. You may use this option at any time to change your password. If you forget your password, you may use the “Reset Password” option on the login screen to receive an e-mail for generating a new temporary password. You may also save your password at the login screen so you do not have to reenter it each time (provided you are operating from the same machine).

Edit DetailsTo make changes to other account details, such as username and e-mail address, again select “Edit Profile” from the main menu, update your information, and hit “Submit”.

Edit Account Details Form

Reset Password Form

3

Admins and User RolesThe Museum VR Planner has a hierarchy of user roles: Viewers may view any content within the appli-cation, but make no changes; Annotators may view any content and add annotation markers with notes throughout the exhibits; Editors may view any content and add annotation markers with notes, as well as create and edit new exhibits and layouts; and Admins may perform all functions, as well as have access to activity logs, the trash bin (to restore or permanently delete trashed items), and create/manage additional admin or user accounts. Items may only be trashed by their original creator or an admin. Notes and their markers may only be edited by their original creator.

Delete AccountsAccounts may be deleted on request to an admin or the developer.

3. Syncing With the CloudSyncing DataIf an internet connection is available, the local database may be synced with the application’s cloud data-base by clicking the “Sync With Cloud” button at the top left of the screen. Once complete, all locally gen-erated data should be mirrored on the cloud server for syncing with other client instances, and any data on the cloud generated by other uses will be mirrored to the local database. In the instance of conflicting updates (e.g. an exhibit’s description altered by two different users before syncing to the cloud), duplicate entries will be created which the users may then review and delete or retain as appropriate.

Syncing FilesOnce the databases have been synced (which must be completed before continuing work in the applica-

Create Account Form

4

tion), model and floorplan files will be synced between the local installation and the cloud server. Since this process can be time consuming, a separate file sync application window will appear to conduct the file transfer in the “background.” The user may continue working in the application while these files are syncing, and placeholders will be displayed in instances when files have not completed transfer. After the transfer is complete, most mod-el and floorplan objects have a “Refresh” icon on their menu item within the application which can be used to import the new files.

4. Server AdministrationAccessing ServerThe cloud-bases scripts and database for user management and data/file syncing are hosted on a server licensed by the museum’s supporting foundation. Access to this server is held by the developer, but can be extended to qualified client personnel if needed. The server is accessed via cPanel front-end, or by way of FTP.

Server ScriptsServer scripts are drawn principally from the LoginPro package for Unity applications, which handle account management operations, encryption and security, and data transfer between the cloud and local instances.

Server DatabaseDesign details regarding the server database can be found in the application’s associated developer docu-mentation, though the server database largely mirrors the local database instance. Administrative access to the server database can be provided by the developer to qualified client personnel as desired (given the server is licensed and maintained by the client’s supporting foundation).

5. User Interface and NavigationGeneralNavigation and interaction with the application is conducted primarily with a standard mouse and key-board. VR navigation and interactions are detailed in the VR section.

Top ToolbarThe top toolbar provides most of the administrative and editor tools. From left to right are: main menu button (menu detailed in its own section); help button (providing a quick reference for controls and panel functions); sync button (typically performed at login and before logging out); undo/redo button for editor window actions (placement, scale and rotation, in particular); object manipulation tools (position, rota-

Sync Button

5

tion, scale, and a toggle for making edits in relation to the object’s orientation or the global orientation); and the deletion button. Additionally, on the far right side of the top toolbar is an indication of the current FPS (frames per second), which helps with gauging the performance impact of imported models, and a toggle for activating/deactivating the VR headset (when activated, two additional buttons appear allowing for toggling between the Oculus headset and a VR ‘sim’ for those without a headset).

Left Panel (Layouts and Exhibits) The left panel houses many of the controls and information panels for layout objects.

The top block, “Standard Objects,” features a window with common “drag and drop” objects for placing annotation markers, warp colliders (for teleporting in VR), and a starting position (when entering VR). Each of these items are paired to a single version of a single exhibit; each exhibit version will house its own collection of these items. More details under the sections on “Editing Exhibits and Versions,” “Annotations”, and “VR.”

Standard Objects Window

Top Toolbar

General Editing Window

6

The center block, “Exhibits,” displays a list of all exhibits in the application’s database, as well as a button for importing new exhibits. Once an exhibit is selected, an information card appears with more options (detailed in “Editing Ex-hibits and Versions”), as well as a list of all versions of the exhibit, and the annotation threads list in the right panel (detailed below) populates with all threads associated with the selected exhibit. A scaling window is also associated with this panel, detailed in the section on “Editing Exhibits and Versions.”

The lower block, “Layouts,” displays a list of layouts that have been created, as well as a button for creating new layouts. Once a layout is selected, an information card ap-pears with more options (detailed in “Editing Layouts”), as well as a list of all floorplans associated with the layout and an info card on its exterior model.

Right Panel (Annotations) The right panel houses many of the controls and panels associated with browsing and editing annotations and their parent threads.

The top block, “Annotation Threads,” displays a list of all threads created for a selected exhibit or exhibit version, each of which is associated with a marker placed within the actual version model.

The lower block, “Annotations,” displays a list of all annotations associated with the selected thread, as well as options for editing/deleting annotations, or creating new posts. More details in the section on “Annotations.”

Footer The footer bar includes buttons for cycling through any versions associated with the currently selected and loaded exhibit, as well as a “Save” button for ensuring object positions are stored (typically not necessary however, as this information is periodically auto-saved or auto-saved when a new version, exhibit or layout is opened).

Footer

Right Panel (top: Annotation Threads, bottom: Annotations)

Layouts (left panel)

Exhibits (left panel)

7

Object FormsSeveral forms will be displayed when appropriate to create/edit an exhibit, create/edit an exhibit version, create/edit a layout, create/edit a floorplan, or create/edit a layout’s exterior model.

Main Menu and Administrative Forms The main menu includes options for linking to the online documenta-tion; viewing items in the trash bin (if an admin); viewing activity logs (if an admin); editing your profile; managing user accounts (if an admin); logging out; or exiting the program. The menu also displays the current user’s details, including role, username, and e-mail address.

6. Editing Exhibits and VersionsNavigationNavigating and adjusting orientation within the 3D editor window is conducted with mouse and keyboard. Moving within the 3D “world” is done with W,S,A, and D to move forward, backward, slide left, and slide right (respectively). E and Q move the view up and down, respectively. Holding shift makes these motions faster. Holding the right mouse button and moving the mouse rotates the view left and right, up and down. A 3D “gizmo” is also provided at the top right of the editor window which can be used to help guage and adjust orientation, as well as switch between perspective and orthographic views. 3D Orientation Gizmo

Sample Object Form (Add Version)

Main Menu

8

Import ExhibitTo create a new exhibit, click the “Import New Exhibit” button in the left panel, which will bring up a form to define the new exhibit’s name and a short description. Once completed, clicking the “Next” button will take you to the form for adding a new version to this exhibit. You can skip this step at first if desired (just defining the exhibit), and you will see the new exhibit appear in the alphabetical listing in the left panel.

Add VersionThe form to add a new version to an exhibit will appear automatically after creating a new exhibit, or you may select the “Add New Version” button on the versions listing panel. In this form, you will set a name and short description for the version; set its priority level; and select the model file to be imported (more details on file format in the section on “Other Considerations”). When complete, click the “Finish” button, and the selected model will begin loading into the editor window.

Version Priority LevelsEach exhibit version must have a priority level ranging from 1 to 5, with 1 being the highest priority and with no gaps in between (i.e. if there are only three ver-sions, they are 1, 2, and 3, with 3 being the lowest priority). The highest prior-ity version (1) will automatically load whenever the exhibit is selected without another version defined, or is loaded into a layout. The version can be cycled through using the “Previous Version” and “Next Version” buttons in the footer, or by selecting a particular version in the version listing panel. Priorities can also be set in this panel by clicking the blue triangles up or down.

Open Exhibit/VersionOnce created, exhibits are listed alphabetically in the left panel. When selected, the exhibit’s listing entry is highlighted blue and its information card is opened, along with a listing of its versions (in order of priority) and its associated annotation threads (in the right panel). To view an exhibit, select the “View/Edit” option on its info card, or the “Load” option on a particular version’s listing. An opened exhibit and its currently ren-dered version are indicated by a green outline around their respective listings. All objects added to the scene (i.e. starting points, warp colliders and annotation markers), will be attached to this version.

Exhibit info (left to right: exhibit listing, exhibit info card, version listing)

Version Priority

9

Access/Edit DetailsExhibit and version details can be edited at any time by selecting the respective “Edit Details” option on either the exhibit’s information card or the version’s listing entry.

Refresh ModelA version’s model can be refreshed without restarting the application (particularly after completion of a syncing operation), by clicking the refresh icon in the version’s listing entry.

ScaleGiven the necessity for an exhibit to display in VR on a 1:1 scale, a special scaling tool has been imple-mented, which can be accessed by clicking the “Scale” button on the exhibit’s info card. This window pro-vides an orthographic top-down view of the exhibit, with UI buttons for moving the camera, zooming in/out, and scaling the exhibit up or down.

Each model that is imported into the Museum VR Planner should ideally have a scale reference pre-incor-porated when it is being designed in Sketchup (or any other editing software), preferably representing 10’ or 20’ in length. This reference can be lined up with the application’s scale bar in the scaling window, and once matched, the exhibit will be correctly displayed in VR at a 1:1 scale.

Note that this scale affects all exhibit version models equally, as it is assumed each version model will be developed at the same scale before being imported into the application.

Starting Points A starting point for setting the viewer’s location in an exhibit version when entering VR can be set by dragging and dropping a starting point object from the top left window on the “Layouts and Exhibits” pan-el. This staring point can be selected (indicated by the starting point receiving a green outline) by clicking on it near its centerpoint, and positioned anywhere within the model (using the position tool selected at the top toolbar), or rotated around the Y axis (using the rotation tool selected at the top toolbar). It cannot be scaled. Starting points are not rendered in VR.

Scaling Tool

10

Warp Colliders Warp colliders are flat planes used as targets for teleporting in VR. They can be placed by dragging and dropping a warp collider object from the top left window on the “Layouts and Exhibits” panel. Warp col-liders can be selected (indicated by a green outline) by clicking on them near their centerpoint , and can be positioned anywhere within the model (using the position tool selected at the top toolbar), scaled in X or Z axis (using the scale tool selected at the top toolbar) but not Y (as they are always flat), or rotated around the Y axis (using the rotation tool selected at the top toolbar). The warp collider will not be rendered in VR, but when the VR teleportation pointer is activated, the pointer will turn green whenever in contact with a warp collider, allowing the viewer to teleport to that location. Warp colliders are also not rendered when a layout is loaded, for the sake of clarity (they are pri-marily to be edited when viewing an exhibit as a standalone).

7. Editing LayoutsCreate New LayoutTo create a new layout, click the “Create New Layout” button on the lower left panel, which will open the new layout form. Much like an exhibit, you will define a name and short description, but once you fin-ish these basic details and submit the form, you will be returned to the editor window with the layout “opened.” Open LayoutA layout is opened after its creation or by clicking the “Open Layout” button on the layout’s info card. Even if the layout is empty, the fact that it is opened can be determined by the green outline around the layout listing and info card.

Access/Edit Layout DetailsA layout’s name and description may be edited at any time by clicking the “Edit Details” button on the

Warp ColliderStarting Point

11

layout’s info card. This will bring up its editing form, which you can use to update and submit its details.

Add Floorplan to LayoutA 2D floorplan can be added to a layout by selecting the “Add Floorplan” option on the floorplans listing panel (if this panel is closed, it can be opened by selected the “Floorplans” option on the layout’s info card). Give the floorplan a name and short description, then select its file (either jpeg or png). It is preferable to keep floorplan files under 1 megabyte in size, and all floorplans are rendered on a square plane, so the image should be pre-formated with this in mind (preferably at a resolution of 1024x1024 or 2048x2048). Floorplans can be selected (indicated by a faint green outline, better seen on their underside) by clicking on them near their centerpoint, and can positioned anywhere within the layout (using the position tool se-lected at the top toolbar), or rotated around the Y axis (using the rotation tool selected at the top toolbar). Due to the requirements of VR, a floorplan must be scaled using the same tool as exhibits (activated by clicking the “Scale Floorplan” button on the floorplan’s listing), providing a top-down orthographic view and scale reference (as with exhibit models, the floorplan image should include a pre-set scale reference, preferably representing a 10’’ or 20’ length). A floorplan can also be locked in place by clicking the lock icon on its listing, and can be hidden by click-ing the hide (eye) icon on its listing.

Floorplans

Layout Info (left to right: layout list, layout info card, floorplans list, exterior model info card)

12

Add Exterior Model to LayoutA 3D model representing the museum’s exterior facade and outlying landscape can be added by selecting the “Exterior Model” option on the layout’s info card. If an exterior model has not been added, this will open a form where the exterior model’s name, a short description, and file can be set. If an exterior model has already been attached (only one per layout), its info card will appear in line with the floorplan listing panel.Exterior models are loaded into a scene locked in place, but may be unlocked by hitting the lock icon on the exterior model’s info card. It may then be selected and positioned or rotated in the same manner as floorplans, and will also be scaled using the special scaling window (activated by clicking the “Scale” but-ton on the exterior model’s info card). Exterior models can also be hidden by clicking the hide (eye) icon on its info card, to facilitate easier layout of exhibits.

Add Exhibit to LayoutWith a layout opened, exhibits can be added to the layout by selecting the “Add to Layout” option on the exhibit’s info card. This will load the exhibit into the layout, where it can be selected (indicated by a green outline) either by clicking on the exhibit near its centerpoint or clicking its listing in the left panel, and then positioned or rotated in the same manner as the object detailed above, typically with reference to an the underlying floorplan.

8. AnnotationsCreate/Access Annotation Threads and MarkersWhen an exhibit or one of its versions is selected, its corresponding annotation threads will be displayed in the upper right panel. To add a new annotation thread, an annotation marker must either be drag and

Exterior Model

13

dropped from the object window in the upper left panel, or instantiated in VR (detailed in the next sec-tion). Once a marker has been created, it can be selected (indicated by a green outline) and positioned or rotated using the tools on the top toolbar the same as the objects previously described. Markers cannot be scaled. When a marker is created, an associated thread is created automatically, and a form opened next to the lower right panel for creating its first annotation. A marker’s associated thread will appear in the upper right panel. This thread listing will include an option to “Jump to Marker,” focusing the view on the marker (wherever it may be in the model), and loading its associated version (if it is not currently).

Viewing AnnotationsAn annotation thread’s listing will include a option to “Read” its associated annotations. Once selected, these annotation will appear in a list on the lower right panel, with posting details (username and date/time of positing) and its text.

Adding or Editing AnnotationsAn annotation can be added to a selected thread by clicking the “Reply to Thread” button on the lower right panel. This will open the annotation creation/editing form, which can also be opened to edit an existing annotation (by the user which created the annotation) by selecting the “Edit” option at the top of the annotation posting.

Annotation Panel

Annotation Marker (light blue)

14

The annotation creation/editing form is principally composed of a large text area for typing a new anno-tation, which can be submitted by clicking the “Post” button. A subject line also appears at the top, which can be edited by the creator of the annotation thread.

9. VRSupported Headsets and Configuration Currently the Museum VR Planner only supports the Oculus Rift VR headset and Oculus Touch control-lers. Details on the Oculus Rift hardware and setup can be found on the Rift website: https://www.oculus.com/ . Additionally, a VR “sim” is included in the application, as a reference for users without a VR head-set. The sim’s functionality is limited to basic VR navigation (keyboard interaction and annotation marker creation are not possible in the simulator).

Entering VRTo enter VR, load an exhibit or select an exhibit loaded into a layout, then click the “Activate VR” button in the top right toolbar. This will launch the Oculus application, and the Rift headset can be put on to begin experiencing the environment in VR.

VR NavigationWhen in VR, the user needs to use both Oculus Touch controllers (left and right hand). The right hand controller provides all navigation and interaction functions. To navigate, click and hold the thumbstick on the right controller to bring up a “laser pointer”; this pointer will be red if it does not contact a warp col-lider surface, and will turn green if it does contact a surface that can be teleported to (a small green sphere will appear at the actual target location). Release the thumbstick to teleport.

VR Simulator

15

Additionally, selecting the “Jump to Marker” option on the annotations panel will teleport to the selected annotation marker.

Annotations PanelThe VR annotations panel appears over the left Touch controller. This panel is composed of a top bar, used to focus a particular exhibit (to which new annotation markers will be attached) as well as cycle exhibit versions while in VR; a left panel including a list of annotation threads (mirroring that on the desktop’s right panel) and a list of annotations (likewise mirroring that on the desktop’s right panel); and a right panel including a VR keyboard and form for entering/editing annotations while in VR.

VR Annotations Panel

VR Teleportation Pointer (no target) VR Teleportation Pointer (valid target)

16

Add Annotation ThreadTo create an annotation thread in VR, click and hold the right Touch controller’s trigger until an annota-tion marker appears in your hand. You may then push the right Touch controller’s thumbstick forward or backward to move the marker toward or away from yourself, and when in the desired position, release the thumbstick to place the marker and generate an associated annotation thread. Note that this marker will belong to whichever exhibit is indicated in the left section of the annotations panel, regardless of user location within the model. Be sure that the appropriate exhibit is selected and version loaded before placing a new marker.

Select Annotation ThreadFrom the annotation panel, an annotation thread’s annotations can be listed, or its marker jumped to, by selecting the appropriate option. This is done by holding the grip button on the right Touch controller, which will bring up a blue interaction pointer. While holding the grip button, place the pointer over the desired option, or over the desired marker in the environment, and click the controller’s trigger to make a selection.

Add or Edit AnnotationsAnnotations can be added or edited in VR by selecting the “Reply to Thread” or “Edit” options the same as on the desktop display. The VR keyboard can be typed using the blue interaction pointer by holding down the right Touch controller’s grip button and then clicking the right Touch controllers trigger when over the desired key. Haptic feedback is also provided.

Exiting VRTo exit VR, remove the headset and click the “Deactivate VR” button in the top right of the top toolbar.

VR Annotation Marker

17

10. Other ConsiderationsFile Formats Currently the Museum VR Planner only supports Collada (.dae) files, as these are the standard export format from Google Sketchup. Each Collada model should consist of a model file (.dae) and a folder of the same name containing all textures (which should all be of jpeg or png format and under 1 megabyte, typically with a square resolution of 1024x1024 or 2048x2048). The application also only supports simple diffuse textures at this point, and transparent textures are treated as “cutouts” (meaning opacity is a hard 1 or 0, with no range of transparency in between). For floorplans, the preferred formats are the same as those for other textures (jpeg or png, under 1 meg, 1024x1024 or 2048x2048).

Performance ConsiderationsModels with high polygon counts can have a significant impact on performance, especially when several mod-els are loaded in a layout or when using VR. Polygon counts for any one version should ideally be kept under 250,000. When a version model is loaded, its polygon count is provided on its listing entry, as a reference.

Texture size also has a significant impact, and texture files should ideally be kept under 1 megabyte a piece. The entire texture folder for any particular version should be kept under 10 megs for optimal performance. Alerts regarding texture size will display when a model is loaded, to aid in tracking down oversized files.

Undoing/Redoing Actions in EditorThe undo/redo buttons in the top toolbar are provided to undo/redo editor positioning, rotation and scal-ing actions. Note that you cannot undo edits to an items details (these must be revised in the item’s editing form), nor can you undo item creation or deletion with these; to undo item creation, it must be explicitly deleted, and to undo deletion, an admin must restore the item from the trash bin.

VR Keyboard

18

Saving EditsEdits made to an items details by way of an editing form are saved upon submission. Edits to object posi-tions, rotations or scales are saved automatically every two minutes, or when transitioning from one layout or exhibit/exhibit version to another. A “Save” button is provided as well at the lower right footer, but is principally included as a means of ensuring edits are committed before exiting the application.

Deleting and Restoring Objects Most items are deleted by using the red “Delete” button on their info card or list-ing, however, placeable items (annotation markers, starting points and warp colliders) are deleted by the deletion button in the top toolbar (near the editor tools). Most items can be restored by an admin via the trash bin window (found in the main menu). Note that starting points and warp colliders do not go to the trash bin, but are permanently deleted.

At this time, model and floorplan files that are unlinked (i.e. not representative of any item within the application due to replacement or deletion of their parent content) will remain on the server and in lo-cal storage unless explicitly deleted by the user or an admin. Refined options for file management will be incorporated in a later release.

Activity LogsMost activities conducted in the application are recorded in the activity log, which can be reviewed by admins. The log can also be cleared in its entirety by admins, and will be unrecoverable. In future releases, this func-tionality will be refined to provided easier navigation and a means of exporting logs to a spreadsheet or text file.

Activity Logs Panel

Trash Bin