Property Stack¶
Property Stack(メニューの種類 CONDITION)は、条件行を 1 つの Boolean のスイッチにまとめ、
スイッチが設定されたときに設定値を書き込みます。
ロジックは全体を置き換えるか、条件行を 1 行ずつ編集します。
While True HUD には専用の関数があります。ロジックの関数は HUD と Property ID を変更しません。
単体の Property は Property で説明します。
関数 |
用途 |
|---|---|
ロジックと登録を |
|
ロジック全体を置き換えます。 |
|
空の条件行を末尾に追加します。 |
|
条件行を 1 行変更します。 |
|
条件行を 1 行と、その行から派生した書き込み項目を削除します。 |
|
While True HUD を変更します。 |
関連項目: Property Stack を作成して状態を表示する。 評価だけに使う行と書き込み方式の意味は Property Stack Editor を参照してください。
関数¶
- pme.editing.update_property_stack(pm_uid, *, logic, expected_digest=None, dry_run=False)¶
Property Stack のロジック全体を置き換えます。
logicに含まれない行と書き込み項目は削除されます。UID の割り当てや修復は行いません。 各condition_uidとentry_uidは、存在し、一意である必要があります。- パラメータ:
pm_uid (str) -- Property Stack の UID。
logic (dict) -- ロジック全体。形式は ロジック のとおりです。
while_true_hudは含めません。HUD はupdate_property_stack_hud()で変更します。expected_digest (str or None) --
read_pm()["property_stack"]["digest"]。保存されているロジックが変わっている場合、更新はstale_property_stack_digestで拒否されます。dry_run (bool) -- ロジックを検査し、書き込まずに返ります。
- 戻り値:
共通の結果 で説明する結果。
condition_uidはありません。- 戻り値の型:
- 例外:
RuntimeError -- Blender のメインスレッド以外から呼ばれた、または PME の読み込みが完了していない。
ステータス
committed、validated、unchanged、rejected、unknownのいずれか。 読み取ったlogicと等しいロジックは、新しい Property Stack でも、書き込まずにunchangedを返します。読み取ったdiagnosticsに"repair"の正規化がある場合は、 同じロジックでも書き込みます。この書き込みで、読み取りのビューが省いたものが保存データから削除されます。診断
共通の結果 のコードに加えて、次のコードを返します。 すべて
scopeは"input"です。code原因と追加のキー
property_stack_logic_must_be_a_mappinglogicが dict ではありません。property_stack_hud_not_editablelogicにwhile_true_hudがあります。property_stack_input_must_be_json_valueslogicに JSON で表せない値 (set や NaN など) があります。property_stack_schema_invalidlogicが Schema v2 のPropertyStackLogicに合いません。pathが項目を、messageが規則を示します。schema_v2_logic_condition_uid_repairedcondition_uidが前の値と重複しています。schema_v2_logic_entry_uid_repairedentry_uidが空、または前の値と重複しています。schema_v2_logic_derived_condition_uid_repaired、schema_v2_logic_derived_condition_uid_unmatchedderived_from_condition_uidが修復された行を指している、またはあるcondition_uidから派生する項目が、その UID を持つ行の数より多くあります。schema_v2_logic_write_entry_pm_property_ref_stale_droppedPME Property への書き込みに、対応する条件行がありません。
schema_v2_logic_predicate_row_malformedfloat行の整数値を float にできません。その他の
schema_v2_logic_*コードSchema v2 の decoder がロジックを拒否または修復しました。
pathは"logic"です。property_stack_normalization_rejecteddecoder が、意味の異なる値に変更しました (修復された UID、破棄された項目、
offになった書き込み状態など)。path、input、normalizedが変更を示します。property_stack_canonicalizedseverityは"info"で、拒否しません。decoder が、意味の同じ値の形を変更しました (1.0から1など)。例
いずれかの条件が一致したときに Stack を TRUE にします。
import copy stack = pme.editing.read_pm(stack_uid)["property_stack"] logic = copy.deepcopy(stack["logic"]) logic["combine_mode"] = "any" result = pme.editing.update_property_stack( stack_uid, logic=logic, expected_digest=stack["digest"], ) assert result["status"] == "committed", result["diagnostics"]
補足
既存の Stack の一部を変えるには、読み取った
logicのその部分を変更し、 読み取ったdigestとともに渡します。その他の値、各condition_uid、entry_uid、derived_from_condition_uidはすべて保持します。読み取った
logicを渡す前に、scope="current_storage"の診断を確認します。 ビューでは、すでに項目が省かれていたり、書き込みが無効になっていたりすることがあります。 入力の検証は、読み取り時に適用された正規化を取り消しません。現在の保存データの診断は、警告として結果に引き継がれます。それだけでは呼び出しを拒否しません。
logicがNoneの Stack も置き換えられます。dry run は、参照元の評価、実行時の書き込み可否の確認、Setter の実行、ウィジェットの検証を行いません。
While True HUD と、保存されている Property ID および登録されている Property ID は変更しません。
この呼び出しは、Preferences のディスクへの保存、Undo ステップの追加、Getter や Setter の実行を行いません。
書き込み中に発生した例外は traceback を保持し、最後のステータスを示す注記が付きます。 再試行の前に
read_pm()を呼んでください。
- pme.editing.add_property_stack_row(pm_uid, *, expected_digest=None, dry_run=False)¶
エディターと同じ処理で、空の条件行を末尾に追加します。
新しい行は有効で
incompleteです。source、op、value、value_typeはNone、ラベルは"Condition N"(N は行の位置) です。 行に定義が設定されるまで、書き込み項目は追加されません。- パラメータ:
- 戻り値:
共通の結果 で説明する結果。
condition_uidは新しい行の UID で、dry run では行に割り当てられる予定の UID です。 候補ができる前に拒否されたときはNoneです。- 戻り値の型:
- 例外:
RuntimeError -- Blender のメインスレッド以外から呼ばれた、または PME の読み込みが完了していない。
診断
共通の結果 のコードに加えて、次のコードを返します。
code原因
property_stack_current_storage_requires_explicit_repair保存されているロジックをデコードできない、または読み取り時に意味や identity が修復されました (blocking のコード、または
"repair"の正規化)。update_property_stack()で置き換えます。predicate_row_limit_reachedStack にすでに 128 行あります。
例
before = pme.editing.read_pm(stack_uid)["property_stack"] added = pme.editing.add_property_stack_row( stack_uid, expected_digest=before["digest"], ) assert added["status"] == "committed", added["diagnostics"] row_uid = added["condition_uid"]
補足
dry run の
condition_uidは、後の呼び出しで確定するまで候補にすぎません。ほかの行、書き込み項目、HUD 設定、Property ID は保持されます。
- pme.editing.update_property_stack_row(pm_uid, condition_uid, fields, *, expected_digest=None, dry_run=False)¶
エディターと同じ処理で、条件行 1 行の参照元、比較方法、値、値の型、ラベル、有効状態を変更します。
省略した項目は保持されます。行の
authoring_stateと、その行から派生した書き込み項目は、 エディターの規則に従います。- パラメータ:
- 戻り値:
共通の結果 で説明する結果。
condition_uidは引数の値です。- 戻り値の型:
- 例外:
RuntimeError -- Blender のメインスレッド以外から呼ばれた、または PME の読み込みが完了していない。
変更
影響
source、op、value、value_typeの変更行に定義が設定されます。比較方法がその値の型を受け付け、値が比較方法に合う場合、
authoring_stateはcomplete、それ以外はincompleteになります。 派生した書き込み項目が作成または更新されます。新しい項目のentry_uidは"write_<condition_uid>"です。結果の
op、value、value_typeがすべてNone参照元のみ。行は
incompleteのままで、派生した書き込み項目は削除されます。labelのみ書き込み計画は変わりません。
enabled派生した書き込み項目はエディターの規則に従います。行を無効にすると、その項目は
offになります。保存値と等しい値は変更として扱いません。何も変わらない場合、ステータスは
unchangedです。診断
共通の結果 のコードに加えて、次のコードを返します。 すべて
scopeは"input"です。code原因
property_stack_current_storage_requires_explicit_repairadd_property_stack_row()と同じです。condition_uid_invalidcondition_uidが空でない文字列ではありません。predicate_row_not_foundcondition_uidを持つ行がありません。condition_identity_ambiguous複数の行が
condition_uidを持っています。property_stack_row_fields_must_be_a_mappingfieldsが dict ではありません。property_stack_row_field_unsupportedfieldsに上の 6 つ以外のキーがあります。property_stack_schema_invalidと、update_property_stack()のその他のコードfieldsを適用した行が Schema v2 のPmeLogicConditionRowに合いません。検査は入力に対して行い、completeになった行に対してもう一度行います。pathは 1 行だけのロジックを基準にします ("logic.predicate_rows[0].value"など)。predicate_row_source_required定義の項目が指定されたが、行に参照元がありません。
predicate_row_operator_unsupportedvalue_typeまたはvalueが設定されているのに、結果のopがNoneです。predicate_row_value_type_unsupportedopが設定されているのに、結果のvalue_typeがNoneです。predicate_row_operator_type_mismatchopがvalue_typeを受け付けません。predicate_row_value_type_mismatchvalueがopとvalue_typeに合いません。write_entry_limit_reached定義によって、書き込み項目が 128 を超えます。
例
フレーム 1 で真になる行を追加します。
before = pme.editing.read_pm(stack_uid)["property_stack"] added = pme.editing.add_property_stack_row(stack_uid, expected_digest=before["digest"]) if added["status"] != "committed": raise RuntimeError(added) row_uid = added["condition_uid"] updated = pme.editing.update_property_stack_row(stack_uid, row_uid, { "source": {"kind": "rna_path", "root": "context", "detected_type": "int", "readonly": False, "segments": [ {"kind": "attr", "name": "scene"}, {"kind": "attr", "name": "frame_current"}]}, "op": "equals", "value": 1, "value_type": "int", "label": "First frame", }, expected_digest=added["after"]["digest"]) print(updated["status"], updated["diagnostics"])
補足
空の行は
labelとenabledを受け付けます。定義の設定には、null ではない参照元が必要です。値を必要とする比較方法を値なしで指定すると、行は
incompleteのまま、 派生した書き込み項目はmanual_requiredになります。独立した書き込み項目、ほかの行、
combine_mode、false_policy、HUD 設定、Property ID は保持されます。この呼び出しは、Preferences のディスクへの保存、Undo ステップの追加、Getter や Setter の実行を行いません。
unknownまたは例外のあとは、再試行の前にread_pm()を呼んでください。
- pme.editing.remove_property_stack_row(pm_uid, condition_uid, *, expected_digest=None, dry_run=False)¶
条件行を 1 行と、その行から派生した書き込み項目を削除します。
最後の 1 行も削除できます。独立した書き込み項目は保持されます。
- パラメータ:
- 戻り値:
共通の結果 で説明する結果。
condition_uidは引数の値です。- 戻り値の型:
- 例外:
RuntimeError -- Blender のメインスレッド以外から呼ばれた、または PME の読み込みが完了していない。
診断
共通の結果 のコードに加えて、
update_property_stack_row()と同じproperty_stack_current_storage_requires_explicit_repair、condition_uid_invalid、predicate_row_not_found、condition_identity_ambiguousを返します。例
current = pme.editing.read_pm(stack_uid)["property_stack"] removed = pme.editing.remove_property_stack_row(stack_uid, row_uid, expected_digest=current["digest"])
- pme.editing.update_property_stack_hud(pm_uid, changes, *, expected=None, dry_run=False)¶
Property Stack の While True HUD を、Advanced settings と同じように変更します。
すべての値を、最初の書き込みの前に検査します。HUD は JSON の import や Duplicate と同じ書き込み境界を通して書き、
enabledを最後に設定して、読み戻します。- パラメータ:
pm_uid (str) -- Property Stack の UID。
changes (dict) -- While True HUD の項目 の項目名と新しい値の対応。指定しない項目は保存値を保ちます。
expected (dict or None) -- 保存されている
while_true_hudの任意の一部。値が異なる場合はstale_property_stack_hudで拒否します。dry_run (bool) -- 書き込まずに検査し、候補を返します。
- 戻り値:
下で説明する結果。
- 戻り値の型:
- 例外:
TypeError --
changesかexpectedが文字列キーのマッピングでない場合、またはdry_runが bool でない場合。ValueError -- 項目名が未知の場合、または UID が存在しない、無効、曖昧、Property Stack でない場合。
RuntimeError -- Blender のメインスレッド以外から呼んだ場合、または PME の読み込みが終わる前に呼んだ場合。
結果
キー
型
値
statusstr
下の「ステータス」を参照してください。
committedbool
statusが"committed"のときだけTrueです。dry_runbool
引数
dry_run。pm_uidstr
引数
pm_uid。beforedict
呼び出し開始時の
while_true_hud。afterdict
呼び出し終了時の
while_true_hud。何も書き込まなかったときはbeforeと同じです。candidatedict or None
保存する、または
dry_run=Trueで保存される HUD 全体。候補を作る前に拒否したときはNoneです。changed_fieldslist[str]
beforeとafterで保存値が異なる項目。recoverydict or None
書き込みに失敗した後:
scope("while_true_hud") とsaved_hud_matches。diagnosticslist[dict]
下の「診断」を参照してください。
ステータス
status意味
committedHUD をメモリ内に保存し、要求どおりに読み戻しました。
validateddry_run=Trueで、要求を受け付けられます。何も書き込んでいません。unchanged候補が保存されている HUD と同じです。何も書き込んでいません。
rejected何も書き込んでいません。原因は
diagnosticsにあります。restored_failure書き込みが例外を送出したか、値が保持されませんでした。直前の HUD を書き戻し、同じ値で読み戻しました。
unknown直前の HUD の書き戻しを確認できませんでした。再試行の前にメニューを読み直してください。
診断
code原因と追加のキー
stale_property_stack_hudexpectedの値が異なります。fields。property_stack_hud_value_invalidHUD が保持できない値です。型の誤り、HUD を表示できないエディター、
LABELとFRAME以外のdisplay、表示形式が持たないalignment、0.0〜1.0 の範囲外のcolorの成分、UTF-8 で 256 byte を超えるmessageやicon、Blender のアイコン名でも@customアイコンでもない名前、HUD が描けない Blender のアイコンのいずれかです。field、value、message。area_type、display、alignmentではchoices、文字列の長さではsizeとlimit。invalid_syntaxis_exprがTrueで、messageをコンパイルできません。field、message、line、column(messageの中の位置)。icon_not_found警告: その
@nameのカスタムアイコンがありません。HUD は保存され、アイコンができるまでアイコンなしで表示します。fieldとvalue。property_stack_hud_write_failed書き込みが例外を送出しました。
exception_typeとmessage。property_stack_hud_value_not_retained項目が要求と異なる値で読み戻されました。
fields、requested、actual。例
stack_uid = pme.create_pm(pme.PmCreationSpec("CONDITION", name="X Mirror")).pm_uid result = pme.editing.update_property_stack_hud(stack_uid, { "enabled": True, "message": "X-Axis Mirror", "display": "FRAME", "alignment": "LEFT", "icon": "MOD_MIRROR", "use_color": True, "color": [0.2, 0.6, 1.0], }) assert result["status"] == "committed", result["diagnostics"]
補足
編集画面は、新しい表示形式が持たない位置を
TOPへ寄せます。この関数は寄せずに拒否します。displayとalignmentは一緒に指定してください。is_exprだけを変えると、編集画面の Expression の切り替えと同じくmessageを変換します。Mirrorはreturn 'Mirror'になります。messageも指定した場合は、指定した本文をそのまま保存します。文字列の上限は文字数ではなく UTF-8 の byte 数です。256 byte は日本語で 85 文字です。
編集画面と同じく、条件のない Property Stack でも HUD を有効にできます。
logic、そのdigest、メニューのバージョンは変わりません。ロジックの関数は HUD を変更しません。複製した Property Stack の HUD は
enabledを切った状態で写されます。書き出しと import ではlogic.while_true_hudに入ります。この呼び出しは Preferences をディスクに保存せず、Undo ステップも追加しません。
While True HUD の項目¶
changes 、 expected 、 read_pm()["property_stack"]["while_true_hud"] は次の項目を使います。
項目 |
型 |
値 |
|---|---|---|
|
bool |
Property Stack が True の間 HUD を表示します。既定値は |
|
str |
文字列。 |
|
bool |
|
|
str |
HUD を表示するエディター。 |
|
str |
|
|
str |
|
|
str |
HUD が描ける Blender のアイコン名、 |
|
bool |
|
|
list[float] |
0.0〜1.0 の 3 成分。既定値は |
TRUE と FALSE¶
FALSE の動作は、設定ごとに選びます。false_policy="no_op" でも、Boolean の
auto_resolved 項目は FALSE のとき反転した値を書き込みます。
目的の操作 |
TRUE |
FALSE/書き込み項目の選択 |
|---|---|---|
Surface または Volume プリセット |
2 つの Boolean を指定値にする |
書き込みなし。固定値の Boolean 項目には |
3D Step Snap |
全体の Snap を ON、対象の変形を ON、INCREMENT に設定 |
対象の変形だけを OFF にする。その Boolean 項目を |
UV Step Snap |
UV Snap を ON、対象の変形を ON、INCREMENT に設定 |
UV Snap を OFF にする。その Boolean 項目を |
Enum 集合では、enum_set_write_mode="replace" と
enum_set_write_values=["INCREMENT"] を持つ manual_resolved 項目は、
TRUE で集合を置き換え、FALSE では書き込みません。
Getter は、目的の集合だけでなく、余分な要素を含む集合でも確かめてください。
FALSE は以前の状態を復元しません。
同じ規則のエディター側の説明は TRUE / FALSE を指定すると何を書き込むか にあります。