If you ask a COP for its geometry via the hou.CopNode.layer, you’ll cook the COP and get a read-only hou.ImageLayer. Unlike with SOPs and Geometry objects, the result is no longer tied to the COP Node so it stays the same if the COP node recooks or is deleted.
Call hou.ImageLayer.freeze to edit an ImageLayer. This returns another ImageLayer object that’s an independent writeable copy. Writing to the frozen layer doesn’t affect the earlier read-only versions.
Methods ¶
close()
Resets this object to be an empty object. This stops it holding a reference to the underlying ImageLayer data. This will also happen when the object goes out of scope and is garbage collected, but the close() provides exact control over the timing.
ImageLayers also support contexts so the with statement can be used to auto-close the nanovdb at the with-block end.
storageType()
→ hou.imageLayerStorageType enum value
Returns the layer’s storage type, which consists of its precision and float vs integer type.
border()
→ hou.imageLayerBorder enum value
Returns the layer’s border type.
typeInfo()
→ hou.imageLayerTypeInfo enum value
Returns the semantic type of the layer. This is used for things like automatic visualizations.
setStorageType(storagetype: hou.imageLayerStorageType)
Changes the storage type of the layer. Existing data will be lost.
Requires a writable layer.
setBorder(border: hou.imageLayerBorder)
Changes the border of the layer.
Requires a writable layer.
setTypeInfo(typeinfo: hou.imageLayerTypeInfo)
Changes the semantic type of the layer.
Requires a writable layer.
channelCount()
→ int
Returns the number of channels in the layer.
setChannelCount(chan: int)
Changes the number of channels in the layer. Existing data will be lost. Must be within 1 and 4.
Requires a writable layer.
isMetadataOnly()
→ bool
Returns true if the layer is a metadata layer and therefore holds no pixel values.
setIsMetadataOnly()
Marks this layer as being metadata only. This is necessary to set when a metadata layer is output from a Python Snippet COP for example.
Requires a writable layer.
setChannelCount(chan: int)
Changes the number of channels in the layer. Existing data will be lost. Must be within 1 and 4.
Requires a writable layer.
bufferResolution()
→ tuple of int
Returns the underlying buffer size. This is the number of data elements in the X and Y directions. When PixelScale is 1, this corresponds to the number of pixels.
onCPU()
→ bool
An ImageLayer may be stored on the CPU or GPU. This is true if it is stored on the CPU.
onGPU()
→ bool
An ImageLayer may be stored on the CPU or GPU. This is true if it is stored on the GPU.
isConstant()
→ bool
True if the layer is compressed as a single constant value. Note that a layer that has all the same values will not necessarily return True, as this only detects if it has been collapsed to a single constant value.
makeConstant(val: [float, ...])
Collapse the layer into a single constant value of the value provided. Value should be a tuple which will be extended to the required number of channels.
Requires a writable layer.
expandConstant()
Expands constant layers into dense layers.
Requires a writable layer.
storesIntegers()
→ bool
True if the layer holds integer data.
dataWindow()
→ hou.BoundingRect
Return the data window. This is the area, in pixels, that the buffer elements cover.
displayWindow()
→ hou.BoundingRect
Return the display window. This is the area, in pixels, that is framed to Image space.
pixelAspectRatio()
→ float
The ratio Image space coordinates and pixel coordinates.
pixelScale()
→ tuple of float
The scaling factor between the pixel values and the underlying
buffer elements. This is the number of pixels in each dimension
that fit in a buffer element. Thus (2,2) would create one buffer
element for every 2×2 block of pixels.
setDataWindow(x: float, y: float, w: float, h: float)
Set the buffer to cover the provided pixels. The actual size of the buffer will vary according to pixel scale. If pixel scale is 1, w and h will be the resolution. Existing data will be lost.
This requires a writable layer.
setDisplayWindow(x: float, y: float, w: float, h: float)
Set the area in pixels that're framed by the Image space conversion.
This requires a writable layer.
setPixelAspectRatio(aspect: float)
Set the ratio between pixel space and image space.
This requires a writable layer.
setPixelScale(scale: float)
Set the scaling between buffer space and pixel space.
This requires a writable layer.
voxelSize()
→ hou.Vector3
Returns the layer’s world space voxel size. The resulting x and y
components correspond to a pixel’s width and height in world space.
projection()
→ hou.imageLayerProjection
Returns the style of projection performed by the layer’s implicit camera.
aperture()
→ float
Returns the width of the camera aperture, nominally in mm, but
most importantly in the same units as focalLength.
focalLength()
→ float
Returns the focal length of the camera, nominally in mm, but
most importantly in the same units as aperture.
cameraPosition()
→ tuple of float
The location of the projection point of the camera as measured from the center of image space.
fStop()
→ float
The camera’s FStop.
clippingRange()
→ tuple of float
The clipping range of the layer’s camera.
focusDistance()
→ float
The location of the focus plane of the camera.
imagingDistance()
→ float
The location of the imaging plane of the camera.
guideScale()
→ float
When the layer is metadata, the size of the camera that is displayed.
shutter()
→ tuple of float
The duration of the camera’s shutter. This is measured relative to a nominal zero point.
setProjection(projection: hou.imageLayerProjection)
Change the projection type of the camera.
setAperture(aperture: float)
Set the camera’s aperture.
setFocalLength(focal: float)
Set the camera’s focal length.
setCameraPosition(pos: [float, float, float])
Adjust the position of the focus point of the camera, as measured in the image space of the layer.
setFStop(fstop: float)
Set the camera’s FStop.
setClippingRange(range: [float, float])
Set the camera’s near/far clipping range.
setFocusDistance(focus: float)
Set the camera’s focus distance.
setImagingDistance(imagingdist: float)
Set the camera’s imaging distance.
setGuideScale(scale: float)
Set the camera’s guide scale. This is the size of the camera being displayed when the layer is metadata.
setShutter(shutter: [float, float])
Set the camera’s shutter.
projectionTransform()
→ hou.Matrix4
Compute the transform from world space to image space, including the camera’s projection.
imageToWorldTransform()
→ hou.Matrix4
Compute the non-projective transform from image space to world space.
setImageToWorldTransform(matrix4)
Set the transform from image space to world space.
transform(matrix4)
Modify the image to world transform by applying an additional transform afterward.
imageToPixelScale()
→ tuple of float
Return the scale factor from image space to pixel space.
imageToPixelTranslate()
→ tuple of float
Return the offset from image space to pixel space.
imageToBufferScale()
→ tuple of float
Return the scale factor from image space to buffer space.
imageToBufferTranslate()
→ tuple of float
Return the offset from image space to buffer space.
bufferToPixelScale()
→ tuple of float
Return the scale factor from buffer space to pixel space.
bufferToPixelTranslate()
→ tuple of float
Return the offset from buffer space to pixel space.
textureToBufferScale()
→ tuple of float
Return the scale factor from texture space to buffer space.
imageToPixel(p: [float, float])
→ tuple of float
Convert a 2-tuple from image space to pixel space.
imageToBuffer(p: [float, float])
→ tuple of float
Convert a 2-tuple from image space to buffer space.
imageToTexture(p: [float, float])
→ tuple of float
Convert a 2-tuple from image space to texture space.
imageToWorld(p: [float, float])
→ tuple of float
Convert a 2-tuple from image space to world space.
image3ToWorld(p: [float, float, float])
→ tuple of float
Convert a 3-tuple from image space to world space.
imageToLocal(p: [float, float])
→ tuple of float
Convert a 2-tuple from image space to local space.
image3ToLocal(p: [float, float, float])
→ tuple of float
Convert a 3-tuple from image space to local space.
pixelToImage(p: [float, float])
→ tuple of float
Convert a 2-tuple from pixel space to image space.
pixelToBuffer(p: [float, float])
→ tuple of float
Convert a 2-tuple from pixel space to buffer space.
pixelToTexture(p: [float, float])
→ tuple of float
Convert a 2-tuple from pixel space to texture space.
bufferToPixel(p: [float, float])
→ tuple of float
Convert a 2-tuple from buffer space to pixel space.
bufferToImage(p: [float, float])
→ tuple of float
Convert a 2-tuple from buffer space to image space.
bufferToTexture(p: [float, float])
→ tuple of float
Convert a 2-tuple from buffer space to texture space.
textureToPixel(p: [float, float])
→ tuple of float
Convert a 2-tuple from texture space to pixel space.
textureToImage(p:[float, float])
→ tuple of float
Convert a 2-tuple from texture space to image space.
textureToBuffer(p: [float, float])
→ tuple of float
Convert a 2-tuple from texture space to buffer space.
worldToBuffer(p: [float, float, float])
→ tuple of float
Convert a 3-tuple from world space to buffer space.
worldToImage(p: [float, float, float])
→ tuple of float
Convert a 3-tuple from world space to image space, returning a 2-tuple.
worldToImage3(p: [float, float, float])
→ tuple of float
Convert a 3-tuple from world space to image space, returning a 3-tuple.
worldToLocal(p: [float, float, float])
→ tuple of float
Convert a 3-tuple from world space to local space, returning a 3-tuple.
localToImage(p: [float, float, float])
→ tuple of float
Convert a 3-tuple from local space to image space, returning a 2-tuple.
localToImage3(p: [float, float, float])
→ tuple of float
Convert a 3-tuple from local space to image space, returning a 3-tuple.
localToWorld(p: [float, float, float])
→ tuple of float
Convert a 3-tuple from local space to world space, returning a 3-tuple.
bufferIndexV4(int x, int y)
→ tuple of float
Returns a layer’s RGBA value at the buffer coordinate (x, y).
bufferIndexI(int x, int y)
→ int
Returns an integer layer’s value at the buffer coordinate (x, y).
bufferIndex(int x, int y)
→ tuple of float
| float
| int
Returns a layer’s value at the buffer coordinate (x, y). The return type corresponds to the layer type, for example a mono layer returns a single float value.
bufferIndexRaw(int x, int y)
→ bytes
Returns a layer’s raw bytes at the buffer coordinate (x, y).
setBufferIndexV4(int x, int y, value: [float, float, float, float])
Set an RGBA layer to value at the buffer coordinate (x, y). value must be a list of floats and of size 4, eg. /hom/hou/1.0, 1.0, 1.0, 1.0.html
setBufferIndexI(int x, int y, int value)
Set an integer layer to value at the buffer coordinate (x, y). value must be an int.
setBufferIndex(int x, int y, val: [float, ...] | float | int)
Set a layer to value at the buffer coordinate (x, y). value must be match the layer type, eg. float for a mono layer, list of two floats for a uv layer, …
freeze()
→ hou.ImageLayer
Create a writable copy of this and return it.
Note
The actual buffer duplication won’t be done until a write is performed.
isFrozen()
→ bool
Returns if this is frozen, and hence writable.
attributes()
→ dict
This method is deprecated in favor of hou.ImageLayer.properties. Returns the layer properties present on this layer.
setAttributes(p: dict)
This method is deprecated in favor of hou.ImageLayer.setProperties. Replaces the layer properties with the provided dictionary.
updateAttributes(p: dict)
This method is deprecated in favor of hou.ImageLayer.updateProperties. Updates the layer properties with the provided dictionary, replacing any matching keys.
properties()
→ dict
Returns the layer properties present on this layer.
setProperties(p: dict)
Replaces the layer properties with the provided dictionary.
updateProperties(p: dict)
Updates the layer properties with the provided dictionary, replacing any matching keys.
allBufferElements()
→ hou.BinaryString
Return all the buffer elements as a binary string. This can then
be effeciently re-interpreted and handled by numpy or tensor
packages. The number of elements is the same as the
bufferResolution. The bit depth and channels are the current
values of the layer.
allBufferElements(storagetype: hou.imageLayerStorageType, channels: int)
→ hou.BinaryString
Return all the buffer elements as a binary string. This can then
be effeciently re-interpreted and handled by numpy or tensor
packages. The number of elements is the same as the
bufferResolution. The bit depth and channels returned will
match those provided, a conversion will be performed just-in-time
if they differ from the internal layout.
setAllBufferElements(values: hou.BinaryString, length: int, storagetype: hou.imageLayerStorageType, channels: int)
Take a binary string in values and replace all of the buffer
elements of this layer with them. The binary string must have a
number of elements matching the bufferResolution and be of the
provided storagetype and channels.
Requires a writable layer.
setAllBufferElements(values: hou.BinaryString, length: int)
Take a binary string in values and replace all of the buffer
elements of this layer with them. The binary string must have a
number of elements matching the bufferResolution and be of the
same storagetype and channels as this layer.
computeMin(channel=0)
→ int
or float
Returns the layer’s minimum value across all pixels of the selected channel.
computeMax(channel=0)
→ int
or float
Returns the layer’s maximum value across all pixels of the selected channel.
computeAverage(channel=0)
→ float
Returns the layer’s average value across all pixels of the selected channel.
computeMinLength()
→ float
Returns the layer’s minimum Euclidean length value across all the pixels.
computeMaxLength()
→ float
Returns the layer’s maximum Euclidean length value across all the pixels.