cask – Alembic Python Convenience Wrapper

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

Arguably one of the biggest conveniences is that cask handles all the OObject and OProperty bookkeeping for you, keeping these objects in scope until you call an explicit “save()” method. Some of the other features are listed below.

• Abstraction layer for I and O object types,
• Automatically schemify objects on read,
• Deferred writing / cached reading,
• Auto convert python data types to alembic data types,
• Deep dictionary access for objects and properties.

Tutorial

Since cask abstracts “I” and “O” objects, creating a new archive or reading an existing one from disk uses the same Archive class.

>>> # read an archive from disk
>>> a = cask.Archive("lights.abc")

>>> # creates a new empty archive
>>> b = Archive()

Both objects have internal “iobject” and “oobject” properties that point to the corresponding Alembic “I” and “O” objects. For “a”, there will be an internal “iobject” property that points to the IArchive, and for “b” that property returns None. In both cases, accessing the Top object is easy, it’s just

>>> a.top
<Top "ABC">

A lot of the accessors in cask are properties vs. methods, like properties, and children, both with return dictionary-like objects. Walking and modifying the archive’s hierarchy is as simple as accessing/manipulating these dict-like objects

>>> def walk(obj):
...     print obj.name, obj.type()
...     for child in obj.children.values():
...         walk(child)
...
>>> walk(a.top)

>>> # add a new xform under the top node
>>> b.top.children["foo"] = cask.Xform()

Navigation

Deep dictionary access and (deferred) auto-schemification are available on the dict-like children and properties accessors.

>>> l = a.top.children["root/world/lgt/gaffer/point/pointShape"]
>>> l
<Light "pointShape">

I say deferred because while the the correct high-level cask class is returned for each object, the underlying Alembic object is still an IObject until we need to wrap it in its subclass and/or access its schema class.

>>> l.iobject
<alembic.Abc.IObject object at 0x1016830>
>>> l.schema.getNumSamples() # access the schema
6
>>> l.iobject
<alembic.AbcGeom.ILight object at 0x1047838>
>>> l.schema
<alembic.AbcGeom.ILightSchema object at 0xfe2670>

To access or create properties, use the properties accessor. For example, to access the value of the diffuse light shader property on our light, l:

>>> l.properties
{'.geom': <Property ".geom">, 'shader': <Property "shader">}
>>> l.properties["shader/arnold.light.params/diffuse"].values[0]
1.0

The “old” way of doing this via the Alembic Python API would require many additional steps after finding the light object, including matching and wrapping the IObject in the alembic.AbcGeom.ILight class, accessing the schema, then navigating to the property through the a series of property accessors. Cask makes this much more straight-forward and user-friendly.

Hierarchy Manipulation

Adding a new Object or Property is as simple as adding an object to a dictionary.

>>> a.top.children["myObject"] = cask.Xform()
>>> l.properties["myProperty"] = cask.Property()

Or you can set the parent attribute on any object:

>>> x = cask.Xform(name="foo")
>>> x.parent = a.top

Cask makes it trivial to extract an object by copying it from one archive to a new one:

>>> l.parent = b.top
>>> b.write_to_file("/var/tmp/point_light.abc")

Check the output:

> abctree /var/tmp/point_light.abc
ABC
`-- pointShape

Inserting nodes is also easy:

>>> a = cask.Archive("animatedcube.abc")
>>> r = cask.Xform()
>>> x = a.top.children["cube1"]
>>> a.top.children["root"] = r
>>> r.children["cube1"] = x
>>> a.write_to_file("/var/tmp/cask_insert_node.abc")

Check the results:

> abctree /var/tmp/cask_insert_node.abc
ABC
 `-- root
     `-- cube1
         `-- cube1Shape

Setting Values

Cask automatically converts Python data types to the appropriate Alembic typed property, or imath type using an internal map. There is no need to know which typed OProperty class to use, or potentially even which imath type you need as an argument to that property.

Currently, you can either set a value on a property directly, or create an Alembic sample object, set values on that, and then set the sample on the cask object.

Setting values directly on properties:

>>> a = cask.Archive("octopus.abc")
>>> a.top.children.values()[0].name = "squid_low"
>>> x = a.top.children.values()[0].properties[".xform/.vals"]
>>> t = imath.M33d((50, 0, 0), (0, -0, -90), (1, 1, 1))
>>> for i in range(len(x.values)):
...     x.set_value(t, index=i)

Setting values on sample objects:

>>> uvsamp = alembic.AbcGeom.OV2fGeomParamSample(meshData.uvs, kFacevaryingScope)
>>> nsamp = alembic.AbcGeom.ON3fGeomParamSample(meshData.normals, kFacevaryingScope)
>>> s = alembic.AbcGeom.OPolyMeshSchemaSample(meshData.verts, meshData.indices,
               meshData.counts, uvsamp, nsamp)
>>> p.set_sample(s)

A third way to set values is using cask wrapped methods on objects. Currently, there is only one method implemented, the setScale method on the cask.Xform class. These methods create an internal sample object and cache it, setting it on the object when save() is called. If this seems like the best, most convenient way of setting values, then we can implement more of these.

>>> x = cask.Xform()
>>> x.set_scale(imath.V3d(1, 2, 3))

Caveat: Setting samples on the object will currently only work for new, empty archives, not archives that have been read in from disk. This is a known limitation and on the to-do list to resolve.

Module Contents

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

cask.find(obj, name='.*', types=None)

Finds and returns a list of Objects with names matching a given regular expression.

>>> find(a.top, ".*Shape")
[<PolyMesh "cube1Shape">, <PolyMesh "cube2Shape">]

Parameters:

• name – Regular expression to match object name
• types – Class type inclusion list

Returns:

Sorted list of Object results

cask.find_iter(obj, name='.*', types=None)

Generator that yields Objects with names matching a given regular expression.

Parameters:

• name – Regular expression to match object name
• types – Class type inclusion list

Yields:

Object with name matching name regex

cask.is_valid(archive)

Returns True if the archive is a valid alembic archive.

Archive

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.Archive(filepath=None, fps=24)

Archive I/O Object

alembic_version()

Returns the version of alembic used to write this archive.

close()

Closes this archive and makes it immutable.

end_frame()

Returns the last frame.

end_time()

Returns the global end time in seconds.

frame_range()

Returns a tuple of the global start and end times in frames.

info()

Returns a metadata dictionary.

iobject

Internal Alembic IArchive object.

is_leaf()

Returns False.

name

Returns the basename of this archive.

oobject

Internal Alembic OArchive object.

path()

Returns the filepath for this Archive.

set_start_frame(frame)

Sets the start frame.

set_start_time(start)

Sets the start time in seconds.

start_frame()

Returns the start frame.

start_time()

Returns the global start time in seconds.

time_range()

Returns a tuple of the global start and end time in seconds.

** Depends on the X.samples property being set on the Top node, which is currently being written by Maya only. **

timesamplings

Generator that yields tuples of (index, TimeSampling) objects.

top

Hierarchy root, cask.Top object.

type()

Returns “Archive”.

using_version()

Returns the version of alembic used to read this archive.

write_to_file(filepath=None, asOgawa=True)

Writes this archive to a file on disk and closes the Archive.

Object

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.Object(iobject=None, schema=None, time_sampling_id=None, name=None)

Base I/O Object class.

add_child(child)

Adds a child object to this object.

Parameters:child – cask.Object

archive()

Returns the Archive for this object.

children

Returns children sub-tree accessor.

clear_children()

Clears the internal children container.

clear_properties()

Clears the internal properties container.

clear_samples()

Clears the internal samples container.

close()

Closes this object by removing references to internal OObject.

end_frame(fps=24)

Parameters:fps – Frames per second used to calculate the end frame

(default 24.0)

Returns:Last frame as float

get_item(item)

used for deep dict access

global_matrix()

Returns world space matrix for this object.

iobject

Internal Alembic IObject object.

is_animated()

Returns True if any properties are not constant.

is_deforming()

Returns True if the object has changing P values.

is_leaf()

Returns True if this object is a leaf node, i.e. it has no children.

classmethod matches(iobject)

Returns True if a given iobject type matches this type.

metadata

Metadata as a dict.

