Tutorial: Cinema Workflows

This tutorial will help the user explore the CinemaScience ecosystem and give examples for possible workflows, including how to generate or export Cinema databases (CDBs).

The CinemaScience GitHub page and the CinemaScience website are useful sources for more information and ideas.

Custom Script

The most basic approach is a custom script that generates a database according to the Cinema Specifications, CinemaScience Specifications. This approach may be appropriate for both simulation and experimental data, run statistics, or other already extant datasets. Taking in one CDB, perfoming analysis and outputting an updated CDB is a common workflow.

Any programming language can be used but here we demonstrate a pandas dataframe approach. In this psuedo script, an input csv file is read in, manipulated, has a final image FILE column added and then is written out to a CDB. Along the way, the necessary directories are created and the images are moved over from an input directory to the data/image directory.

#! /usr/bin/env python
# Psuedo code to generate a custom Cinema Database

import sys, os
import pandas as pd

###############################################
# writes the data frame to the CDB data.csv file
################################################
def write_data(fname, df):
    sys.stderr.write ("Writing Cinema database data.csv...\n")

    with open(fname, "w") as output:
                df.to_csv(fname, mode='w', sep=',' , index=False)
################################################

# get database parameters from sys.argv
runParams = [180101, 00]   # Default run params
if len(sys.argv) == 3:
    runParams[0] = int( float(sys.argv[1]) )
    runParams[1] = int( float(sys.argv[2]) )
else:
    sys.stderr.write ( ("Warning, no run information, using defaults: {};{}\n").format(runParams[0],runParams[1]) )

# Setup CDB directory structure and default image for file
sys.stderr.write ( 'Run Params: {}_{}\n'.format(runParams[0],runParams[1]))
sys.stderr.write ( 'Creating Cinema Database directory structure ...\n' )
inputDir = 'input/'
dataDir  = 'data/run_{}_{}.cdb'.format(runParams[0],runParams[1] )
imageDir = dataDir+'/image'
defaultFILEimg = 'cinemaNoFILE.png'

# check for dataDir; copy default File img to image directory
os.makedirs(dataDir, exist_ok=True)
os.system('/bin/cp ' + defaultFILEimg +' '+ imageDir+'/.')

# Read in the already-existing dataset
sys.stderr.write ("Reading in datafile file...\n")
inputFile = inputDir + 'run_{}_{}.csv'.format(runParams[0],runParams[1] )
dfRun = pd.read_csv(inputFile, sep=',')

#  manipulate the dfRun dataframe:
sys.stderr.write ("Analysis and Image File Code Block...\n")
dfRun['newVar'] = dfRun['var1']/dfRun['var2']    # perform some analysis
if 'uselessProperty' in dfRun.columns:           # delete a column
    dfRun = dfRun.drop(['uselessProperty'], axis =1)
# ...etc...
dfRun['FILE'] = defaultFILEimg                   # add the final FILE column for images
for index, row in dfRun.iterrows():              # select an image to show for that row
    thisValue = row['newVar']
    thisImage = inputDir + 'run_{}_{}_{}.png'.format(thisValue, runParams[0],runParams[1])
    if os.path.isfile(thisImage):                # check if it exists and if so
         row['FILE'] = imageDir + thisImage      # set the FILE variable to that image
         os.system('/bin/mv ' + inputDir+thisImage +' '+ imageDir+'/.')  # and move it to the image directory

# Write out the dataframe to a Cinema database data.csv
datafilename = dataDir+'/data.csv'
write_data( datafilename, dfRun)

PostProcessing via ParaView Cinema Export Wizard

The current ParaView release v5.6 (in Release Candidate status as of this writing) has a Cinema Export Wizard that outputs Cinema Spec A databases. These can be converted to Cinema Spec D databases through the cinema_lib command line interface. The Cinema Spec D export wizard will be included in an upcoming ParaView release. This tutorial will be updated when that change takes place. The basic functionality will be similar to the following.

A Cinema database can be exported directly from ParaView. This can be demonstrated with a wavelet source. Open ParaView, select Sources -> Data Objects –> Wavelet. Click on Apply to load a basic wavelet.

_images/PV56waveletSource.png

Select RTData as the variable of interest and choose a Volume representation (answer Yes when it asks if you want to change the representation type):

_images/PV56RTData.png _images/PV56volume.png

File, open Export Scene. This will bring up the export dialog to input the CDB name and location. The Cinema Export Wizard will pop up. On the left is the default export dialog. A typical set of answers to generate a CDB placing cameras around the globe is given on the right. The Cinema export will automatically cycle through all time steps present in the data.

This Spec A data can be converted to a Spec D CDB using the cinema_lib tools. Please see Converting Spec A to Spec D databases for details. Once converted, the Spec D database is available for viewing in one of the Cinema Viewers as explained in the Viewer tutorial, Tutorial: Cinema Viewers.

In Situ via ParaView Catalyst

ParaView’s in situ Catalyst library can be used to output Cinema Spec D databases. Within ParaView, again, load the data and create the visualization you wish to generate in situ. From the Catalyst menu, select Define Exports to open the Catalyst Export Inspector. On the left is the default script, on the right, a set of choices to export a Cinema database. The Cinema Image Database option has been selected along with Save Cinema D Table.

_images/CatalystExportInspector.png

Then choose Export Catalyst Script from the ParaView Catalyst menu and enter a location and name for the exported python script. The exported script can be edited to fine-tune as needed. This script can then be integrated into an in situ pipeline.

The ParaView Python Documentation is an excellent source of information on how to create a Catalyst pipeline.

PostProcessing via VisIt Cinema Export Wizard

A Cinema Export Wizard is an addition to the VisIt v3.0 release, currently in beta release. This tutorial is based on the beta release and will be updated when VisIt v3.0 is officially released.

A Cinema database can be exported directly from VisIt. This can be demonstrated with sample data that can be downloaded from the VisIt tutorial page. Start by clicking on Open to bring up the VisIt File open dialog box. Navigate to the correct directory, select the data you wish to visualize and click OK:

_images/visit_openDataFiles.png

Click Add, select Pseudocolor and choose an appropriate variable such as pressure. On the control bar, click File –> Save To Cinema to bring up the VisIt Cinema database dialog:

_images/visit_pseudocolorPressure.png _images/visit_saveToCinema.png

In the Cinema wizard, change the database name and path as needed, select Spec D for the current Cinema specification and choose Use screen capture to select the entire VisIt viewing window. The Camera type can be either static (no rotation, only time evolution of the currently rendered view) or phi-theta for the default rotations. Modify the number of phi and theta camera locations as desired. Click Next. On the next window, choose the number of frames (time steps) to include and click Finish.

_images/visit_CinemaWizard1.png _images/visit_CinemaWizard2.png

Note: The beta version currently adds an unnecessary column (max and min of the rendered variable) to the data.csv file. The user will need to edit data.csv to delete this column. (Issue is opened and fix is underway.)

In Situ via VisIt LimSim

In Situ via ALPINE Ascent