zBuilder package

Subpackages

Submodules

zBuilder.IO module

class zBuilder.IO.BaseNodeEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: json.encoder.JSONEncoder

default(obj)[source]

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)
zBuilder.IO.dump_json(file_path, json_data)[source]

Saves a json file to disk given a file path and data.

Parameters
  • file_path – The location to save the json file.

  • json_data – The data to save in the json.

Returns

file path if successful.

Raises

IOError – If not able to write file.

zBuilder.IO.find_class(module_, type_)[source]

Given a module and a type returns class object.

Parameters
  • module_ (str) – The module to look for.

  • type_ (str) – The type to look for.

Returns

class object.

Return type

obj

zBuilder.IO.is_sequence(var)[source]

Returns: True if input is a sequence data type, i.e., list or tuple, but not string type. False otherwise.

zBuilder.IO.load_base_node(json_object)[source]

Loads json objects into proper classes. Serves as object hook for loading json.

Parameters

json_object (obj) – json obj to perform action on

Returns

Result of operation

Return type

obj

zBuilder.IO.load_json(file_path)[source]

loads a json file from disk given a file path.

Parameters

file_path – The location to save the json file.

Returns

json data

Raises

IOError – If not able to read file.

zBuilder.IO.pack_zbuilder_contents(builder, type_filter=[], invert_match=False)[source]

Utility to package the data in a dictionary.

zBuilder.IO.unpack_zbuilder_contents(builder, json_data)[source]

Gets data out of json serialization and assigns it to node collection object.

Parameters

json_data – Data to assign to builder object.

zBuilder.builder module

class zBuilder.builder.Builder[source]

Bases: object

The main entry point for using zBuilder.

build(*args, **kwargs)[source]
get_parameters_from_node(node, types=[])[source]

Get parameters (e.g. maps and meshes) for the specified node. :param node: zBuilder scene item :type node: zBuilder node :param types: node types to return, e.g. map, mesh. If empty return all types. :type types: list

Returns

list of zBuilder node parameters

get_scene_items(type_filter=[], name_filter=[], name_regex=None, association_filter=[], association_regex=None, invert_match=False)[source]

Gets the scene items from builder for further inspection or modification.

Parameters
  • type_filter (str or list, optional) – filter by scene_item type. Defaults to list.

  • name_filter (str or list, optional) – filter by scene_item name. Defaults to list.

  • name_regex (str) – filter by scene_item name by regular expression. Defaults to None.

  • association_filter (str or list, optional) – filter by scene_item association. Defaults to list.

  • association_regex (str) – filter by scene_item association by regular expression. Defaults to None.

  • invert_match (bool) – Invert the sense of matching, to select non-matching items. Defaults to False

Returns

List of scene items.

Return type

list

log()[source]
node_factory(node, parent=None, get_parameters=True)[source]

Given a maya node, this checks objType and instantiates the proper zBuilder.node and populates it and returns it.

Parameters
  • node (str) – Name of maya node.

  • get_parameters (bool) –

Returns

zBuilder node populated.

Return type

obj

parameter_factory(parameter_type, parameter_args)[source]

This looks for zBuilder objects in sys.modules and instantiates desired one based on arguments.

Parameters
  • type_ (str) – The type of parameter to instentiate (map or mesh)

  • names (str or list) –

    The name of parameter to instentiate. This should be a node in the maya scene. Either a mesh or a map name.

    Currently sometimes parameter_names could be a list. It is a list when dealing with a map. The second element is the payload whereas the first is the name.

Returns

zBuilder parameter object, either one created or an existing one that has already been created.

Return type

object

print_(type_filter=[], name_filter=[])[source]

Prints out basic information for each scene item in the Builder. Information is all information that is stored in the __dict__. Useful for trouble shooting.

Parameters
  • type_filter (list or str) – filter by scene_item type. Defaults to list

  • name_filter (list or str) – filter by scene_item name. Defaults to list

retrieve_from_file(file_path)[source]

Reads scene items from a given file. The items get placed in the bundle.

Parameters

file_path (str) – The file path to read from disk.

retrieve_from_scene(*args, **kwargs)[source]

must create a method to inherit this class

stats()[source]

Prints out basic information in Maya script editor. Information is scene item types and counts.

string_replace(search, replace)[source]

Searches and replaces with regular expressions scene items in the builder.

Parameters
  • search (str) – what to search for

  • replace (str) – what to replace it with

Example

replace r_ at front of item with l_:

