State Parameters and Transitions

Need to identify all the possible state parameters that can be changed between two states. All of those parameters need to be retained, probably in some form of immutable data type (tuple) within a dictionary for easy access to several parameter groups (viewer, volumes, surfaces, models, labels, etc.). Some of the elements in a state may have shared spatial parameters (e.g., molecular surfaces, molecules, and atoms may share a common spatial transform).

The savepos/reset functionality works with a tuple:

#
# 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
        )

Something like this gains access to a lot of view parameters:

for n in dir(chimera.viewer):
    print n, eval('type(chimera.viewer.%s)' % n)

Some tips in the ​programming FAQ are useful (esp, items 4, 5, 7-10).

openState attribute (from FAQ)

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

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

#
# 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

>>> 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:

class Xform(__builtin__.object)
 |  Xform() -> Xform
 |  Xform(_x: Xform) -> Xform
 |  
 |  Methods defined here:
 |  
 |  __copy__(...)
 |      __copy__() -> Xform
 |  
 |  __eq__(...)
 |      x.__eq__(y) <==> x==y
 |  
 |  __ge__(...)
 |      x.__ge__(y) <==> x>=y
 |  
 |  __gt__(...)
 |      x.__gt__(y) <==> x>y
 |  
 |  __init__(...)
 |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
 |  
 |  __le__(...)
 |      x.__le__(y) <==> x<=y
 |  
 |  __lt__(...)
 |      x.__lt__(y) <==> x<y
 |  
 |  __ne__(...)
 |      x.__ne__(y) <==> x!=y
 |  
 |  __repr__ lambda s
 |  
 |  __str__(...)
 |      x.__str__() <==> str(x)
 |  
 |  apply(...)
 |      apply(p: Point) -> Point
 |      apply(p: Vector) -> Vector
 |  
 |  getCoordFrame(...)
 |      getCoordFrame() -> Vector, Vector, Vector, Point
 |  
 |  getOpenGLMatrix(...)
 |      getOpenGLMatrix() -> 16-tuple of float
 |  
 |  getRotation(...)
 |      getRotation() -> Vector, float
 |  
 |  getTranslation(...)
 |      getTranslation() -> Vector
 |  
 |  inverse(...)
 |      inverse() -> Xform
 |  
 |  invert(...)
 |      invert()
 |  
 |  isIdentity(...)
 |      isIdentity() -> bool
 |  
 |  makeOrthogonal(...)
 |      makeOrthogonal(modify: bool)
 |  
 |  multiply(...)
 |      multiply(op: Xform)
 |  
 |  premultiply(...)
 |      premultiply(op: Xform)
 |  
 |  rotate(...)
 |      rotate(xyz: Vector, angle: float)
 |      rotate(x: float, y: float, z: float, angle: float)
 |  
 |  translate(...)
 |      translate(xyz: Vector)
 |      translate(x: float, y: float, z: float)
 |  
 |  xRotate(...)
 |      xRotate(angle: float)
 |  
 |  yRotate(...)
 |      yRotate(angle: float)
 |  
 |  zRotate(...)
 |      zRotate(angle: float)
 |  
 |  ----------------------------------------------------------------------
 |  Static methods defined here:
 |  
 |  coordFrame(...)
 |      coordFrame(x: Vector, y: Vector, z: Vector, origin: Point, orthogonalize: bool = false) -> Xform
 |  
 |  identity(...)
 |      identity() -> Xform
 |  
 |  lookAt(...)
 |      lookAt(eye: Point, at: Point, up: Point) -> Xform
 |      lookAt(eye: Point, at: Point, up: Vector) -> Xform
 |  
 |  rotation(...)
 |      rotation(xyz: Vector, angle: float) -> Xform
 |      rotation(x: float, y: float, z: float, angle: float) -> Xform
 |  
 |  translation(...)
 |      translation(xyz: Vector) -> Xform
 |      translation(x: float, y: float, z: float) -> Xform
 |  
 |  xRotation(...)
 |      xRotation(angle: float) -> Xform
 |  
 |  xform(...)
 |      xform(r00: float, r01: float, r02: float, t03: float, r10: float, r11: float, r12: float, t13: float, r20: float, r21: float, r22: float, t23: float, orthogonalize: bool = false) -> Xform
 |  
 |  yRotation(...)
 |      yRotation(angle: float) -> Xform
 |  
 |  zAlign(...)
 |      zAlign(p0: Point, p1: Point) -> Xform
 |      zAlign(p: Point, v: Vector) -> Xform
 |  
 |  zRotation(...)
 |      zRotation(angle: float) -> Xform
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  __hash__ = None
 |  
 |  __new__ = <built-in method __new__ of libwrappy2.mutable object>
 |      T.__new__(S, ...) -> a new object with type S, a subtype of T

>>> 

Integrity Checking

Take a look at the code for chimera.update.checkForChanges(). This may be helpful in checking the validity of state parameters and in automatically detecting changes for transitions.

Also, chimera.openModels.addRemoveHandler(func, data) might be used to add a trigger handler when removing models. This might be useful in the creation of a state instance as a way to maintain integrity or validity of the saved state. It may depend on whether the state instance keeps a reference or a copy of models in the saved state. For efficiency, it is better to keep a reference. For validity, it could be better to keep a copy. Perhaps a copy is required only when a model is removed, so the copy action could be triggered then. If a state instance that is registered as a handler is deleted, then call chimera.openModels.deleteRemoveHandler(handler) to delete the trigger handler.