Cinema python toolkit

pycinema is a toolkit of python-based components for creating, filtering, transforming and viewing Cinema databases. Cinema databases are a compact and interactive output format that can be created from scientific visualization tools and infrastructures (ParaView, Ascent, etc.) or created through other code by writing to the common output format. There is more information about the Cinema project here.

Full documentation for this project can be found on readthedocs.org

Screen capture of two pycinema applications, cinema:explorer and cinema:view, which mimic the functionality of existing viewers in Cinema (and add a few added features). Both of these are available in the pycinema toolkit.

New concepts to Cinema: 'filter graphs' and 'applications'

This toolkit introduces the concept of filter graphs and applications to Cinema. Data operations (loading, querying, manipulating and viewing) are performed by filters that take input data, transform it, and pass it on in the form of tables, data, or data products. A collection of these filters is connected in a filter graph, and a filter graph can be saved in a reusable way known as an application. This makes the cinema toolkit a flexible platform for creating, modifying and saving data applications.

Screen capture of Cinema:Explorer application, showing the normal view (left) and also revealing the 'filter graph' view (lower right) of the application. pycinema introduces both of these concepts to cinema data application.

Viewers and support for image formats

pycinema supports two types of image formats: rgb and cinema-specific hdf5 float image format. Viewers included with the pycinema release support viewing of rgb databases. Select viewers support the hdf5 float image format. The types of data supported are reported by the cinema --help command (this is an example ... for the latest information, see the online documentation or run the command in a shell).

usage: cinema [-h] {recolor,compose,meta,browse,discover,explore,imagegrid,view,theater} ...

Cinema command line tool

positional arguments:
  {recolor,compose,meta,browse,discover,explore,imagegrid,view,theater}
                        Sub-commands
    recolor             recolor Cinema float (hdf5) images to .png
    compose             convert Cinema float (hdf5) images to .png
    meta                dump descriptive metadata about a cinema database (rgb and hdf5)
    browse              browse a cinema database (rgb)
    discover            discover a cinema database (rgb)
    explore             explore a cinema database (hdf5 and rgb)
    imagegrid           imagegrid a cinema database (rgb)
    view                view a cinema database (hdf5 and rgb)
    theater             run a cinema script in theater

options:
  -h, --help            show this help message and exit

Working with the code and the pycinema module

The pycinema module can be installed as part of a python environment:

pip install pycinema

Or you can install the module and run by using the pycinema repository:

git clone git@github.com:cinemascience/pycinema.git
cd pycinema
python3 -m venv pcenv
source pcenv/bin/activate
pip install --upgrade pip
pip install . 

• Installing and running with the released pycinema module

mkdir pyc-test
cd pyc-test
python3 -m venv pcenv
source pcenv/bin/activate
pip install --upgrade pip
pip install pycinema 

• Running examples

You can now use this python environment to run examples from the repository. Run cinema and select a file from the data directory:

source pcenv/bin/activate
cinema view data/sphere.cdb

Making and uploading the python module

make module

And then to upload it to pypi (assuming you have permission):

make module-upload

To upload it to testpypi (assuming you have permission):

make module-test-upload

Creating a new release

Instructions for creating a new release are here.

DSI support

pycinema support for LANL's DSI project is explained here.

Documentation

Documentation for this project can be found on readthedocs.org.

Related repositories

• pycinema-data example Cinema datasets.
• pycinema-examples examples referenced in the readthedocs site
• pycinema-testdata Cinema databases used for unit testing and CI testing.

Citing this work

• Cinema paper (2014): James Ahrens, Sébastien Jourdain, Patrick O'Leary, John Patchett, David H. Rogers, and Mark Petersen. An image-based approach to extreme scale in situ visualization and analysis. In Proceedings of the International Conference for High Performance Computing, Networking, Storage and Analysis (SC '14). IEEE Press, Piscataway, NJ, USA, 424-434, 2014.
• pycinema (this toolkit): Cite this web page

Contributing

Contributions can be made by submitting issues and contributing code through pull requests. The code shall be reviewed by the core Cinema team, and accepted when both content and code standards are met.