pymel.core.system.createReference

createReference(filepath, **kwargs)

Create a reference to the specified file. Returns the name of the file referenced.Query all file references from the specified file.

Flags:

• loadNoReferences:

  This flag is obsolete and has been replaced witht the loadReferenceDepth flag. When used with the -open flag, no references will be loaded. When used with -import, -reference or -loadReference flags, will load the top-most reference only.

• loadReferenceDepth:

  Used to specify which references should be loaded. Valid types are “all”, “none” and “topOnly”, which will load all references, no references and top-level references only, respectively. Must be used with the -open, -import, -reference or -loadReference flags. When “none” is used with -loadReference, only path validation is performed. This can be used to replace a reference without triggering reload. Not using loadReferenceDepth will load references in the same loaded or unloaded state that they were in when the file was saved.

• defaultNamespace:

  Use the default name space for import and referencing. This is an advanced option. If set, then on import or reference, Maya will attempt to place all nodes from the imported or referenced file directly into the root (default) name space, without invoking any name clash resolution algorithms. If the names of any of the new objects already exist in the root namespace, then errors will result. The user of this flag is responsible for creating a name clash resolution mechanism outside of Maya to avoid such errors. Note:This flag is intended only for use with custom file translators written through the API. Use at your own risk.

• deferReference:

  When used in conjunction with the -reference flag, this flag determines if the reference is loaded, or if loading is deferred.C: The default is false.Q: When queried, this flag returns true if the reference is deferred, or false if the reference is not deferred. If this is used with -rfn/referenceNode, the -rfn flag must come before -q.

• groupReference:

  Used only with the -r or the -i flag. Used to group all the imported/referenced items under a single transform.

• groupLocator:

  Used only with the -r and the -gr flag. Used to group the output of groupReference under a locator

• groupName:

  Used only with the -gr flag. Optionally used to set the name of the transform node that the imported/referenced items will be grouped under.

• namespace:

  The namespace name to use that will group all objects during importing and referencing. Change the namespace used to group all the objects from the specified referenced file. The reference must have been created with the “Using Namespaces” option, and must be loaded. Non-referenced nodes contained in the existing namespace will also be moved to the new namespace. The new namespace will be created by this command and can not already exist. The old namespace will be removed.

• referenceNode:

  When queried, this flag returns the name of the reference node associated with the file. If the file is not a reference or does not have a reference node, an empty string is returned. In query mode, this flag can accept a value.

• renamingPrefix:

  The string to use as a prefix for all objects from this file. This flag has been replaced by -ns/namespace.

• swapNamespace:

  Can only be used in conjunction with the -r/reference or -i/import flags. This flag will replace any occurrences of a given namespace to an alternate specified namespace. This namespace “swap” will occur as the file is referenced in. It takes in two string arguments. The first argument specifies the namespace to replace. The second argument specifies the replacement namespace. Use of this flag, implicitly enables the use of namespaces and cannot be used with deferReference.

• sharedReferenceFile:

  Can only be used in conjunction with the -r/reference flag and the -ns/namespace flag (there is no prefix support). This flag modifies the ‘-r/-reference’ flag to indicate that all nodes within that reference should be treated as shared nodes. New copies of those nodes will not be created if a copy already exists. Instead, the shared node will be merged with the existing node. The specifics of what happens when two nodes are merged depends on the node type. This flag cannot be used in conjunction with -shd/sharedNodes.

• sharedNodes:

  This flag modifies the ‘-r/-reference’ flag to indicate that certain types of nodes within that reference should be treated as shared nodes. All shared nodes will be placed in the default namespace. New copies of those nodes will not be created if a copy already exists in the default namespace, instead the shared node will be merged with the existing node. The specifics of what happens when two nodes are merged depends on the node type. In general attribute values will not be merged, meaning the values set on any existing shared nodes will be retained, and the values of the nodes being merged in will be ignored. The valid options are “displayLayers”, “shadingNetworks”, “renderLayersByName”, and “renderLayersById”. This flag is multi-use; it may be specified multiple times to for example, share both display layers and shading networks. Two shading networks will only be merged if they are identical: the network of nodes feeding into the shading group must be arranged identically with equivalent nodes have the same name and node type. Additionally if a network is animated or contains a DAG object or expression it will not be mergeable. This flag cannot be used in conjunction with -srf/sharedReferenceFile.

• returnNewNodes:

  Used to control the return value in open, import, loadReference, and reference operations. It will force file command to return a list of new nodes added to the current scene.

Derived from mel command maya.cmds.file