VES/KiwiViewer Scene File

Introduction

KiwiViewer can load scene files that describe a scene consisting of one or more data files. KiwiViewer v2.0 uses a scene file in the JSON format. KiwiViewer v1.0 for Android used a CSV format. A scene file can be added to a folder with data files and zipped up for KiwiViewer to read.

JSON scene file for KiwiViewer v2.0

KiwiViewer v2.0 is available for iOS in the App Store. An experimental version for Android can be downloaded from the KiwiViewer packages page.

Examples

The best way to get started with kiwi scene files in the JSON format is to look at examples. There are two ways to get examples. You can use the paraview_to_kiwi macro, described in the following section, to automatically create scene files. Or, you can look at the examples that are bundled with the KiwiViewer v2.0 app.

Bundled Examples

KiwiViewer is bundled with sample datasets that demonstrate how to do animations, custom color maps, and textured meshes. The sample datasets that have a .zip file extension will extract into folders that contain data files and a kiwi scene file with the .kiwi file extension. You can download the sample datasets from Midas. The exception is the SPL-PNL Brain Atlas.zip, this dataset does not use a kiwi scene file, it is handled with a custom behavior by the KiwiViewer app.

ParaView Exporter

You can download the paraview_to_kiwi.py python script and add it to ParaView as a python macro. In ParaView, go to the Macros menu and choose Add new macro. Select the paraview_to_kiwi.py script and it will become a macro in ParaView. ParaView macros are accessible from the Macros menu or the Macros toolbar (enable the Macros toolbar using the View menu).

When you run the paraview_to_kiwi macro, the current scene will be exported to a zip file on your desktop. If the export operation fails, you can open the Python Console from the Tools menu, error messages will be displayed in the console. If you are unable to resolve the error, please ask for help on the ParaView User's mailing list.

You can use iTunes file sharing to copy the zip file into KiwiViewer. Or, place the zip file into your Dropbox folder, or upload it to Midas where KiwiViewer can access it.

Finally, if you read the paraview_to_kiwi.py script, you will see that it can be modified to automatically upload the zip file to a Midas server by changing two lines at the bottom of the file. If you make this change, you must also have the pydas package installed. On systems where pip is available (and installs to the same version of python that ParaView uses), this can be accomplished with

 pip install pydas

Otherwise, you can obtain pydas from Github.

Scene file from exported ParaView animation

You can use ParaView to export an animation using the Save Geometry option in the File menu. ParaView will export the animation into a directory, and that directory will contain a subdirectory for each frame of the animation. The subdirectories will contain the data files for each frame of the animation. For this example, we assume that each subdirectory contains just one vtp file. You can open a terminal and cd to the exported animation directory. Running ls */*.vtp should list all the data files. Run python and paste this code into the interactive prompt:

import glob
import json

filenames = glob.glob('*/*.vtp')
object = dict(filenames=filenames)
scene = dict(objects=[object])
open('scene.kiwi', 'w').write(json.dumps(scene, indent=2))

Now you will have a .kiwi scene file inside the exported animation directory. At this point, you can zip the whole directory and open it with KiwiViewer.

Textured mesh

For an example, you can download the NASA Blue Marble. The zip file contains a geometry file (vtp format), an image (jpg format), and a scene file.

$ unzip "NASA Blue Marble.zip"
Archive:  NASA Blue Marble.zip
   creating: nasa-blue-marble/
  inflating: nasa-blue-marble/earth.jpg  
  inflating: nasa-blue-marble/nasa-blue-marble.kiwi  
  inflating: nasa-blue-marble/textured_sphere.vtp  

$ cat nasa-blue-marble/nasa-blue-marble.kiwi 
{
  "objects": [
               {
                 "filename": "textured_sphere.vtp",
                 "texture": "earth.jpg"
               }
             ],
  "camera": {
              "position": [-2,0,0],
              "focal_point": [0,0,0],
              "view_up": [0,0,1]
            }
}

Note that that data files can be stored in sub directories. Filenames in the scene file can be recorded with relative paths to the data files.

You need to have a geometry file that has texture coordinates. The best way to do this is to open your data file in ParaView and confirm that it has a texture coordinates array. You can apply a texture to the data in ParaView using the Texture display property in the Display settings. This way, you can verify in ParaView that your data and texture coordinates are correct.

Old style Kiwi CSV scene file for KiwiViewer v1.0

KiwiViewer v1.0 for Android supports a scene file that uses a simple comma-separated-value format. This format is not used in newer versions of KiwiViewer, it has been replaced with the JSON format scene file described above.

File extension

The scene description file extension should be .kiwi.

Separators

Each field should be separated by a comma without leading or trailing spaces. Fields are not quoted.

Headers

The first row of the file contains text column headers, separated by comma. The order of the columns does not matter. The file may contain extra columns, they will be ignored. The only required header is filename. The available headers are: filename, url, r, g, b, a. The r, g, b columns specify the dataset color. The a column specifies alpha (transparency). Color and alpha are specified using decimal numbers between 0.0 and 1.0. If color is not specified, it will default to white. If alpha is not specified, it defaults to 1.

Example Files

This file specifies two datasets:

filename
foo.vtk
bar.vtk

This file specifies two datasets. The datasets will be downloaded from URLs and saved to local storage.

filename,url
foo.vtk,http://example.com/foo.vtk
bar.vtk,http://example.com/bar.vtk

This file specifies one dataset that will be green and translucent.

filename,r,g,b,a
foo.vtk,0,1,0,0.5

Specifying a URL

You can specify a url column to download datasets. The file must still have the filename column. The dataset will be downloaded from the URL and saved to local storage using the value specified in the filename column. If the scene file is loaded again in the future, and the file still exists on local storage, it will not be downloaded again.

Specifying a filename

The filename specified is relative to the .kiwi scene file. For example, loading the scene file /sdcard/Documents/test.kiwi that specifies a filename models/foo.vtk will open the file /sdcard/Documents/models/foo.vtk. If a dataset is downloaded from a URL and saved to local storage, subdirectories will be created if they are specified in the filename field.