Skip to content

Core Utils

OmniStep includes a set of utility classes accessible through core.util. These provide common operations for objects, animation, collections, and materials - handling the boilerplate that Blender's API typically requires.

core.util.obj

core.util.obj.duplicate(source, target_collection=None, linked=True, include_children=False, clear_animation=False)

Duplicates a Blender object. By default creates a linked copy (shared mesh data). Preserves parenting and animation data unless told otherwise. If no target collection is specified, the copy is placed in the source's collection. :::params source (Object) - Object to duplicate. target_collection (Collection) - (Optional) collection to place the copy in. linked (bool) - (Optional) if True, shares mesh data with the source. If False, creates an independent copy. include_children (bool) - (Optional) duplicate the full child hierarchy. clear_animation (bool) - (Optional) strip all animation data from the copy. :::return new_obj (Object) - The duplicated object.

core.util.obj.delete(target, include_children=False)

Removes an object from all collections and deletes it. Optionally deletes the full child hierarchy. :::params target (Object) - Object to delete. include_children (bool) - (Optional) also delete all children recursively.

core.util.obj.align_to(source, target, mode='lrs')

Aligns one object to another. The mode string controls which components are copied: l for location, r for rotation, s for scale. Any combination works — e.g. 'lr' copies position and rotation but keeps the original scale. :::params source (Object) - Object to move. target (Object) - Object to align to. mode (string) - (Optional) combination of l, r, s. Defaults to 'lrs'.

core.util.obj.align_to_ray(target, pos, direction, forward='Y', up='Z')

Positions and orients an object along a ray direction. Useful for placing objects at hit points from raycasts. Scale is preserved. :::params target (Object) - Object to align. pos (Vector) - World position to place the object. direction (Vector) - Direction to orient the forward axis along. forward (string) - (Optional) which local axis points along the direction. Defaults to 'Y'. up (string) - (Optional) which axis is treated as up. Defaults to 'Z'.

core.util.obj.translate(target, vec, space='local')

Moves an object by a vector in local or global space. :::params target (Object) - Object to move. vec (Vector) - Translation offset. space (string) - (Optional) 'local' or 'global'. Defaults to 'local'.

core.util.obj.rotate(target, angle, axis, origin, space='global')

Rotates an object around a point. The rotation is applied around origin, not the object's own center. :::params target (Object) - Object to rotate. angle (float) - Rotation angle in radians. axis (Vector) - Axis to rotate around. origin (Vector) - World-space pivot point. space (string) - (Optional) 'global' or 'local'. Defaults to 'global'.

core.util.obj.ray_cast(target, pos, direction)

Casts a ray against a single mesh object, handling the local-space conversion internally. :::params target (Object) - Mesh object to test against. pos (Vector) - Ray origin in world space. direction (Vector) - Ray direction in world space. :::return hit, location, normal, index (bool, Vector, Vector, int) - Hit result. Location and normal are in world space. Returns False, None, None, -1 on miss or non-mesh objects.

core.util.obj.get_children(target)

Returns all children of an object recursively, flattened into a single list. :::params target (Object) - Parent object. :::return children (list) - All descendant objects.

core.util.anim

core.util.anim.key_transform(target, mode='lrs', frame=None, interpolation=None)

Inserts transform keyframes on an object. The mode string controls which channels are keyed: l for location, r for rotation, s for scale. Automatically uses the correct rotation path based on the object's rotation mode. Optionally sets the interpolation type on the inserted keyframes. :::params target (Object) - Object to keyframe. mode (string) - (Optional) combination of l, r, s. Defaults to 'lrs'. frame (int) - (Optional) frame number. Defaults to current frame. interpolation (string) - (Optional) keyframe interpolation type, e.g. 'LINEAR', 'CONSTANT', 'BEZIER'.

core.util.anim.key_visibility(target, state, frame=None, include_children=False)

Keyframes an object's visibility (hide_viewport and hide_render). When keying at a frame other than the current one, the object's actual visibility is temporarily changed and then restored. :::params target (Object) - Object to keyframe. state (bool) - Visible (True) or hidden (False). frame (int) - (Optional) frame number. Defaults to current frame. include_children (bool) - (Optional) also keyframe all children.

core.util.anim.clear_transform(target)

Deletes all transform fcurves (location, rotation, and scale) from an object. :::params target (Object) - Object to clear.

core.util.anim.delete_fcurves(target, data_paths)

Deletes fcurves matching specific data paths from an object's action. Accepts a single string or a tuple of strings. :::params target (Object) - Object to modify. data_paths (string or tuple) - Data path(s) to remove, e.g. 'location' or ('location', 'scale').

core.util.anim.set_fcurves_state(target, data_paths, mute=False, lock=False)

Mutes or locks fcurves matching specific data paths. Useful for temporarily disabling animation on certain channels. :::params target (Object) - Object to modify. data_paths (string or tuple) - Data path(s) to affect. mute (bool) - (Optional) mute the fcurves. lock (bool) - (Optional) lock the fcurves.

core.util.anim.is_animated(target)

Checks whether an object is considered animated. Returns True if the object has an action, active constraints, an active rigid body, or an animated parent. Also returns True if the custom property ostep.force_animated is set. :::params target (Object) - Object to check. :::return animated (bool) - Whether the object is animated.

core.util.collection

core.util.collection.clear(target)

Removes and deletes all objects from a collection. :::params target (Collection) - Collection to clear.

core.util.collection.get_objects(target, type_filter=None, include_children=False, recursive=False)

Returns a list of objects from a collection, optionally filtered by type. Can include child objects and recurse into sub-hierarchies. :::params target (Collection) - Collection to query. type_filter (string) - (Optional) Blender object type, e.g. 'MESH', 'EMPTY', 'CAMERA'. include_children (bool) - (Optional) include child objects of each collection member. recursive (bool) - (Optional) recurse into children of children. :::return objects (list) - Matching objects.

core.util.mat

core.util.mat.get_shader_node(target, node_name, material_name=None)

Finds a shader node by name on an object's material. If material_name is provided, searches that specific material. Otherwise uses the object's active material. :::params target (Object) - Object with the material. node_name (string) - Name of the shader node to find. material_name (string) - (Optional) specific material to search in. :::return node (ShaderNode) - The shader node, or None if not found.