View source for 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 [http://packages.kitware.com/packages/application/view?applicationId=14 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 <b>paraview_to_kiwi</b> 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 <b>animations, custom color maps, and textured meshes</b>.  The sample datasets that have a .zip file extension will extract into folders that contain data files and a kiwi scene file with the <i>.kiwi</i> file extension.  You can download the sample datasets [https://midas3.kitware.com/midas/folder/9479 from Midas].  The exception is the <i>SPL-PNL Brain Atlas.zip</i>, 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 [http://packages.kitware.com/item/3021 paraview_to_kiwi.py] python script and add it to ParaView as a python macro.  In ParaView, go to the <i>Macros</i> menu and choose <i>Add new macro</i>.  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 <i>paraview_to_kiwi</i> 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 <i>Tools</i> 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.  If you read the paraview_to_kiwi.py script.

===Scene file from exported ParaView animation===

You can use ParaView to export an animation using the <i>Save Geometry</i> option in the <i>File</i> 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 <i>vtp</i> file.  You can open a terminal and cd to the exported animation directory.  Running <b>ls */*.vtp</b> should list all the data files.  Run python and paste this code into the interactive prompt:

<pre>
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))
</pre>

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 [https://midas3.kitware.com/midas/item/34767 NASA Blue Marble].  The zip file contains a geometry file (vtp format), an image (jpg format), and a scene file.


<pre>
$ 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]
            }
}
</pre>

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 <b>.kiwi</b>.

===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 <b>filename</b>.  The available headers are: <b>filename, url, r, g, b, a</b>.  The <b>r, g, b</b> columns specify the dataset color.  The <b>a</b> 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:
<pre>
filename
foo.vtk
bar.vtk
</pre>

This file specifies two datasets.  The datasets will be downloaded from URLs and saved to local storage.
<pre>
filename,url
foo.vtk,http://example.com/foo.vtk
bar.vtk,http://example.com/bar.vtk
</pre>

This file specifies one dataset that will be green and translucent.
<pre>
filename,r,g,b,a
foo.vtk,0,1,0,0.5
</pre>

===Specifying a URL===

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

===Specifying a filename===

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