Hip File Tools

The hip_file module provides tools related to dealing with a Houdini scene/session.

check_unsaved_changes

check_unsaved_changes() is a function decorator that can be used to wrap a function where you want to ensure the current hip file is saved before execution. This is useful as an automated pre-check for operations that require the hip to be saved, such as submitting to a render farm.

@check_unsaved_changes()
def submit():
    """Submit to the farm."""
    print("Submitted!")

When the wrapped function is called and there are no unsaved changes, the function will execute as expected:

>>> submit()
Submitted!

However, if there are unsaved changes, it will raise an exception:

>>> submit()
Traceback (most recent call last):
  File "<console>", line 1, in <module>
  File "python/houdini_core_tools/hip_file.py", line 99, in wrapper
  raise hou.OperationFailed("Hip file has unsaved changes")  # noqa: TRY003
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
hou.OperationFailed: The attempted operation failed.
Hip file has unsaved changes

The decorator accepts a prompt parameter and when True, will prompt the user on whether to save and continue, or abort.

>>> submit()
Traceback (most recent call last):
  File "<console>", line 1, in <module>
  File "python/houdini_core_tools/hip_file.py", line 95, in wrapper
    raise hou.OperationFailed("Hip file save declined")  # noqa: TRY003
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
hou.OperationFailed: The attempted operation failed.
Hip file save declined

The prompt execution is wrapped in UI available check so if the code is being executed non-graphically it will be skipped and the check will fail.

get_hip_save_time_from_file

The get_hip_save_time_from_file() function will parse the start of the hip file to try and determine when it was last saved by using the value of $_HIP_SAVETIME.

The result is returned as a datetime.datetime object.

>>> get_hip_save_time_from_file("/path/to/a/file.hip")
datetime.datetime(2025, 2, 5, 5, 33, 57)

get_hip_save_version_from_file

The get_hip_save_version_from_file() function will parse the start of the hip file to try and determine the version of Houdini last used to save the hip file by using the value of $_HIP_SAVEVERSION.

The result is returned as a tuple of integers, similar to hou.applicationVersion().

>>> get_hip_save_version_from_file("/path/to/a/file.hip")
(20, 5, 493)

hip_save_time

The hip_save_time() function will try and determine when the current hip file was last saved.

The result is returned as a datetime.datetime object if the file exists, otherwise None.

>>> hip_save_time()
datetime.datetime(2025, 2, 5, 5, 33, 57)

hip_save_version

The hip_save_version() function will try and determine the version of Houdini last used to save the current hip file.

The result is returned as a tuple of integers, similar to hou.applicationVersion(), if the file exists, otherwise None.

>>> hip_save_version()
(20, 5, 493)

hip_version

The hip_version() function can be used to quickly grab the major version from a hip file name. It does this by simply looking for a v## string in the name and grabbing the number. In the event multiples are contained, the last one is used. Any version number is %02d padded.

untitled.hip -> None
hipname_v00.hip -> "00"
hipname_v01.hip -> "01"
hipname.v01.hip -> "01"
hipname_v00003.hip -> "03"
hipname_v02.03.hip -> "02"
hipname_v05_alternate_v01.hip -> "01"
hipname_v3021.hip -> "3021"

save_copy

Unless you’re super familiar with the intricacies of Houdini files it’s not readily apparent how you would go about saving off a copy of your current session while not saving over the currently open file. It’s not complex, but save_copy() will handle the small bit of work to do it.

>>> hou.hipFile.path()
'/var/tmp/test.hip'
>>> hou.hipFile.hasUnsavedChanges()
True
>>> save_copy("/var/tmp/copy_of_test.hip")
>>> hou.hipFile.hasUnsavedChanges()
True

As previously mentioned, the current state of the session is saved to the new path and the original file remains unchanged with the changes since last change remaining unsaved.

set_frame_range

The set_frame_range() function is a convenience function which handles updating Houdini’s frame and playback ranges to the supplied values. If the current frame is outside of the new range it will be set to the first frame.

>>> hou.playbar.frameRange()
<hou.Vector2 [1, 240]>
>>> hou.playbar.playbackRange()
<hou.Vector2 [1, 240]>
>>> hou.frame()
1.0
>>>
>>> set_frame_range(1001, 1010)
>>>
>>> hou.playbar.frameRange()
<hou.Vector2 [1001, 1010]>
>>> hou.playbar.playbackRange()
<hou.Vector2 [1001, 1010]>
>>> hou.frame()
1001.0