Import, export and transfer

Examples

Export weigths to file:

import os
from ngSkinTools2 import api as ngst_api

output_file_name = os.path.join(target_dir, 'export_sample_mesh.json')
ngst_api.export_json("sample_mesh", file=output_file_name)

Import weights from file:

from ngSkinTools2.api import InfluenceMappingConfig, VertexTransferMode

# prerequisites: mesh with skinCluster attached, "sampleMesh" in our case

# configure how influences described in a file will be matched against the scene
config = InfluenceMappingConfig()
config.use_distance_matching = True
config.use_name_matching = False

# run the import
ngst_api.import_json(
    "sampleMesh",
    file=source_file_name,
    vertex_transfer_mode=VertexTransferMode.vertexId,
    influences_mapping_config=config,
)

Transfer with default settings: vertices mapped with closestPoint rule, and influences with default settings for mesh-to-mesh transfer (using InfluenceMappingConfig.transfer_defaults()).

from ngSkinTools2 import api as ngst_api

# prerequisites: we have two meshes with skinCluster attached ready
source = "sample_source_mesh"
destination = "sample_destination_mesh"

# normally we would assume that source mesh already has skin layers created,
# but for example's sake, just create some layers on the fly
source_layers = ngst_api.init_layers(source)
l1 = source_layers.add("layer1")
l1.set_weights(0, [1.0] * 4)
l1.set_weights(1, [0.2, 0.2, 0.8, 0.8])
l2 = source_layers.add("layer_two")
l2.set_weights(1, [1, 1, 0, 0])
l3 = source_layers.add("layer3", parent=l1)
l4 = source_layers.add("layer4", parent=l1)

# there is no need to init layers on destination,
# but if destination had layers already, then  transferred layers
# would be created on top of old ones

# so this line is all you need, if you have source mesh ready with skinning layers,
# and destination mesh with skinCluster attached.
ngst_api.transfer_layers(source, destination)

To customize transfer options for vertex and influences mapping:

infl_config = ngst_api.InfluenceMappingConfig.transfer_defaults()
infl_config.use_label_matching = False
infl_config.use_distance_matching = True
infl_config.use_name_matching = False

ngst_api.transfer_layers(
    "sample_source_mesh",
    "sample_destination_mesh",
    vertex_transfer_mode=ngst_api.VertexTransferMode.closestPoint,
    influences_mapping_config=infl_config,
)

API reference

ngSkinTools2.api.export_json(target, file)

Save skinning layers to file in json format, to be later used in import_json

Parameters

• target (str) – source mesh or skin cluster node name

• file (str) – file path to save json to

ngSkinTools2.api.import_json(target, file, vertex_transfer_mode='closestPoint', influences_mapping_config=<ngSkinTools2.api.influenceMapping.InfluenceMappingConfig object>)

Transfer layers from file into provided target mesh. Existing layers, if any, will be preserved

Parameters

• target (str) – destination mesh or skin cluster node name

• file (str) – file path to load json from

• influences_mapping_config (InfluenceMappingConfig) –

ngSkinTools2.api.transfer_layers(source, destination, vertex_transfer_mode='closestPoint', influences_mapping_config=<ngSkinTools2.api.influenceMapping.InfluenceMappingConfig object>)

Transfer skinning layers from source to destination mesh.

Parameters

• source (str) – source mesh or skin cluster node name

• destination (str) – destination mesh or skin cluster node name

• vertex_transfer_mode (str) – describes how source mesh vertices are mapped to destination vertices. Defaults to closestPoint

• influences_mapping_config (InfluenceMappingConfig) – configuration for InfluenceMapping; supply this, or influences_mapping instance; default settings for transfer are used if this is not supplied.

• influences_mapping (InfluenceMapping) – mapper instance to use for matching influences; if this is provided, influences_mapping_config is ignored.

Returns

class ngSkinTools2.api.InfluenceMappingConfig

This class represents a configuration for how influences are matched for weights mirroring or transfering between meshes.

globs = [('L_*', 'R_*'), ('l_*', 'r_*'), ('lf_*', 'rt_*'), ('*_lf', '*_rt')]

For mirrored influences matching, this specifies the globs that will be used for name substitution

use_dg_link_matching = True

turn on to use dependency graph links

use_name_matching = True

should matching by name be used?

use_label_matching = True

should matching by label be used?

use_distance_matching = True

should matching by influence X,Y,Z coordinates be used?

distance_threshold = 0.001

When matching by distance, if distance between two positions is greater than this threshold, that pair of influences is not considered as potential match.

dg_destination_attribute = 'oppositeInfluence'

default attribute name

property mirror_axis

Mirror axis (0 - X, 1 - Y, 2 - Z)

When mirror axis is not None, matching is done in “mirror” mode:

• left/right side .globs are used;

• matching by position uses mirrorAxis to invert positions first;

Type

int

classmethod transfer_defaults()

Builds a mapping configuration that is suitable as default for transferring between meshes (or importing)

Returns

default transfer configuration

Return type

InfluenceMappingConfig

as_json()

serializes config as JSON string

load_json(json_string)

loads configuration from previously saved as_json output

class ngSkinTools2.api.InfluenceMapping

this class serves as a hub to calculate influences mapping, given a mapping config and source/destination influences

config: ngSkinTools2.api.influenceMapping.InfluenceMappingConfig

assigned config

influences: list[ngSkinTools2.api.influenceMapping.InfluenceInfo]

Source influences list. Can be assigned to result of Layers.list_influences()

calculate()

class ngSkinTools2.api.VertexTransferMode

Constants for vertex_transfer_mode argument

closestPoint = 'closestPoint'

When vertices from two surface are matched, each destination mesh vertex finds a closest point on source mesh, and weights are calculated based on the triangle weights of that closest point.

uvSpace = 'uvSpace'

Similar to closestPoint strategy, but matching is done in UV space instead of XYZ space.

vertexId = 'vertexId'

Vertices are matched by ID. Not usable for mirroring; this is used for transfer/import cases where meshes are known to be identical

class ngSkinTools2.api.InfluenceInfo(pivot=None, path=None, name=None, logicalIndex=None, labelSide=None, labelText=None)

Metadata about an influence in a skin cluster

SIDE_LEFT = 'left'

SIDE_RIGHT = 'right'

SIDE_CENTER = 'center'

SIDE_MAP = {0: 'center', 1: 'left', 2: 'right'}

oppositeSides = {'left': 'right', 'right': 'left'}

pivot

influence pivot in world-space coordinates

path

influence node path

name

influence node name (if influence is not a DAG node, like )

logicalIndex

influence logical index in the skin cluster.

labelSide

joint label “side” attribute

labelText

joint label text

path_name()

returns path if it’s not None, otherwise returns name :return:

as_json()

from_json(json)