符号付き距離関数（SDF）

符号付き距離場（SDF）を使用すると、メッシュの代わりに距離関数を用いて、球体、箱、カプセル、平面などの単純な3D形状を記述することができます。 当社のハプティクス・スタックでは、SDFはデバイス・セッションに紐付けることができる力場となります。カーソルが形状に接近（または 進入）すると、システムは距離、範囲、およびイージングに基づいて強さが決まる法線力を生成します。

このページでは、このパッチによって追加・更新された公開APIについて説明します。具体的には、SDFハプティクスエフェクトのペイロード、サポートされている形状、パラメータ、 およびSDFエフェクトの作成、更新、一覧表示、削除に関するリクエストとレスポンスの例を記載しています。

概念モデル

SDFの効果は次のとおりです：

• A 形状 （例： sphere, box, capsule, plane)
• トランスフォーム（空間におけるエフェクトの位置・回転・拡大縮小）
• A パラメータオブジェクト (params) 選択した図形の形状（半径、端点、範囲、法線など）を設定する
• フォースの操作：
  • force_scale — 総合的な増幅率
  • range — 表面の外側で力がゼロになるまでの「アクティブバンド」の厚さ
  • ease + reverse_easing — 距離に伴う力の変化
• 構成の制御：
  • symmetry — 内側と外側の扱い方
  • blend — 複数のSDF効果がどのように組み合わさるか

1つのデバイスにつき複数のSDFエフェクトを作成できます。各エフェクトには固有の id.

SDF効果

{
  "id": "string",
  "transform": {
    /* transform object */
  },
  "shape": "sphere | box | rounded_box | capsule | capsule_vertical | capped_cylinder | capped_cylinder_vertical | plane",
  "params": {
    /* shape parameters */
  },
  "force_scale": 1.0,
  "range": 1.0,
  "ease": "linear",
  "reverse_easing": false,
  "symmetry": "single | mirror | align",
  "blend": "additive"
}

フィールド参照

フィールド	タイプ	必須	意味
id	ストリング	✅	デバイス内におけるこのエフェクトの一意の識別子。
transform	オブジェクト	✅	ワールド座標系／デバイス座標系におけるエフェクトの位置。
shape	ストリング	✅	評価対象のSDFプリミティブ。
params	オブジェクト	✅	形状固有のパラメータ（下記参照）。
force_scale	番号	⛔	最終的な力の大きさを乗算します。デフォルト： 1.0.
range	番号	⛔	効果が有効となる表面からの距離（メートル単位）。デフォルト： 1.0.
ease	ストリング	⛔	適用された緩和曲線 [0..range]. 既定値： linear.
reverse_easing	ブール値	⛔	これが true の場合、イージングの方向が反転します。デフォルト： false.
symmetry	ストリング	⛔	内部と外部の扱い（下記参照）。デフォルト： single.
blend	ストリング	⛔	複数のSDF効果の組み合わせ方。デフォルト： additive.

---

形状とパラメータ

すべての形状は、単一の params オブジェクト。以下のように指定できます 必要なフィールドのみ 選択した図形に対して。

params オブジェクト

{
  "r": 1.0,
  "h": 0.0,
  "a": [0.0, 0.0, 0.0],
  "b": [0.0, 0.0, 0.0],
  "n": [0.0, 1.0, 0.0]
}

ヒント：値はエフェクトの ローカル空間 （適用後 transform).

対応形状（現在）

現在、以下のSDFプリミティブのみがサポートされています（数学的な背景については、IQのSDFギャラリーを参照してください）：

形状	shape 値	使用されたパラメータ
スフィア	sphere	r
ボックス	box	b （半ページ）
角が丸い箱	rounded_box	b （ハーフエクステンツ）、 r （コーナー半径）
カプセル（セグメント）	capsule	a, b, r
カプセル（縦型）	capsule_vertical	h, r
キャップ付きシリンダー（セグメント）	capped_cylinder	a, b, r
蓋付きシリンダー（縦型）	capped_cylinder_vertical	h, r
飛行機	plane	n, h

規約に関する注意事項

• ベクトル 配列は： a, b, n は3D（[x,y,z]).
• ボックス 用途 b ハーフエクステンツとして（例： b=[0.1,0.2,0.1]).
• 飛行機 用途 n 通常通り、そして h 法線に沿ってオフセットされたものとして。
• 縦 バリアントの使用 h 半分の高さとして（ローカルY軸に沿って原点に中心が位置するカプセル／円柱）。

---

対称性

symmetry フィールドがサーフェスに対してどのように振る舞うかを制御します：

• single — 標準的な動作です。「内部」と「外部」の区別は維持されます。
• mirror — 表面までの絶対距離を使用し、表面の「後ろ」に来た際に進行方向を反転させ、鏡像のような挙動を実現します。
• align — 方向を反転させずに絶対距離を使用します（「常に同じ方向に押す」ようなエフェクトに便利です）。

---

緩和と範囲

力の大きさは、表面からの距離とともに増加する：

