Primitive groups reside inside the geometry, and each primitive group has a unique name.
Groups are either ordered or unordered. When asking for the contents of an
ordered group, the results will be returned in the order they were added to
to the group. For an unordered group, the results will be returned in an
arbitrary order (though it is normally arranged by increasing primitive number).
When creating a group using the group SOP, use the ‹Create Ordered› checkbox
to create an ordered group. When creating one from Python, Use the
is_ordered
parameter of hou.Geometry.createPrimGroup to control
whether a group is ordered.
See hou.Prim for more information about primitives. See also hou.PointGroup, hou.VertexGroup, and hou.EdgeGroup.
Methods ¶
name()
Return the name of the group. Each primitive group has a unique name.
geometry()
→ hou.Geometry
Return the geometry object containing this group.
prims()
→ tuple
of hou.Prim
Return the contents of this group.
See also hou.PrimGroup.iterPrims.
iterPrims()
→ generator of hou.Prim
Return a generator that iterates through all the contents of this group.
Whereas hou.PrimGroup.prims allocates and returns a tuple of all the primitives in the group, this method returns a generator object that will yield hou.Prim objects on demand.
contains(prim)
→ bool
Return whether or not a primitive is in this group.
Raises hou.OperationFailed if the primitive belongs to a different geometry object than this group.
primCount()
→ int
Returns the number of primitives in this group.
isOrdered()
→ bool
Returns whether or not this group is ordered.
add(prim_or_list_or_prim_group)
If given a hou.Prim or a list of hou.Prim's, add the primitive(s) to the group. If given a hou.PrimGroup, merge the contents of the other primitive group with this group (the other group is unaffected). You would typically call this method from the code of a Python-defined SOP.
It is okay to add primitives to the group that were already in the group.
Raises hou.GeometryPermissionError if this geometry is not modifiable.
Raises hou.OperationFailed if the primitive or primitive group belong to a different geometry object than this group.
remove(prim_or_list_or_prim_group)
If given a hou.Prim or a list of hou.Prim's, remove the primitive(s) from the group. If given a hou.PrimGroup, remove all primitives in the other group from this group (the other group is unaffected). You would typically call this method from the code of a Python-defined SOP.
It is not an error to try to remove a primitive from the group that wasn’t already in the group.
Raises hou.GeometryPermissionError if this geometry is not modifiable.
Raises hou.OperationFailed if the primitive belongs to a different geometry object than this group.
clear()
Remove all primitives from this group. You would typically call this method from the code of a Python-defined SOP.
The primitives remain in the geometry; only the group is affected.
Raises hou.GeometryPermissionError if this geometry is not modifiable.
destroy()
Remove this group from the geometry. You would typically call this method from the code of a Python-defined SOP.
Raises hou.GeometryPermissionError if this geometry is not modifiable.
options()
→ dict
of str
to bool
, int
, float
, str
Return a dictionary containing the extra options attached to this primitive group.
Note that the contents of this dictionary are saved to geometry files.
See also hou.PrimGroup.option, hou.PrimGroup.setOption and hou.PrimGroup.removeOption.
option(name)
→ bool
, int
, float
, str
, hou.Vector2, hou.Vector3, hou.Vector4, hou.Quaternion, hou.Matrix3, hou.Matrix4, tuple of int
, or tuple of float
Return the value of an individual option, on None
if no such option
exists.
See also hou.PrimGroup.options, hou.PrimGroup.setOption and hou.PrimGroup.removeOption.
optionType(name)
→ hou.fieldType enum value
Return a hou.fieldType enumerated value that describes the type
of data stored in an option. Returns hou.fieldType.NoSuchField
if
no field exists with that name.
setOption(name, value, type_hint = hou.fieldType::NoSuchField)
Set an entry in the dictionary of options. See hou.PrimGroup.options for more information.
name
The name of the option to set.
value
An integer, float, string, hou.Vector2, hou.Vector3, hou.Vector4, hou.Quaternion, hou.Matrix3, hou.Matrix4, or sequence of numbers.
type_hint
Used to determine the exact hou.fieldType desired when the specified value type is not enough to unambiguously determine it.
removeOption(name)
Remove an entry in the dictionary of options. See hou.PrimGroup.options for more information.
Raises hou.OperationFailed if there is no entry in the dictionary with this name.
dataId()
Returns the data id that represents the contents of this group.
incrementDataId()
Increment the data id to indicate that the contents of this group has changed.