본문으로 건너뛰기

탐색

네비게이션 모듈을 사용하면Inverse3 커서를 통해 애플리케이션의 작업 공간을 이동할 수 있습니다. 이를 ‘속도 제어 이동(rate-control locomotion )’ 또는 ‘게임패드식 드리프트(gamepad-like drift)’라고도 부릅니다. 커서는 물리적 작업 공간의 가장자리에서 단단한 벽에 부딪히는 대신, 가상 중심으로부터의 거리가 작업 공간 전체를 미끄러지게 하는 속도로 변환되는 ‘부드러운 쉘’ 영역으로 들어갑니다. 커서를 멀리 밀수록 장면이 더 빠르게 스크롤됩니다.

주요(현재로서는 유일한) 동작은 버블 내비게이션입니다. 버블의 모양은 SDF 프리미티브를 사용하여 정의됩니다. 개념에 대해서는 ‘SDF란? ’을 참조하십시오.

버블 내비게이션 — 개요​

가상 버블은 장치의 마운트 공간 내 중심점을 기준으로 배치됩니다. 커서는 다음 세 개의 동심원 모양 구역을 통과합니다:

┌──────────────────────────────────────────┐
│              WALL ZONE                   │  cursor beyond outer shell
│  ┌────────────────────────────────────┐  │
│  │         VELOCITY ZONE              │  │  soft shell → scene moves
│  │  ┌──────────────────────────────┐  │  │
│  │  │       DEAD ZONE (inside)     │  │  │  no scene movement
│  │  │                              │  │  │
│  │  │         ● centre             │  │  │
│  │  │                              │  │  │
│  │  └──────────────────────────────┘  │  │
│  │       bubble surface               │  │
│  └────────────────────────────────────┘  │
│       outer boundary                     │
└──────────────────────────────────────────┘
존커서 위치동작
데드존(무감지 구역)버블의 내부내비게이션 기능은 제공되지 않습니다. 약간의 댐핑 효과가 적용됩니다. 장면을 자유롭게 조작할 수 있습니다.
속도 제한 구역표면과 바깥쪽 경계 사이거리에서 속도로 이어지는 곡선에 따라 커서가 가리키는 방향으로 작업 공간이 이동합니다.
벽 구역바깥쪽 경계를 넘어선 위치단단한 스프링이 커서를 안쪽으로 밀어내어, 탐색 속도가 상한선에서 포화 상태에 이릅니다.

3개의 구역 전체에 걸쳐 스프링·댐퍼 방식의 촉각 힘이 작용하여 표면, 드리프트 쉘, 바깥쪽 벽을 느낄 수 있습니다.

빠른 시작 — Bubble Navigation 활성화하기​

탐색 기능은 영구적이고 일회성 설정입니다. 한 번 전송하면 명시적으로 중지하거나, 서비스를 다시 시작하거나, 세션을 종료할 때까지 유효한 상태로 유지됩니다.

시작 (최소 구성 — 기본 둥근 모서리 상자형 버블)​

{
  "inverse3": [
    {
      "device_id": "04C3",
      "configure": {
        "navigation": { "mode": "bubble" }
      }
    }
  ]
}

중지​

{
  "inverse3": [
    {
      "device_id": "04C3",
      "configure": {
        "navigation": { "mode": "disabled" }
      }
    }
  ]
}

기타 HTTP 엔드포인트​

메서드패스용도
GET/{type}/{id}/config/navigation?session=<expr>현재의 탐색 설정 및 상태
POST/{type}/{id}/config/navigation?session=<expr>탐색 시작 또는 새로 고침
DELETE/{type}/{id}/config/navigation?session=<expr>탐색 중지

버블 모양 목록​

버블의 데드존(무반응 구역)은 부호 있는 거리 함수(SDF)의 형태에 따라 정의됩니다. 형태에 따라 내비게이션의 느낌이 달라집니다. 편안한 직사각형 정지 구역에는 모서리가 둥근 상자(기본값)를, 등방성 드리프트에는 구체를, 특정 축을 우선시하는 경우에는 타원체를, 통로에는 캡슐을 사용합니다.

모서리가 둥근 상자 (기본값)​

기본 데드존은 평평하고, 깊이보다 높이가 약간 더 큰 입체 형태입니다. 이는Inverse3 와 MInverse 모두에서 편안하게 느껴지도록 조정되어 있습니다:

{
  "shape": {
    "primitive": "rounded_box",
    "parameters": { "b": { "x": 0.05, "y": 0.02, "z": 0.03 }, "r": 0.01 }
  }
}

공 — 등방성 드리프트​

{
  "shape": {
    "primitive": "sphere",
    "parameters": { "r": 0.05 }
  }
}

타원체 — X/Z 방향이 Y 방향보다 넓음​

수직 방향보다 수평 방향의 드리프트를 더 완만하게 느끼게 하고 싶을 때 사용합니다:

{
  "shape": {
    "primitive": "ellipsoid",
    "parameters": { "a": { "x": 0.06, "y": 0.03, "z": 0.06 } }
  }
}

캡슐 — 가늘고 긴 통로​

두 끝점 a/b 와 반지름 r 을 지정합니다:

{
  "shape": {
    "primitive": "capsule",
    "parameters": {
      "a": { "x": 0.0, "y": -0.03, "z": 0.0 },
      "b": { "x": 0.0, "y": 0.03, "z": 0.0 },
      "r": 0.04
    }
  }
}

크기와 움직임의 느낌을 맞춤 설정한 완벽한 예시:

{
  "inverse3": [
    {
      "device_id": "04C3",
      "configure": {
        "navigation": {
          "mode": "bubble",
          "bubble": {
            "shape": {
              "primitive": "ellipsoid",
              "parameters": { "a": { "x": 0.06, "y": 0.03, "z": 0.06 } }
            },
            "velocity_zone_width": 0.025,
            "max_velocity": 1.0,
            "velocity_ease": "quadratic_in"
          }
        }
      }
    }
  ]
}

속도 곡선​

속도 구간의 거리는 워크스페이스의 속도로 변환되기 전에 이징 커브를 통해 매핑됩니다. 사용자가 쉘 안쪽으로 밀어 넣을 때 장면이 어떻게 가속되기를 원하는지에 따라 이징을 선택하십시오.

velocity_ease느낌사용하는 상황
linear일정한 경사예측하기 쉬우며, 표준적인 선택지로 적합합니다.
quadratic_in시작은 완만하지만, 그 후의 추진력은 빠르다표면 근처에서는 정밀하게, 장거리 이동 시에는 고속으로
cubic_in매우 완만한 상승세매우 정밀하며, 장거리 이동 시 서서히 가속됩니다.
sine_out부드럽고 빠른 가속, 바깥쪽 부근에서 속도가 정체됨반응성이 뛰어나며, 서서히 상한선에 도달한다
quadratic_out출발 가속이 빠르며, 장거리 주행에서도 편안함민첩한 미세 조정, 쾌적한 순항
{ "velocity_ease": "quadratic_in", "max_velocity": 1.5 }

중심의 작동​

버블의 중심은 중첩되어 있었다 center 객체를 통해 설정합니다. 이 객체에는 4개의 필드가 있습니다 — position、relative、follow、speed — 를 가지고 있으며, 이전의 center、center_enabled、center_mode、center_drift_speed 로 구성된 평면 레이아웃을 대체하는 것입니다.

{
  "center": {
    "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
    "relative": true,
    "follow":   false,
    "speed":    0.02
  }
}

중심 기준 위치​

position 그리고 relative 는 활성화 시 중심점의 초기 위치를 제어합니다:

relativeposition 의 의미
true(기본값)position 는 커서로부터의 오프셋 입니다. 초기에는 주로 cursor + position 가 됩니다. 기본값은 (0, 0, 0) 이 경우, 버블은 커서 위치에 정확히 생성됩니다.
falseposition 는 응용 공간 내의 절대점 입니다. 입력 시 마운트 공간으로 변환되고, 출력 시 애플리케이션 공간으로 되돌아가기 때문에, 왕복 값은 일치합니다.

이후의 주요 동향​

버블이 활성화된 후, 틱마다의 동작은 follow 그리고 speed 다음에 의해 제어됩니다:

