クリーク･アンド･リバー社 テクニカルアーティストチームの長谷川です。
本記事ではngSkinToolsのAPI活用方法について紹介していきたいと思います。
3行でわかる今回の内容
・Maya2027で ngSkinTools が標準搭載された
・基本的なAPIの使い方と活用例を紹介
・APIを使うことでウェイト管理をツール化できそう
対象読者
・テクニカルアーティスト
・ngSkinToolsを使用している人
・Mayaツールを制作している人環境
・Maya 2024.2.4
・Maya 2027
ngSkinToolsについて
ngSkinTools は、スキンウェイトをLayer ベースで非破壊的に編集できることができるプラグインです。
近年のキャラクター制作では、インフルエンス数やジョイント数の増加に加え、
モデル自体のハイポリゴン化も進み、スキニング作業は年々複雑になっています。
そうした中で ngSkinTools は、ウェイトをレイヤーごとに分けて管理できるため、
リテイク対応や細かな調整を安全かつ効率的に行えるツールとして、多くの現場で活用され始めています。
また、Maya 2027 では Autodesk による買収・統合が行われ、
ngSkinTools の機能が Maya に正式に組み込まれる形となりました。
そこで本記事では、ngSkinTools の API に注目し、基本的な使い方から、
実際の制作現場で活用できる自動化例まで紹介していきます。
APIについて
ngSkinTools は レイヤーベースのウェイト編集ツールとしてよく知られていますが、
API を利用することで、スクリプトから様々な制御することができます。
単純なレイヤー作成やウェイトのエクスポートだけでなく、
既存スキンからのレイヤー自動生成や、命名規則を利用したウェイト分類など、
制作フローに合わせた自動化を行える点が大きな特徴です。
ngSkinTools の API を利用することで、下記のようなことをプログラム側で簡単に行うことができます。
- シーン内のモデルのウェイト情報を一括でJSON エクスポート
- モデル更新時の再バインド
- 指定したジョイントのウェイトを別レイヤーへ抽出
- ウェイトデータを一括でインポートする
- 別スキンクラスター間でウェイトをコピーする
- レイヤー構成をテンプレート化する
また、Maya 標準の maya.cmds と組み合わせることで、選択オブジェクトに対して一括処理を行ったり、独自ツールとして UI 化することも可能です。
基本的な API は ngSkinTools2.api モジュールから利用できます。
from ngSkinTools2 import api公式ドキュメント
https://www.ngskintools.com/documentation/v2/api/index.html
Maya2027 SkinTools新機能について
APIの紹介に入る前に、Maya 2027への統合にあわせてSkin Toolsに追加されていた機能について、
いくつか紹介します。
※ 統合された ngSkinToolsは SkinToolsという名称になっています。
まずは、Influenceのロック機能です。
Maya標準のスキニング機能にもある、特定のInfluenceのウェイトを変更されないようにロックできる機能で、
普段から活用している方も多いのではないでしょうか。
このロック機能がSkin Toolsにも導入されたことで、調整済みのジョイントのウェイトを固定したまま、
ほかのジョイントだけを編集するといった作業がしやすくなりました。
Maya標準のスキニングで慣れ親しんだ機能がSkin Tools上でも使えるようになり、
これまで以上に扱いやすくなった印象です。
そして次に、コンポーネントエディタからレイヤーごとの
ウェイトを細かく調整できる機能が追加されていました。
以前は、コンポーネントエディタからウェイトを編集しても Skin Tools側のレイヤー情報が優先されるため、
レイヤーを使用しながら頂点単位で細かな数値調整を行うのが難しい部分がありました。
今回の機能追加によって Skin Toolsのレイヤーを保持した状態でも、
コンポーネントエディタから各頂点のウェイトを確認・調整できるようになっています。
ペイントだけでは調整しづらい頂点のウェイトを数値で直接修正したい場合や、
特定の頂点だけを細かく整えたい場合にも便利です。
レイヤーによる管理のしやすさを残しつつ、
Maya標準のコンポーネントエディタを使った細かな調整も行えるようになったことで、
仕上げのウェイト調整がより行いやすくなりました。
APIの使い方
レイヤーの初期化
ngSkinTools の Layer は、skinCluster が存在していても自動では作成されません。
まずは、対象の skinCluster に ngSkinTools の Layer 情報が存在するかを確認し、
存在しない場合は init_layers() を使って初期化を行います。
import maya.cmds as cmds
import ngSkinTools2
from ngSkinTools2 import api
# 選択しているメッシュを取得
mesh = cmds.ls(selection=True)[0]
# メッシュからスキンクラスターを取得する
skin_cluster = api.target_info.get_related_skin_cluster(mesh)
# ngSkinTools のノードがあるかどうか確認する
has_ng_skin_tools = cmds.attributeQuery(
"ngst2SkinLayerData",
node=skin_cluster,
exists=True
)
# ngSkinTools の Layer 情報が存在しない場合は初期化する
if not has_ng_skin_tools:
api.init_layers(mesh)
# レイヤー情報がない場合 ベースのレイヤーを追加する
layer_data = api.Layers(mesh)
if not layer_data.list():
layer_data.add(
name="Base weights"
)※スクリプトを実行してもツールの表示が変わらない場合は
メッシュの選択を外して再度メッシュを選択すると表示されるようになります。
レイヤーのリストを取得
下記のような形式で取得することができます
[[Layer #1 '#Base Layer'], [Layer #2 '#New Layer'], [Layer #3 '#New Layer (2)']]
import maya.cmds as cmds
import ngSkinTools2
from ngSkinTools2 import api
# 選択しているメッシュを取得
mesh = cmds.ls(selection=True)[0]
# レイヤーデータを取得
layer_data = api.Layers(mesh)
# レイヤーデータからlistを取得
print(layer_data.list())レイヤーの追加
名前を指定してレイヤーを追加
import maya.cmds as cmds
import ngSkinTools2
from ngSkinTools2 import api
# 選択しているメッシュを取得
mesh = cmds.ls(selection=True)[0]
# レイヤーデータを取得
layerData = api.Layers(mesh)
layerData.add(
name="Test Layer"
)
レイヤーの削除
import maya.cmds as cmds
import ngSkinTools2
from ngSkinTools2 import api
# 選択しているメッシュを取得
mesh = cmds.ls(selection=True)[0]
# レイヤーデータを取得
layerData = api.Layers(mesh)
for layer in layerData.list():
print(layer.name)
if layer.name == "Base weights":
layerData.delete(layer)
レイヤーごとのウェイトの取得方法
選択したオブジェクトのレイヤー0，レイヤー1，レイヤー2 の spine_01をそれぞれ取得する例
from maya import cmds
import ngSkinTools2
from ngSkinTools2 import api
print("\n"*7)
print("="*15)
# 選択したメッシュを取得
mesh = cmds.ls(selection=True)[0]
print(f"mesh : {mesh}")
print("\n")
# レイヤーデータを取得
layerData = api.Layers(mesh)
layerDataList = layerData.list()
print(f"layerData : {layerData}")
print(f"layerDataList : {layerDataList}")
print("\n")
# インフルエンスを取得
influences = api.target_info.list_influences(mesh)
print(f"influences : {influences}")
for inf in influences:
if inf.path.split("|")[-1] == "spine_01":
influence_id = inf.logicalIndex
print(f"influence_id : {influence_id}")
print("\n")
weights = layerDataList[0].get_weights(influence_id)
print(f"layerDataList[0] : {weights}")
weights = layerDataList[1].get_weights(influence_id)
print(f"layerDataList[1] : {weights}")
weights = layerDataList[2].get_weights(influence_id)
print(f"layerDataList[2] : {weights}")
print("="*15)
ウェイトのエクスポート
pathに保存場所のパスを指定して、メッシュを選択して実行。
import maya.cmds as cmds
import ngSkinTools2
from ngSkinTools2 import api
path = "D:/ngskin_weights.json"
# 選択しているメッシュを取得
mesh = cmds.ls(selection=True)[0]
api.export_json(
mesh,
file=path
)
print(f"export : {path}")
ウェイトのインポート
pathに保存場所のパスを指定して、メッシュを選択して実行。
頂点番号（transfer.VertexTransferMode.vertexId）
import ngSkinTools2
from ngSkinTools2 import api
from ngSkinTools2.api import transfer
path = "D:/ngskin_weights.json"
# 選択しているメッシュを取得
mesh = cmds.ls(selection=True)[0]
api.import_json(
target=mesh,
file=path,
vertex_transfer_mode=transfer.VertexTransferMode.vertexId # 頂点番号
)
近接頂点（transfer.VertexTransferMode.closestPoint）
import ngSkinTools2
from ngSkinTools2 import api
from ngSkinTools2.api import transfer
path = "D:/ngskin_weights.json"
# 選択しているメッシュを取得
mesh = cmds.ls(selection=True)[0]
api.import_json(
target = mesh,
file = path,
vertex_transfer_mode=transfer.VertexTransferMode.closestPoint # 近接頂点
)
UV（transfer.VertexTransferMode.uvSpace）
import ngSkinTools2
from ngSkinTools2 import api
from ngSkinTools2.api import transfer
path = "D:/ngskin_weights.json"
# 選択しているメッシュを取得
mesh = cmds.ls(selection=True)[0]
api.import_json(
target = mesh,
file = path,
vertex_transfer_mode=transfer.VertexTransferMode.uvSpace # UV
)活用例
インポート・エクスポート機能を使ったケージモデル
上記の通り、ngSkinToolsでは頂点番号（Vertex ID）だけでなく、
近接頂点（Closest Point）やUV空間（UV Space）インポートにも対応しています。
そのため、トポロジーが異なるモデル間でもウェイトをきれいに転写できる場合があります。
例えば、ローポリモデルでウェイト調整を行い、
その結果をハイポリモデルへ転写するといったワークフローにも活用できます。
モデル更新によって頂点番号が変わってしまった場合でも、
状況に応じて転送方法を切り替えることで、柔軟にウェイトを引き継ぐことが可能です。
次の画像はBoxのウェイトをエクスポートしてほかのモデルに近接頂点でインポートした結果になります。
ローポリゴンでウェイトをつけたものをjsonであらかじめエクスポートしておくことで、
モデルをシーン内に読み込みウェイトをつけることなく、
ジョイント名を参照してウェイトを持ってくることもできます。
Boxとジャケット
BOXのウェイト
Boxから近接頂点でインポートしたもの
レイヤーからレイヤーにウェイトをコピー
レイヤーからレイヤーにジョイントのウェイトをコピーするサンプルです。
extract_joint に下から2番目のレイヤーに抽出したいジョイント名を入力しレイヤーが三つあるメッシュを選択して、実行することができます。
import ngSkinTools2
from maya import cmds
from ngSkinTools2 import api
# 抽出するジョイント名
extract_joint = "Spine1"
print("\n"*7)
print("="*15)
# 選択したメッシュを取得
mesh = cmds.ls(selection=True)[0]
print(f"mesh : {mesh}")
print("\n")
# レイヤーデータを取得
layer_data = api.Layers(mesh)
# layer_data_list[0]の0は下から順番になっています
layer_data_list = layer_data.list()
print(f"layerData : {layer_data}")
print(f"layerDataList : {layer_data_list}")
print("\n")
# スキンクラスターのジョイント名を取得
influences = api.target_info.list_influences(mesh)
print(f"influences : {influences}")
for inf in influences:
if inf.path.split("|")[-1] == extract_joint:
influence_id = inf.logicalIndex
print(f"influence_id : {influence_id}")
print("\n")
# 1番下のレイヤーから下から2番目のレイヤーに extract_joint のウェイト情報をコピー
layer_data_list[1].set_weights(
influence_id,
layer_data_list[0].get_weights(influence_id)
)
# 1番下のレイヤーから下から3番目のレイヤーにすべてのウェイト情報をコピー
for inf in influences:
layer_data_list[2].set_weights(
inf.logicalIndex,
layer_data_list[0].get_weights(inf.logicalIndex)
)まとめ
今回は、ngSkinToolsのPython APIを使った基本的な操作を紹介しました。
APIを利用すれば、普段GUIから行っている作業を自動化したり、
自分のワークフローに合わせたツールを作成したりすることができます。
一方で、今回紹介したようなウェイトの抽出やインポート・エクスポートといった機能は、
APIを使わなくても通常のツールとして利用するだけでも十分便利です。
バックアップやウェイトの管理、モデル更新時のデータ移行など、
日々のスキニング作業を効率化できる場面は多くあります。
ぜひ、SkinToolsを活用して、自分の制作フローに合った使い方を見つけてみてください。
