TrackingImageDatabaseInspector を読み解いてみる

概要

TrackingImageDatabase の生成を理解するために TrackingImageDatabaseInspector を読み解いてみます。 個人的な読解結果であるため誤りが含まれている可能性があることをご了承ください。

目次

確認環境

  • NRSDK 1.2.1
  • macOS 10.15

解説

拾い読み

ざっくりと TrackingImageDatabaseInspector を拾い読みすると、以下が要点になるのかなと思います。

  • TrackingImageDatabaseInspector
    • NRTrackingImageDatabase のインスペクターを表示する際
      • UpdateDatabaseQuality を呼び出す
      • BuildImage を呼び出す
        • 出力先は [Application.persistentDataPath]/TrackingImageData/[DB_GUID]/markers.json
    • TrackingImageDatabasePreprocessBuild の OnPreprocessBuild が実行される際
      • BuildDataBase を呼び出す
        • BuildImage を呼び出す
          • 出力先は [Application.persistentDataPath]/TrackingImageData/[DB_GUID]/markers.json
        • m_UpdatedQualityScores (JsonData) を更新する
        • UpdateDatabaseQuality を呼び出す
        • 呼び出した次に NRTrackingImageDatabase の BuildIfNeeded を呼び出す
          • BuildIfNeeded では
            • [Application.persistentDataPath]/TrackingImageData/[DB_GUID]/markers.json を読み込み
            • [Application.persistentDataPath]/TrackingImageData/[DB_GUID]/markers.dat に書き込み
            • [Application.persistentDataPath]/TrackingImageData/[DB_GUID] を [Application.persistentDataPath]/TrackingImageData/[DB_GUID]_zipFile にアーカイブ
            • zip のバイナリを NRTrackingImageDatabase の m_RawData に保持する
    • UpdateDatabaseQuality
      • m_UpdatedQualityScores (JsonData) の内容を NRTrackingImageDatabaseEntry に設定する
        • NRTrackingImageDatabaseEntry の Quality, Width, Height を設定する
    • BuildImage
      • trackableImageTools_[os] -image_path="[imagePath]" -save_dir="[outPath]" -width="[imageWidth]" を ShellHelper.RunCommand で実行する
        • os : osx/win/linux
        • imagePath : Texture のパス
        • outPath : [Application.persistentDataPath]/TrackingImageData/[DB_GUID]
          • macOS では /Users/xxx/Library/Application Support/DefaultCompany/[Project]/TrackingImageData/[DB_GUID]/
        • imageWidth : NRTrackingImageDatabaseEntry の Width

要点の整理

拾い読んだ内容を整理すると、インスペクター表示やビルドを行う際に TrackingImageData ディレクトリに追跡対象画像の学習結果を保存していると思われます。 macOS では /Users/[Account]/Library/Application Support/DefaultCompany/[Project]/TrackingImageData/[DB_GUID]/ ディレクトリに保存されます。

TrackingImageData/[DB_GUID] ディレクトリの内容は以下の様になっています。

.
├── Data
│   ├── nreal_city.fset
│   ├── nreal_city.fset3
│   ├── nreal_city.iset
│   ├── nreal_snake.fset
│   ├── nreal_snake.fset3
│   ├── nreal_snake.iset
│   ├── nreal_trib.fset
│   ├── nreal_trib.fset3
│   └── nreal_trib.iset
├── markers.dat
└── markers.json

さらに、markers.json と makers.dat の内容は以下の様になっています。

{
   "is_use_world_cam" : 0,
   "list" : [ "nreal_city", "nreal_snake", "nreal_trib" ],
   "nreal_city" : {
      "filter" : 50,
      "info" : "20200422212420_30.72_1.79_2_2",
      "physical_height" : 396.87496948242188,
      "physical_width" : 396.87496948242188,
      "train_score" : 70.502113342285156,
      "type" : "NFT"
   },
   "nreal_snake" : {
      "filter" : 50,
      "info" : "20200422212420_30.72_1.79_2_2",
      "physical_height" : 396.87496948242188,
      "physical_width" : 396.87496948242188,
      "train_score" : 64.339988708496094,
      "type" : "NFT"
   },
   "nreal_trib" : {
      "filter" : 50,
      "info" : "20200422212420_30.72_1.79_2_2",
      "physical_height" : 396.87496948242188,
      "physical_width" : 396.87496948242188,
      "train_score" : 68.515426635742188,
      "type" : "NFT"
   },
   "pixel_format" : "MONO8",
   "track_thread_num" : 8
}
# Number of markers
3

./Data/nreal_city
NFT
FILTER 50
MARKER_WIDTH 396.874969482422
MARKER_HEIGHT 396.874969482422

./Data/nreal_snake
NFT
FILTER 50
MARKER_WIDTH 396.874969482422
MARKER_HEIGHT 396.874969482422

./Data/nreal_trib
NFT
FILTER 50
MARKER_WIDTH 396.874969482422
MARKER_HEIGHT 396.874969482422

そして、markers.json を生成するために以下のコマンドを実行しています。

trackableImageTools_[os] -image_path="[imagePath]" -save_dir="[outPath]" -width="[imageWidth]"
  • os : osx/win/linux
    • コード上は Linux も記述されているがコマンドは osx/win しか存在しない
  • imagePath : Texture のパス
  • outPath : TrackingImageData/[DB_GUID] ディレクトリのパス
  • imageWidth : 画像の幅 [m]

ビルド時には、NRTrackingImageDatabase の BuildIfNeeded にて markers.json を markers.dat に変換し、TrackingImageData/[DB_GUID] ディレクトリ zip ファイル ([DB_GUID]_zipFile) にアーカイブしています。

また、NRTrackingImageDatabase は ScriptableObject であり以下の情報を保持しています。

  • RawData : byte[]
    • zip ファイルのバイナリデータ
  • Images : List
    • Name : string
    • Width : float
    • Height : float
    • Quality : string
    • TextureGUID : string

NRSDK の Native API を整理する

概要

NRSDK の Script から DllImport している部分を抽出しました。DLL 毎、ファイル毎に階層化して API を羅列します。 なお、nreal-examples/NativeApiFinder.cs at master · nosix/nreal-examples · GitHub を使って抽出しています。

