Cinema Simple Database Examples

It’s simple to write a valid Cinema Spec A database from your application, or to write a script that organizes existing files into one. These examples can be modified to suit your needs. Once you have a Cinema database written to disk, download the viewer and you should be able to explore it.

Required elements of a Cinema Spec A database.

All it takes to create a Spec A database is:

  • a directory name your-databse.cdb (note the extension)
  • an info.json file that contains metadata for the database
  • files, as described by the info.json file

Under the top level directory, the files are organized in the following way:

       your-database.cdb/
           image/
               info.json
               <relative paths, per the json file>

An info.json file has three important sections. Examples of files are shown below, along with the directory and file structures that are described by it.

  • name_pattern This shows how the arguments are used to construct a path to each file in the database. This can be used by a viewer to iterate over all possible combinations of values.
  • arguments This enumerates all the variables that can be used in paths.
  • metadata This tells a reader of the database what type of information to expect. The key, value pair “type": "parametric-image-stack" is the only one possible for a Spec A database.

‘One Parameter’ example

A Cinema database is a set of images that are controlled by a set of parameters. The simplest database is a one parameter example. You might use this if you are creating a series of images of a simulation, from a fixed viewpoint. An example ‘one parameter’ info.json file and resulting directories and files are shown here.

{
    "name_pattern": "{my_param}.png", 
    "arguments": {
        "my_param": {
            "default":  "0.0", 
            "values":   ["0.0", "1.0", "2.0", "3.0"],
            "type":     "range", 
            "label":    "UI label for my_param"
        }
    }, 
    "metadata": {
        "type": "parametric-image-stack"
    }
}

Using the above info.json file, we would expect the following files on disk:

   your-database.cdb/
       image/
           info.json
           0.0.png
           1.0.png
           2.0.png
           3.0.png

‘Two Parameter’ example

If you are varying two parameters, a typical way to show the data would be a directory for the first parameter, and a filename for the second parameter. This is shown in the example below, in the value for name_parameter:

{
    "name_pattern": "{my_param-01}/{my_param-02}.png", 
    "arguments": {
        "my_param-01": {
            "default":  "0", 
            "values":   ["0", "1", "2"],
            "type":     "range", 
            "label":    "UI label for my_param-01"
        },
        "my_param-02": {
            "default":  "0.0", 
            "values":   ["0.0", "1.0", "2.0"],
            "type":     "range", 
            "label":    "UI label for my_param-02"
        }
    }, 
    "metadata": {
        "type": "parametric-image-stack"
    }
}

This would result in the following data on disk:

   your-database.cdb/
       image/
           info.json
           0/
               0.0.png
               1.0.png
               2.0.png
               3.0.png
           1/
               0.0.png
               1.0.png
               2.0.png
               3.0.png
           2/
               0.0.png
               1.0.png
               2.0.png
               3.0.png

Example Databases

Finally, here are several examples of common use cases for Cinema Spec A databases. You can download these examples, edit the info.json file, and then write your own files over the ones included in the examples. It should be easy to edit the json files to describe your use cases.