followspeed동작기존의 상당 설정
false(기본값)무시중심점은 초기화된 위치에 고정됩니다 — 고정된 중심점.center_mode: "fixed"
true> 0커서가 안쪽에 있는 동안 중심은 speed m/s 단위로 커서 방향으로 드리프트합니다.center_mode: "auto_follow"(center_drift_speed (사용)
true0.0매 틱마다 중심이 커서에 스냅됩니다 — 마치 순간이동하는 듯한 느낌입니다.center_mode: "track_cursor"
3.5 버전에서 기본값이 변경되었습니다

기본 중심 동작은 현재 고정(follow = false）입니다. 이전 버전에서는 기본적으로 커서 방향으로 드리프트가 발생했습니다（auto_follow). 이전의 드리프트 동작으로 되돌리려면 center.follow = true 을 설정하고,center.speed 이전의 center_drift_speed 해당 값에 맞춰 조정해 주십시오.

follow = true 이 상태에서 커서가 바깥쪽 경계를 벗어나면,speed 값에 관계없이 중심은 커서를 따라갑니다. 이를 통해 버블이 커서 주변에 머물게 되어, 커서가 밖으로 빠져나가는 것을 방지합니다.

충돌 시의 대응​

버블은,collision_detection.force_threshold 다음보다 큰 외부 커서 힘에 반응합니다:

  • 속도 제한 구역은 일시적으로 팽창 합니다（최대 collision_detection.inflate_ratio 배의 velocity_zone_width (까지). 이를 통해 사용자는 장애물을 피할 수 있는 여유를 확보할 수 있습니다.
  • collision_detection.enabled 하지만 true(기본값)인 경우, 버블의 중심은 충돌력의 방향으로 이동하지 않습니다. 이를 통해 사용자가 작업 공간을 단단한 벽 쪽으로 끌고 들어가는 것을 방지합니다.

충돌 감지 시, 임계값 부근에서 발생하는 깜빡임을 방지하기 위해 히스테리시스 다음과 같이 사용합니다: 일단 충돌이 활성화되면,|ext_force| 가적 collision_detection.force_threshold × collision_detection.exit_ratio ...보다 낮아질 때까지 유효한 상태가 유지됩니다. exit_ratio 을 작게 하면 히스테리시스 폭이 넓어지며(충돌 상태가 더 오래 지속되기 쉬워집니다),1.0 로 설정하면 히스테리시스를 비활성화하고 단일 임계값을 사용할 수 있습니다.

{
  "collision_detection": {
    "enabled":         true,
    "force_threshold": 0.5,
    "inflate_ratio":   2.0,
    "exit_ratio":      0.7
  }
}

매개변수 참조​

자주 조정되는 매개변수​

매개변수기본값설명
shape{rounded_box, r=0.01, b=(0.05,0.02,0.03)}데드존을 정의하는 SDF 형상
velocity_zone_width0.03 m레이트 컨트롤 쉘의 두께
max_velocity0.5 분/초항법 최대 속도
velocity_ease"quadratic_in"거리에서 속도로의 이징 곡선
center.followfalse중심이 커서를 따라가는지 여부
center.speed0.02 분/초follow = true 때의 드리프트 속도

전체 매개변수 목록​

필드형기본값설명
center.positionvec3(0, 0, 0)초기 센터 — relative = true ~일 때는 커서로부터의 오프셋,false 이 경우 앱 공간의 절대 좌표
center.relativebooltruetrue: position 는 커서로부터의 오프셋입니다.false: 앱 공간의 절대 좌표로, 경계에서 마운트 공간으로 변환됩니다
center.followboolfalsefalse: 중심은 초기화된 위치에 고정된 상태로 유지됩니다.true: 중심이 커서를 따라갑니다
center.speedfloat0.02follow = true 때의 추종 속도(m/s).0.0 인 경우 매 틱마다 커서 위치에 스냅됩니다
shape모양{rounded_box, r=0.01, b=(0.05,0.02,0.03)}데드존 SDF 형상
velocity_zone_widthfloat0.03속도 제어 쉘의 폭 (m)
max_velocityfloat0.5항법 최대 속도 (m/s)
velocity_ease문자열"quadratic_in"거리에서 속도로의 이징
reset_velocity_on_entrybooltrue커서가 속도 제한 구역에 다시 진입하면 누적 속도를 0으로 초기화합니다.
bump_widthfloat0.005표면의 촉각 범프(m)
bump_stiffnessfloat200.0표면 범프의 탄성 계수
spring_innerfloat0.0중심에 기포가 있는 스프링
spring_surfacefloat10.0표면 스프링
spring_outerfloat15.0외측 경계의 스프링
wall_stiffnessfloat700.0외측 경계를 넘어선 지점의 하드월용 스프링
damping_innerfloat0.1중심 댐핑
damping_surfacefloat4.0표면 감쇠
damping_outerfloat7.0외측 경계의 감쇠
rotation_enabledboolfalse작업 공간의 회전을 탐색 방향에 적용합니다
scale_enabledboolfalse작업 공간의 배율을 탐색 속도에 적용합니다
collision_detection.enabledbooltrue충돌 방향으로의 이동을 차단합니다
collision_detection.force_thresholdfloat1.0충돌에 이르게 하는 외력의 크기(N)
collision_detection.inflate_ratiofloat2.0충돌 시 속도 구간의 폭에 대한 배수(1.0 이상이어야 함)
collision_detection.exit_ratiofloat0.7히스테리시스 비율.|ext_force| < force_threshold × exit_ratio 이 될 때까지 충돌 상태를 유지합니다. 범위는 (0, 1]。1.0 로 히스테리시스를 비활성화합니다
3.5에서 숨겨진 필드

다음 두 기능 그룹은 3.6 버전을 위해 구현이 재설계되는 동안3.5 버전의 JSON 스키마에서 제외되었습니다:

  • 아바타 경계 클램프: avatar_boundary_enabled、avatar_boundary、avatar_boundary_hysteresis 각 필드.
  • 작업 공간의 경계 설정: workspace_bounded、workspace_transition_speed、workspace_transition_ease 각 필드.

틱 처리 코드는 계속해서 컴파일되고 기본값을 사용하여 실행되지만, 클라이언트는 HTTP 또는 WebSocket을 통해 이러한 필드를 읽거나 쓸 수 없습니다. 3.6에서는 아바타 경계가 완전한 배치 변환을 가진 버블 객체와 동일한 계층 구조의 최상위 수준에 위치합니다. bounds 로 다시 적용될 예정입니다. 워크스페이스의 경계 설정은 중심 지터에 대한 조사가 완료되는 시점에 다시 적용될 예정입니다.

검증 규칙​

  • velocity_zone_width > 0
  • 0 ≤ bump_width < velocity_zone_width
  • max_velocity > 0
  • bump_stiffness ≥ 0
  • spring_inner ≥ 0 그리고 spring_inner ≤ spring_surface ≤ spring_outer
  • wall_stiffness ≥ 0
  • damping_inner ≥ 0 그리고 damping_inner ≤ damping_surface ≤ damping_outer
  • collision_detection.force_threshold > 0
  • collision_detection.inflate_ratio ≥ 1.0
  • collision_detection.exit_ratio 하지만 (0, 1] ~ 범위 내
  • center.speed ≥ 0

잘못된 매개변수를 지정했습니다. POST 또는 configure.navigation 거절되었고,invalid-value 이벤트가 생성됩니다. 이전 설정은 계속 유효합니다.

이벤트​

이벤트명발화 시점
navigation-started기기에서 내비게이션이 활성화된 경우
navigation-updated네비게이션이 이미 활성화된 상태에서 설정이 업데이트되었을 때
navigation-stopped내비게이션이 중지되었을 때(명시적인 비활성화,DELETE, 또는 세션 종료)
invalid-value검증 결과 내비게이션 설정이 거부된 경우

알려진 제한 사항​

  • 3.5에서 숨겨진 워크스페이스의 바운딩 및 아바타 경계: 두 기능 그룹은 3.6을 위해 재설계 중인 관계로 JSON 스키마에 포함되어 있지 않습니다.앞서 언급한 매개변수 참조의주석을 참조하십시오.
  • 비균일 스케일 + 회전: rotation_enabled 그리고 scale_enabled 두 가지가 모두 활성화된 경우, 속도 방향이 약간 부정확해집니다. 회전은 스케일 축에 적용되지 않습니다.
  • 기기별 크기 조정: 버블의 크기(반지름, 영역 너비)는 기기의 물리적 배율에 따라 조정되지 않습니다.MInverse 와 Inverse3 는 동일한 절대 크기를 사용하므로, 기기에 따라 사용감이 다를 수 있습니다.