目次

確認環境

  • NRSDK 1.2.1

Native API

kernel32

NativeEmulator.cs

  • bool FreeLibrary
    • IntPtr hModule

NativeInterface.cs

  • bool SetDllDirectory
    • string lpPathName

NativeConstants.NRNativeLibrary

NativeEmulator.cs

  • NativeResult NRSIMTrackingCreate

    • ref UInt64 out_tracking_handle
  • NativeResult NRSIMTrackingSetHeadTrackingPose

    • UInt64 tracking_handle
    • ref NativeVector3f position
    • ref NativeVector4f rotation
  • NativeResult NRSIMTrackingUpdateTrackableImageData

    • UInt64 tracking_handle
    • ref NativeVector3f center_pos
    • ref NativeVector4f center_rotation
    • float extent_x
    • float extent_z
    • UInt32 identifier
    • int state
  • NativeResult NRSIMTrackingUpdateTrackablePlaneData

    • UInt64 tracking_handle
    • ref NativeVector3f center_pos
    • ref NativeVector4f center_rotation
    • float extent_x
    • float extent_z
    • UInt32 identifier
    • int state
  • NativeResult NRSIMControllerCreate

    • ref UInt64 out_controller_handle
  • NativeResult NRSIMControllerDestroyAll

  • NativeResult NRSIMControllerSetTimestamp

    • UInt64 controller_handle
    • UInt64 timestamp
  • NativeResult NRSIMControllerSetPosition

    • UInt64 controller_handle
    • ref NativeVector3f position
  • NativeResult NRSIMControllerSetRotation

    • UInt64 controller_handle
    • ref NativeVector4f rotation
  • NativeResult NRSIMControllerSetAccelerometer

    • UInt64 controller_handle
    • ref NativeVector3f accel
  • NativeResult NRSIMControllerSetButtonState

    • UInt64 controller_handle
    • Int32 buttonState
  • NativeResult NRSIMControllerSetIsTouching

    • UInt64 controller_handle
    • bool isTouching
  • NativeResult NRSIMControllerSetTouchPoint

    • UInt64 controller_handle
    • ref NativeVector3f point
  • NativeResult NRSIMControllerSubmit

    • UInt64 controller_handle

NRDevice.cs

  • NativeResult NRSDKInitSetAndroidActivity

NativeCamera.cs

  • NativeResult NRRGBCameraImageGetRawData

    • UInt64 rgb_camera_handle
    • UInt64 rgb_camera_image_handle
    • ref IntPtr out_image_raw_data
    • ref UInt32 out_image_raw_data_size
  • NativeResult NRRGBCameraImageGetResolution

    • UInt64 rgb_camera_handle
    • UInt64 rgb_camera_image_handle
    • ref NativeResolution out_image_resolution
  • NativeResult NRRGBCameraImageGetHMDTimeNanos

    • UInt64 rgb_camera_handle
    • UInt64 rgb_camera_image_handle
    • ref UInt64 out_image_hmd_time_nanos
  • NativeResult NRRGBCameraCreate

    • ref UInt64 out_rgb_camera_handle
  • NativeResult NRRGBCameraDestroy

    • UInt64 rgb_camera_handle
  • NativeResult NRRGBCameraSetCaptureCallback

    • UInt64 rgb_camera_handle
    • NRRGBCameraImageCallback image_callback
    • UInt64 userdata
  • NativeResult NRRGBCameraSetImageFormat

    • UInt64 rgb_camera_handle
    • CameraImageFormat format
  • NativeResult NRRGBCameraStartCapture

    • UInt64 rgb_camera_handle
  • NativeResult NRRGBCameraStopCapture

    • UInt64 rgb_camera_handle
  • NativeResult NRRGBCameraImageDestroy

    • UInt64 rgb_camera_handle
    • UInt64 rgb_camera_image_handle

NativeConfigration.cs

  • NativeResult NRConfigCreate

    • UInt64 session_handle
    • ref UInt64 out_config_handle
  • NativeResult NRConfigDestroy

    • UInt64 session_handle
    • UInt64 config_handle
  • NativeResult NRConfigGetTrackablePlaneFindingMode

    • UInt64 session_handle
    • UInt64 config_handle
    • ref TrackablePlaneFindingMode out_trackable_plane_finding_mode
  • NativeResult NRConfigSetTrackablePlaneFindingMode

    • UInt64 session_handle
    • UInt64 config_handle
    • TrackablePlaneFindingMode trackable_plane_finding_mode
  • NativeResult NRConfigGetTrackableImageDatabase

    • UInt64 session_handle
    • UInt64 config_handle
    • ref UInt64 out_trackable_image_database_handle
  • NativeResult NRConfigSetTrackableImageDatabase

    • UInt64 session_handle
    • UInt64 config_handle
    • UInt64 trackable_image_database_handle