• 表面では（距離＝ 0): 最大振幅（緩和の対象となる）
• 距離 = range: 振幅は 0 （非アクティブ）

ease 減衰曲線を定義します。 reverse_easing 曲線を反転させる。

---

コマンド

• "set_sdf": ローカライズされたSDFエフェクト（アイテムの配列）を作成または更新する
• "remove_sdf": ID（IDの配列）でエフェクトを削除する

SDFエフェクトの設定／更新

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_sdf": [
          {
            "id": "boundary_049D",
            "transform": {
              "position": {
                "x": 0,
                "y": -0.05,
                "z": -0.04
              },
              "rotation": {
                "x": 0,
                "y": 0,
                "z": 0,
                "w": 1
              },
              "scale": {
                "x": 0.15,
                "y": 0.1,
                "z": 0.1
              }
            },
            "shape": "sphere",
            "force_scale": -2.0,
            "range": 0.1,
            "ease": "cubicInOut",
            "reverse_easing": false,
            "symmetry": "single",
            "blend": "additive",
            "params": {
              "r": 1.0
            }
          }
        ]
      }
    }
  ]
}

SDFエフェクトを解除する

{
  "inverse3": [{
    "device_id": "049D",
    "commands": {
      "remove_sdf": ["boundary_049D"]
    }
  }]
}

• 配列内の各IDが存在する場合、それらは削除されます。
• 存在しないIDの削除は、何もしない操作（呼び出しても安全）として扱われます。

---

REST API

SDFエンドポイントは、その他のハプティクスAPIと同様のセッション/デバイスルーティングの規則に従います。

• 1つのデバイスに複数のSDFエフェクトを適用することができます。
• 各エフェクトは、その id.
• エフェクトは、デバイスごとに個別に、または一括で管理できます。

ルート

• 取得

  • /{device_type}/{device_id}/sdf?session_id=<sid> → デバイススコープ（SDFの一覧）
  • /{device_type}/{device_id}/sdf/{hfx_id}?session_id=<sid> → 単一のSDF
  • /{device_type}/*/sdf?session_id=<sid> → セッションスコープ（すべてのデバイス）
  • /{device_type}/*/sdf (いいえ session_id) → すべてのセッション

• 投稿

  • /{device_type}/{device_id}/sdf/{hfx_id}?session_id=<sid> 本文： sdf_hfx （作成／更新）
  • /{device_type}/{device_id}/sdf?session_id=<sid> 本文： device_sdf_dto （デバイスの「many」を置換またはアップサートする）

• 削除

  • /{device_type}/{device_id}/sdf?session_id=<sid> または .../sdf/{hfx_id}?session_id=<sid>
  • session_id=* 「すべてクリア」に対応しています。

インフォメーション

ハンドラーが検証を行う device_type (inverse3 （のみ）、強制する session_id/device_id 存在、そして帰還 404 セッション／デバイス／エフェクトが見つかりません。

主な行動の特徴

• GETリクエストのルーティング範囲：パスやパラメータに応じて、すべて → セッション → デバイス → 単一の効果。
• POSTはパス/ボディを強制する id リストを投稿する際、単一効果の書き込みとマージ/セットの一貫性を確保し、デバイスレベルのSDFを設定します。
• DELETE は冪等であり、何も削除されなかった場合でも標準的な成功応答を返します

---

例

指で押せる球形の「バブル」

{
  "id": "bubble",
  "transform": {
    /* place it where you want */
  },
  "shape": "sphere",
  "params": {
    "r": 0.12
  },
  "force_scale": 1.0,
  "range": 0.08,
  "ease": "linear",
  "reverse_easing": false,
  "symmetry": "single",
  "blend": "additive"
}

角が丸い箱「ソフトウォール」

{
  "id": "soft_wall",
  "transform": {
    /* oriented wall */
  },
  "shape": "rounded_box",
  "params": {
    "b": [
      0.30,
      0.02,
      0.30
    ],
    "r": 0.01
  },
  "force_scale": 0.9,
  "range": 0.06,
  "ease": "cubicInOut",
  "reverse_easing": false,
  "symmetry": "single",
  "blend": "additive"
}

セグメントカプセル「レール」

{
  "id": "rail",
  "transform": {
    /* position/rotate rail */
  },
  "shape": "capsule",
  "params": {
    "a": [
      -0.15,
      0.0,
      0.0
    ],
    "b": [
      0.15,
      0.0,
      0.0
    ],
    "r": 0.015
  },
  "force_scale": 0.7,
  "range": 0.05,
  "ease": "quadraticOut",
  "reverse_easing": false,
  "symmetry": "mirror",
  "blend": "additive"
}

平面上の「見えない境界線」

{
  "id": "boundary",
  "transform": {
    /* place plane */
  },
  "shape": "plane",
  "params": {
    "n": [
      1.0,
      0.0,
      0.0
    ],
    "h": 0.0
  },
  "force_scale": 0.8,
  "range": 0.10,
  "ease": "linear",
  "reverse_easing": false,
  "symmetry": "single",
  "blend": "additive"
}