Import/Export

Import/export API consists of:

• Data objects: LayerData, Layer, and Influence; data objects are intermediate objects between exporters, importers and actual skin layer data in layers node;
• Importers are used to load LayerData object from external format, e.g. XML or JSON
• Similarly, exporters serialize LayerData objects into external formats.

For example, to import layers from XML into mesh you’d have to do the following:

from ngSkinTools.importExport import XmlImporter

# create layers from
importer = XmlImporter()
# read file contents here using one of your prefered methods
xml = loadFileData('path/to/my.xml')
# load layer data
data = importer.process(xml)
# set that into given mesh
data.saveTo('skinnedMesh')

To export, the process is reversed - we load data from skinned mesh (which should have skin layers initialized for it) and save it to file:

from ngSkinTools.importExport import LayerData,XmlExporter

data = LayerData()
data.loadFrom('skinnedMesh')
exporter = XmlExporter()
xml = exporter.process(data)
saveXmlToFile(xml,'path/to/my.xml')

Note that neither importers nor exporters work with files directly - instead, they use/produce content as strings.

Having this modular approach instead allows for more usage paths other than “import from file” and “export to file”. Not only it allows plugging in new importers/exporters; instead loading data from external source, it can be created on the fly; loaded layer data can be manipulated and saved back to mesh; it’s even possible to convert from one format to another!

To create layer data object, do one of the following:

• import with an Importer:

  data = JsonImporter().process(jsonString)
  

• load from a skinned mesh:

  data = LayerData()
  data.loadFrom('rig|mesh|bodyMesh')
  

• construct from scratch:

  data = LayerData()
  layer = Layer()
  # set layer properties
  influence = Influence()
  # set influence properties
  layer.addInfluence(influence)
  data.addLayer(layer)
  

LayerData is an ordinary python object, containing a list of layers, which in turn contains a list of influences. For properties of each object, see below documentation. For more usage reference, look into implementations of XML/JSON importers/exporters.

Helper classes

class ngSkinTools.importExport.InfluenceInfo(pivot=None, path=None, logicalIndex=None)

Metadata about an influence in a skin cluster

pivot

influence pivot in world-space coordinates

path

influence node path

logicalIndex

influence logical index in the skin cluster.

Layer Data

class ngSkinTools.importExport.LayerData

Intermediate data object between ngSkinTools core and importers/exporters, representing all layers info in one skin cluster.

layers

a list of Layer objects.

influences

a list of InfluenceInfo objects. Provides information about influences that were found on exported skin data, and used for influence matching when importing.

addLayer(layer)

register new layer into this data object

Parameters:layer (Layer) – layer object to add.

addMirrorInfluenceAssociationOverride(sourceInfluence, destinationInfluence=None, selfReference=False, bidirectional=True)

Adds mirror influence association override, similar to UI of “Add influences association”. Self reference creates a source<->source association, bidirectional means that destination->source link is added as well

getAllInfluences()

a convenience method to retrieve a list of names of all influences used in this layer data object

loadFrom(mesh)

loads data from actual skin cluster and prepares it for exporting. supply skin cluster or skinned mesh as an argument

saveTo(self, mesh)

saves data to actual skin cluster

class ngSkinTools.importExport.Layer

Represents single layer; can contain any amount of influences.

name

layer name. Default value: None; set/use as any python string.

opacity

layer opacity. Defaults to 0.0. Set to float value between 0.0 and 1.0

enabled

layer on/off flag. Default value is False. Set to True or False.

influences

list of Influence objects.

mask

layer mask: list of floats. Set to None for uninitialized mask, or to float list, containing as many values as there are vertices in a target mesh.

dqWeights

dual quaternion blend weights. None if not defined for this layer, or float list, one value per vertex in the target mesh.

parent

index of parent layer (in the context of this model’s layer list)

addInfluence(influence)

Add an influence in this layer.

Parameters:influence (Influence) – influence to be added

class ngSkinTools.importExport.Influence

Single influence in a layer

weights

vertex weights for this influence. Set to float list, containing as many values as there are vertices in a target mesh.

influenceName

Full path of the influence in the scene. Required value when importing data back into skin cluster, as influences are associated by name in current implementation.

logicalIndex

Logical index for this influence in a skin cluster. Not required for import and only provided in export as a reference.

Importers/Exporters

class ngSkinTools.importExport.JsonExporter

process(layerDataModel)

transforms LayerDataModel to JSON

Parameters:layerDataModel (LayerData) – layers information as object; Returns:string containing a json document

class ngSkinTools.importExport.JsonImporter

process(jsonDocument)

transform JSON document () into layerDataModel

Parameters:jsonDocument (str) – layers info, previously serialized as json string Return type:LayerData