NativeController.cs

  • NativeResult NRControllerCreate

    • ref UInt64 out_controller_handle
  • NativeResult NRControllerStart

    • UInt64 controller_handle
  • NativeResult NRControllerPause

    • UInt64 controller_handle
  • NativeResult NRControllerResume

    • UInt64 controller_handle
  • NativeResult NRControllerStop

    • UInt64 controller_handle
  • NativeResult NRControllerDestroy

    • UInt64 controller_handle
  • NativeResult NRControllerGetCount

    • UInt64 controller_handle
    • ref int out_controller_count
  • NativeResult NRControllerGetAvailableFeatures

    • UInt64 controller_handle
    • int controller_index
    • ref uint out_controller_available_features
  • NativeResult NRControllerGetType

    • UInt64 controller_handle
    • int controller_index
    • ref ControllerType out_controller_type
  • NativeResult NRControllerRecenter

    • UInt64 controller_handle
    • int controller_index
  • NativeResult NRControllerStateCreate

    • UInt64 controller_handle
    • int controller_index
    • ref UInt64 out_controller_state_handle
  • NativeResult NRControllerStateUpdate

    • UInt64 controller_state_handle
  • NativeResult NRControllerStateDestroy

    • UInt64 controller_state_handle
  • NativeResult NRControllerHapticVibrate

    • UInt64 controller_handle
    • int controller_index
    • Int64 duration
    • float frequency
    • float amplitude
  • NativeResult NRControllerStateGetConnectionState

    • UInt64 controller_state_handle
    • ref ControllerConnectionState out_controller_connection_state
  • NativeResult NRControllerStateGetBatteryLevel

    • UInt64 controller_state_handle
    • ref int out_controller_battery_level
  • NativeResult NRControllerStateGetCharging

    • UInt64 controller_state_handle
    • ref int out_controller_charging
  • NativeResult NRControllerStateGetPose

    • UInt64 controller_state_handle
    • ref NativeMat4f out_controller_pose
  • NativeResult NRControllerStateGetGyro

    • UInt64 controller_state_handle
    • ref NativeVector3f out_controller_gyro
  • NativeResult NRControllerStateGetAccel

    • UInt64 controller_state_handle
    • ref NativeVector3f out_controller_accel
  • NativeResult NRControllerStateGetMag

    • UInt64 controller_state_handle
    • ref NativeVector3f out_controller_mag
  • NativeResult NRControllerStateGetButtonState

    • UInt64 controller_state_handle
    • ref uint out_controller_button_state
  • NativeResult NRControllerStateGetButtonUp

    • UInt64 controller_state_handle
    • ref uint out_controller_button_up
  • NativeResult NRControllerStateGetButtonDown

    • UInt64 controller_state_handle
    • ref uint out_controller_button_down
  • NativeResult NRControllerStateTouchState

    • UInt64 controller_state_handle
    • ref uint out_controller_touch_state
  • NativeResult NRControllerStateGetTouchUp

    • UInt64 controller_state_handle
    • ref uint out_controller_touch_up
  • NativeResult NRControllerStateGetTouchDown

    • UInt64 controller_state_handle
    • ref uint out_controller_touch_down
  • NativeResult NRControllerStateGetTouchPose

    • UInt64 controller_state_handle
    • ref NativeVector2f out_controller_touch_pose
  • NativeResult NRControllerSetHeadPose

    • UInt64 controller_handle
    • ref NativeMat4f out_controller_pose

NativeHeadTracking.cs

  • NativeResult NRHeadTrackingCreate

    • UInt64 tracking_handle
    • ref UInt64 outHeadTrackingHandle
  • NativeResult NRTrackingGetHMDTimeNanos

    • UInt64 tracking_handle
    • ref UInt64 out_hmd_time_nanos
  • NativeResult NRHeadTrackingGetRecommendPredictTime

    • UInt64 tracking_handle
    • UInt64 head_tracking_handle
    • ref UInt64 out_predict_time_nanos
  • NativeResult NRHeadTrackingAcquireTrackingPose

    • UInt64 sessionHandle
    • UInt64 head_tracking_handle
    • UInt64 hmd_time_nanos
    • ref UInt64 out_tracking_pose_handle
  • NativeResult NRTrackingPoseGetPose

    • UInt64 tracking_handle
    • UInt64 tracking_pose_handle
    • ref NativeMat4f out_pose
  • NativeResult NRTrackingPoseGetTrackingReason

    • UInt64 tracking_handle
    • UInt64 tracking_pose_handle
    • ref LostTrackingReason out_tracking_reason
  • NativeResult NRTrackingPoseDestroy

    • UInt64 tracking_handle
    • UInt64 tracking_pose_handle
  • NativeResult NRHeadTrackingDestroy

    • UInt64 tracking_handle
    • UInt64 head_tracking_handle

NativeHMD.cs

  • NativeResult NRHMDCreate

    • ref UInt64 out_hmd_handle
  • NativeResult NRHMDGetEyePoseFromHead

    • UInt64 hmd_handle
    • int eye
    • ref NativeMat4f outEyePoseFromHead
  • NativeResult NRHMDGetEyeFov

    • UInt64 hmd_handle
    • int eye
    • ref NativeFov4f out_eye_fov
  • NativeResult NRHMDGetEyeResolution

    • UInt64 hmd_handle
    • int eye
    • ref NativeResolution out_eye_resolution
  • NativeResult NRHMDDestroy

    • UInt64 hmd_handle

NativeMultiDisplay.cs

  • NativeResult NRDisplayCreate

    • ref UInt64 out_display_handle
  • NativeResult NRDisplayPause

    • UInt64 display_handle
  • NativeResult NRDisplayResume

    • UInt64 display_handle
  • NativeResult NRDisplaySetMainDisplayTexture

    • UInt64 display_handle
    • IntPtr controller_texture
  • NativeResult NRDisplayDestroy

    • UInt64 display_handle

NativePlane.cs

  • NativeResult NRTrackablePlaneGetType

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref TrackablePlaneType out_plane_type
  • NativeResult NRTrackablePlaneGetCenterPose

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref NativeMat4f out_center_pose
  • NativeResult NRTrackablePlaneGetExtentX

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref float out_extent_x
  • NativeResult NRTrackablePlaneGetExtentZ

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref float out_extent_z
  • NativeResult NRTrackablePlaneGetPolygonSize

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref int out_polygon_size
  • NativeResult NRTrackablePlaneGetPolygon

    • UInt64 session_handle
    • UInt64 trackable_handle
    • IntPtr out_polygon

NativeRenderring.cs

  • NativeResult NRRenderingCreate

    • ref UInt64 out_rendering_handle
  • NativeResult NRRenderingStart

    • UInt64 rendering_handle
  • NativeResult NRRenderingDestroy

    • UInt64 rendering_handle
  • NativeResult NRRenderingPause

    • UInt64 rendering_handle
  • NativeResult NRRenderingResume

    • UInt64 rendering_handle
  • NativeResult NRRenderingInitSetAndroidSurface

  • NativeResult NRRenderingDoRender

    • UInt64 rendering_handle
    • IntPtr left_eye_texture
    • IntPtr right_eye_texture
    • ref NativeMat4f head_pose

