From Immersive Visualization Lab Wiki
Jump to: navigation, search

Catalyst Project: Preserving At-Risk Cultural Heritage in the Digital Age

Software Configuration

The Unity application can be configured through configuration files. We decided to use the JSON format for them, because it is human-readable so that we can edit the files with a simple text editor. The two main configuration files are in the Config_Files folder: cave_settings.json and screen_config.txt. cave_settings.json controls three basic aspects of the application: the location of the site configuration file, whether the system should run in 3D or 2D mode, and how quickly the system should start up. screen_config.txt controls the configuration of the CAVEkiosk’s displays. The names and locations of these files should not be changed, or the application won’t be able to find them. They are referred to by a path in the application, and removing one without replacing it can break the application.

cave_settings.json. This file defines the following parameters:

  • “pathToDataJSONFile”: The path to the site configuration file. This defaults to the UCSD NFS mount point and should not be changed unless you want to point to local data only.
  • “runIn3D”: Determines if the application will display in 3D or 2D.
  • “loadAllDataOnStart”: When true, the application will attempt to load the data for all sites upon launch. This can take a long time, but it will greatly reduce site load times after finishing.

screen_config.txt. This file is formatted like an XML file. The provided screen_config is set up for a six-screen CAVEkiosk system. For different screen configurations there are two sections that need to be edited:

<ViewerPosition>, inside the <GLOBAL> tag: ViewerPosition has x, y, and z attributes, which determine the default position of the camera in world space. The Earth object is located at <0,0,0> and has a radius of about 120 units, so the default ViewerPosition is <0,0,-400>

<Screen>, inside <ScreenConfig>: Each <Screen> tag defines a screen that will be rendered to by the application.

  • height: The height of the screen.
  • width: The width of the screen.
  • originX: The screen's distance from the camera on the camera's X axis (left/right).
  • originY: The screen's distance from the camera on the camera's Z axis (forward/back). This should be greater than 1000 as otherwise the planes that are being rendered onto will be visible in the application.
  • originZ: The screen's distance from the camera on the camera's Y axis (up/down).
  • h: The horizontal rotation of the screen compared to the camera (in degrees).
  • r: The rotation of the screen about its Z axis. This should always be 0 or 180 for landscape mode, or 90 or -90 for portrait mode.
  • p/comment/name: You can safely ignore these attributes, although comment/name can be helpful for organization purposes.

It is possible to create a custom site configuration file instead of using the one on the server. A site with a point cloud (or set of point clouds) should look like the following:

"description": "", 
"latitude": "32.82421110161336", 
"longitude": "-117.158203125", 
"name": "name of site", 
"models": [
"filePath": "filepath.ply",
"description": "", 
"id": 121, 
"name": "name of point cloud",
"customData": "{\"modelType\":\"ply\"}"

The customData field is especially important, as the \"modelType\":\"ply\" section is what indicates to the application that the file is a point cloud and should be displayed as such.

Local JSON Settings. The new customData field in site elements (models, panos) stores another JSON object in string form. However, often these custom attributes (splines, translation, and audio) are often unique to the local machine. If you wish to change one of these settings locally you can do so without having to change everything else to be local as well. Inside of the file cave_settings.json, there is a line "pathToCustomOverrideFile": "./Config_Files/overrides.json", which specifies the file that will be used for local overrides. This file has a list of elements, each having a name (which matches the name of a site element in the data JSON file) and a custom object, which defines what settings to override.

The images for the Unity application are multi-page TIFF cube maps exported from our data storage system, plus a JSON configuration file containing metadata, for example a name or a description, for the panoramas. There should be six pages per file - one for each face of a cube. The Unity application reads the JSON file and loads the cube maps and metadata dynamically, only when needed. There are variants at 4096 x 4096 pixels per face and 1024 x 1024 pixels per face. The cube4096 and cube1024 sections for each entry under panos in the JSON file indicate which files correspond to the left and right views for the two resolution options.

Cached_Data. The Cached_Data folder inside of the project is where processed data will be stored, so that the raw database data only need to be processed once. If this cache folder is cleared, load times for each panorama site will be longer as there will be an additional processing step for the images. When the computer’s harddisk drive is low on storage, this folder can be deliberately cleared to free up space.