name

Set and get the name of the object.

oobject

Internal Alembic OObject object.

parent

Parent object accessor.

path()

Returns the full path/name of this object.

properties

Properties accessor.

samples

Returns samples from the Alembic IObject.

save()

Walks child and property sub-trees creating OObjects as necessary.

schema

Returns the Alembic schema object.

set_item(name, item)

used for deep dict access

set_sample(sample, index=None)

Sets an Alembic sample object on this object.

*Do we want to expose samples at all? Should all data be set via seting values on properties, directly or with high level methods?

Parameters:

• sample – Alembic sample object.
• index – Index of the sample to set, or None.

start_frame()

Parameters:fps – Frames per second used to calculate the start frame

(default 24.0)

Returns:Start frame as float

time_sampling_id

Time sampling ID.

type()

Returns the name of the class.

Property

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.Property(iproperty=None, time_sampling_id=0, name=None, klass=None)

Property I/O Object.

add_property(prop)

Add a property to this, making this property a compound property.

Parameters:property – cask.Property class object.

archive()

Returns the Archive for this property.

clear_properties()

Clears the properties container.

clear_values()

Clears the values container.

close()

Closes this property by removing references to internal OProperty.

datatype

DataType object.

extent()

Returns the property’s datatype extent.

get_item(item)

used for deep dict access

get_value(index=None, time=None, frame=None)

Returns a the value stored on this property for a given sample index, time or frame.

Provide one of the following args. If none are provided, it will return the 0th value.

Parameters:

• index – sample index
• time – time in seconds
• frame – frame number (assumes 24fps, to change set on archive)

iobject

Internal Alembic IProperty object.

is_compound()

Returns True if this property contains sub-properties.

Note that compound properties cannot have values, and simple properties cannont have sub-properties.

is_leaf()

Returns True if this property is a leaf node, i.e. it has no sub-properties.

metadata

Metadata as a dict.

name

Gets and sets the property name.

object()

Returns the object parent for this property.

oobject

Internal Alembic OProperty object.

parent

Parent object or property.

path()

Returns the full path/name of this property.

pod()

Returns the property’s datatype POD value.

properties

Child properties accessor.

save()

Walks sub-tree and creates corresponding alembic OProperty classes, if they don’t exist, and sets values.

set_item(name, item)

used for deep dict access

set_value(value, index=None, time=None, frame=None)

Sets a value on the property at a given index.

Provide one of the following args. If none are provided, it will append to the end.

Parameters:

• index – sample index
• time – time in seconds
• frame – frame number (assumes 24fps, to change set on archive)

type()

Returns the name of the class.

values

Returns dictionary of values stored on this property.

Top

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.Top(archive, iobject=None)

Alembic Top Object.

is_leaf()

Returns False.

classmethod matches(iobject)

Returns True if iobject is a Top object.

name

Returns the object name, which for Top is always ABC

path()

Returns the full path/name of this object.

Camera

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.Camera(*args, **kwargs)

Camera I/O Object subclass.

Curve

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.Curve(*args, **kwargs)

Curve I/O Object subclass.

FaceSet

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.FaceSet(*args, **kwargs)

FaceSet I/O Object subclass.

Light

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.Light(*args, **kwargs)

Light I/O Object subclass.

Material

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.Material(*args, **kwargs)

Material I/O Object subclass.

NuPatch

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.NuPatch(*args, **kwargs)

NuPath I/O Object subclass.

PolyMesh

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.PolyMesh(*args, **kwargs)

PolyMesh I/O Object subclass.

SubD

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.SubD(*args, **kwargs)

SubD I/O Object subclass.

Xform

Cask is a high level convenience wrapper for the Alembic Python API. It blurs the lines between Alembic “I” and “O” objects and properties, abstracting both into a single class object. It also wraps up a number of lower-level functions into high level convenience methods.

More information can be found at http://docs.alembic.io/python/cask.html

class cask.Xform(*args, **kwargs)

Xform I/O Object subclass.

matrix(index=0)

Returns the xform matrix value for a given index.

Parameters:index – Sample index.

set_scale(*args)

Creates an internal XformSample object and sets the scale value.