NativeTrackable.cs

  • NativeResult NRTrackableListCreate

    • UInt64 session_handle
    • ref UInt64 out_trackable_list_handle
  • NativeResult NRTrackableListDestroy

    • UInt64 session_handle
    • UInt64 out_trackable_list_handle
  • NativeResult NRTrackableListGetSize

    • UInt64 session_handle
    • UInt64 trackable_list_handle
    • ref int out_list_size
  • NativeResult NRTrackableListAcquireItem

    • UInt64 session_handle
    • UInt64 trackable_list_handle
    • int index
    • ref UInt64 out_trackable
  • NativeResult NRTrackableGetIdentifier

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref UInt32 out_identifier
  • NativeResult NRTrackableGetType

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref TrackableType out_trackable_type
  • NativeResult NRTrackableGetTrackingState

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref TrackingState out_tracking_state

NativeTrackableImage.cs

  • NativeResult NRTrackableImageDatabaseCreate

    • UInt64 session_handle
    • ref UInt64 out_trackable_image_database_handle
  • NativeResult NRTrackableImageDatabaseDestroy

    • UInt64 session_handle
    • UInt64 trackable_image_database_handle
  • NativeResult NRTrackableImageDatabaseLoadDirectory

    • UInt64 session_handle
    • UInt64 trackable_image_database_handle
    • string trackable_image_database_directory
  • NativeResult NRTrackableImageGetCenterPose

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref NativeMat4f out_center_pose
  • NativeResult NRTrackableImageGetExtentX

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref float out_extent_x
  • NativeResult NRTrackableImageGetExtentZ

    • UInt64 session_handle
    • UInt64 trackable_handle
    • ref float out_extent_z

NativeTracking.cs

  • NativeResult NRTrackingCreate

    • ref UInt64 out_tracking_handle
  • NativeResult NRTrackingInitSetTrackingMode

    • UInt64 tracking_handle
    • TrackingMode tracking_mode
  • NativeResult NRTrackingStart

    • UInt64 tracking_handle
  • NativeResult NRTrackingDestroy

    • UInt64 tracking_handle
  • NativeResult NRTrackingPause

    • UInt64 tracking_handle
  • NativeResult NRTrackingResume

    • UInt64 tracking_handle
  • NativeResult NRTrackingRecenter

    • UInt64 tracking_handle
  • NativeResult NRTrackingUpdateTrackables

    • UInt64 tracking_handle
    • TrackableType trackable_type
    • UInt64 out_trackable_list_handle

NativeVersion.cs

  • NativeResult NRGetVersion
    • ref NRVersion out_version

NRNativeEncodeLibrary

NativeEncoder.cs

  • int HWEncoderCreate

    • ref UInt64 out_encoder_handle
  • int HWEncoderStart

    • UInt64 encoder_handle
  • int HWEncoderSetConfigration

    • UInt64 encoder_handle
    • string config
  • int HWEncoderUpdateSurface

    • UInt64 encoder_handle
    • IntPtr texture_id
    • UInt64 time_stamp
  • int HWEncoderStop

    • UInt64 encoder_handle
  • int HWEncoderDestroy

    • UInt64 encoder_handle

TrackingImageDatabase の生成を理解する

概要

ImageTracking を行うためには予め NRKernalSessionConfig に追跡対象を登録した TrackingImageDatabase (NRTrackingImageDatabase) を設定する必要があります。 TrackingImageDatabase は Unity Editor で生成します。 この記事では、TrackingImageDatabase の生成方法を説明し、生成を行っているソースコードを解読してみます。 個人的な読解結果であるため誤りが含まれている可能性があることをご了承ください。

目次

確認環境

  • NRSDK 1.2.1

解説

TrackingImageDatabase の生成方法

TrackingImageDatabase を生成する手順は以下のとおりです。

  1. Texture を用意する
    • Requirements は要注意
      • JPEG (コードを読むと PNG にも対応している様子)
      • grayscale or RGB color
      • 150 dpi
      • The dimensions of printed reference images < 1m2
      • well-distributed feature points
      • low degrees of self-similarity
      • Adobe Photoshop よりは Adobe Illustrator で書き出すことを推奨
  2. Texture を選択する
    • 複数登録する場合は複数選択する
  3. コンテキストメニュー Create/NRSDK/TrackingImageDatabase を選択する
  4. TrackingImageDatabase が生成される

TrackingImageDatabase を生成しているソースコードを解読する

TrackingImageDatabase を行っている Script は TrackingImageDatabaseContextMenu です。 TrackingImageDatabaseContextMenu では以下の処理を行っています。

  • MenuItem に Assets/Create/NRSDK/TrackingImageDatabase を追加する
  • 選択した ImagePath を取得する
    • サポート対象となる拡張子 : .png, .jpg, .jpeg
    • 警告ダイアログを表示する拡張子 : .psd, .tiff, .tga, .gif, .bmp, .iff, .pict
    • スルーする : 他
  • サポート対象となる ImagePath が指定されたときのみ以下を行う
  • NRTrackingImageDatabase (ScriptableObject) を生成する
  • 各 ImagePath に対して、NRTrackingImageDatabaseEntry を生成する
    • imageName, Texture2D を指定
  • NRTrackingImageDatabaseEntry を imageName 順に並べ替え
  • NRTrackingImageDatabase に NRTrackingImageDatabaseEntry を追加する
  • NRTrackingImageDatabase を TrackingImageDatabase.asset として保存する

NRTrackingImageDatabase

NRTrackImageDatabase は ScriptableObject です。 Unity Editor で NRTrackingImageDatabaseEntry を登録し、実機で動かす場合には NRTrackingImageDatabaseEntry の参照だけを行います。 そのため、Add, RemoveAt, NRTrackingImageDatabaseEntry の set などの編集 API は Unity Editor のときのみ有効になっています。 また、NRTrackingImageDatabaseEntry の Width, Heigh, Quality を編集する処理は含まれていません。 これらの処理は TrackingImageDatabaseInspector で行っています。

NRTrackingImageDatabaseEntry

以下を保持する構造体です。

  • Name : string
  • Width : float
  • Height : float
  • Quality : string
  • TextureGUID : string