>>> z.string_replace('^r_','l_')

replace _r at end of line with _l:

>>> z.string_replace('_r$','_l')
static time_this(original_function)[source]

A decorator to time functions.

view()[source]
write(file_path, type_filter=[], invert_match=False)[source]

Writes out the scene items to a json file given a file path.

Parameters
  • file_path (str) – The file path to write to disk.

  • type_filter (list, optional) – Types of scene items to write.

  • invert_match (bool) – Invert the sense of matching, to select non-matching items. Defaults to False

zBuilder.builder.builder_factory(class_name)[source]

A factory node to return the correct Builder given class name.

If it cannot find a class it uses the base Builder class.

Parameters

type_ ([str]) – The class name to search for.

Returns

Builder object.

Return type

[obj]

Raises

[Error] – if class_name cannot be found.

zBuilder.builder.restore_scene_items_from_string(item, builder)[source]

zBuilder.bundle module

class zBuilder.bundle.Bundle[source]

Bases: object

Mixin class to deal with storing node data and component data. meant to be inherited by main.

append_scene_item(scene_item)[source]

Deprecated. Use extend_scene_items instead, because batch processing is faster.

compare(type_filter=[], name_filter=[])[source]

Compares info in memory with that which is in scene.

Parameters
  • type_filter (list or str) – filter by scene_item type. Defaults to list

  • name_filter (list or str) – filter by scene_item name. Defaults to list

extend_scene_items(scene_items)[source]

Add a list of scene items into this bundle. Any duplicates with existing scene items replace the existing item. Duplicates are identified by long name.

Parameters

scene_items – List of objects derived from zBuilder.nodes.Base

get_scene_items(type_filter=[], name_filter=[], name_regex=None, association_filter=[], association_regex=None, invert_match=False)[source]

Gets the scene items from builder for further inspection or modification.

Parameters
  • type_filter (str or list, optional) – filter by scene_item type. Defaults to list.

  • name_filter (str or list, optional) – filter by scene_item name. Defaults to list.

  • name_regex (str) – filter by scene_item name by regular expression. Defaults to None.

  • association_filter (str or list, optional) – filter by scene_item association. Defaults to list.

  • association_regex (str) – filter by scene_item association by regular expression. Defaults to None.

  • invert_match (bool) – Invert the sense of matching, to select non-matching items. Defaults to False

Returns

List of scene items.

Return type

list

print_(type_filter=[], name_filter=[])[source]

Prints out basic information for each scene item in the Builder. Information is all information that is stored in the __dict__. Useful for trouble shooting.

Parameters
  • type_filter (list or str) – filter by scene_item type. Defaults to list

  • name_filter (list or str) – filter by scene_item name. Defaults to list

remove_scene_item(scene_item)[source]

Removes a scene_item from the bundle list while keeping order. :param scene_item: The scene_item object to remove. :type scene_item: obj

stats(type_filter='')[source]

Prints out basic information in Maya script editor. Information is scene item types and counts.

Parameters

type_filter (str) – filter by scene_item type. Defaults to str

string_replace(search, replace)[source]

Searches and replaces with regular expressions the scene items in the builder.

Parameters
  • search (str) – what to search for

  • replace (str) – what to replace it with

Example

replace r_ at front of item with l_:

>>> z.string_replace('^r_','l_')

replace _r at end of line with _l:

>>> z.string_replace('_r$','_l')

zBuilder.utils module

zBuilder.utils.check_map_validity()[source]

This checks the map validity for zAttachments and zFibers. For zAttachments it checks if all the values are zero. If so it failed and turns off the associated zTissue node. For zFibers it checks to make sure there are at least 1 value of 0 and 1 value of .5 within a .1 threshold. If not that fails and turns off the zTissue

Returns

list of offending maps

zBuilder.utils.copy_paste(*args, **kwargs)[source]

A utility wrapper for copying and pasting a tissue

zBuilder.utils.copy_paste_with_substitution(regular_expression, string_to_substitute_matches_with)[source]
zBuilder.utils.listConnectionPlugs(node, destination=True, source=True)[source]

Get all of the connections with ‘node’ as a list of pairs of plugs. The first plug in each pair is a plug on ‘node’. The second plug in each pair is a plug the first is connected to.

zBuilder.utils.load_rig(file_name, solver_name=None)[source]
zBuilder.utils.merge_solvers(solver_transforms)[source]

Given a list of zSolverTransform nodes, merge them all into the first solver.

