주요 콘텐츠로 건너뛰기
버전: 3.5.x

부호 있는 거리 함수 (SDF)

부호화된 거리 필드(SDF)를 사용하면 메쉬 대신 거리 함수를통해 구, 상자, 캡슐, 평면과 같은 간단한 3D 기하학적 형태를 표현할 수 있습니다. 저희 햅틱스 스택에서 SDF는 장치 세션에 연결할 수 있는 힘 필드로 변환됩니다. 커서가 해당 형상에 접근하거나 형상 내부로 들어갈 때, 시스템은 거리, 범위, 이징(easing)에 따라 강도가 결정되는 법선력을 생성합니다.

이 페이지에서는 해당 패치를 통해 추가되거나 업데이트된 공개 API를 설명합니다. 여기에는 SDF 햅틱 효과 페이로드, 지원되는 형상, 매개변수, 그리고 SDF 효과를 생성, 업데이트, 열거 및 삭제하기 위한 요청/응답 예시가 포함됩니다.

개념 모델​

SDF 효과는 다음과 같습니다:

  • A 모양 (예: sphere, box, capsule, plane)
  • 변환 (공간 내 효과의 위치/회전/크기)
  • A 매개변수 객체 (params) 선택한 도형의 속성(반지름, 끝점, 크기, 법선 등)을 설정합니다
  • 강제 제어:
    • force_scale — 전체 크기 배율
    • range — 표면 바깥쪽에서 힘이 0으로 점차 감소하는 “활성 대역”의 두께
    • ease + reverse_easing — 거리에 따른 힘의 변화율
  • 구성 제어:
    • symmetry — 내부와 외부의 구분 방식
    • blend — 여러 SDF 효과가 어떻게 결합되는지

장치당 여러 개의 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부울⛔사실이라면 이완 방향을 반전시킵니다. 기본값: 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 값사용된 매개변수
구체spherer
상자boxb (반쪽 크기)
둥근 상자rounded_boxb (반쪽 크기), r (모서리 반경)
캡슐 (세그먼트)capsulea, b, r
캡슐 (세로형)capsule_verticalh, r
뚜껑이 있는 실린더 (세그먼트)capped_cylindera, b, r
뚜껑이 있는 실린더 (수직형)capped_cylinder_verticalh, r
비행기planen, 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와 동일한 세션/디바이스 라우팅 규칙을 따릅니다.

  • 한 장치에 여러 개의 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 (device에 대해 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 명령어는 이뎁포텐트(idempotent)이며, 데이터가 삭제되지 않았더라도 표준 OK 응답을 반환합니다.

예시​

손으로 눌러서 모양을 바꿀 수 있는 구형 “버블”​

{
  "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"
}