TrackingImageDatabaseContextMenu では、Name と Texture を指定して生成しています。 Texture 自身を保持せずに Texture の識別子 TextureGUID を保持して、Texture を求められた際には Texture を Load しています。 Width, Height, Quality は 0 や空文字列が設定されます。

RGBCamera-Record を読み解いてみる

概要

RGBCamera-Capture を読み解いてみる - NOSIX に引き続き、 RGB Camera の使い方を理解するために、 サンプルとして提供されている RGBCamera-Record (Scene) のソースコードを解読してみます。 個人的な読解結果であるため誤りが含まれている可能性があることをご了承ください。

目次

確認環境

  • NRSDK 1.2.1

解説

RGBCamera-Capture を読み解いてみる - NOSIX と重複している内容は省略しています。

Video Capture に関連するのは VideoCaptureExample (GameObject) の部分です。 PlaneDetector, Canvas は Video Capture には関係ありません。 そのため、これらの説明は省略します。

Video Capture を行うためには NRVideoCapture を使います。 録画した Video は StartRecordingAsync の引数で指定する Path に保存されます。 また、Previewer の Texture に NRVideoCapture の PreviewTexture を設定することでプレビューを行っています。

Hierarchy

Scripts

VideoCaptureExample の Scripts

  • VideoCapture2LocalExample (in Demos/Record/Scripts/VideoCapture2LocalExample)
    • Inspector での設定項目
      • Previewer
    • 起動時に NRVideoCapture インスタンスを生成する
      • NRVideoCapture.CreateAsync を使う
    • startBtn 押下時に NRVideoCapture.StartVideoModeAsync を行う
      • Previewer.SetData で NRVideoCapture.PreviewTexture と再生中を設定する
      • CameraParameters で Camera 設定を行う
        • NRVideoCapture.SupportedResolutions で有効な resolution を取得して CameraParameters に使う
        • NRVideoCapture.GetSupportedFrameRatesForResolution で有効な frame rate を取得して CameraParameters に使う
      • NRVideoCapture.AudioState.ApplicationAndMicAudio を設定する
      • Start に成功した時、NRVideoCapture.StartRecordingAsync を行う
        • 保存先の Path を指定する
    • stopBtn 押下時に NRVideoCapture.StopRecordingAsync を行う
      • Previewer.SetData で NRVideoCapture.PreviewTexture と停止中を設定する
      • Stop に成功した時、NRVideoCapture.StopVideoModeAsync を行う

PlaneDetector の Scripts

  • PlaneDetector (in Demos/HelloMR/Scripts)
    • 主題から逸れるため省略
  • HelloMRController (in Demos/HelloMR/Scripts)
    • 主題から逸れるため省略

RGBCamera-Capture を読み解いてみる

概要

RGBCamera を読み解いてみる - NOSIX に引き続き、 RGB Camera の使い方を理解するために、 サンプルとして提供されている RGBCamera-Capture (Scene) のソースコードを解読してみます。 個人的な読解結果であるため誤りが含まれている可能性があることをご了承ください。

目次

確認環境

  • NRSDK 1.2.1

解説

RGBCamera を読み解いてみる - NOSIX と重複している内容は省略しています。

このサンプルは以下の 2 つの機能のサンプルになっています。これらは同時に使わずに別々に使うことができます。

  • PhotoCapture
  • Previewer

PhotoCapture は静止画の Texture2D を取得する機能です。 このサンプルでは、Trigger ボタン (マウスの左ボタンクリックで Emulate される) で静止画が撮影され、目の前に静止画が表示されます。 また、目の前に表示するだけではなく Previewer にも表示します。 PhotoCaptureExample (Script) で処理方法は確認できます。 NRPhotoCapture クラスを使うことで実現しています。

Previewer は撮影した画像 (Texture2D) をプレビューする機能です。 このサンプルでは、App ボタン (Emulator では Space キーでも可) でプレビューの On/Off を切り替えます。 Previewer を On にすると右手コントローラーの付近にプレビューが表示されます。 Previewer を Off にすると Raycast の Laser と Reticle が表示されます。 Previewer (Prefab) を追加して、Previewer.SetData をいずれかの Script から呼び出して使用します。 このサンプルでは、PhotoCaptureExample (Script) で静止画を撮影した際に Previewer.SetData を呼び出してプレビューを更新しています。 Previewer には State Icon があり、再生中は緑、停止中は赤になります。 この再生中の状態も Previewer.SetData で設定します。 このサンプルでは、停止中に設定されることがないため赤に変わりません。

Hierarchy

  • RGBCamera-Capture (Scene)

  • Previewer (Prefab)

    • [C] Canvas
    • [C] NRPreviewer
    • Root : Rotation X で 90 度回転している (Laser と水平)
      • PreviewScreen
        • [C] RawImage
      • StateIcon
        • [C] Image

Scripts

PhotoCaptureExample の Scripts

  • PhotoCaptureExample (in Demos/Record/Scripts/PhotoCaptureExample)
    • Inspector での設定項目
      • Previewer
    • 起動時に RGB Camera を Activate する
    • Trigger ボタン、もしくは、T キーで、写真を撮影する
    • Home ボタン、もしくは、Q キーで、RGB Camera を Deactivate する
    • App ボタン、もしくは、O キーで、RGB Camera を Activate する
    • NRPhotoCapture が生成されているならば、Previewer.SetData を呼び出し、Previerwer に Texture2D と状態を設定する
      • Deactivate しても Previewer の状態は変更されない
        • Deactivate すると NRPhotoCapture が破棄されて Previewer.SetData が呼び出されなくなるため
    • Activate の手順は
      • NRPhotoCapture.CreateAsync で NRPhotoCapture インスタンスを生成する
      • 生成した NRPhotoCapture インスタンスに対して StartPhotoModeAsync で Activate する
        • CameraParameters で RGB Camera の設定を行う
    • Deactivate の手順は
      • NRPhotoCapture.StopPhotoModeAsync を呼び出す
      • 完了通知コールバックで、NRPhotoCapture.Dispose()
    • 写真を撮影する手順は
      • NRPhotoCapture.TakePhotoAsync を呼び出す
      • 撮影成功すると PhotoCaptureFrame インスタンスが得られる
        • PhotoCaptureFrame.UploadImageDataToTexture で Texture2D を更新する
        • 撮影した画像の Quad を生成して、目の前に表示する
          • NRSessionManager から NRHMDPoseTracker を取得し、Center Camera の位置を取得する
          • Center Camera の前方に Quad の位置を設定する
          • Quad の Material に Texture2D を設定する

