An attribute describes extra data you can attach to different elements of geometry. The attribute values are the individual instances of that data, and for each attribute there is exactly one attribute value per geometry element. For example, if you look at the points in Houdini’s geometry spreadsheet, the point numbers are listed down the side, the point attributes are listed across the top, and the point attribute values are contained in the table.
The attribute specifies which elements store the attribute values: points, primitives, or vertices. An attribute can also be global (also known as a detail attribute), in which case there is one instance of the attribute value in the geometry.
The attribute also specifies the data type of the attribute values.
To look up existing attributes, use hou.Geometry.findPointAttrib, hou.Geometry.findPrimAttrib, hou.Geometry.findVertexAttrib, and hou.Geometry.findGlobalAttrib. To add a new attribute, use hou.Geometry.addAttrib.
Note
Point positions are stored in a point attribute named P and point weights
are stored in Pw. See hou.Point.position and
hou.Point.weight for more information.
Methods ¶
name()
→ str
Return the attribute’s name. Each attribute in the geometry has a unique name.
type()
→ hou.attribType enum value
Return the type of attribute (point, primitive, vertex, or global).
dataType()
→ hou.attribData enum value
Return the attribute’s data type (int, float or string).
The size of the attribute also determines the format of the attribute
values. For example, if the data type is int and the size is 3,
the attribute value will be a tuple of 3 ints. If the size was 1,
the attribute value would simply be an int.
Note that a string attribute’s size must be 1.
numericDataType()
→ hou.numericData enum value
Return the numeric (int, float) attribute’s precision.
isArrayType()
→ bool
Return True if the attribute is a type that contains array data (i.e. Float Array, Integer Array, String Array) and False otherwise.
qualifier()
→ str
Return the attribute’s type qualifier. The qualifier is a description
of the data contained in the attribute. An empty string is returned
if the attribute has no numeric representation or if the
attribute is the pseudo Pw point attribute.
size()
→ int
Return the number of data components in the attribute value. See hou.Attrib.dataType for more information.
setSize()
Sets the number of data components in the attribute value. See hou.Attrib.dataType for more information.
defaultValue()
→ int
or float
or str
or tuple
Return the attribute’s default value. Returns a single int/float/string for attributes of size 1 and a tuple of values for attributes with more than one component.
This method is useful when duplicating an attribute. See hou.Geometry.addAttrib for an example.
strings()
→ tuple of str
Return the string table for this attribute. If the attribute is not a string, returns an empty tuple.
A string attribute does not store each string value inside the attribute element (i.e. point, primitive, etc.). Instead, the unique string attribute values are stored in a table inside the attribute, and each attribute value stores an index to that string.
For example, suppose this attribute stores strings on points. If
all points have the attribute value "foo" then the string table will be
just ("foo",) and each point will store the index 0. When you set some
points' values to "bar", Houdini adds sets the string table to
("foo", "bar") and sets stores the index 1 in those points. When you set
one of those points back to "foo", Houdini leaves the string table
unchanged and stores the index 0 in that point.
When using string attribute values, this implementation is hidden from you, and you get and set those attributes as strings. This method is provided only in case you need access to the string table.
replaceString(before, after)
→ bool
Replace a string in the attribute’s string table.
This changes the string value for all elements that had the before value,
without iterating over all these elements.
You can get the current table of strings using hou.Attrib.strings.
Returns True if an element was replaced. Returns False if the attribute
doesn’t have a string table or before string wasn’t found.
Note
The attribute drops a table entry when the replacement action would result in a duplicate. All elements are then updated so they point to the remaining entry.
dicts()
→ tuple of dict
Return the dictionary table for this attribute. If the attribute is not a dictionary, returns an empty tuple.
A dictionary attribute does not store each dictionary value inside the attribute element (i.e. point, primitive, etc.). Instead, the unique dictionary attribute values are stored in a table inside the attribute, and each attribute value stores an index to that dictionary.
For example, suppose this attribute stores dictionaries on points. If all
points have the attribute value { "foo" : 1 } then the dictionary table
will be just ({ "foo" : 1 },) and each point will store the index 0.
When you set some points' values to { "bar" : 2}, Houdini adds sets the
dictionary table to ({"foo":1}, {"bar":2}) and sets stores the index 1 in
those points. When you set one of those points back to {"foo":1},
Houdini leaves the dictionary table unchanged and stores the index 0 in
that point.
When using dictionary attribute values, this implementation is hidden from you, and you get and set those attributes as dictionaries. This method is provided only in case you need access to the dictionary table.
indexPairPropertyTables()
→ tuple of hou.IndexPairPropertyTable
Return the property tables for this attribute. If the attribute is not an index pair, returns an empty tuple.
geometry()
→ hou.Geometry
Return the Geometry object containing this attribute.
isTransformedAsNormal()
→ bool
Return whether attribute values in the geometry are automatically transformed as a normal when Houdini transforms (e.g. rotates) the geometry.
For more information, see the hou.Geometry.addAttrib, in the
transform_as_normal parameter documentation.
destroy()
Remove this attribute 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.
Raises hou.OperationFailed if you try to destroy the P or Pw
point attributes.
options()
→ dict
of str
to bool
, int
, float
, str
Return a dictionary containing the extra options attached to this attribute.
Note that the contents of this dictionary are saved to geometry files.
See also hou.Attrib.option, hou.Attrib.setOption and hou.Attrib.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.Attrib.options, hou.Attrib.setOption and hou.Attrib.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.Attrib.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.Attrib.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 attribute.
incrementDataId()
Increment the data id to indicate that the contents of this attribute has changed.