The zSolverTransform, zSolver, and zEmbedder nodes for all but the first solver in the list will be deleted. If that’s not possible, such as when the solvers are referenced nodes, those solvers will remain in the scene but be empty. They will have no bones, tissues, cloth, attachments, etc.

The first solver keeps all of its attribute values and connections. Any differences between this solver and the others is ignored.

All other nodes (besides the zSolverTransform, zSolver, and zEmbedder) are re-wired to connect to the first solver. All existing attributes, connections, or any other properties remain unchanged.

e.g. merge_solvers([‘zSolver1’, ‘zSolver2’, ‘zSolver2’])

zBuilder.utils.merge_two_solvers(solver_transform1, solver_transform2)[source]

Given two solvers, take everything from the second solver and put it into the first solver. Then, delete the second solver. See ‘merge_solvers’ for details. e.g. merge_two_solvers(‘zSolver1’, ‘zSolver2’)

zBuilder.utils.next_free_plug_in_array(dst_plug)[source]

Use this to work around the fact that zSolver.iGeo (and other attrs) have indexMatters=True even though the index doesn’t matter. As a result, connectAttr(a,b,indexMatter=True) won’t work on those attrs. We need to find a specific array element to connect to instead.

This function takes a plug name, and if it’s an element of an array, sets the index to a free index. Else, it’s the identity function.

next_free_plug_in_array(‘foo.bar[7]’) –> ‘foo.bar[42]’ next_free_plug_in_array(‘foo.bar’) –> ‘foo.bar’

zBuilder.utils.remove(nodes)[source]
zBuilder.utils.remove_all_solvers(confirmation=False)[source]
zBuilder.utils.remove_solver(solvers=None, askForConfirmation=False)[source]
zBuilder.utils.rig_copy()[source]

Copy selected.

Returns

True if successful

Return type

bool

zBuilder.utils.rig_cut()[source]

Cut selected.

Returns

True if successful

Return type

bool

zBuilder.utils.rig_cut_copy(cut=False)[source]

Cut or copy the Ziva rig available on currently selected objects into the Ziva clipboard. Selection cannot be empty; otherwise an error is reported. Selection can contain zero or one solver node; otherwise an error is reported (it does not matter if the solver node is a solver transform node, or solver shape node). The selected objects must all come from exactly one solver; otherwise an error is reported.

Parameters

cut (bool, optional) – If cut is True, the Ziva rig is removed from the selection after being copied (i.e., perform a cut). Defaults to False.

Returns

True if successful

Return type

bool

zBuilder.utils.rig_paste()[source]
zBuilder.utils.rig_transfer(source_solver, prefix, target_solver='')[source]
zBuilder.utils.rig_update(solvers=None)[source]
zBuilder.utils.save_rig(file_name)[source]
zBuilder.utils.skincluster_transfer(prefix='')[source]

zBuilder.zMaya module

zBuilder.zMaya.ZNODES = ['zGeo', 'zSolver', 'zSolverTransform', 'zIsoMesh', 'zDelaunayTetMesh', 'zTet', 'zTissue', 'zBone', 'zCloth', 'zSolver', 'zCache', 'zEmbedder', 'zAttachment', 'zMaterial', 'zFiber', 'zCacheTransform', 'zFieldAdaptor', 'zRivetToBone', 'zRestShape']

All available ziva nodes to be able to cleanup.

zBuilder.zMaya.build_attr_key_values(selection, attr_list)[source]

Builds a dictionary of attribute key/values. Stores the value, type, and locked status. :param selection: Items to save attrbutes for. :param attr_list: List of attributes to save.

Returns

of attribute values.

Return type

dict

zBuilder.zMaya.build_attr_list(selection, attr_filter=None)[source]

Builds a list of attributes to store values for. It is looking at keyable attributes and if they are in channelBox.

Parameters
  • attr_filter

  • selection (str) – maya object to find attributes

Returns

list of attributes names

Return type

list

zBuilder.zMaya.check_body_type(bodies)[source]

Checks if given bodies are either zTissue, zCloth and or zBone. Mostly used to see if we can create a zAttachment before we try. Additionally does a check if all objects exist in scene.

Parameters

bodies (list) – List of bodies we want to check type of.

Returns

True if all bodies pass test, else False.

Return type

(bool)

zBuilder.zMaya.check_map_validity(map_parameters)[source]

