Spec D (Dietrich) examples

A Cinema Spec D database is a set of precomputed data artifacts that can be queried and interactively viewed. The user can decide what types of components comprise the database, based on the type of interaction that is desired with the final database. A general design philosophy of Cinema is that applications reading and viewing a Cinema database can ignore data and determine which operations to perform. This promotes a wide range of possible interactions with the data – not just the ones imagined by the creator of the database.

Previous Cinema database specifications have concentrated on the notion that a database is a set of results sampled by visualization parameters. In this specification, we abstract this to include typical use cases from experiments by scientists.

A scientist often has a spreadsheet with data about parameters for an experiment. This results in a set of parameters that map to a particular result – a graph, a sensor image, or other image-based data. These are a natural abstraction from previous Cinema databases.

Required elements

A Spec D version 1.0 Cinema database is directory that contains all of the data in the database. The directory must have the following files. Additional files or directories may be present, but they are ignored by Cinema.

  • a folder named database name.cdb containing:
    • data.csv, a comma-separated value file. This file is specified in section Section3.2. The presence of this named file exactly indicates that this is a Spec D, version 1.0 file, due to the fact that there is no other metadata in the database. In particular, if this file is present, the database is by definition a Spec D, version 1.0 database.
    • optional data files, referenced in the csv file
    • there may be additional files in the directory, but they are ignored by this specification.

TYPE I: Data Only

A data-only csv file is simply a table of float values. There is no external data referenced. The requirements for this file are:

  1. The file is UTF-8 encoded.
  2. Each line is fully populated (there can be no missing values).
  3. The first line of the file is required. It is unique, and is strings that are labels for the columns in the file.
  4. All other lines in the file are data. Each value in these lines must be a float.

Example

    timestep, time value, x, y, z
    1.0, 0.1, 1.0, 1.1, 1.2
    2.0, 0.2, 2.0, 2.1, 2.2
    3.0, 0.3, 3.0, 3.1, 3.2
    4.0, 0.4, 4.0, 4.1, 4.2

In this case, the cinema database would contain a single file:

    database.cdb/
        data.csv

TYPE II: Data with file reference

A Data with File Reference csv file is a table of float values, with a final column that references an external file containing additional data. The file can be of any type or extension. The requirements on this type of csv file are:

  1. The file is UTF-8 encoded.
  2. Each line is fully populated (there can be no missing values).
  3. The first line of the file is required. It is unique, and is strings that are labels for the columns in the file. The last label is required to be the keyword FILE.
  4. All other lines in the file are data. In the data lines:
    • All values except the last value must be floats.
    • The last column is a string that is a POSIX file path relative to the base directory (the name.cdb path) of the Cinema database. This is the location of the data matched to the values in the columns for that row. The file can be of any type or extension.
      • Cinema Spec D readers are only required to handle (display) image files of type JPG, JPEG, PNG, and GIF.

Example

This data.csv example shows the FILE keyword on the last column, and POSIX string paths.

    timestep, time value, x, y, z, FILE
    1.0, 0.1, 1.0, 1.1, 1.2, img/001.jpg
    2.0, 0.2, 2.0, 2.1, 2.2, img/002.jpg
    3.0, 0.3, 3.0, 3.1, 3.2, data/003.jpg
    4.0, 0.4, 4.0, 4.1, 4.2, data/004.png

In this case, the cinema database would contain the following files:

    database.cdb/
        data.csv
        img/001.jpg
            002.jpg
        data/
            003.jpg
            004.png