Doc talk:2.6/Manual/Animation/Techs/Shape/Shape Keys

Shape Keys Discussion

Shape key frame

I have conducted experiments with absolute shape keys recently that lead me to conclude that the documentation on this page has a few holes, or at least some very weak floorboards. My current understanding (which might significantly differ from fact and I welcome corrections):

• the "value" field displayed in the non-Basis shape keys seems to be completely irrelevant for absolute shape keys
• the "frame" field on the shape key is a read-only python property and is not visible on the UI and is infinitely more relevant to absolute shape keys than the "value"
• bpy.ops.object.shape_key_retime() will set the "frame" property to 0.1*i. (and i=1 for Basis. This is documented)
• Interesting values for Evaluation Time range from 10..(10*n) where n is the number of shape keys. (Once you understand this the documentation seems correct, but the current wording is not engineered to create understanding in a novice's mind)
• shape keys created by python function Object.shape_key_add(name) have frame=0 and therefore will not do anything interesting until the user fixes it by clicking the shape_key_retime() button.

Open questions:

• How can users set the "frame" field from the UI?
• How can a python script set the "frame" field? (failing that, how can it create shape keys that are valid and have an effect without resorting to bpy.ops?)
• I can contrive a few situations where it would be useful to have control over the values of "frame". I'm not sure how common they are in real animation.

Before I make edits to the docs about absolute shape keys, I'd like to get some feedback from knowledgeable people. Mutantbob 22:20, 21 April 2014 (CEST)

shape key frame

"the "value" field displayed in the non-Basis shape keys seems to be completely irrelevant for absolute shape keys"

I agree.

"the "frame" field on the shape key is a read-only python property and is not visible on the UI and is infinitely more relevant to absolute shape keys than the "value""

This one, bpy.data.shape_keys['Key'].key_blocks['Shape_Key'].frame

Thats true, frame would probably be better to display than value, when using absolute shape keys.

Or maybe frame*10. This could be a good UI proposal.

Heres a picture of it working.

Absolute Shape Key frame

"bpy.ops.object.shape_key_retime() will set the "frame" property to 0.1*i. (and i=1 for Basis. This is documented)"

"Interesting values for Evaluation Time range from 10..(10*n) where n is the number of shape keys. (Once you understand this the documentation seems correct, but the current wording is not engineered to create understanding in a novice's mind)"

I agree, its a bit technical for an novice user or artist to know about frame.

Maybe it could be worded differently, though im not sure.

"shape keys created by python function Object.shape_key_add(name) have frame=0 and therefore will not do anything interesting until the user fixes it by clicking the shape_key_retime() button."

This info is probably more useful for coders.

Maybe a note could be added to one of the python api pages.

"How can users set the "frame" field from the UI?"

I dont know. I dont think its possible via python. But I may be wrong.

Koilz 22 April 2014 00:08 (CEST)

shape key frame

I cant read all the changes at the moment.

I see you would like to add a better explaination or workflow for frame and Evaluation Time, but, ive readded the old page back for now.

From 14:12, 23 April 2014 revision.

> "Since absolute shape keys have so many quirks, you may find it more flexible to animate through a sequence of relative shape keys."

Its easier to animate a sequence of shape keys with evaluation time, which uses one F-Curve.

When you do the same thing with relative shape keys, you have to add keyframes to each shape key value and also set the basic to deform from, which can make the workflow tricky.

Absolute shape keys, are a bit funny, but all you need todo is reset timing then keyframe evaluation time.

> "When you create a shape key its "frame" property is zero, which is a completely useless value."

This is not true if shape keys are added via the UI. They can loose there timing, but that is what the reset timing button is for.

> "This frame value is not (yet) displayed on the UI so you can't easily tell if something is wrong or screwy until your animation starts misbehaving."

> "An upgrade of the shape key system is on the developers' TODO."

This documentation is for animators, comments like 'something is going to be improved' dont help an animator.

Its better to rewrite a page after a new feature been added.

I hope my comments dont put you off editing the page in the future.

The page is not perfect, there are problems with it.

Maybe better workflows could be written, one for absolute shape keys for example.

At the moment, the only different with absolute shape key workflow, is at the end, you press Reset Timing then set Evaluation Time.

Koilz 24 April 2014 CEST 20:51.

and then

> Its easier to animate a sequence of shape keys with evaluation time, which uses one F-Curve.

That's why I used the word "flexible" instead of "easier". I have actually envisioned an "upgraded" shape key system which allows multiple strings of absolute shape keys (or even a tree structure). This is already anticipated (3 years ago) by animators who have rigged drivers and bones to relative shape keys. http://vimeo.com/18881312 demonstrates techniques with old blender which are still relevant. Future blender might bake those techniques into the UI. The biggest challenge will be to put it together in a UI that quickly causes understanding in the user.

>> "When you create a shape key its "frame" property is zero, which is a completely useless value."

> This is not true if shape keys are added via the UI. They can loose there timing, but that is what the reset timing button is for.

Actually, https://developer.blender.org/T39897 . The frame property is definitely zero if you do not have the Relative checkbox checked (which would be the case for absolute shape keys).

This combination of minor bugs, baroque design decisions (why does Evaluation time map to 100*frame? why does frame increment by 0.1?), the invisible frame value, and mildly disjointed documentation is why I tried to adjust the page.

I'll resurrect my narrative in a separate section outlining the workflow for absolute shape keys. To be clear, the section on absolute shape keys still needs to be improved. Embedding redundant and abbreviated narratives in UI element descriptions is not optimal. It can be improved with a longer flowing narrative whose words both

• engineer understanding in the reader's brain and
• outline newbie pitfalls and repair strategies

and refer to that narrative from the element descriptions. You really want the user to think "it's not working. Oh, this is just like that thing I read in the documentation and it says how to fix it". The first step in documentation is to lay out the facts. The second step is to upgrade the wording to create understanding in the reader's brain. The third step is to outline common mistakes and fixes. Mutantbob 17:21, 25 April 2014 (CEST)

shape key frame

> Actually, https://developer.blender.org/T39897 . The frame property is definitely zero if you do not have the Relative checkbox checked (which would be the case for absolute shape keys).

K. Its not something I noticed before. You are correct.

Sorry for readding the old page like that.

I did give reasons why I did it, but it was still the wrong thing todo.

Koilz 26 April 2014 CEST 17:35

possible fix is in git

https://developer.blender.org/rB875aff2a9a832d162141e1f6a39f9d08c46912b7 claims to be a fix for the frame=0 bug. When a new build of blender is published that includes the fix, I must remember to update the wiki. I might also pare down this discussion page while I'm at it. Mutantbob 17:27, 19 May 2014 (CEST)