cinema_python.database

cinema_python.database.store module

Module defining classes and methods for managing cinema data storage.

class cinema_python.database.store.Document(descriptor, data=None)

Bases: object

This refers to a document in the cinema data storage. A document is uniquely identified by a ‘descriptor’. A descriptor is a dictionary with key-value pairs, where key is a parameter name and value is the value for that particular parameter. TODO: A document can have arbitrary data (as ‘data’) and meta-data (as ‘attributes’) associated with it. At the moment we are ignoring the attributes.

attributes

Attributes are arbitrary meta-data associated with the document. If no attributes are present, it is set to None. When present, attributes are a dict with arbitrary meta-data relevant to the application.

data

Data associated with the document.

descriptor

A document descriptor is a unique identifier for the document. It is a dict with key value pairs. The descriptor cannot be changed once the document has been instantiated.

class cinema_python.database.store.Store

Bases: object

API for cinema stores. A store is a collection of Documents, with API to add, find, and access them. This class is an abstract class defining the API and storage independent logic. Storage specific subclasses handle the ‘database’ access.

The design of cinema store is based on the following principles:

The store comprises of documents (Document instances). Each document has a unique set of parameters, aka a “descriptor” associated with it. This can be thought of as the ‘unique key’ in database terminology.

One defines the parameters (contents of the descriptor) for documents on the store itself. The set of them is is referred to as ‘parameter_list’. One uses ‘add_parameter()’ calls to add new parameter definitions for a new store instance.

Users insert documents in the store using ‘insert’. One can find document(s) using ‘find’ which returns a generator (or cursor) allow users to iterate over all match documents.

add_control(name, properties)

A control is a togglable parameter for a filter. Examples include: isovalue, offset.

add_field(name, properties, parent_layer, parents_values)

A field is a component of the final color for a layer. Examples include: depth, normal, color, scalar values.

add_layer(name, properties)

A Layer boils down to an image of something in the scene, and only that thing, along with the depth at each pixel. Layers (note the plural) can be composited back together by a viewer.

add_metadata(keyval)

add_parameter(name, properties)

Add a parameter. :param name: Name for the parameter. :param properties: Keyword arguments can be used to associate miscellaneous meta-data with this parameter.

assign_parameter_dependence(dep_param, param, on_values)

mark a particular parameter as being explorable only for a subset of the possible values of another.

For example given parameter ‘appendage type’ which might have value ‘foot’ or ‘flipper’, a dependent parameter might be ‘shoe type’ which only makes sense for ‘feet’. More to the point we use this for ‘layers’ and ‘fields’ in composite rendering of objects in a scene and the color settings that each object is allowed to take.

create()

Creates an empty store. Subclasses must extend this.

dependencies_satisfied(dep_param, descriptor)

Check if the values in decriptor satisfy all of the dependencies of dep_param. Return true if no dependencies to satisfy. Return false if dependency of dependency fails.

determine_type(desc)

Given a descriptor this figures out what type of data it holds. It works by first looking into the __type_specs for registered relationships and if that fails returning the registered default type for the store.

find(q=None)

Return iterator to all documents that match query q. Should support empty query or direct values queries e.g.

for doc in store.find({‘phi’: 0}):

print (doc.data)

for doc in store.find({‘phi’: 0, ‘theta’: 100}):

print (doc.data)

find_field_key(desc)

Given a descriptor this finds the field value if any in the descriptor.

getDependeeValue(depender, dependee)

Return the required value of a dependee to fulfill a dependency.

getRelatedField(parameter)

Returns the ‘field’ argument related to a ‘parameter’.

get_camera_model()

return the camera model that the raster images in the store correspond to

get_complete_descriptor(partial_desc)

Convenience method that expands an incomplete list of parameters into the full set using default values for the missing variables. TODO: doesn’t make sense with bifurcation (dependencies) remove

get_default_type()

subclasses override this if they know more

get_parameter(name)

get_parameter_values(name)

Get all values of type value :param name: Name for the parameter.

get_version_major()

major version information corresponds with store type

get_version_minor()

minor version information corresponds to larger changes in a store type

get_version_patch()

patch version information corresponds to slight changes in a store type

getdependees(depender)

return a list of all the parameters that ‘depender’ depends on

getdependers(name)

return a list of all the parameters that depend on the given one

hasRelatedParameter(fieldName)

Predicate to know if a field has a related ‘parameter’ argument.

insert(document)

Inserts a new document. Subclasses must extend this.

iscontrol(name)

isdependee(name)

check if the named parameter has others that depend on it

isdepender(name)

check if the named parameter depends on any others

isfield(name)

islayer(name)

iterate(parameters=None, fixedargs=None, progressObject=None)

Run through all combinations of parameter/value pairs without visiting any combinations that do not satisfy dependencies among them. Parameters, if supplied, is a list of parameter names to enforce an ordering. Fixed arguments, if supplied, are parameter/value pairs that we want to hold constant in the exploration.

load()

Loads contents on the store (but not the documents). Subclasses must extend this.

