トレイト

Unity MARS の Trait (トレイト) とは、意味的に重要なデータのことです。トレイトには、名前と、関連付けられているデータ型があります。トレイト は、タグ付けされたカスタムデータを MARS データベースに追加するために使用されます。Proxy (プロキシ) は、エンティティのトレイトがプロキシの Condition (条件) や Relation (関係) を満たしたときにデータベース内のエンティティと一致します。複雑な条件や関係が設定されたプロキシでは、合成トレイトを使用して、部屋の隅をマークする、椅子にタグ付けするなどの処理を実行できます。また、MARS Reasoning API を使用すると、Floor Reasoning API で部屋の床平面に Floor Trait (床トレイト) を追加する方法のように、既存のエンティティに トレイト を自動で追加することもできます。

このセクションでは、MARS に含まれているトレイト、Semantic Tag (セマンティックタグ) のほか、プロキシにトレイトの要件を追加する方法 (エディターを使用した場合とスクリプトを使用した場合の両方) について説明します。さらに、独自のカスタムトレイトタイプを定義する方法とカスタムトレイトタイプを MARS に追加する方法についても説明します。

セマンティックタグ

Semantic (セマンティック) タグとは、説明ラベルをデータにタグ付けする、特殊なトレイトです。"Plane" (平面) トレイトはセマンティックタグであり、データを AR 平面に分類します。セマンティックタグトレイトの値は bool 型で、タグを有効にするには true に設定する必要があります。SemanticTagCondition をタグの Match または Exclude に設定できます。Match は、照合を成功させるために、指定したセマンティックタグトレイトがデータに含まれる必要があることを意味します。Exclude は、データにタグが含まれて いない 場合にのみプロキシが一致することを意味します。

一般的なトレイト

Unity MARS には、一般的なトレイトが多数含まれています (以下の表を参照)。データベースには独自のカスタムタイプを追加できます。

トレイト	型	説明
pose	Pose	位置と回転
alignment	MarsPlaneAlignment	垂直/水平/なし
bounds2d	Vector2	使用可能な 2D スペースの範囲
markerid	string	このマーカーの ID
geolocation	GeographicCoordinate	地理的位置の緯度と経度
environment	bool	ユーザーの現在置かれている環境かどうか
face	bool	顔かどうか
inView	bool	表示されているかどうか
marker	bool	マーカーかどうか
plane	bool	平面かどうか
point	bool	点かどうか
user	bool	ユーザーかどうか
body	bool	ボディかどうか

プロキシへのトレイトの要件の追加

プロキシにトレイトの要件を追加するには、Add MARS Component ボタンをクリックして、Condition > Semantic Tag または Trait の順に選択し、プロキシに必要なタグまたはトレイトを選択します。

プロキシへのトレイトの追加

スクリプトによるトレイトの要件の追加

コードでは、IRequiresTraits<T> インターフェースを使用して、一致するデータオブジェクトに含まれるこれらのトレイトをリクエストしてアクセスすることができます。アクションによって指定されるすべての要件により、トレイトの結果の値が QueryResult 内の適切なディクショナリに格納されるため、その後、アクションはそれらにアクセスして処理を行うことができます。トレイトが任意の場合は、アクションによって、そのトレイトのないプロキシが一致しなくなることはありません。アクションの詳細については、アクションの記述を参照してください。

トレイトの要件を定義するには、TraitDefinition を使用して、それが任意かどうかを指定します。デフォルトでは、トレイトの要件は任意ではありません。以下に例を示します。

var nonOptionalRequirement = new TraitRequirement(TraitDefinitions.Pose);
var optionalRequirement = new TraitRequirement(TraitDefinitions.Bounds2D, false);

スクリプトによるトレイトの指定

IProvidesTraits<T> を実装したクラスは、トレイトを特定のデータ ID に関連付ける際に使用できる拡張メソッド AddOrUpdateTrait(int dataID, string traitName, T value) にアクセスできます。最初にデータ ID を作成するには、IUsesMARSTrackableData から取得した AddOrUpdateData を使用します。

IRequiresTraits を実装したクラスは、拡張メソッド TryGetTraitValue にアクセスできます。

システム内の任意のトレイトに対して Create、Update、および Delete 操作を実行できます。詳細については、Reasoning API に関するドキュメントを参照してください。

カスタムトレイトタイプ

独自のデータ型をトレイトの値として使用することができます。

トレイトタイプはクラスではなく 構造体 である必要があります (文字列を除く)。これは、トレイトが 1 つのエンティティ (サーフェスや顔など) の プロパティ であり、別のオブジェクトへの参照ではあってはならないためです。また、トレイトタイプには、参照型ではなく、他の値型だけをフィールドとして設定する必要があります。

例

サーフェスのライティング推定値を表すシンプルなカスタムトレイトタイプがどのようになるかを以下に示します。

SurfaceLightTrait.cs:

public struct SurfaceLightTrait
{
    public float Confidence;
    public float SurfaceBrightnessEstimate;
}

さらに、そのサーフェスのライティングのデータ型を使用する条件を記述します。

独自のタイプを使用する Condition または Relation を記述すると、そのタイプをトレイトとして使用したいことを Unity MARS に認識させることができます。

SurfaceBrightnessCondition.cs:

public class SurfaceBrightnessCondition : Condition<SurfaceLightTrait>
{
    public override float RateDataMatch(ref SurfaceLightTrait data)
    {
        // ここには実際の評価ロジックを設定しますが、これはスタブにすぎません
        return data.Confidence - 0.5f;
    }

    static readonly TraitRequirement[] k_RequiredTraits = { new TraitRequirement("surfaceBrightness", typeof(SurfaceLightTrait)) };
    public override TraitRequirement[] GetRequiredTraits() => k_RequiredTraits;

タイプの追加

Unity MARS で独自のタイプをトレイトとして使用するには、タイプをそのアセンブリにコンパイルし、コードを生成する必要があります。

その処理を実現するには、データ型のみを含むファイル (上記の例では SurfaceLightTrait.cs) を Assets/MARS/Extension Types フォルダーに移動します。再コンパイルが行われ、その後、独自のトレイトタイプが使用できるようになります。

データ型を使用する Condition または Relation をすでに記述していても、Extension Types フォルダーにない場合は、MARS によってそのことが検出され、データ型のファイルを移動するよう促すメッセージがコンソールに記録されます。