Previewer の Scripts

  • NRPreviewer (in Scripts/Capture)
    • Inspector での設定項目
      • Root
      • Preview Screen : PreviewScreen (RawImage)
      • State Icon : StateIcon (Image)
      • Is Bind To Controller : true
    • App ボタン、もしくは、Space キーで以下を切り替える
      • Controller の Laser, Reticle 表示
      • Root (GameObject) の表示
    • Is Bind To Controller が true ならば、Controller (Right) の ModelAnchor から forward 方向に 0.3 の位置に Previewer (GameObject) を表示する
      • false ならば、Unity Editor で設定した位置になる

RGBCamera を読み解いてみる

概要

TrackableImageEmulator を読み解いてみる - NOSIX に引き続き、 RGB Camera の使い方を理解するために、 サンプルとして提供されている RGBCamera (Scene) のソースコードを解読してみます。 個人的な読解結果であるため誤りが含まれている可能性があることをご了承ください。

目次

確認環境

  • NRSDK 1.2.1

解説

TrackableImageEmulator を読み解いてみる - NOSIX と同様に HierarchyScripts を網羅したいところですが、内容に重複する部分が多いため重複部分は省略します。

TrackableImageEmulator を読み解いてみる - NOSIX との差異は、大きく分けて 3 点あります。

  • NRInput (Component) で Override Camera Center を設定する
  • CanvasRaycastTarget (Component) で Canvas を Raycast Target に設定する
  • CameraCaptureController (Component) で NRRGBCamTexture を操作する

NRInput の Override Camera Center に CenterCamera を設定する変更は、コードを読む限りでは不要(なのではないかと思います【検証予定】)。 設定しない場合は MainCamera が使用されます。 RGBCamera (Scene) では CenterCamera が MainCamera になっています。

CanvasRaycastTarget は Raycast に関する設定なので、RGB Camera の使用に関係しているわけではない(と思います【検証予定】)。

RGB Camera の使用に関しては CameraCaptureController (Component) だけを理解すれば良い(と思われます)。 CameraCaptureController (Component) では NRRGBCamTexture を使っています。 NRRGBCamTexture は Texture の生成/破棄と NRRgbCamera の操作を行います。

Hierarchy

  • RGBCamera (Scene)
    • NRCameraRig (Perfab)
    • NRInput (Prefab)
    • TextureCanvas
      • [C] Canvas
      • [C] Canvas Scaler
      • [C] CanvasRaycastTarget
      • CaptureController
        • [C] CameraCaptureController
        • RawImage
          • [C] Raw Image
        • FrameCount
          • [C] Text
        • Controller
          • [C] Grid Layout Group
          • Play
            • [C] Image
            • [C] Button
            • Text
              • [C] Text
          • Pause
            • [C] Image
            • [C] Button
            • Text
              • [C] Text
          • Stop
            • [C] Image
            • [C] Button
            • Text
              • [C] Text
    • Directional Light : 上から差し込むライト
      • [C] Light

Scripts

NRInput の Scripts

  • NRInput (in Scripts/Input/Controller)
    • こちらを参照
    • Override Camera Center に CenterCamera が設定されている
      • None が設定されている場合は CameraCenter として Camera.main が使用される
      • Camera.main は MainCamera Tag が付与されている Camera なので、このサンプルでは None でも構わない(と思われる【未検証】)

TextureCanvas の Scripts

  • CanvasRaycastTarget (in Scripts/Input/EventSystem/CanvasRaycast)
    • Inspector での設定項目
      • Ignore Reversed Graphics : true
    • CanvasTargetController に Canvas を登録する
      • 実際に登録するのは ICanvasRaycastTarget として
      • ICanvasRaycastTarget は canvas, enabled, ignoreReversedGraphics を持つ
      • CanvasTargetController に設定された CanvasNRPointerRaycaster で Raycast(Ray ray, float distance, List<RaycastResult> raycastResults) を実行する際にRaycast 対象の Canvas として使用される
        • 但し、Enable Graphic Raycast が有効である必要がある
  • CameraCaptureController (in Demos/RGBCamera/Scripts)
    • Inspector での設定項目
      • Capture Image : RawImage (RawImage)
      • Frame Count : FrameCount (Text)
    • NRRGBCamTexture を使い画像を取り込む
      • GetTexture() で Texture を取得し、取得した Texture を RawImage に設定する
      • FrameCount でフレーム数を取得し、取得したフレーム数を FrameCount (Text) に設定する
      • Play() で取り込み開始
      • Pause() で取り込み停止
      • Stop() で取り込み終了
      • Stop() すると Texture が破棄されるので、Stop() 後に再度 Play() する場合は GetTexture() を再実行する必要がある
      • (Reference の更新まで手がまわっていないのか、Reference には記載がないクラス)

TrackableImageEmulator を読み解いてみる

概要

NRSDK (Nreal Light の Software Developer Kit) の Emulator を理解するために、 サンプルとして提供されている TrackableImageEmulator (Scene) のソースコードを解読してみます。 個人的な読解結果であるため誤りが含まれている可能性があることをご了承ください。

目次

確認環境

  • NRSDK 1.2.1

解説

まず、TrackableImageEmulator (Scene) を開き Hierarchy を確認しました。 Hierarchy に GameObject と GameObject にアタッチされている Component の一覧を網羅しています。 続いて、網羅した Component に含まれている Script を確認しました。 Scripts に Script の一覧を網羅しています。

網羅するだけでは分かりづらいので、サンプルコードを Application、Emulator、SDKの 3 つに分類します。

  • Application
    • Application に応じて変わるコードやオブジェクト
    • つまり、サンプルの部分になるコードやオブジェクト
  • Emulator
    • Emulator で動かす場合に必要となるコードやオブジェクト
    • Unity Editor の Play mode で動かす
  • SDK
    • Emulator を使わない場合でも必ず必要になるコードやオブジェクト
    • 大体の Application で使うのではと想像する

