| Inheritance |
|
Channel primitives are lightweight, standalone channels optimized for quick evaluation. The following example demonstrates how to construct, insert keys into, and evaluate a channel primitive:
# Create a mutable geometry g = hou.Geometry() # Add a new channel primitive to the geometry chan = g.createChannelPrim() keys = [24, 48, 72, 96] values = [0.5, 1.0, 1.5, 2.0] # Insert keys at the specified frames and set their values for i in range(len(keys)): chan.insertKey(keys[i]) chan.setKeyValue(keys[i], values[i]) # Smooth the slopes of all keys chan.smoothAutoSlopes() # Evaluate the channel at frame 36 value = chan.eval(36)
Channel primitives can also be added to the global channel list in order to visualize and edit them on the playbar or animation editor. For an example of this, see hou.ChannelList.addGeometryChannels.
Methods ¶
start()
→ float
Returns the start frame of this channel primitive.
end()
→ float
Returns the end frame of this channel primitive.
length()
→ float
Returns the length in frames of this channel primitive.
setStart(frame: float)
Sets the start frame of this channel primitive.
defaultValue()
→ float
Returns the default value for this channel primitive, which is used when the channel is empty.
setDefaultValue(value: float)
Sets the default value for this channel primitive.
eval(frame: float)
→ float
Evaluates the channel at the given frame, returning the result.
hasKeyAtFrame(frame: float)
→ bool
Returns whether or not the channel has a key at the given frame.
insertKey(frame: float, auto_slope = True)
Inserts a key at the given frame, if there isn’t one already. If the frame is outside the channel’s current range, it will be extended accordingly.
auto_slope determines whether slopes for this key are set automatically or manually.
destroyKey(frame: float)
Destroys a key at the given frame, if one exists.
destroyKeys(frame_start: float, frame_end: float)
Destroys all keys in the given time range, inclusive.
clear()
Clears the channel primitive, removing all keys and segments.
keyIndex(frame: float)
→ int
Returns the index of the key at the given frame, or -1 if there is no key at that frame.
keyValue(frame: float, value: float, key_half = hou.keyHalf.Out)
→ float
Returns the value of the key at the given frame, if one exists.
key_half is a hou.keyHalf which defines the side of the key to get.
setKeyValue(frame: float, value: float, key_half = hou.keyHalf.InOut)
→ bool
Sets the value of the key at the given frame, if one exists.
Returns False if no key exists at the given frame.
key_half is a hou.keyHalf which defines the side of the key
to set (in, out, or both). Setting this to hou.keyHalf.In or hou.keyHalf.Out
will create a discontinuity at this key.
keySlope(frame: float, value: float, key_half = hou.keyHalf.Out)
→ float
Returns the slope of the key at the given frame, if one exists.
key_half is a hou.keyHalf which defines the side of the key to get.
setKeySlope(frame: float, slope: float, key_half = hou.keyHalf.InOut)
→ bool
Sets the slope of the key at the given frame.
Returns False if no key exists at the given frame.
key_half is a hou.keyHalf which defines the side of the key
to set (in, out, or both). Setting this to hou.keyHalf.In or hou.keyHalf.Out
will create a discontinuity in the slope at this key.
keyAccel(frame: float, value: float, key_half = hou.keyHalf.Out)
→ float
Returns the acceleration of the key at the given frame, if one exists.
key_half is a hou.keyHalf which defines the side of the key to get.
setKeyAccel(frame: float, accel: float, key_half = hou.keyHalf.InOut)
→ bool
Sets the acceleration of the key at the given frame, if one exists.
Returns False if no key exists at the given frame.
key_half is a hou.keyHalf which defines the side of the key
to set (in, out, or both). Setting this to hou.keyHalf.In or hou.keyHalf.Out
will create a discontinuity in the acceleration at this key.
setKeyAutoSlope(frame: float, auto_slope: bool, key_half = hou.keyHalf.InOut)
→ bool
Sets the auto slope property of the key at the given frame, if one exists.
Returns False if no key exists at the given frame.
key_half is a hou.keyHalf which defines the side of the key
to set (in, out, or both). Setting this to hou.keyHalf.In or hou.keyHalf.Out results in only the respective half of the key’s slope being affected when hou.ChannelPrim.smoothAutoSlopes is called, which will create a discontinuity in the slope at this key.
segmentType(frame: float)
→ hou.segmentType
Returns the type of the segment at the given frame.
setSegmentType(frame: float, type)
Sets the type of the segment at the given frame, where type is a hou.segmentType.
keyFrames()
→ tuple
Returns an ordered list of frames at which keys exist in this channel.
keyValues(key_half = hou.keyHalf.Out)
→ tuple
Returns a list of the values of each key (ordered by frame) in this channel.
key_half is a hou.keyHalf which defines the side of the key to get.
setKeyValues(values: list[float], key_half = hou.keyHalf.InOut)
Sets the values of each key in the channel.
values is a list of floats which contains the values to set. Its length
must match the channel’s length as given by channel.length().
key_half is a hou.keyHalf which defines the side of the keys to set
(in, out, or both). Setting this to hou.keyHalf.In or hou.keyHalf.Out
will create discontinuities at each key.
keySlopes(key_half = hou.keyHalf.Out)
→ tuple
Returns a list of the slopes of each key (ordered by frame) in this channel.
key_half is a hou.keyHalf which defines whether to get the out-slope
or in-slope.
setKeySlopes(slopes: list[float], key_half = hou.keyHalf.InOut)
Sets the slopes of each key in the channel.
slopes is a list of floats which contains the slope values to set. Its
length must match the channel’s length as given by channel.length().
key_half is a hou.keyHalf which defines the side of the keys
to set (in, out, or both). Setting this to hou.keyHalf.In or hou.keyHalf.Out
will create discontinuities in the slopes at each key.
keyAccels(key_half = hou.keyHalf.Out)
→ tuple
Returns a list of the accelerations of each key (ordered by frame) in this channel.
key_half is a hou.keyHalf which defines whether to get the
out-acceleration or in-acceleration.
setKeyAccels(accels: list[float], key_half = hou.keyHalf.InOut)
Sets the accelerations of each key in the channel.
accels is a list of floats which contains the acceleration values to set.
Its length must match the channel’s length as given by channel.length().
key_half is a hou.keyHalf which defines the side of the keys
to set (in, out, or both). Setting this to hou.keyHalf.In or hou.keyHalf.Out
will create discontinuities in the accelerations at each key.
moveKeyframes(key_indices, frame_offsets)
Shifts the keys at the given indices by the offsets, specified in frames.
key_indices is a tuple of integers, each specifying an index of a key
to move.
frame_offsets is a tuple of numbers, specifying the offset to apply to
each key. It must either be the same length as the key_indices tuple, or
it must be a tuple of a single element, in which case all specified keys
will be shifted by the same offset.
smoothAutoSlopes(force: bool = False)
Smooths the slopes of any keys with the auto slope flag set to true. If the force parameter is set to True, smooths the slopes of all keys regardless of the auto slope flag.
smoothAutoSlopesForKeys(start_index, end_index = -1, force: bool = False)
Smooths the slopes of any keys in the given range which have the auto slope flag set to true. If the force parameter is set to True, smooths the slopes of all keys in the range regardless of the auto slope flag.
start_index is the index at which to start smoothing auto slopes
end_index is the index at which to stop smoothing slopes. If omitted, only
the key at the start_index will be smoothed.
addVertex(point)
→ hou.Vertex
Creates a new vertex inside this channel primitive, adding it to the end of the vertex list. You would typically call this method from the code of a Python-defined SOP.
point is a hou.Point object that the new vertex will refer to. See
hou.Vertex for information on the relationship between points and
vertices.
Raises hou.GeometryPermissionError if this geometry is not modifiable.
See also:
vertex(index)
A shortcut for self.vertices()[index]. You probably don’t need to
call this method.
This method supports negative indices to index from the end, just like
self.vertices()[index] would. Also, like Python’s indexing operator,
it will raise IndexError when the index is out of range.
Methods from hou.Prim ¶
attribValue(name_or_attrib)
→ int
, float
, str
, tuple
or dict
Return the value stored in this primitive for a particular attribute. The attribute may be specified by name or by hou.Attrib object.
Looking an attribute value using a hou.Attrib object is slightly faster than looking it up by name. When looking up attribute values inside a loop, look up the hou.Attrib object outside the loop, and pass it into this method.
When looking up the attribute values of all primitives, it is faster to call hou.Geometry.primFloatAttribValues or hou.Geometry.primFloatAttribValuesAsString than to call this method for each primitive in the geometry.
Raises hou.OperationFailed if no attribute exists with this name.
floatAttribValue(attrib)
→ float
Return the primitive attribute value for a particular floating point attribute. The attribute may be specified by name or by hou.Attrib object.
Raises hou.OperationFailed if no attribute exists with this name or the attribute is not float of size 1.
In most cases, you’ll just use hou.Prim.attribValue to access attribute values. Houdini uses this method internally to implement attribValue.
floatListAttribValue(name_or_attrib)
→ tuple
of float
Return the primitive attribute value for a particular floating point attribute. The attribute may be specified by name or by hou.Attrib object. The return value is a tuple of floats.
It is valid to call this method when the attribute’s size is 1. In this case, a tuple with one element is returned.
See also hou.Prim.attribValue.
intAttribValue(name_or_attrib)
→ int
Return the primitive attribute value for a particular integer attribute of size 1. The attribute may be specified by name or by hou.Attrib object. See hou.Point.floatAttribValue for more information.
intListAttribValue(name_or_attrib)
→ tuple
of int
Return the primitive attribute value for a particular integer attribute. The attribute may be specified by name or by hou.Attrib object. The return value is a tuple of ints. See hou.Prim.floatListAttribValue for more information.
stringAttribValue(name_or_attrib)
→ str
Return the primitive attribute value for a particular string attribute. The attribute may be specified by name or by hou.Attrib object. See hou.Prim.floatAttribValue for more information.
stringListAttribValue(name_or_attrib)
→ tuple
of str
Return the primitive attribute value for a particular string attribute. The attribute may be specified by name or by hou.Attrib object. The return value is a tuple of strings.
It is valid to call this method when the attribute’s size is 1. In this case, a tuple with one element is returned.
See also hou.Prim.attribValue.
dictAttribValue(name_or_attrib)
→ dict
Return the primitive attribute value for a particular dictionary attribute. The attribute may be specified by name or by hou.Attrib object. See hou.Prim.floatAttribValue for more information.
dictListAttribValue(name_or_attrib)
→ tuple
of str
Return the primitive attribute value for a particular dictionary attribute. The attribute may be specified by name or by hou.Attrib object. The return value is a tuple of dictionaries.
It is valid to call this method when the attribute’s size is 1. In this case, a tuple with one element is returned. See hou.Prim.floatAttribValue for more information.
setAttribValue(name_or_attrib, attrib_value)
Store an attribute value in this primitive. The attribute may be specified by name or by hou.Attrib object, and must be an existing primitive attribute in the geometry. You would typically call this method from the code of a Python-defined SOP.
Raises hou.OperationFailed if no attribute exists with this name or if the attribute’s data type does not match the value passed in. If the attribute’s size is more than 1, the attribute value must be a sequence of integers/floats, and the size of the sequence must match the attribute’s size.
If the attribute is an array, the seqeunce must be a flat array, not an array of tuples. If the attribute is float, ensure the python objects are float, and not integer (1.0, not 1).
Raises hou.GeometryPermissionError if this geometry is not modifiable.
# Create a float primitive attribute of size 3 named "Cd", and assign # each primitive a unique color. This code will work from inside a Python # SOP, but not from the Python shell. geo = hou.pwd().geometry() color_attrib = geo.addAttrib(hou.attribType.Prim, "Cd", (1.0, 1.0, 1.0)) num_prims = len(geo.prims()) color = hou.Color() for prim in geo.prims(): fraction = float(prim.number()) / num_prims # Give each primitive a different hue, but full saturation and value. # Store the RGB value in the attribute. color.setHSV((fraction * 255, 1, 1)) prim.setAttribValue(color_attrib, color.rgb())
attribType()
→ hou.attribType enum value
Return the enumerated value hou.attribType.Prim. Points, primitives, vertices, and geometry support the same set of methods for querying their attributes, and this method is one of them.
See also:
intrinsicValueDict()
→ dict
of str
to value
Returns a dictionary mapping intrinsic names to their values.
intrinsicValue(intrinsic_name)
→ int
, float
, str
, or tuple
Gets the value of an “intrinsic”, often computed, value of the primitive, such as bounds, measuredarea, vertexcount, and so on.
Most intrinsic values are computed, such as measuredarea, however a few are writeable with hou.Prim.setIntrinsicValue.
For example, sphere primitives have a transform matrix as part of their definition.
You can also view these values in the user interface using the geometry spreadsheet.
Raises hou.OperationFailed if the given intrinsic name does not exist. You can get a list of the available intrinsic value names with hou.Prim.intrinsicNames. Different primitive types will have different intrinsic values available.
Bounding box intrinsic values like bounds or packedbounds are returned
in (xmin, xmax, ymin, ymax, zmin, zmax) order.
intrinsicNames()
→ tuple
of str
Returns a tuple of strings representing the intrinsic values available for this primitive. Different primitive types will have different intrinsic values available. You can then get or set the value using hou.Prim.intrinsicValue and/or hou.Prim.setIntrinsicValue.
setIntrinsicValue(intrinsic_name, value)
Some “intrinsic” values can be modified. For example, you change the internal size and rotation (transform) of a sphere primitive by passing a 9 float tuple representing the transform to hou.Prim.setIntrinsicValue. Raises hou.OperationFailed if the intrinsic is not writeable or does not accept the passed value, or if the given intrinsic name does not exist.
intrinsicReadOnly(intrinsic_name)
→ bool
Returns whether the intrinsic is read-only or can be modified with hou.Prim.setIntrinsicValue.
intrinsicSize(intrinsic_name)
→ int
Returns the intrinsic value’s tuple size.
positionAtInterior(u, v, w=0.0)
→ hou.Vector3
Given normalized (i.e. from 0 to 1) u, v, w values, return the interior position of the primitive at that parametric location.
Use hou.Face.positionAt for querying positions along the perimeter.
attribValueAtInterior(attrib_or_name, u, v, w=0.0)
→ int
, float
, str
or tuple
Return an attribute value at the normalized u, v, w parametric position in the interior of the primitive.
Raises hou.OperationFailed if the attribute is not a point or vertex attribute. If you want a primitive attribute value, it doesn’t vary across the surface, so use hou.Prim.attribValue.
If the attribute name is “N” the primitive’s intrinsic normal is evaluated, not the value from any point or primitive attributes.
Use hou.Face.attribValueAt for querying attributes along the perimeter.
geometry()
→ hou.Geometry
Return the hou.Geometry object containing this primitive.
number()
→ int
Return the number of this primitive. Primitives are numbered sequentially starting from 0, and the primitives returned by hou.Geometry.prims are in order by their number.
type()
→ hou.primType enum value
Return a hou.primType value containing the type of this primitive (e.g. polygon, NURBS curve, metaball, etc).
vertices()
→ generator of hou.Vertex
Return a sequence of the vertices contained in this primitive.
If the primitive is a face (e.g. a polygon or NURBS curve), the result corresponds to the order of the vertices in that face. If it is a surface (e.g. a NURBS mesh), however, the primitive has a 2D array of vertices, and this method returns all vertices in the 2D array, ordered by the rows.
See hou.Surface.vertex for more information about the relationship between the 2D vertex array and the sequential vertex index, and for more ways to access the vertices in a surface.
numVertices()
→ int
A shortcut for len(self.vertices()). You probably don’t need to call
this method.
points()
→ list of hou.Point
Shortcut for getting all the points of a primitive without iterating through each vertex.
boundingBox()
→ hou.BoundingBox
Return an axis-aligned 3D bounding box that is sized and positioned to be large enough to hold this primitive.
nearestToPosition(pos3)
Given a sequence of three floats containing a position, find the location on this primitive that is closest to that position. Returns a tuple containing the u value on this primitive, the v value on this primitive, and the distance to this primitive.
NOTE: The returned UVs are in real coordinates, use the primuvConvert to switch to unit coordinates to match VEX’s xyzdist.
primuvConvert(uv, mode, tol)
Given a 2D uv coordinate, compute the location in a different coordinate system. The tol argument is optional. See the primuvconvert VEX function for the different valid modes.
primuConvert(u, mode, tol)
Given a 1D u coordinate, compute the location in a different coordinate system. The tol argument is optional. See the primuvconvert VEX function for the different valid modes.
groups()
→ tuple
of hou.PrimGroup
Return a tuple of the primitive groups that contain this primitive.