This checks the map validity for zAttachments and zFibers. For zAttachments it checks if all the values are zero. If so it failed and turns off the associated zTissue node. For zFibers it checks to make sure there are at least 1 value of 0 and 1 value of .5 within a .1 threshold. If not that fails and turns off the zTissue

Parameters

map_parameters – map parameters to check.

Returns

list of offending maps

zBuilder.zMaya.check_maya_node(maya_node)[source]
Parameters

maya_node

Returns:

zBuilder.zMaya.check_mesh_quality(meshes)[source]

Light wrapper around checking mesh quality.

Parameters

meshes (list) – A list of meshes you want to check

Raises

Exception – If any mesh does not pass mesh check

zBuilder.zMaya.clean_scene()[source]

Deletes all ziva nodes in scene. Effectively cleaning it up.

zBuilder.zMaya.cull_creation_nodes(scene_items, permissive=True)[source]

To help speed up the build of a Ziva setup we are creating the bones and the tissues with one command. Given a list of zBuilder nodes this checks if a given node needs to be created in scene. Checks to see if it already exists or if associated mesh is missing. Either case it culls it from list.

Parameters
  • permissive (bool) –

  • scene_items (object) – the zBuilder nodes to check.

Returns

Dictionary of non culled

Return type

dict

zBuilder.zMaya.delete_rivet_from_solver(solvers)[source]

This deletes all items related to zRivetToBone from a connected solver. This includes The locator, locator transform and the zRivetToBone node. current implementation of zQuery does not handle rivets so this is temporary until we get a python version going.

Parameters

solver ([list]) – The solver/s that have the rivets that are to be deleted.

zBuilder.zMaya.get_association(zNode)[source]

Gets an association of given zNode

Parameters

zNode (string) – the zNode to find association of.

zBuilder.zMaya.get_fiber_lineofaction(zFiber)[source]

Gets the zLineOfAction node hooked up to a given zFiber in any.

Parameters

zFiber (string) – the zFiber to query.

Returns

zLineOfAction

Return type

str

zBuilder.zMaya.get_fields_on_zFieldAdaptors(adaptors)[source]

Gets Maya fields connected into some zFieldAdaptors. :param adaptors: list of names of Maya zFieldAdaptor nodes

Returns

list of names of fields plugged into the adaptors.

zBuilder.zMaya.get_lineOfAction_fiber(zlineofaction)[source]

Gets the zFiber node hooked up to a given zLineOfAction in any.

Parameters

zlineofaction (string) – the zLineOfAction to query.

Returns

Name of zFiber hooked up to lineOfAction

Return type

str

zBuilder.zMaya.get_mdagpath_from_mesh(mesh_name)[source]

Maya stuff, getting the dagpath from a mesh name

Parameters

mesh_name – The mesh to get dagpath from.

zBuilder.zMaya.get_name_from_m_object(m_object, long_name=True)[source]

Gets maya scene name from given mObject. :param m_object: The m_object to get name from. :param long_name: Returns long name. Default = True

Returns

Maya object name.

Return type

str

zBuilder.zMaya.get_soft_bodies(selection)[source]

Get all the soft bodies (tissue and cloth). This is a wrapper around get_zCloth and get_zTissues.

zBuilder.zMaya.get_type(body)[source]

Really light wrapper for getting type of maya node. Ya, I know.

Parameters

body (str) – Maya node to get type of

Returns

String of node type.

Return type

str

zBuilder.zMaya.get_zAttachments(bodies)[source]

Gets zAttachments in scene. :param body: Maya node to find associated zAttachments.

Returns

string of name of zAttachments.

zBuilder.zMaya.get_zBones(bodies)[source]

Gets zBones in scene. :param body: Maya node to find associated zBones.

Returns

string of name of zBones.

zBuilder.zMaya.get_zCloth(bodies)[source]

Gets zCloth in scene. :param body: Maya node to find associated zCloth.

Returns

string of name of zCloth.

zBuilder.zMaya.get_zFibers(bodies)[source]

Gets zFibers in scene. :param body: Maya node to find associated zFibers.

Returns

string of name of zFibers.

zBuilder.zMaya.get_zFieldAdaptors(bodies)[source]

Gets zFieldAdaptors connected into some bodies. :param bodies: List of names of Maya zTissue or zCloth nodes to get zFieldAdaptors for.

Returns

list of names of zFieldAdaptor nodes.

zBuilder.zMaya.get_zMaterials(bodies)[source]

Gets zmaterials in scene. :param body: Maya node to find associated zMaterials.