Game Object を上記の規則で分類すると以下の様になると思います。

  • Application
    • Directional Light
      • 無くても構わない
      • Emulator の Room、Image と Application の Cube を照らす
    • CubeCenter
      • Image Tracking の結果を示すためのオブジェクト
      • Image を認識したら Cube が表示される
  • Emulator
    • TrackableFoundTest
      • TrackableObserver と GameObject を関連づける
      • TrackableObserver の FoundEvent, LostEvent にリスナーを登録する
        • Found では GameObject の位置、方向を設定して有効化する
        • Lost では GameObject を無効化する
      • (Demo に合わせた機能になっている気がしないでもない)
      • (Emulator フォルダには Emulator の Demo も含まれていると考えた方がよいのかも)
    • EmulatorRoom
      • 部屋の Model
      • Emulator で動作させない時には不要になる
    • NRTrackableImageTarget
      • EmulatorRoom 同様、Emulator で動作させない時には不要なオブジェクト(のはず)
      • NRTrackableImageBehavior (Component) では、GameView に表示されている間は TrackingState を Tracking として Emulate する
      • TrackableObserver (Component) では、TrackingState に応じて FoundEvent/LostEvent を呼び出す
        • (Emulator を使わない場合でも必要な処理だと思うのだが、Emulator を使わない場合は書き換えないといけない?)
  • SDK
    • NRCameraRig
      • とにもかくにも必須になるカメラ
      • HMD の位置と方向を追跡する NRHMDPoseTracker (Component) を持つ
      • Emulator として動かすと以下をインスタンス化する
        • Prefabs/NREmulatorManager
        • Prefabs/NREmulatorHeadPose
    • NRInput
      • 入力を扱う為に必須になる
      • GazeTracker, ControllerTracker (Left/Right) により 3 つの Raycast を扱う
      • Laser の描画、Raycast が hit する点の描画を行う
      • デフォルトでは、ControllerTracker (Right) だけが有効
        • NRInput (Component) の DomainHand で Left/Right を指定
        • NRInput (Component) の Raycast Mode で Gaze/Laser を指定
      • Emulator として動かすと以下をインスタンス化する
        • Prefabs/NREmulatorManager
        • Prefabs/NREmulatorController

Hierarchy

※ [C] は Component を意味する。

Scripts

TrackableFoundTest の Scripts

  • TrackableFoundTest (in Emulator/Scripts)

NRTrackableImageTarget の Scripts

  • TrackableObserver (in Emulator/Scripts)
    • NRTrackableImageBehavior の DatabaseIndex を参照して、追跡対象であるかを検証している
    • NRFrame.GetTrackables(List<NRTrackableImage>, NRTrackableQueryFilter.All) を呼び出す
    • NRTrackableImage の TrackingState が Tracking ならば FoundEvent を呼び出し、Tracking 以外ならば LostEvent を呼び出す
    • FoundEvent の呼び出しでは、NRTrackableImage の CenterPose の position と rotation を渡す
      • CubeCenter の position と rotation に使われる
  • NRTrackableImageBehavior : NRTrackableBehaviour (in Emulator/Scripts)
    • NREmulatorManager.IsInGameView で transform (Tracking対象) が GameView に表示されているかを調べる
    • NREmulatorManager.NativeEmulatorApi.UpdateTrackableData() により TrackingState を Tracking/Stopped に切り替える
    • UpdateTrackableData を呼び出す際に、DatabaseIndex (NRTrackableBehaviour のメンバ) を渡している
    • つまり、GameView に表示されていれば画像の追跡は Tracking、表示されていなければ画像の追跡は Stopped として Emulate している

NRCameraRig の Scripts

  • AppManager (in Demos/HelloMR/Scripts)
    • OnEnable/OnDisable で NRInput に ClickListener を追加/削除している
    • ClickListener では HomeButton, AppButton の動作を設定している
    • (NRCameraRig (Prefab) から Demo の Script を参照してしまっていいんですかね?)
  • NRSessionBehavior (Reference) (in Scripts)
    • NSSessionManager を制御するMonoBehavior
      • Awake : CreateSession
      • Start : StartSession
      • OnApplicationPause(true) : DisableSession
      • OnApplicationPause(false) : ResumeSession
      • OnDisable : DisableSession
      • OnDestroy : DestroySession
    • NRSessionConfig で設定できる
      • Start のタイミングで NSSessionManager.SetConfiguration に渡される
  • NSSessionManager (in Scripts/Managers)
    • NRDevice の Init/Destroy
    • NativeTracking, NativeHeadTracking の開始/終了
    • InitEmulator
  • NRHMDPoseTracker (Reference) (in Scripts)
    • GetHeadPose で Pose (position と rotation の組) を取得できる
  • NRMultiDisplayManager (in Scripts/Managers)