metadata

Auxiliary data about the store itself. An example is hints that help the viewer app know how to interpret this particular store.

parameter_associations

paremeter associations establish a dependency relationship between different parameters.

parameter_list

The parameter list is the set of variables and their values that the documents in the store vary over.

parameters_for_object(obj)

Given <obj>, an element of the layer <vis>, this method returns: 1. the names of independent parameters (t, theta, etc) that affect it 2. the name of its associated field 3. the names of the controls that affect it

cinema_python.database.store.make_field(name, _values, **kwargs)

specialization of make_parameters for parameters that define fields (aka color inputs). In this case the values is a list of name, type pairs where types must be one of ‘rgb’, ‘lut’, ‘depth’, ‘value’, or ‘luminance’ May also be given an set of valueRanges, which have min and max values for named ‘value’ type color selections.

cinema_python.database.store.make_parameter(name, values, **kwargs)

define a new parameter that will be added to a store. Primarily takes a name and an array of potential values. May also be given a default value from inside the array. May also be given a typechoice to help the UI which is required to be one of ‘list’, ‘range’, ‘option’ or ‘hidden’. May also bve given a user friendly label.

cinema_python.database.file_store module

An implementation of the database API based on named files and directories.

class cinema_python.database.file_store.FileStore(dbfilename=None)

Bases: cinema_python.database.store.Store

Implementation of a store based on named files and directories.

create()

creates a new file store

filename_pattern

Files corresponding to Documents are arranged on disk according the the directory and filename structure described by the filename_pattern. The format is a regular expression consisting of parameter names enclosed in ‘{‘ and ‘}’ and separated by spacers. “/” spacer characters produce sub directories.

Composite type stores ignore the file name pattern other than the extension.

find(q=None)

overridden to implement parent API with files

get(q)

optimization of find()[0] for an important case where caller knows exactly what to retrieve.

get_default_type()

overridden to use the filename pattern to determine default type

insert(document)

overridden to write file for the document after parent makes a record of it in the store

load()

loads an existing filestore

save()

writes out a modified file store

cinema_python.database.vti_store module

An implementation of the database API stored in one VTK .vti format file.

class cinema_python.database.vti_store.VTIFileStore(dbfilename=None)

Bases: cinema_python.database.store.Store

Implementation of a store based on a single volume file (image stack). NOTE: This class is limited to parametric-image-stack type stores, currently unmaintained and may go away in the near future.

create()

creates a new file store

find(q=None)

Overridden to search for documentts withing the stack. TODO: algorithm is dumb, but consisent with compute_sliceindex (which is also dumb)

get_sliceindex(document)

returns the location of one document within the stack

insert(document)

overridden to store data within a volume after parent makes a note of it

load()

loads an existing filestore

save()

writes out a modified file store

cinema_python.database.raster_wrangler module

Module that uses one of the available back end libraries to write out image files for cinema’s file store class.

class cinema_python.database.raster_wrangler.RasterWrangler

Bases: object

Isolates the specifics of raster file formats from the cinema store. In particular this delegates the task to one or more subsidiary modules. The choice of which is open to facilitate packaging in different places, i.e. PIL for desktop and small packages, VTK for HPC contexts.

assertvalidimage(filename)

tests that a given file is syntactically correct

enableOpenEXR()

Try to turn on OpenEXR file IO support

enablePIL()

Try to turn on PIL file IO support

enableVTK()

Try to turn on VTK file IO support

floatExtension()

determine file extension for depth images

genericreader(fname)

read generic binary data dump

genericwriter(imageslice, fname)

write generic binary data dump

rgbreader(fname)

opens a color image file and returns it as a color buffer

rgbwriter(imageslice, fname)

takes in a color buffer and writes it as an image file

valuereader(fname, shape=None)

Opens a value image file and returns it as either a color buffer or a floating point array (depending on how the image was exported).

valuewriter(imageSlice, fname, vrange)

Takes in either a (1C) float or a RGB (3C) buffer and writes it as an image file.

zreader(fname, shape=None)

reads a depth file to make a depth buffer

zwriter(imageslice, fname)

takes in a depth buffer and writes it as a depth file

cinema_python.database.oexr_helper module

Interface to OpenEXR library. TODO: fold this into raster_wrangler.

class cinema_python.database.oexr_helper.OexrCompression

NONE = 0

PIZ = 4

PXR24 = 5

RLE = 1

ZIP = 3

ZIPS = 2

cinema_python.database.oexr_helper.load_depth(filePath)

Loads an depth OpenEXR image.

cinema_python.database.oexr_helper.load_rgb(filePath)

Loads an rgb OpenEXR image.

cinema_python.database.oexr_helper.save_depth(image, filePath, comp=3)

Saves the zBuffer (image) in OpenEXR format. Expects a 1-chann float32 image.

cinema_python.database.oexr_helper.save_rgb(image, filePath, comp=3)

Saves the rgb (image) in OpenEXR format. Expects a 3-chan uint32 image.