See Crowd Animation Clips for more information.
Methods ¶
__init__(name, filename, rig, keep_external_ref = True, delay_load = False)
Creates a new agent clip by loading it from the specified .bclip
or .clip
file.
The channels within the clip should be of the form transform_name:channel_name
, where transform_name
is a string matching the values returned by hou.AgentRig.transformName and channel_name
is one of tx
, ty
, tz
, rx
, ry
, rz
, sx
, sy
, or sz
.
The channels starting with t
denote translation, r
denote rotation, and s
denote scale.
The resulting transforms will be treated as local transforms and can be read via hou.AgentClip.sampleLocal (i.e. they are relative to the corresponding parent transform in the agent’s skeleton).
Any other channels can be read via hou.AgentClip.sample.
Raises hou.OperationFailed if the file does not exist or otherwise cannot be loaded.
name
A name for the new clip, such as walk
.
filename
A path to a clip file.
rig
The hou.AgentRig that the clip will be associated with. The rig is used, for example, when converting transforms from local space to world space.
keep_external_ref
A bool
indicating whether the external reference should be maintained when the agent is saved to a geometry file.
If the reference is maintained, then the clip file needs to be available when the saved geometry is used (only the path to the clip is saved in the geometry file).
Otherwise, a copy of the clip will be inlined when saving out the geometry so that the original clip is no longer needed.
delay_load
If keep_external_ref
is True
, specifies whether to delay loading the clip from disk until the clip’s data is queried.
This can improve loading times and memory usage if some clips are unused, but any load errors will not be immediately reported.
__init__(name, chop, rig, frame = hou.frame())
Creates a new agent clip from a CHOP in the scene.
name
A name for the new clip, such as walk
.
chop
A hou.ChopNode to load the clip from.
rig
The hou.AgentRig that the clip will be associated with. The rig is used, for example, when converting transforms from local space to world space.
frame
Specifies the frame to cook the CHOP node at.
__init__(name, rig, sample_count)
Creates an empty (and modifiable) agent clip with the specified number of samples. The samples are initialized to identity transforms.
name
A name for the new clip, such as walk
.
rig
The hou.AgentRig that the clip will be associated with. The rig is used, for example, when converting transforms from local space to world space.
sample_count
The number of samples that the clip will have.
__init__(clip, rig, name = "")
Creates a copy of an existing agent clip. The source clip may reference a different rig - in this case, identity transforms will be filled in for any new joints in the rig.
clip
A hou.AgentClip to copy the clip from.
rig
The hou.AgentRig that the clip will be associated with. The rig is used, for example, when converting transforms from local space to world space.
name
A name for the new clip, such as walk
. If this parameter is not specified, the source clip’s name will be used.
__init__(name, stage, prim_path, rig)
Creates a new agent clip from a USD primitive. Raises hou.OperationFailed if the clip could not be loaded.
name
A name for the new clip, such as walk
.
stage
The USD stage to load the clip from. For example, this could be the output stage from a LOP node.
prim_path
A path to a Skeleton
or SkelRoot
primitive in the stage to load the clip from.
rig
The hou.AgentRig that the clip will be associated with. The rig is used, for example, when converting transforms from local space to world space.
addChannel(name, samples)
Creates an additional channel in the clip. If a channel already exists with the same name, the previous samples will be overwritten.
Raises hou.GeometryPermissionError if the clip is not modifiable.
name
The name of the channel.
`samples
A float
sequence containing the channel’s data.
Raises hou.InvalidSize if the length does not match hou.AgentClip.sampleCount.
allLocalTransformValues()
→ tuple
of float
Returns a flat tuple of floats containing the local transforms for all samples.
This data layout can be convenient for manipulating the transforms with other Python libraries.
The number of entries is 16 * rig.transformCount() * clip.sampleCount()
.
channelNames()
→ tuple
of str
Returns the names of the additional (non-transform) channels in the clip. These channels can be sampled with hou.AgentClip.sample.
data(binary, worldspace = False)
→ str
for Python 2, bytes
for Python 3
Returns the clip data in ASCII or binary.
The returned clip data is a bytes
object in Python 3 and a str
object in Python 2. See HOM binary data for more
information.
binary
Specifies whether the clip data should be saved in ASCII (.clip
) or binary (.bclip
) format.
worldspace
Specifies whether the transform channels should be saved in local or world space.
extractLocomotion(cog_transform, cog_lookat_transform=-1, convert_inplace=True, project_on_dominant_axis=False)
Converts the animation to in-place and records the locomotion transform in the __locomotion__:[srt][xyz]
channels.
Raises hou.GeometryPermissionError if the clip is not modifiable.
cog_transform
Index of a transform in the agent’s rig that controls the locomotion of the character (i.e. has the translation that moves it forward in space).
cog_lookat_transform
Optional index of a transform in the agent’s rig, which is used to extract an overall rotation using the vector from the cog_transform
to this transform.
convert_inplace
Specifies whether to convert the animation to an in-place clip in addition to recording the locomotion transform.
project_on_dominant_axis
Projects the locomotion translation along the dominant axis of motion in the XZ plane. If the clip will be used as an in-place clip in the crowd solver, this can help to maintain hip swaying in the motion.
fileName(expanded = False)
→ str
If the clip is an external reference, returns the path to the file on disk.
expanded
Specifies whether to expand any variables in the path, such as $HIP
.
freeze()
→ hou.AgentClip
Creates a modifiable copy of the clip. The copy will not be marked as an external reference.
isExternalReference()
→ bool
Returns a bool
indicating whether the clip references a file on disk.
isLoaded()
→ bool
If the clip is an external reference, returns whether the clip’s data has been loaded from disk.
length()
→ float
Returns the length (in seconds) of the clip.
loadFromFile()
Explicitly loads the clip’s data from disk if it is an external reference that is delay loaded. Raises hou.OperationFailed if the file does not exist or otherwise cannot be loaded.
Calling any methods that require access to the clip’s data will also cause the clip to be loaded, but this method can be used to report errors immediately.
localTransforms(sample)
→ tuple
of hou.Matrix4
Returns the local space transforms for the specified sample. The number of entries matches hou.AgentRig.transformCount.
sample
Index of a sample in the clip.
name()
→ str
Returns the name of the clip.
sample(time, channel_name)
→ float
time
The time (in seconds) to evaluate the clip at.
channel_name
Name of a channel in the clip. See hou.AgentClip.channelNames.
Evaluates the clip at the given time and returns the value of the specified channel. For sampling the clip’s transforms, use hou.AgentClip.sampleLocal or hou.AgentClip.sampleWorld.
sampleCount()
→ int
Returns the number of samples in the clip.
sampleLocal(time, transform)
→ hou.Matrix4
time
The time (in seconds) to evaluate the clip at.
transform
Index of a transform in the agent’s rig.
Evaluates the clip at the given time and returns the local transform.
sampleRate()
→ float
Returns the sample rate of the clip.
sampleWorld(time, transform)
→ hou.Matrix4
time
The time (in seconds) to evaluate the clip at.
transform
Index of a transform in the agent’s rig.
Evaluates the clip at the given time and returns the world transform.
setAllLocalTransformValues(values)
Edits the local transforms for all samples in the clip from a flat sequence of floats.
Raises hou.GeometryPermissionError if the clip is not modifiable.
values
A flat tuple of floats containing the local transforms for each sample. The length and data layout is expected to match hou.AgentClip.allLocalTransformValues. Raises hou.InvalidSize if the length is invalid.
setLocalTransforms(sample, xforms)
Edits the local transforms for a sample in the clip.
Raises hou.GeometryPermissionError if the clip is not modifiable.
sample
Index of a sample in the clip.
xforms
A sequence of hou.Matrix4, with a local space transform for each joint in the rig. Raises hou.InvalidSize if the length does not match hou.AgentRig.transformCount.
startTime()
→ float
Returns the start time of the clip (in seconds).
worldTransforms(sample)
→ tuple
of hou.Matrix4
Returns the world space transforms for the specified sample. The number of entries matches hou.AgentRig.transformCount.
sample
Index of a sample in the clip.