NRInput の Scripts

  • NRInput (in Scripts/Input/Controller)
    • Inspector での設定項目
      • Emulate Virtual Display : false
      • Override Camera Center : None (Transform)
      • Anchor Helper
      • Raycast Mode : Laser
      • Click Interval : 0.3
      • Drag Threshold : 0.02
    • 各種入力の取得
    • 各種入力イベントのリスナー登録
    • DomainHand の設定により有効化するコントローラーを指定
    • InitEmulator
  • ControllerAnchorsHelper (in Scripts/Input/Controller)
    • 以下のAnchor を保持する
      • GazePoseTrackerAnchor
      • RightPoseTrackerAnchor
      • LeftPoseTrackerAnchor
      • RightModelAnchor
      • LeftModelAnchor
      • RightLaserAnchor
      • LeftLaserAnchor
  • GazeTracker (in Scripts/Input/Controller)
    • Gaze には注視、凝視という意味がある
    • Inspector での設定項目
      • raycaster に NRPointerRaycaster を設定する
        • GazeRaycaster (GameObject) の NRPointerRaycaster (Component) が設定されている
    • NRInput.OnControllerStatesUpdated に UpdateTracker を登録する
    • UpdateTracker では
      • NRInput.RaycastMode == RaycastModeEnum.Gaze ならば、GazeTracker を有効にする
      • GazeTracker が有効ならば
        • raycaster を有効にする
        • GazeTracker の position, rotation を NRInput.CameraCenter の position, rotation にする
  • ControllerTracker (in Scripts/Input/Controller)
    • Inspector での設定項目
      • defaultHandEnum に Right/Left を設定する
      • raycaster に NRPointerRaycaster を設定する
        • LaserRaycaster (GameObject) の NRPointerRaycaster (Component) が設定されている
      • modelAnchor に ModelAnchor (GameObject) が設定されている
    • NRInput.OnControllerRecentering に OnRecentering を登録する
    • NRInput.OnControllerStatesUpdated に UpdateTracker を登録する
    • OnRecentering では
      • VerifyYAngle の再計算
    • UpdateTracker では
      • NRInput.CheckControllerAvailable(defaultHandEnum) が真ならば、ControllerTracker を有効にする
      • ControllerTracker が有効ならば
        • NRInput.RaycastMode == RaycastModeEnum.Laser ならば、raycaster を有効にする
        • modelAnchor を有効にする
        • TrackPose を呼び出す
    • TrackPose では
      • NRInput.GetControllerAvailableFeature を呼び出して 6 DOF であるかを調べる
      • 6 DOF ならば
        • ControllerTracker の position を NRInput.GetPosition(defaultHandEnum) にする
        • raycaster, modelAnchor の localPosition を zero にする
        • ControllerTracker の localRotation を NRInput.GetRotation(defaultHandEnum) に VerifyYAngle の回転を加えた値にする
      • 6 DOF でなければ
        • ControllerTracker の position を SmoothTrackTargetPosition で計算して設定する
        • raycaster, modelAnchor の localPosition を起動時の初期値にする
        • ControllerTracker の localRotation を NRInput.GetRotation(defaultHandEnum) に VerifyYAngle の回転を加えた値にする
    • SmoothTrackTargetPosition では
      • TargetPos を NRInput.CameraCenter の位置と向きに基づいて計算する
      • ControllerTracker と TargetPos の距離が MaxDistanceFromTarget より大きくなれば、IsMovingToTarget を真にする
      • ControllerTracker と TargetPos の距離が 0.02f より小さくなれば、IsMovingToTarget を偽にする
      • IsMovintToTarget が真であれば、ControllerTracker を TargetPos に近づける
  • NRPointerRaycaster (in Scripts/Input/EventSystem/Raycasters)
    • Inspector での設定項目
      • Near Distance : 0
      • Far Distance : 15
      • Mask Type : Exclusive (/Inclusive)
      • Mask : Nothing (LayerMask value)
      • Show Debug Ray : true
      • Enable Physics Raycast : true
      • Enable Graphic Raycast : true
    • Raycast()
      • Near Distance と Far Distance の間で Ray をとばす
      • sortedRaycastResults に Raycast の結果が保存される
      • breakPoints (要素数 2 の List<Vector3>) に Ray の始点と終点を保存する
        • hit した場合は、終点は hit した位置
        • hit しなかった場合は、Far Distance の位置
    • Raycast(Ray ray, float distance, List raycastResults)
      • Enable Physics Raycast が有効ならば、PhysicsRaycast を呼び出す
      • Enable Graphic Raycast が有効ならば、CanvasTargetCollector.GetCanvases() で得られた全ての ICanvasRaycastTarget に対して GraphicRaycast を呼び出す
    • PhysicsRaycast(Ray ray, float distance, List<RaycastResult> raycastResults)
      • Physics.RaycastNonAlloc に Mask を渡す
      • Mask は Mask Type によって Exclusive/Inclusive を切り替える
    • GraphicRaycast(Canvas canvas, bool ignoreReversedGraphics, Ray ray, float distance, NRPointerRaycaster raycaster, List<RaycastResult> raycastResults)
  • NRLaserReticle (in Scripts/Input/EventSystem)
    • 焦点板、十字線、焦点面につける十字線のことをレチクルと呼ぶらしい
    • Inspector での設定項目
      • Raycaster : NRPointerRaycaster
      • Default Visual : ReticleState.Normal のときに有効にされる GameObject
      • Hover Visual : ReticleState.Hover のときに有効にされる GameObject
      • Default Distance : Raycaster の Near Distance と Far Distance の間に収まる値
        • ReticleState.Normal のときの表示に使われる
      • Reticle Size Ratio
        • localScale の計算に使われる
    • NRInput.ReticleVisualActive が false の場合は、ReticleState.Hide になる
    • Raycaster で hit があれば、ReticleState.Hover になる
      • HitTarget に hit した GameObject が設定される
    • Raycaster で hit がなければ、ReticleState.Normal になる
      • HitTarget は null に設定される
  • NRLaserVisual (in Scripts/Input/EventSystem)
    • Inspector での設定項目
      • Raycaster : NRPointerRaycaster
      • Line Renderer
      • Show On Hit Only
      • Default Distance : Raycaster の Near Distance と Far Distance の間に収まる値
    • NRInput.LaserVisualActive が false の場合は、Line Renderer が無効になる
    • Show On Hit Only が true、かつ、Raycaster で hit がなければ、Line Renderer が無効になる
    • Show On Hit Only が flase、または、Raycaster で hit があれば、Line Renderer で線を描画する
      • 始点は Near Distance の位置
      • 終点は hit した位置、または、Default Distance の位置

NREmulatorManager の Scripts

  • NREmulatorManager (in Emulator/Scripts)
    • NativeEmulatorApi の CreateSIMTracking を呼び出す
    • NativeEmulatorApi の CreateSIMController を呼び出す

NREmulatorHeadPose の Scripts

  • NREmulatorHeadPose (in Emulator/Scripts)
    • キーボード、マウス操作を HMD の動きとして Emulate する

NREmulatorController の Scripts

  • NREmulatorController (in Emulator/Scripts)
    • キーボード、マウス操作を Controller の動きとして Emulate する

参考文献