Returns

string of name of zmaterials.

zBuilder.zMaya.get_zSolver(body)[source]

Gets zSolver in scene. :param body: Maya node to find associated solver.

Returns

returns long name of zSolver.

zBuilder.zMaya.get_zSolverTransform(body)[source]

Gets zSolverTransform in scene. :param body: Maya node to find associated solverTransform.

Returns

returns long name of zSolverTransform.

zBuilder.zMaya.get_zTet_user_mesh(zTet)[source]

Gets the user tet mesh hooked up to a given zTet in any.

Parameters

zTet (string) – the zTet to query.

Returns

User tet mesh.

Return type

str

zBuilder.zMaya.get_zTets(bodies)[source]

Gets zTets in scene. :param body: Maya node to find associated zTets.

Returns

string of name of zTets.

zBuilder.zMaya.get_zTissues(bodies)[source]

Gets zTissues in scene. :param body: Maya node to find associated zTissues.

Returns

string of name of zTissues.

zBuilder.zMaya.isSolver(selection)[source]

Checks if passed is zSolver or zSolverTransform. :param selection: Item of interest.

Returns

True if it is solver, else false.

zBuilder.zMaya.none_to_empty(x)[source]

Turn None into empty list, else just return the input as-is.

This is a utility to work with Maya’s Python API which returns None instead of empty list when no results are found. That non-uniformity is annoying. Use this to fix it.

Parameters

x – anything

Returns

[] if x is None else x

zBuilder.zMaya.parse_maya_node_for_selection(args)[source]

This is used to check passed args in a function to see if they are valid maya objects in the current scene. If any of the passed names are not in the it raises a Exception. If nothing is passed it looks at what is actively selected in scene to get selection. This way it functions like a lot of the maya tools, uses what is passed OR it uses what is selected.

Parameters

args – The args to test

Returns

(list) maya selection

zBuilder.zMaya.rename_ziva_nodes(replace=['_muscle', '_bone'])[source]

Renames zNodes based on mesh it’s connected to.

Parameters

replace (list) – subset of mesh name to replace with zNode name

  • zFiber: <meshName>_zFiber

  • zMaterial: <meshName>_zMaterial

  • zTet: <meshName>_zTet

  • zTissue: <meshName>_zTissue

  • zBone: <meshName>_zBone

  • zCloth: <meshName>_zCloth

  • zRestShape: <meshName>_zRestShape

  • zAttachment: <sourceMesh>__<destinationMesh>_zAttachment

zBuilder.zMaya.replace_dict_keys(search, replace, dictionary)[source]

Does a search and replace on dictionary keys

Parameters
  • search (str) – search term

  • replace (str) – replace term

  • dictionary (dict) – the dictionary to do search on

Returns

result of search and replace

Return type

dict

zBuilder.zMaya.replace_long_name(search, replace, long_name)[source]

does a search and replace on a long name. It splits it up by (‘|’) then performs it on each piece

Parameters
  • search (str) – search term

  • replace (str) – replace term

  • long_name (str) – the long name to perform action on

Returns

result of search and replace

Return type

str

zBuilder.zMaya.rivet_to_bone_rename_helper(rtbs, postfix, replace)[source]

The same idea as for znode_rename_helper but for zRivetToBone :param rtbs: list of zRivetToBone nodes to rename :type rtbs: list :param postfix: postfix to use for renaming :type postfix: string :param replace: list of strings to remove from the new name :type replace: list

Returns

old names, new names

Return type

tuple of lists

zBuilder.zMaya.safe_rename(old_name, new_name)[source]

Same as cmds.rename but does not throw an exception if renaming failed Useful if need to rename all the nodes that are not referenced

zBuilder.zMaya.select_tissue_meshes()[source]

Selects all zTissues in scene

zBuilder.zMaya.strip_namespace(node)[source]
zBuilder.zMaya.znode_rename_helper(zNode, postfix, solver, replace)[source]

Helper for cases when need to rename nodes like: zMaterial1, zMaterial4, zMaterial25 to zMaterial1, zMaterial2, zMaterial3 And not to rename nodes like: zMaterial1, zMaterial2, zMaterial3 to zMaterial4, zMaterial5, zMaterial6 :param zNode: node type :type zNode: string :param postfix: postfix to use for renaming :type postfix: string :param solver: solver name :type solver: string :param replace: list of strings to remove from the new name :type replace: list

Returns

old names, new names

Return type

tuple of lists

Module contents