Dev:JA/Ref/Release Notes/3.00/Python API

元記事：Reference/Release Notes/3.0/Python API - Blender Developer Wiki

Blender 3.0: Python API

Python バンドル

• zstandard パッケージが zstd 圧縮の .blend ファイルの操作のために Python バンドルに追加されました（rBa5917175、[Core#Blend_file_read_.26_Write|リリースノートの .blend ファイル読み書き]]も参照してください）。

Text Editor（テキストエディター）

• Python スクリプトを立ち上げ時に実行する "Register"（登録）オプションで、名前に .py 拡張子が必要なくなりました。(3e775a4fc57cfd4)

その他の追加

• bpy.props ベクトルタイプ（FloatVectorProperty、IntVectorProperty、BoolVectorProperty）が多次元配列に対応しました。(bc0a7d3fae5cfbe)

4x4 行列のプロパティの定義例:

bpy.props.FloatVectorProperty(size=(4, 4), subtype='MATRIX')

• VSE: Sequence.parent_meta() python API 関数を追加。(eec1ea0ccf2)

• ファイルブラウザー内の選択ファイルリストを bpy.context.selected_files で取得可能に。(7ec839adfa99)

• ファイルブラウザー内で、FileSelectEntry.relative_path により、現在表示中のディレクトリに相対的な（ファイル名を含む）ファイルパスが得られます。
  これはファイルブラウザーが複数のレベルの再帰を表示する設定の時に使用する物で、この場合、同じ名前の複数のファイルが表示される可能性があります。そのため、ファイルの参照にはファイル名を使用せず、代わりにこの FileSelectEntry.relative_path を使用してください。(79281336c055)

• mathutils.{Vector/Matrix/Euler/Color/Quaternion} に、is_valid 属性が付きました。そのオーナーが有効かどうかをチェックするのに使用できます。(0950cfd9d53ef66)

• エリア管理の "Close" がスクリプト化可能に。例：bpy.ops.screen.area_close({"area": bpy.context.screen.areas[0]})。(9290b41381fd)

• UI: 追加のマウスカーソル [PICK_AREA, STOP, COPY, CROSS, MUTE, ZOOM_IN, ZOOM_OUT] がアクセス可能に。(6bf8c95e521d6ef)

• UI: bl_options 用の新しいオペレーター設定、DEPENDS_ON_CURSOR。メニューからのアクセス時、入力を待つオペレーターに使用します。(da2ba402689d7ed)

• UI: DEPENDS_ON_CURSOR を OperatorType.bl_cursor_pending を通して使用している時のカーソルの設定に対応。(2a8e5128c16c17a)

その他の変更

• RNA 構造体の IDProperties のクリアと確認を行う関数 id_properties_clear() と id_properties_ensure() を追加。(c202d3865904)

• Operator.poll_message_set(message, ...) を追加。
  オペレーターのポーリング関数が失敗した理由のメッセージを、オペレーターにセットできるようになりました。(ebe04bd3cafaa1f)

• 新しい bpy.app.handlers.xr_session_start_pre ハンドラ。バーチャルリアリティセッション開始時に実行されます。VR コントローラーのアクションマップ（キーマップの XR 版のようなもの）をセッションに渡すのが、主なユースケースです。(rBcb12fb78cad4)

• 新しい XrSessionSettings.use_absolute_tracking プロパティが true の時、個別のヘッドセット位置を定義する原点の VR トラッキングが可能になります。(rB36c0649d32aa)

• 新しい XrSessionSettings.base_scale プロパティは、VR ビューアーの参照スケールを定義します。(rB3434a991ec5b)

• 新しい XrSessionSettings プロパティは、VR オーバーレイ（show_selection、show_controllers、show_custom_overlays）とコントローラー表示（controller_draw_style）用です。(rB9dda65455b54)

• 新しい XrSessionState メソッドは VR アクション用です。(e844e9e8f3bb)
  • アクション作成：action_set_create()、action_create()、action_binding_create()、active_action_set_set()、controller_pose_actions_set()
  • アクションのクエリ：action_state_get()
  • ハプティクス：haptic_action_apply(),haptic_action_stop()
  • コントローラーポーズ：controller_grip_location_get()、controller_grip_rotation_get()、controller_aim_location_get()、controller_aim_rotation_get()

• 新しい XrSessionState.actionmaps コレクションプロパティは、デフォルトの VR アクションマップを格納します。Python スクリプトからデフォルトのアクションマップをこのコレクションに読み出し、その後で xr_session_start_pre ハンドラ中にてセッションのアクションを作成するのが主なユースケースです。(e844e9e8f3bb)

• 新しい XrSessionState.navigation_location/rotation/scale プロパティは、VR ビューアーのベースポーズ/スケールに差分を加算し、ビューポートをナビゲートできるようにします。(rB3434a991ec5b)

• 新しい XR_ACTION イベントタイプと Event.xr プロパティ。入力状態やコントローラーポーズなどの XR イベントデータへのアクセス用です。(rBcdeb506008e9)

• 新しい XR リージョンタイプ。VR ビューポート（ヘッドセットディスプレイ）と、ミラーリージョンへの描画用です。Space.draw_handler_add() を、リージョンタイプ XR と描画タイプ POST_VIEW で使用することで、アドオンから VR のカスタム描画が可能です。(rB9dda65455b54)

• 新しい Matrix.LocRotScale コンストラクタ。全トランスフォームチャンネルを、1コールで一つの行列にまとめます。(rBa86e815dd86)

互換性がなくなる変更

• PoseBone.custom_shape_scale スカラ値を、PoseBone.custom_shape_scale_xyz ベクトル値で置き換えました。さらに、custom_shape_translation と custom_shape_rotation_euler を追加しました。(rBfc5bf09fd88c)

• bbone_curveiny/bbone_curveouty を bbone_curveinz/bbone_curveoutz にリネーム。スケールのチャンネルを bbone_scalein.x/y/z と、bbone_scaleout.x/y/z ベクトルにまとめ、また、オリジナルの y も実際の Y スケールチャンネル用の空間にするため、z になりました。(rB682a74e0909)

• 未使用の BMesh.from_object の deform 引数を削除。(ead084b6e1a05b9)

• context.active_base を削除しました。(44db4e50b245041)

• アドオン用の wiki_url と bl_info の使用を停止（代わりに "doc_url" を使用してください。(aaa07a3a8f6427a)

• IDPropertyGroup.iteritems を削除、今は使用するすべてのイテレータに keys、values、items を使用してください。(B265d97556aa0f0)

• 一部の RNA アクセサがデータを作成しており、設計レベルにおいて複数の理由で非常に問題があるため、以下が変更されました。
  • フォースフィールドとコリジョン設定（Object.field、Object.collision、ParticleSettings.force_field_1、ParticleSettings.force_field_2）。
    オブジェクトの物は None である可能性があり、今は明示的に追加が必要です（Collision モディファイアーと forcefield_toggle オペレーター）、パーティクルの物は常にパーティクル設定と一緒に生成されます。
  • ID preview が None の可能性があるため、まず最初に新しい preview_ensure 関数を使用してください。

• bpy.app.binary_path_python を削除（代わりに sys.executable を使用してください）。(90b0fb135fdd060)

• UILayout.emboss の UI_EMBOSS_NONE_OR_STATUS を、NONE_OR_STATUS で置き換え。(0afe4e81cbb2)

• bpy.ops.wm.alembic_export から、機能していない renderable_only 引数を削除。(834e87af7bbf)

• preferences.view.show_layout_ui を、preferences.apps.show_corner_split に移動。(9fee59a4849)

• bpy.types.TOPBAR_MT_app と bpy.types.TOPBAR_MT_app_system を、bpy.types.TOPBAR_MT_blender と bpy.types.TOPBAR_MT_blender_system にリネーム。(58043c0637f8)

• アイコン SMALL_TRI_RIGHT_VEC を削除（同様のアイコンには DISCLOSURE_TRI_RIGHT を使用してください）。(368d7944073e)

IDProperty UI Data API

IDProperty UI データストレージがリファクタリングされ、特別な _RNA_UI サブグループを削除、プロパティの UI データ用に適したマネージャを追加しました。(8b9a3b94fc148d)

• 

  3.0より前の IDProperty UI データ。UI データは "_RNA_UI" サブグループに格納されていました

• 

  現在、UI データはこのプロパティに直接格納されています

• カスタムプロパティのある Python オブジェクトに、id_properties_ui(prop_name) メソッドが付きました。以下のメソッドのある UI データのマネージャが返ります。
  • update: UI データ値を更新します。min=1.0 や default="new_default" など
  • as_dict: UI データ値の入った辞書が返ります
  • clear: プロパティの UI データを削除します
  • update_from: プロパティ間で UI データを、違うオーナー間であってもコピーします

• 注意: 単純に UI データとともにプロパティを作成したいコードには、rna_prop_ui モジュール内の rna_idprop_ui_create ユーティリティ関数への切り替えをお勧めします。これは2.80から存在し、この内部への変更を通じ、互換性を維持した透過的なアップデートが行われています。

対応する UI データ

プロパティタイプ	Min	Max	Soft Min	Soft Min	Step	Precision	Default	Subtype	Description
Float	○	○	○	○	○	○	○（＋配列）	○	○
Integer	○	○	○	○	○	○	○（＋配列）	○	○
String							○	○	○
ID								○	○

ジオメトリのインスタンス化

従来では、オブジェクトはインスタンス化の最小単位でした。現在、メッシュなどのオブジェクトデータも、オブジェクトとそのデータを先につくらずにインスタンス化ができるようになりました。(5a9a16334c573c)

インスタンスにアクセスする API には変更はありませんが、一つだけより注意しないといけないことがあります。

import bpy
depsgraph = bpy.context.view_layer.depsgraph
for object_instance in depsgraph.object_instances:
    if object_instance.is_instance:
        print(object_instance.object.data, object_instance.instance_object.data)

従来、.object.data と .instance_object.data は常に同じでしたが、現在は差異がある可能性があり、.object.data を使用するのが正しいです。

• object_instance.object: インスタンスをラップする一時オブジェクト。ループ繰り返しの間は、このオブジェクトへの参照を格納してはいけません。

• object_instance.object.data: インスタンスの実際のオブジェクトデータ/ジオメトリ。このデータをレンダリング/エクスポートしてください。ループ繰り返しの間に格納可能で、ループ後も有効です。

• object_instance.matrix_world: インスタンスの変換行列。

• object_instance.instance_object: インスタンスを作成・所持するオブジェクト。

• object_instance.instance_object.data: インスタンスを作成したオブジェクトのデータ。今は多分使用されていません。

キーワードのみの引数の使用

• addon_utils.module_bl_info の2つめの引数 info_basis

• addon_utils.modules の最初の module_cache、2つめの引数 refresh

• addon_utils.modules_refresh の最初の引数 module_cache

• bl_app_template_utils.activate の最初の引数 template_id

• bl_app_template_utils.import_from_id の2つめの引数 ignore_not_found

• bl_app_template_utils.import_from_path の2つめの引数 ignore_not_found

• bl_keymap_utils.keymap_from_toolbar.generate の2つめと3つめの引数 use_fallback_keys と use_reset

• bl_keymap_utils.platform_helpers.keyconfig_data_oskey_from_ctrl の2つめの引数 filter_fn

• bl_ui_utils.bug_report_url.url_prefill_from_blender の最初の引数 addon_info.

• bmesh.types.BMFace.copy の最初と2つめの引数 verts、edges.

• bmesh.types.BMesh.calc_volume の最初の引数 signed.

• bmesh.types.BMesh.from_mesh の2つめから4つめまでの引数 face_normals、use_shape_key、shape_key_index

• bmesh.types.BMesh.from_object の3つめと4つめの引数 cage、face_normals

• bmesh.types.BMesh.transform の2つめの引数 filter

• bmesh.types.BMesh.update_edit_mesh の2つめと3つめの引数 loop_triangles、destructive

• bmesh.types.{BMVertSeq,BMEdgeSeq,BMFaceSeq}.sort の最初と2つめの引数 key、reverse

• bmesh.utils.face_split の4つめから6つめまでの引数 coords、use_exist、example

• bpy.data.libraries.load の2つめから4つめまでの引数 link、relative、assets_only

• bpy.data.user_map の最初から3つめまでの引数 subset、key_types、value_types

• bpy.msgbus.subscribe_rna の5つめの引数 options

• bpy.path.abspath の2つめと3つめの引数 start と library

• bpy.path.clean_name の2つめの引数 replace

• bpy.path.ensure_ext の3つめの引数 case_sensitive

• bpy.path.module_names の2つめの引数 recursive

• bpy.path.relpath の2つめの引数 start

• bpy.types.EditBone.transform の2つめと3つめの引数 scale、roll

• bpy.types.Operator.as_keywords の最初の引数 ignore

• bpy.types.Struct.{keyframe_insert,keyframe_delete} の2つめから5つめまでの引数 index、frame、group、options

• bpy.types.WindowManager.popup_menu の2つめと3つめの引数 title、icon

• bpy.types.WindowManager.popup_menu_pie の3つめと4つめの引数 title、icon

• bpy.utils.app_template_paths の最初の引数 subdir

• bpy.utils.blend_paths の最初から3つめまでの引数 absolute、packed, local

• bpy.utils.execfile の2つめの引数 mod

• bpy.utils.keyconfig_set の2つめの引数 report

• bpy.utils.load_scripts の最初の & 2つめ reload_scripts と refresh_scripts

• bpy.utils.preset_find の3つめと4つめの引数 display_name、ext

• bpy.utils.resource_path の2つめと3つめの引数 major、minor

• bpy.utils.script_paths の最初から4つめまでの引数 subdir、user_pref、check_all、use_user

• bpy.utils.smpte_from_frame の2つめと3つめの引数 fps、fps_base

• bpy.utils.smpte_from_seconds の2つめと3つめの引数 fps、fps_base

• bpy.utils.system_resource の2つめの引数 subdir

• bpy.utils.time_from_frame の2つめと3つめの引数 fps、fps_base

• bpy.utils.time_to_frame の2つめ & 3つめ 引数 fps、fps_base

• bpy.utils.units.to_string の4つめから6つめまでの引数 precision、split_unit、compatible_unit

• bpy.utils.units.to_value の4つめの引数 str_ref_unit

• bpy.utils.user_resource の2つめと3つめの引数 subdir、create

• bpy_extras.view3d_utils.location_3d_to_region_2d の4つめの引数 default

• bpy_extras.view3d_utils.region_2d_to_origin_3d の4つめの引数 clamp

• gpu.offscreen.unbind の最初の引数 restore

• gpu_extras.batch.batch_for_shader の4つめの引数 indices

• gpu_extras.batch.presets.draw_circle_2d の4つめの引数 segments

• gpu_extras.presets.draw_circle_2d の4つめの引数 segments

• imbuf.types.ImBuf.resize の2つめの引数 resize

• imbuf.write の2つめの引数 filepath

• mathutils.kdtree.KDTree.find の2つめの引数 filter

• nodeitems_utils.NodeCategory の3つめと4つめの引数 descriptions、items

• nodeitems_utils.NodeItem の2つめから4つめまでの引数 label、settings、poll

• nodeitems_utils.NodeItemCustom の最初と2つめの引数 poll、draw

• rna_prop_ui.draw の5つめの引数 use_edit

• rna_prop_ui.rna_idprop_ui_get の2つめの引数 create

• rna_prop_ui.rna_idprop_ui_prop_clear の3つめの引数 remove

• rna_prop_ui.rna_idprop_ui_prop_get の3つめの引数 create

• rna_xml.xml2rna の2つめの引数 root_rna

• rna_xml.xml_file_write の4つめの引数 skip_typemap

コミットを参照してください。(f29a738e23ce487)

モーションブラーの速度

Fluid（流体）と Alembic モディファイアーの頂点の速度のプロパティが削除されました。これらは頂点の位置が他のフレームと合わない、トポロジーの変わるメッシュのモーションブラーに使用されていました。(128eb6c)

• FluidDomainSettings.mesh_vertices

• MeshSequenceCacheModifier.vertex_velocities、MeshSequenceCacheModifier.has_velocity、MeshSequenceCacheModifier.read_velocity

代わりに、レンダラーとエクスポーターでは mesh の velocity 属性を使用してください。

for attribute in mesh.attributes:
    if attribute.name == 'velocity' and attribute.data_type == 'FLOAT_VECTOR':
         print([item.vector for item in attribute.data])

速度の単位も変更され、Blender のシーンの距離の単位/秒になりました。従来の頂点速度は秒ではなく、フレームを基準にしていました。