[Bf-python] pose key inserting

[Toni Alatalo]

Hey-a fellows,

sorry for lagging with this to so late, but perhaps this kind of a thing 
can be done still before release -- as it may require no changes to 
code, even, just adding docs and/or deleting unused code.. (and debug 
prints)

It is about the key inserting methods i added to Object.c back during 
Orange already, the code actually is built in the 2.42 series but not 
documented - also because they were partly experimental and not hastily 
added to the actual / public API. On an occasion someone on 
#blendercoders just asked for on of those things and I told about it 
also 'cause I wanted to learn if it works correctly with the cur 
codebase, and reportedly it worked ok. There are also other variations 
there and some of those I already decided to remove.

The question with the working & sensible ones is just api design or 
'layout'. Those methods are:

armatureobject.insertPoseKey(action, channelname, sourceact_framenum, 
target_framenum)
  action: the action object to copy the pose from ('source action')
  channelname: the action channel to be used
  sourceact_framenum: the framenum in the source action for the pose to 
be copied/inserted
  target_framenum: the time in this object where the key is to be inserted
 
armatureobject.insertCurrentPoseKey(channelname, target_framenum)
  (same, but using the current pose the ob has - not copying from an 
arbitary action)

the logic may seem strange / backwards -- the use case perhaps explains 
the *history* of that but i dont know if has to do with validation here:

"""bake action in py

the use case for what pose inserting feats in ArmatureObject were added:
to create a new action based on existing ones, to bake walk paths / ...

using this (or actually at that point experimental code on the c-side, 
instead,
by Roland Hess (harkyman) to bake use of multiple actions to one was then
after this worked on by trying to implement a new blend
that is: mix/multiply - state of that is unstable, Ton commented it 
recently (autumn 2006)
"""

walking = acts['walk']
for t in range(100):
    walker.move() #some imaginary py code to move the guy
    #.. in the actual case was moved by advancing time and making 
blender move on a path curve
    walker.insertPoseKey(walking, 'normalwalk', t, t)

i guess .. just wrote that now, pretty tired already, the actual code is 
on the ED dvd .. well, i guess i'll test it from there, but post this 
now anyway to not lag more.. i think the blend is called walktest.blend 
and is in ED production/lib/scripts/

the question is: should those methods be docced and hence made a part of 
the API for 2.43 now? it would require at least removing debug prints 
(simple of course). the doc i think i can put together based on this 
post pretty much. BUT the problem before was that I do not know if it 
was proper api code, like have been trying to discuss on IRC:

18:46 < antont> stivs: i dont know the responsility of the Key module 
really,
          so am in trouble trying to figure out Object.*Key* methods like
          insertPoseKey etc .. insertShapeKey seemed to be there from 
before,
          the pose thing is undocumented / no part of api yet
18:48 < antont> stivs: there is also a Pose type now, that i actually also
          added at the same time, but joeedh then too for the new 
Armature ..
          but, err, well gotta read more of the api i guess
18:58 < antont> anyone up for testing / reviewing a couple anim py methods?
          Object.insertPoseKey, Object.insertCurrentPoseKey? if they are 
ok i
          document them and they become part of the api.
19:08 < antont> LetterRip: the thing is Object.insertPoseKey seems 
strange when
          we have Pose and Key modules too, not to mention Armature. i 
think it
          tells us of the prob kaito likes to bring up: api should be 
more on
          object level, than on obdata. 'cause internal blender funcs 
often are
          on the Ob level i guess? manipulations happen via those. that 
perhaps
          translates to an api that has ArmatureObject which takes 
things from
          Object.c that are for armatures only, and moves data handing 
things
          from the current Armature module to that.

ok i guess that was it for now, cu.

~Toni
   
P.S. one of my excuses for lagging is that Ken once said that those 
funcs would be gone/cleaned anyway by his Object refactor (to 
tp-getset?), but that did not happen (iirc that talk was in 
july-august), so this returned to my table. No accusations here though!, 
just happened to remember :)