Shade Math 説明書(ver0.3.1)

概要

Shade Python スクリプトでは、 Shade 内部の3dデータは、リストまたはタプルで渡される仕様です。 Python は、オブジェクト指向のスクリプト言語なのに、何でこんな仕様なのか理解に苦しみます。プラグインでは、 vec3 等の専用のクラスがちゃんと定義され、とても楽に数式表記が可能です。その資産を利用すれば、難しいことではなかったはずです。
そこで、 Shade スクリプトで普通使う範囲で十分実用的な、三次元ベクトル( Vec3 )とクォータニオン( Quaternion )のクラスを定義したモジュールを作ってみました。これを使えば、3次元ベクトルのちょっと複雑な計算をするときに楽になると同時にミスも防げると思います。
同時にあれば便利そうな汎用関数と汎用変数も包含してます。

モジュールは、以前私がスクリプトを作り始めたときに作ったものです。製作の主体をすぐにプラグインに移したため、倉庫入り していたのですが、スクリプトを製作しておられる方が結構いらっしゃるので、そういう人達に少しでも役に立てればと思い、今回公表しました。

導入法

Shade Python のファイル検索パスに含まれるディレクトリに同梱の、 shade_math.py をコピーします。(パスは、同梱の get_path.py というスクリプトを実行することで Shade メッセージウインドウに表示できます。)
Shade のインストールディレクトリ内の bin\Python27\lib\ 以下の任意の場所は、検索パスになってますので、そこに置いても構いませんが、そこはシステム領域ですので、出来ればユーザのDocument 下の Shade の管理領域に保存して、 sys.path に検索パスをそこを追加した方が適切かもしれません。
そして、利用する側のスクリプトの最初に

import shade_math または、 from shade_math import * のように記述して shade_math を取り込んでください。(この詳しい意味は、 Python の仕様を確認願います。ただ、最初の記述では、モジュール内のクラスの参照は、 shade_math.Vec3 のような表現になり、後半の記述では、 Vec3 のように、クラス名だけで直接参照できます。)
一度、スクリプトからインポートされると、新たに shade_math.pyc というモジュールが作られます。
一度、.pycが出来ると、.pyは不要になります。削除しても構いません。

基本的使い方

単純な話、インポートすると Python に、新たに Vec3 Quaternion (最初の文字は大文字です!)という新しい型が付加されます。
これらの型は、
v1 = Vec3(mesh.vertex(0).position) #mesh は、polygon_meshクラスのオブジェクト v2 = Vec3(mesh.vertex(1).position) q = Quaternion(ball.rotation) #ball は、ball_jointクラスのオブジェクト のように定義して、 w = v1 - v2 # v1 と v2 の差ベクトルを w に得る x = v1 ** v2 # v1 と v2 の外積を x に得る y = v1 * q # v1 を クォータニオン Q で回転した位置を y に得る のような表現が使えるようになります。数式は、一行にいくらでも複雑な記述が出来ますので、相当複雑な処理が見通しよく表現できます。さらに、 w = v * mesh.local_to_world_matrix で、w mat4 を掛けると、wmat4 の変換を施すことができます。(つまり、ワールド位置の取得:注:実際には Shade 自体の内部事情でこんなに簡単にワールド位置は取得出来ませんが・・・)
ただ、Vec3では、 Shade の座標値設定用の関数の引数には使えませんので、単なるリストに戻す、to_list() というメンバー関数も用意してあります。
それ以外に、幾つかの汎用関数と、 Pi :πの値 Sqrt2 :√2の値の二つの定数が定義してます。
詳細は、以下の各章でのリファレンスを参照願います。

Vec3 リファレンス

Vec3 は、3次元ベクトルクラスです。ベクトル間の基本的演算と内部情報の取得、クォータニオン及び、2次元タプルで表現された Mat4 との乗算をサポートしています。

Quaternion リファレンス

Quaternion は、4元数クラスです。ベクトル及び、4元数間の基本的演算と内部情報の取得をサポートしています。

汎用関数

以下は、shade_math内に定義されている関数の内、十分実用になりそうなもののみ説明してます。 今回ここに形状のポイントのワールド座標での値を得る関数と、対象の形状のローカル座標系を考慮しながら、ワールド位置を与えてそこにポイントを設定する関数を加えました。 それ以外にその時点で私が必要に迫られて作った関数も内包してますが、 あまり実用的でないものは、説明しません。

定数

時々直接定数として欲しいと思える定数を定義してます。他のモジュールで既に定義があるかもしれないし、必要性も気になる点ではありますが、わざわざ記述したのを削除するのも何なのでそのまま残してます。
Pi:πの値です。モジュール内で値を確認してください。
Sqrt2:√2の値です。時々利用するときがあるので、定義しました。

履歴