| Inheritance |
|
Methods ¶
resolution()
→ hou.Vector3
Return the x, y, and z dimensions of the volume. For example, a resolution of (10, 20, 30) means the volume is 10 voxels in x by 20 voxels in y by 30 voxels in z.
sample(position)
→ float
Given a sequence of three floats containing a 3D position, return the value of the volume at that position. If the position is not in the middle of a voxel, Houdini will interpolate using values from surrounding voxels.
See also hou.Volume.voxel and hou.Volume.posToIndex.
gradient(position)
→ hou.Vector3
Given a sequence of three floats containing a 3D position, return a vector which points in the direction of the greatest rate of increase of the volume’s value.
See Wikipedia’s gradient page for more information.
voxel(index)
→ float
Given a sequence of three integers containing a voxel index, return the value of the corresponding voxel.
>>> volume_sop = hou.node("/obj").createNode("geo").createNode("volume") >>> volume_sop.parm("initialval1").set(0.3) >>> volume = volume_sop.geometry().prims()[0] >>> volume.resolution() (10, 10, 10) >>> volume.voxel((0, 0, 0)) 0.3
setVoxel(index, value)
Set the value of a voxel. You would typically call this method from the code of a Python-defined SOP.
index
A sequence of three integers containing a voxel index. Raises hou.OperationFailed if any of the values in index are out of range.
value
A float containing the voxel’s new value.
Raises hou.GeometryPermissionError if this geometry is not modifiable.
allVoxels()
→ tuple of float
Return a tuple of floats containing the values of all voxels. It is faster to call this method to retrieve all the voxels than it is to loop through the voxel array in Python.
You can, for example, use Python’s Numpy library to perform operations on the voxel data and then store the result back into the volume from a Python SOP using hou.Volume.setAllVoxels. Note that Numpy allows you to reshape the flat tuple of floats to behave like a 3D matrix of floats.
This method can be approximately implemented as follows (though this Python implementation is much slower):
def allVoxels(self): result = [] xres, yres, zres = self.resolution() for z in range(zres): for y in range(yres): for x in range(xres): result.append(self.voxel((x, y, z))) return tuple(result)
See also hou.Volume.allVoxelsAsString, hou.Geometry.pointFloatAttribValues, and hou.Geometry.primFloatAttribValues.
allVoxelsAsString()
→ str
for Python 2, bytes
for Python 3
Return a binary string representation of the floats
containing all the values of all voxels. This method is faster than
hou.Volume.allVoxels, and you can use the array module to convert
the string into a Python sequence.
The returned binary string is a bytes object in Python 3 and a str
object in Python 2. See HOM binary data for more
information.
This method provides a faster implementation of the following:
import array def allVoxelsAsString(self): return array.array("f", self.allVoxels()).tostring()
You can convert the return value from this method to an array using the following method:
import array def allVoxelsAsArray(volume): a = array.array("f") a.fromstring(volume.allVoxelsAsString()) return a
See hou.Volume.allVoxels for more information.
setAllVoxels(values)
Set the value of all voxels in this volume. You would typically call this method from the code of a Python-defined SOP.
Raises hou.OperationFailed if the sequence of values is not exactly
the same as self.resolution()[0] * self.resolution()[1] *
self.resolution()[2].
Raises hou.GeometryPermissionError if this geometry is not modifiable.
See also hou.Volume.allVoxels.
setAllVoxelsFromString(values)
Set the value of all voxels in this volume from a string representation of a sequence of single precision float values. This method is faster than hou.Volume.setAllVoxels.
Note that this method can accept more types that just a string: it can
receive any Python object that supports the buffer interface. In
particular, arrays from the array and numpy Python modules are
supported, so there is no need to first construct strings from those
arrays.
Raises hou.OperationFailed if the length of the string is not exactly
the same as self.resolution()[0] * self.resolution()[1] *
self.resolution()[2] * 4.
See hou.Volume.setAllVoxels and hou.Volume.allVoxelsAsString for more information.
The following example function accepts an array.array("f") and sets
the voxels to its contents:
def setAllVoxelsFromArray(volume, arr): assert(arr.typecode == "f") volume.setAllVoxelsFromString(arr)
voxelSlice(plane, index)
→ tuple
of float
Return a tuple of floats containing the values of all voxels in a particular slice. It is faster to call this method to retrieve a slice than it is to loop through the voxel array in Python.
plane
The plane corresponding to this slice. This value must be either “xy”, “xz”, or “yz”.
index
The index of this slice in the array. For example, if the plane is “xy”, this index is the z value and the result will contain all values in the voxel with this particular z value.
This method can be approximately implemented as follows (though this Python implementation is much slower):
def voxelSlice(self, plane, index): result = [] start = [0] * 3 stop = list(self.resolution()) slice_axis = {"xy": 2, "xz": 1, "yz": 0}[plane] start[slice_axis] = index stop[slice_axis] = index + 1 for z in range(start[2], stop[2]): for y in range(start[1], stop[1]): for x in range(start[0], stop[0]): result.append(self.voxel((x, y, z))) return tuple(result)
See also hou.Volume.voxelSliceAsString and hou.Volume.allVoxels.
voxelSliceAsString(plane, index)
→ str
Return a binary string representation of the floats containing all the values of voxels in a particular slice.
The returned binary string is a bytes object in Python 3 and a str
object in Python 2. See HOM binary data for more
information.
See hou.Volume.voxelSlice and hou.Volume.allVoxelsAsString for more information.
setVoxelSlice(values, plane, index)
Set the value of the voxels in a particular slice of this volume. You would typically call this method from the code of a Python-defined SOP.
values
A sequence of floats containing the new values for the slice.
plane
The plane corresponding to this slice. This value must be either “xy”, “xz”, or “yz”.
index
The index of this slice in the array. For example, if the plane is “xy”, this index is the z value and the result will contain all values in the voxel with this particular z value.
Raises hou.OperationFailed if the sequence of values is not equal to the number of voxels in the slice.
Raises hou.GeometryPermissionError if this geometry is not modifiable.
See also hou.Volume.voxelSlice. See hou.Volume.setVoxelSliceFromString for an example.
setVoxelSliceFromString(values, plane, index)
Set the value of the voxels in a particular slice of this volume. You would typically call this method from the code of a Python-defined SOP.
values
A binary string representing of a sequence of floats containing the new values for the slice.
Note that this method can accept more types that just a string: it can
receive any Python object that supports the buffer interface. In
particular, arrays from the array and numpy Python modules are
supported, so there is no need to first construct strings from those
arrays.
plane
The plane corresponding to this slice. This value must be either “xy”, “xz”, or “yz”.
index
The index of this slice in the array.
See hou.Volume.setVoxelSlice for more information.
The following example builds a volume from an compositing network sequence:
def buildVolumeFromCopSequence( cop_node, geo, voxel_depth, plane="C", component="r"): zres = int(cop_node.sequenceFrameLength()) volume_bbox = hou.BoundingBox(*( 0, 0, 0, cop_node.xRes(), cop_node.yRes(), zres) * voxel_depth) volume = geo.createVolume( cop_node.xRes(), cop_node.yRes(), zres, volume_bbox) for z in range(zres): pixels = cop_node.allPixelsAsString( plane, component, time=hou.frameToTime(z + cop_node.sequenceStartFrame())) volume.setVoxelSliceFromString(pixels, "xy", z)
posToIndex(position)
→ tuple
of int
Given a sequence of three floats containing a 3D position, return a tuple of three ints containing the corresponding index into the voxel array.
Note that the returned index will be invalid if the position is outside the volume. Use hou.Volume.isValidIndex to determine if the index is valid.
indexToPos(index)
→ hou.Vector3
Given a sequence of three ints containing an index into the voxel array, return the corresponding 3D position of the middle of that voxel.
isValidIndex(index)
→ bool
Return whether or not a sequence of three ints containing an index into the voxel array is valid, ie, within the bounds of the array.
This method can approximately be implemented as follows:
def isValidIndex(self, index): for i, maximum in zip(index, self.resolution()): if i < 0 or i >= maximum: return False return True
isSDF()
→ bool
Return whether or not the volume is flagged as a signed distance field. Such volumes have a special border condition where out of bound reads will add the distance to the bounding box to the streaked boundary condition. They are also best to be semantically treated as signed distance fields.
isHeightField()
→ bool
Return whether or not the volume is flagged as a heightfield. Such volumes are two dimensional and have the heightfield visualization set.
volumeAverage()
→ float
Return the average value of all voxels.
volumeMin()
→ float
Return the minimum value of all voxels.
volumeMax()
→ float
Return the maximum value of all voxels.
transform()
→ hou.Matrix3
Return a 3×3 matrix containing the scale and rotation transformations for this volume.
Note that the position information for the volume can be obtained by
calling volume.vertex(0).point().position().
The following function returns a 4×4 transformation matrix for the volume that includes the translation:
def fullTransform(volume): return (hou.Matrix4(volume.transform()) * hou.hmath.buildTranslate(volume.vertex(0).point().position()))
Note
You need to get the node transform to get to worldspace.
setTransform(matrix4)
Given a 4×4 matrix, set the position, rotation, and scale of this volume.
Note that if you want to just set the translate portion of a volume to a
hou.Vector3, you could just call
volume.vertex(0).point().setPosition(position).
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.
voxelSize()
→ hou.Vector3
Returns the size of voxels within the volume. All voxels will be of this size for untapered volumes.
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.