== Animation Resources ==

 * [wiki:Animation Chimera Animation] notes
 * [wiki:ChimeraAnimationTasks Animation Tasks]

 * [http://www.cgl.ucsf.edu/chimera/docs/UsersGuide/modelattrib.html Model Attribute Inspectors]


=== State Parameters: Categories ===

 * Elements
   * 2D Labels
   * Models (Molecules, Atoms)
   * Surfaces
   * Volumes
   * Selections
 * Display State
   * Hidden
   * Active for Motion
 * Spatial
   * Camera
   * Model Geometry (Center of Rotation, Xform, etc.)
   * Clipping Planes
 * Lighting
   * Background
   * Directional Lights
 * Surfacing
   * Textures
   * Materials (Color, Specular reflection, etc.)
   * Transparency
 * Rendering
   * Model and ribbon styles (ball-and-stick, wire, sphere, ribbons)
   * Surfaces: wire, solid, dots
   * Motion Blur


=== State Parameters: initial work based on {{{savepos}}} and {{{reset}}} ===

The savepos/reset functionality works with a tuple:
{{{
#!python
#
# savepos returns a tuple of various parameters (my comments added)
#
return (
    chimera.viewer.scaleFactor, #cam
    chimera.viewer.viewSize, #cam
    cam.center, #cam
    cam.nearFar, #cam
    cam.focal, #cam
    xforms, # spatial/geometry
    clips, # per-model clipping
    chimera.openModels.cofrMethod, # spatial/geometry
    cofr, # spatial/geometry
    chimera.viewer.clipping #cam
)
}}}


== State Parameters: Saving Immutable State ==

Options for saving state:

 1. incremental diff for sequential key-frames
 2. saving immutable openModels.list()
    a. saving to RAM
    b. saving to disk (pickle, sqlite, etc.)
    c. optimization issues (threading)
    d. see http://docs.python.org/library/persistence.html


=== Model Types ===

Models types are Python classes.  They all subclass from chimera.Model, but Python does not keep track of what classes subclass from a base class.  The best you can do is to get a set of all the currently open model types.  Keep in mind that a Chimera extension can introduce additional model types, so the set is always a subset. 
{{{
#!python
modelTypes = [x.__class__ for x in chimera.openModels.list(all=True)]
modelTypes = list(set(modelTypes))
for i, t in enumerate(modelTypes):
    modelTypes[i] = re.findall("_chimera[.](.*)[']", str(t))[0]
}}}

=== Atoms ===

{{{
#!python
atomSelections = chimera.selection.currentAtoms()
anAtom = chimera.openModels.list(modelTypes=[chimera.Molecule])[0].atoms[0]
}}}

==== Color ====

{{{
#!python
molecules = chimera.openModels.list(modelTypes=[chimera.Molecule])
for m in molecules:
    for a in m.atoms:
        print a.color

>>> a = chimera.openModels.list(modelTypes=[chimera.Molecule])[0].atoms[0]
>>> a.color
<_chimera.MaterialColor object at 0x3f36490>
>>> MC = chimera.MaterialColor
>>> help(MC)  # see various contructors
>>> MC = chimera.MaterialColor(0.0, 0.0, 0.0, 1.0)
>>> MC.rgba()
(0.0, 0.0, 0.0, 1.0)
>>> r,g,b,a = a.color.rgba()
>>> MC = chimera.MaterialColor( r,g,b,a )
}}}


==== Representations ====

Each atom in a molecule has a drawMode attribute, with possible values: 0 = 'dot', 1 = 'sphere', 2 = 'endcap', 3 = 'ball'.  These values can be compared with the equivalent 'enum' values in chimera.Atom, i.e.:

{{{
#!python
>>> chimera.Atom.Dot
0
>>> chimera.Atom.Sphere
1
>>> chimera.Atom.EndCap
2
>>> chimera.Atom.Ball
3
}}}

{{{
#!python
molecules = chimera.openModels.list(modelTypes=[chimera.Molecule])
for m in molecules:
    for a in m.atoms:
        print a.drawMode == chimera.Atom.Sphere
}}}


=== Parameter Access Methods ===

Something like this gains access to a lot of view parameters:
{{{
#!python
for n in dir(chimera.viewer):
    print n, eval('type(chimera.viewer.%s)' % n)
}}}

Some tips in the [http://www.cgl.ucsf.edu/chimera/docs/ProgrammersGuide/faq.html programming FAQ] are useful (esp, items 4, 5, 7-10).

==== Attributes: To Copy or Not to Copy, that is the question! ====

From the [http://www.cgl.ucsf.edu/chimera/docs/ProgrammersGuide/faq.html FAQ], item (7): Some attributes return a copy of an object.
{{{
#!python
>>> xf = model.openState.xform	# xf is a copy of the model's Xform matrix.
>>> xf.zRotate(45)		# This will not rotate the model.

>>> c = model.atoms[0].color	# c is the MaterialColor object for the atom
>>> c.ambientDiffuse = (1,0,0)	# The Atom color changes immediately to red.
}}}

Some Chimera objects returned as attributes are always copies, some are always references to the uncopied object. Objects that are always copied include {{{Xform, Vector, Point, Sphere, Element, MolResId, Coord,}}} .... Objects that are never copied include {{{Atom, Bond, PseudoBond, CoordSet, Molecule, Residue, RibbonStyle,}}} .... Object that can be copied have a {{{__copy__}}} method. In order to know if an object type is passed by value is to look at the Chimera C++ header files. Classes without a !WrapPy base class are always copied. This base class is part of the C++ to Python interface generation.



==== Color and Material Attributes ====

See http://www.cgl.ucsf.edu/chimera/docs/ProgrammersGuide/Examples/Main_ColorWellUI.html

Also need a function for color interpolations (linear may suffice).  This may be a simple function to interpolate each component of the RGBA tuple from stateA to stateB over N frames (the range of values is between 0-1, so it's a floating point interpolation).

Get a PDB molecule to play with:
{{{
#!python
chimera.runCommand('open 2por')
om = chimera.openModels.list(all=True)
por2 = om[1]
}}}

Exploring color properties:
{{{
#!python
>>> por2.color
<_chimera.MaterialColor object at 0x3d50dc8>
>>> por2.color.name()
u'_openColor00'
>>> por2.color.rgba()
(1.0, 1.0, 1.0, 1.0)
>>> por2.color.ambientDiffuse
(1.0, 1.0, 1.0)
>>> por2.color.isTranslucent()
False
>>> por2.color.opacity
1.0
}}}

Chimera material attributes are collected with color attributes.
{{{
#!python
# chimera.Material object
>>> por2.color.material
<_chimera.Material object at 0x2fd7c60>
>>> por2.color.material.name()  # material name (unicode str)
u'default'
>>> por2.color.material.shininess
30.0
>>> por2.color.material.specular
(0.85, 0.85, 0.85)
>>> por2.color.material.opacity
1.0
>>> por2.color.material.ambientDiffuse
(1.0, 1.0, 1.0)
>>> por2.color.material.isTexture()
False
>>> por2.color.material.isTranslucent()
False
}}}



==== openState attributes ====

Get the !OpenState attributes of a model: {{{chimera.openModels.openState(id: int, subid: int)}}}

From the [http://www.cgl.ucsf.edu/chimera/docs/ProgrammersGuide/faq.html FAQ], item (10):  The openState attribute of a Model controls whether that model is active for motion ('.active'), and contains the model's transformation matrix ('.xform') and center of rotation ('.cofr'). Since some models must move in synchrony (e.g. a molecule and its surface), !OpenState instances may be shared among multiple models. If you create a model that needs a shared openState with another model, then when adding your model to the list of open models with chimera.openModels.add(), you should use the 'sameAs' keyword to specify the other model.



==== 'Active' models ====

{{{
#!python
#
# Working with a specific active model:
# openState(id: int, subid: int)
modelID = chimera.openModels.listIds()[0]
model_openState = chimera.openModels.openState(*modelID)
if model_openState.active:
    # do something useful with it
    print model_openState.xform
    print model_openState.xform.getRotation()
    print model_openState.xform.getTranslation()
#
# looping over all open-active models
#
if chimera.openModels.hasActiveModels():
    om = chimera.openModels.list(all=True)
    for m in om:
        if m.openState.active:
            # do something useful with it
            print m.openState.xform
#
# Setting 'active' models:
# chimera.openModels.setActive(id: int, active: bool)
#
chimera.openModels.setActive(modelID[0], False)
model_openState.active
# False
chimera.openModels.setActive(modelID[0], True)
model_openState.active
# True

}}}



==== openState.xform ====

{{{
#!python

>>> dir(model_openState.xform)
['__class__', '__copy__', '__delattr__', '__dict__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__le__', '__lt__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'apply', 'coordFrame', 'getCoordFrame', 'getOpenGLMatrix', 'getRotation', 'getTranslation', 'identity', 'inverse', 'invert', 'isIdentity', 'lookAt', 'makeOrthogonal', 'multiply', 'premultiply', 'rotate', 'rotation', 'translate', 'translation', 'xRotate', 'xRotation', 'xform', 'yRotate', 'yRotation', 'zAlign', 'zRotate', 'zRotation']

>>> help(model_openState.xform)
Help on Xform object:

...

}}}